本文档收录了IndexSDK的常见问题及解答。您也可以查阅 获取更多问题解决方案。若仍未找到答案，欢迎 提问。
问题现象[object Object][object Object]
编译Faiss 1.10.0时，出现报错信息，提示“CMake 3.24.0 or higher is required”。
问题原因[object Object][object Object]
当前CMake的版本过低，Faiss 1.10.0需要配套CMake 3.24.0及以上版本。
解决方案[object Object][object Object]
安装CMake 3.24.0或以上版本。以安装CMake 3.24.0版本为例：
x86环境：
获取CMake安装脚本。
[object Object]运行安装脚本。
[object Object][object Object]查看CMake版本。
[object Object]显示当前的CMake版本：
[object Object]
aarch64环境：
获取CMake安装脚本。
[object Object]运行安装脚本。
[object Object][object Object]查看CMake版本。
[object Object]显示当前的CMake版本：
[object Object]
问题现象[object Object][object Object]
从Faiss 1.7.1版本升级到Faiss 1.10.0版本后，IVFSQT算法在添加较大底库后，update接口性能下降。
问题原因[object Object][object Object]
IVFSQT算法在添加较大底库后，update接口会使用IndexFlat来进行CPU聚类。IndexFlat在Faiss 1.7.1版本中，使用了exhaustive_L2sqr_seq接口；在Faiss 1.10.0版本中，exhaustive_L2sqr_seq添加了omp的线程数约束，导致了性能下降。
解决方案[object Object][object Object]
Faiss源码的exhaustive_L2sqr_seq接口中去掉omp的num_threads(nt)约束后,重新编译安装Faiss 1.10.0版本,多卡场景可设置export OMP_NUM_THREADS=2.
问题现象[object Object][object Object]
生成算子时，发生报错，提示MemoryError错误或者multiprocessing报错。
问题原因[object Object][object Object]
生成算子的过程中资源不足。
解决方案[object Object][object Object]
在运行算子生成脚本时通过降低“-pool”参数值，重新运行脚本，可从-pool 1开始尝试设置。
问题现象[object Object][object Object]
生成算子时出现类似如下错误：
Failed to import Python module [AttributeError: `np.float_` was removed in the NumPy 2.0 release. Use `np.float64` instead.].
问题原因[object Object][object Object]
Python3.9及以上版本默认安装NumPy 2.0版本，但CANN9.0.0以下版本（不包括9.0.0）目前未适配NumPy 2.0。
解决方案[object Object][object Object]
将NumPy版本更换到1.26。
问题现象[object Object][object Object]
生成距离算子时，ATC出现以下报错：
Call InferShapeAndType for nodeXXXX failed
问题原因[object Object][object Object]
新版CANN加强了校验，InferDataType实现不可缺少。
解决方案[object Object][object Object]
可以设置以下环境变量进行规避：
问题现象[object Object][object Object]
生成算子失败，报错信息.../libgomp.so: cannot allocate memory in static TLS block。
问题原因[object Object][object Object]
在低版本的OS上存在gcc相关bug，该bug官方说明可参见。
解决方案[object Object][object Object]
请执行以下命令导入环境变量。
问题现象[object Object][object Object]
部分操作系统下，生成算子失败，报错：fatal error: 'cstdint' file not found 或 fatal error: 'cstdio' file not found。
问题原因[object Object][object Object]
问题原因一：可参见《CANN 软件安装》中的“”章节中的“可能原因”部分。
问题原因二：在部分特定系统中，该问题源于操作系统发行版的工具链命名差异。昇腾 CANN 软件栈在构建算子时，默认会去查找标准的 aarch64-linux-gnu 工具链目录以获取 C++ 标准库头文件。然而，在部分特定操作系统（kylin、openEuler、ctyunos）中，为了区分特定的系统 ABI，其工具链目录被重命名（例如 aarch64-kylin-linux）。由于 CANN 编译器未在默认路径中找到对应的头文件，从而导致编译中断。
解决方案[object Object][object Object]
您需要手动将系统实际的 C++ 头文件路径添加到环境变量 CPLUS_INCLUDE_PATH 中，以指引编译器找到正确的文件。以 Kylin 系统（GCC 12）为例，请执行以下命令：
问题现象[object Object][object Object]
检索进程执行结束后，程序退出时报错，出现“segmentation fault”或者TBE报错等提示。
问题原因[object Object][object Object]
可能是由于用户的业务进程中，有别的组件使用了ACL资源并调用aclFinalize进行释放，从而导致ACL资源重复释放。
解决方案[object Object][object Object]
可以设置环境变量“MX_INDEX_FINALIZE”为0，则Index SDK不调用aclFinalize；设置为“1”表示仍调用aclFinalize。其他为无效设置。
用户需要确保进程退出时调用一次aclFinalize进行释放，否则仍可能在进程退出时出现错误。
问题现象[object Object][object Object]
执行查询操作，当查询的条数大于1000时，出现了性能波动。
问题原因[object Object][object Object]
Host侧CPU并发处理时，调度到非亲和性的CPU核上，导致耗时增加。
解决方案[object Object][object Object]
需对检索应用进行绑核操作，具体过程参考如下。
获取对应的NUMA node信息。如可以看到当前查询的NPU属于“NUMA node 0”。
图 1 获取NUMA node信息[object Object][object Object]
使用lscpu查看NUMA node 0上包含的CPU核信息，如所示，可以看到“NUMA node 0”所拥有的CPU核为“0-13,28-41”。
图 2 使用命令确认CPU核信息[object Object][object Object]
对当前的检索应用与确认完成的CPU进行绑核，命令参考如下。
[object Object]其中，mxIndexApp为待绑定的检索应用，请根据实际应用名称进行替换。
问题现象[object Object][object Object]
编译过程中，出现提示libascendfaiss.so not found。
问题原因[object Object][object Object]
未能通过环境变量中的路径找到“libascendfaiss.so”文件。
解决方案[object Object][object Object]
请确认“libascendfaiss.so”的路径（位于安装包host/lib下），并将其添加进“LD_LIBRARY_PATH”环境变量中。
在openEuler release 22.03 (LTS)系统中，通过系统默认的Cmake和gcc编译安装Faiss后，在链接“libfaiss.so”时，返回undefined reference错误。
问题原因[object Object][object Object]
openEuler release 22.03 (LTS)系统默认安装或使用yum工具安装的Cmake存在兼容性问题。
解决方案[object Object][object Object]
请访问组件官网，获取对应版本的Cmake源码，重新编译安装。
问题现象[object Object][object Object]
使用 AscendIndexIVFRaBitQ，[object Object]（nlist）设为 10048 或其他大于 2512 的值时，[object Object] 后 NPU search 的 recall@K 明显低于 CPU baseline；nlist ≤ 8192 的控制组可能正常。
问题原因[object Object][object Object]
常见根因包括：
- RotateAndL2AtFP32 算子 GEMM tiling 与多核分核不一致：coarse centroid 仅前约 2512 行（单 AIC core batch）被正确旋转写入 device，row ≥ 2512 为零，导致 IVF 粗排 probe 选择失效。
- L1 距离算子 8192 codes tile 边界问题：第二个及后续 tile 距离缺失 query norm 项。
- custom opp 未重新编译部署：修改 host tiling 或 kernel 后仍运行旧版算子。
解决方案[object Object][object Object]
聚类时，有些点到两个聚类中心的距离几乎相等，由于浮点数计算存在百万分之一的误差（faiss CPU版本详见：）， 会导致这些向量归属的聚类簇不确定，这种误差在多次迭代后得到放大，所以NPU聚类与CPU聚类的结果不完全一致，在与CPU对比一致性的时候，应统一使用cpu聚类。