常用操作
日志说明
检索日志组件基于《CANN 软件安装》以及《CANN 日志参考》设计和开发。
对于标准态部署，检索的日志属于应用类日志，可以参考《CANN 日志参考》中的“查看日志（Ascend EP标准形态）”章节的“查看应用类日志”描述。默认路径为“$HOME/ascend/log”。也可以使用环境变量ASCEND_PROCESS_LOG_PATH指定日志落盘路径。命令参考如下：
export ASCEND_PROCESS_LOG_PATH=$HOME/xxx
可指定日志落盘路径为任意有读写权限的目录。
日志级别由低到高依次为DEBUG < INFO < WARNING < ERROR，级别越低，输出日志越详细，可以通过ASCEND_GLOBAL_LOG_LEVEL环境变量设置日志级别。命令参考如下：
export ASCEND_GLOBAL_LOG_LEVEL=1
不传入此参数，默认为ERROR等级。ASCEND_GLOBAL_LOG_LEVEL 全部取值说明如下：
0：DEBUG
1：INFO
2：WARNING
3：ERROR
4：NULL，NULL级别。不输出日志。
Note
- 对于容器化场景中使用检索功能，应用类日志位于容器中，需要将日志目录挂载到宿主机才能实现持久化，否则日志将在容器退出时被销毁。
- 应用类日志未配置自动轮转，日志会不断增多，因此需要用户定期清理该目录（可以使用系统自带的logrotate实现日志切分），否则可能导致磁盘空间不足，影响业务正常运行。
- 软件包的安装升级卸载等管理面的相关日志会保存至“$HOME/log/mxIndex/deployment.log”，文件中保存有登录用户的用户名、访问端地址以及 hostname，用于支持后续的日志记录及审计的操作。
IVFRaBitQ 运行时诊断
AscendIndexIVFRaBitQ 提供三组可选调试环境变量，用于排查coarse centroid（聚类中心）NPU上传异常与L1粗排probe选择偏差。默认全部关闭，对生产路径零开销；仅在开发/联调环境按需开启。
Note
- 环境变量在进程启动时读取，需在运行应用程序或测试用例之前export。
- 诊断日志输出至 stderr 及 APP 日志（
IVFRABITQ_VERIFY_COARSE_CENTER）；建议重定向到.log文件便于 grep。 IVFRABITQ_VERIFY_L1_DIST与L1 golden对比会触发全量D2H，不要在性能基准测试中常开。- 修改
RotateAndL2AtFP32算子后须重新编译部署custom opp，否则诊断结果可能仍反映旧版算子行为。
环境变量说明
表 1 IVFRaBitQ 调试环境变量
| 环境变量名 | 取值 | 触发时机 | 用途 |
|---|---|---|---|
| IVFRABITQ_VERIFY_COARSE_CENTER | 非空且非 0 |
copyFrom / 训练后更新 centroid（updateCoarseCenterImpl） |
分阶段 D2H 校验：区分 H2D Memcpy 失败 vs rotate 算子输出不完整 |
| IVFRABITQ_DEBUG_L1_PROBE | 1 / stats / full |
每次 search 的 L1 阶段 |
观察 probe 是否仅落在 [0,8192) 而忽略后半段 list |
| IVFRABITQ_VERIFY_L1_DIST | 非空且非 0 |
每次 search 的 L1 阶段 |
CPU golden vs NPU L1 距离及 probe 一致性对比 |
关闭方式：
unset IVFRABITQ_VERIFY_COARSE_CENTER IVFRABITQ_DEBUG_L1_PROBE IVFRABITQ_VERIFY_L1_DIST
# 或设为 0
export IVFRABITQ_VERIFY_COARSE_CENTER=0
诊断决策流程
- recall 低且发生在
copyFrom之后 → 开启IVFRABITQ_VERIFY_COARSE_CENTER=1，重跑copyFrom。 - 查看
centroidsOnDevice_rotated_full日志中的zeroRowsAfter2512：- H2D后originCentroidsOnDevice与host一致，但
zeroRowsAfter2512 > 0→ 故障在RotateAndL2AtFP32算子。 - H2D 即 mismatch → 排查Memcpy参数或buffer容量。
- H2D后originCentroidsOnDevice与host一致，但
- centroid 已确认正常，recall仍低 → 开启
IVFRABITQ_DEBUG_L1_PROBE=stats，检查probe在tile1/tile2的分布。 - 需对比8192边界L1距离 → 开启
IVFRABITQ_VERIFY_L1_DIST=1或IVFRABITQ_DEBUG_L1_PROBE=full。
Coarse Center 上传诊断
export IVFRABITQ_VERIFY_COARSE_CENTER=1
# 边界测试（copyFrom 触发 updateCoarseCenterImpl）
./TestAscendIndexIVFRaBitQBoundary --gtest_filter="*CoarseCenterCopy10048*" 2>&1 | tee coarse_verify.log
grep -E 'CoarseCenterVerify|zeroRowsAfter2512' coarse_verify.log
修复后期望日志：
[CoarseCenterVerify] originCentroidsOnDevice: row 2512 OK vs host (devNorm=...)
[CoarseCenterVerify] centroidsOnDevice_rotated_full full: mismatchRows=0 zeroRowsBefore2512=0 zeroRowsAfter2512=0 / 7536
修复前典型异常（nlist=10048）：
[CoarseCenterVerify] centroidsOnDevice_rotated: row 2512 is all-zero on device (devNorm=0.000000)
[CoarseCenterVerify] centroidsOnDevice_rotated_full full: zeroRowsAfter2512=7536 / 7536
关键判定：2512 = 10048 / 4，为四核 AIC 均匀分核时单核 batch 大小；row 2512 是首个“非 core 0”边界行。
L1 Probe 分布诊断
# 打印 q0 前 8 个 probe id
export IVFRABITQ_DEBUG_L1_PROBE=1
# 仅统计 probe 在 [0,8192) 与 [8192,nlist) 的分布（推荐，开销小）
export IVFRABITQ_DEBUG_L1_PROBE=stats
# probe 列表 + CPU golden 对比 + 分布统计（开销最大）
export IVFRABITQ_DEBUG_L1_PROBE=full
stats 模式示例：
[IVFRaBitQ] L1 probe stats q0: nprobe=1024 in[0,8192)=1024 in[8192,10048)=0 min=3 max=8191
异常信号：in[8192,nlist)=0 且 nlist > 8192，说明 probe 未覆盖后半段 list，常与 centroid device 零行或 L1 距离算子异常相关。
L1 距离 Golden 对比
export IVFRABITQ_VERIFY_L1_DIST=1
# 运行 search 场景
grep 'L1 dist golden\|jaccard' search.log
边界 id 距离（抽样 8191/8192/8193 及尾部行）：
[IVFRaBitQ] L1 dist golden id=8192 cpu=15.678901 npu=15.678902 absErr=0.000001
Probe overlap：
[IVFRaBitQ] L1 probe overlap q0: nprobe=1024 overlap=980 jaccard=0.957 cpu_tile2=128
| 字段 | 含义 | 健康参考 |
|---|---|---|
| overlap | CPU top-nprobe 与 NPU probe 交集 | 接近 nprobe |
| jaccard | overlap / nprobe | > 0.95 |
| cpu_tile2 | CPU golden probe 落在 [8192,nlist) 的数量 |
若 NPU tile2=0 而 cpu_tile2>0，说明 NPU 遗漏后半段 |
推荐组合
| 场景 | export 组合 |
|---|---|
| 验证 copyFrom 上传 | IVFRABITQ_VERIFY_COARSE_CENTER=1 |
| centroid 正常，排查 L1 | IVFRABITQ_DEBUG_L1_PROBE=stats |
| 8192 边界 L1 距离 | IVFRABITQ_VERIFY_L1_DIST=1 |
| 一次性完整 dump | IVFRABITQ_DEBUG_L1_PROBE=full |
延伸阅读
Device 内存调试
AscendFaiss 提供两组可选环境变量，用于排查 Device HBM 分配失败、索引上传/扩容过程中的显存占用变化。默认全部关闭，对生产路径零开销；仅在开发/联调环境按需开启。环境变量一览见《附录》。
Note
- 环境变量在进程首次查询时读取并缓存，需在运行应用程序或测试用例之前 export。
- 调试日志输出至 stderr，并同步写入 APP 日志（
[MemDebug]前缀）；建议重定向到.log文件便于 grep。 - 开启后会查询
aclrtGetMemInfo(ACL_HBM_MEM)并抽样打印，不要在性能基准测试中常开。
环境变量说明
表 2 Device 内存调试环境变量
| 环境变量名 | 取值 | 默认 | 用途 |
|---|---|---|---|
| ASCENDFAISS_MEM_DEBUG | 非空且非 0 / false / off（大小写不敏感） |
关闭 | 总开关：开启分配抽样、HBM 余量打印；aclrtMalloc 失败时 dump 最近分配环形缓冲 |
| ASCENDFAISS_MEM_DEBUG_EVERY | 正整数 N | 64 |
抽样周期：分配序号满足 seq % N == 0，或 size ≤ 4096 时打印明细；未设置/非法/0 时回退为 64 |
关闭方式：
unset ASCENDFAISS_MEM_DEBUG ASCENDFAISS_MEM_DEBUG_EVERY
# 或
export ASCENDFAISS_MEM_DEBUG=0
使用示例
# 开启内存调试（默认每 64 次分配抽样一次）
export ASCENDFAISS_MEM_DEBUG=1
# 提高采样密度（每 8 次分配打印一次）
export ASCENDFAISS_MEM_DEBUG=1
export ASCENDFAISS_MEM_DEBUG_EVERY=8
# 运行业务或 UT，并保存日志
./your_app 2>&1 | tee mem_debug.log
grep '\[MemDebug\]' mem_debug.log
日志解读
| 日志关键字 | 含义 |
|---|---|
[MemDebug] alloc seq=... |
一次 Device 分配的抽样记录：序号、size、space、device、分配前 HBM free/total |
[MemDebug] ... HBM free=... |
关键路径上的 HBM 余量快照（如 copyVectorToDevice_*、DeviceMemArena::Grow、IndexIVFRaBitQ_resize） |
[MemDebug] aclrtMalloc FAILED ... |
分配失败：当前请求 size/space/device、错误码、当时 HBM free/total |
dumping last N alloc records |
失败前最近最多 64 条分配记录（oldest→newest），用于定位耗尽显存的连续分配 |
典型排查流程：
- 复现 OOM /
aclrtMalloc失败场景前设置ASCENDFAISS_MEM_DEBUG=1。 - 在失败日志中查看
HBM_free是否已接近 0，以及size/space（DEVICE或DEVICE_HUGEPAGE）。 - 根据 dump 的最近分配记录，对照业务阶段（索引上传、list resize、arena grow）缩小泄漏或峰值分配点。
- 需要更密采样时增大频率：
export ASCENDFAISS_MEM_DEBUG_EVERY=1（每笔分配都打印，日志量很大）。