/label add help-wanted

/label add good-first-issue

👋 您好，感谢向 IndexSDK 提交 Issue！
🎉 我们已收到您的反馈，感谢你对开源社区的支持！

📅 处理时效 维护团队将在工作日 24 小时内查看并回复您的问题。
🔍 自助排查（推荐优先查看） 在等待回复期间，您可以先查阅仓库README以及历史 Issue 中相似问题的解决方案，多数问题可快速解决。
💡 为了更快定位问题，请您确保 Issue 包含：

• 清晰的问题描述
• 可复现的操作步骤
• 相关日志、截图或环境信息
  我们会尽快跟进，感谢您的理解与配合！

/label add triaged

认领 IndexSDK#13

@yihao1234 @xiangjie10 我想搭建 Milvus + IndexSDK Flat NPU 加速验证环境，任务验收涉及真实 Ascend NPU 性能和用例验证，请问社区是否有可申请的测试机/算力环境？感谢～

认领这个任务

@yihao1234 老师您好，Ascend/IndexSDK#13 关联交付已按 GitCode 主线整理完成，麻烦协助验收。

本次任务目标是让 Milvus 能够基于 IndexSDK / Ascend NPU 加速 Flat 算法，并补齐代码、UT/ST、性能对比、接口资料、测试报告和 Dockerfile。考虑到任务实际涉及 IndexSDK、Faiss、Knowhere、Milvus 以及 issue 中给出的 mindsdk-referenceapps/IndexSDK/opensource/milvus25-ascend 承载目录，本次最终拆成 7 个关联 PR 提交。

1. 关联 PR

截至当前可见状态，7 个 PR 均为 open、可合入状态，CLA 均已通过，CI 标签均已通过。

2. Review 与问题闭环

本组 PR 已按机器人反馈做过多轮修复和复验。当前最新可见 AI review 情况如下：

• PR-A：多轮 AI review 后 P0/P1/P2 已清零，剩余 P3 为可维护性建议，不影响运行时行为。
• PR-B：最新 AI review 未发现需要报告的问题。
• PR-C1：多轮 AI review 后 P0/P1/P2 已清零，剩余 P3 为 helper 代码重复等可维护性建议。
• PR-C2：多轮 AI review 后 P0/P1/P2 已清零，剩余 P3 为变量可见性、错误信息表述等低风险建议。
• PR-C3：CLA/CI 已通过，作为服务级 ST patch carrier 提交。
• PR-C4：AI review 后 P0/P1/P2 为 0，剩余 P3 为性能 ST 小型代码质量建议。
• PR-C5：AI review 后 P0/P1/P2 为 0，剩余 P3 为 README 中一条复验命令口径建议。

如果验收要求希望 P3 也全部清零，我可以继续在同一组 PR 分支上补充修复；当前没有发现 P0/P1/P2 阻塞问题。

3. 使用与复验方式

推荐按 PR-C5 中更新后的 README 作为总入口复验：

https://gitcode.com/Ascend/mindsdk-referenceapps/merge_requests/976

整体顺序如下：

1. 合入或应用 PR-B 的 Faiss custom ops 修复，构建并安装 DistanceFlatL2 相关 custom ops。
2. 合入或应用 PR-A 的 IndexSDK ASCEND_FLAT strict rerank / verifier / 验证脚本改动。
3. 在 Knowhere v2.5.13 上应用 PR-C1 提供的 patch：

git am --whitespace=error knowhere-v2.5.13-ascend.patch

4. 在 Milvus v2.5.19 上按顺序应用 PR-C2、PR-C3、PR-C4 提供的 patch：

git apply --whitespace=error --index milvus-2.5.19-ascend-c2-build-index.patch
git apply --whitespace=error --index milvus-2.5.19-ascend-c3-service-st.patch
git apply --whitespace=error --index milvus-2.5.19-ascend-c4-performance-st.patch

5. 按 README 设置 Ascend / Faiss / mxIndex / CANN 相关环境变量，编译 Milvus，并启动 standalone。
6. 执行服务级 ST 和性能 ST：

MILVUS_ASCEND_ST=1 go test ./ascend/interface_test -run TestAscendFlatL2SelfRecall -count=1 -v
MILVUS_ASCEND_ST=1 go test ./ascend/perf_test -run TestAscendFlatServiceCPUOverNPUPerf -count=1 -v

4. 已覆盖的验收点

5. 关键验证结果

已完成的关键验证包括：

• PR-A strict baseline：BASE_exact_top1=62/64。
• PR-A 开启 optional exact rerank 后：RERANK_exact_top1=64/64。
• PR-A guard：duplicate id、remove 后复用 ID、reset 后复用 ID、fp16 add/search 边界均通过。
• PR-B：Faiss custom ops clean rebuild、DistanceFlatL2 单算子测试、package install 验证通过。
• Milvus indexbuilder：ASCEND_FLAT 最小功能验证 top1_hits=64/64、top10_contains_self=64/64。
• Milvus standalone E2E：collection 创建、插入、ASCEND_FLAT 建索引、load、search 均通过。
• CPU/NPU 性能：
  • Milvus indexbuilder search：CPU 106.684 ms，NPU 35.9084 ms，约 2.97x。
  • Milvus standalone search：CPU 543.575 ms，NPU 359.819 ms，约 1.51x。
  • Go warmup/repeats ST best search：CPU 39.179 ms，NPU 3.719 ms，约 10.53x。
  • PR-C4 已提供可复验的 CPU/NPU 性能对比 ST。

6. 边界说明

• 旧 strict baseline 是 BASE_exact_top1=62/64。
• 64/64 是开启 PR-A optional exact rerank 后的结果。
• 当前 HiDevLab 环境未完成容器内 NPU 映射运行验证，因此没有声明“容器内 NPU 已验证”。已检查到该环境虽可通过包管理器看到 docker.io、containerd、podman 等候选包，但当前会话本身运行在受限 Docker 容器内，没有宿主 Docker/containerd socket，且缺少 CAP_SYS_ADMIN、CAP_NET_ADMIN、CAP_SYS_MODULE，关键 cgroup 子目录不可写，无法可靠启动 Docker-in-Docker / rootless 容器完成 NPU 设备映射验证；Dockerfile 和具备容器运行时环境下的复验命令已提供。
• 性能结论限定在当前任务复验场景和 search 阶段，不泛化到所有规模、所有阶段。

麻烦老师根据以上 7 个 PR 和 PR-C5 README 的复验入口进行验收。如需要我继续补齐剩余 P3 或调整 PR 拆分/说明，我会继续在同一组 PR 上处理。

七个关联 PR 更新汇总

围绕 IndexSDK#13，七个现有 PR 按职责拆分如下。请沿用原 PR 的评审讨论和链接继续审阅：

建议复验顺序

主链为：B → C1 → C2 → C3 → C4 → C5。

• B 提供 Faiss DistanceFlatL2 custom ops 底座。
• C1 在 Knowhere v2.5.13 上提供 Ascend L2/IP 配置、I/O 和适配 patch。
• C2、C3、C4 在 Milvus v2.5.19 上按顺序应用，分别承接构建/索引参数、服务正确性和性能。
• C5 汇总唯一权威复验入口；旧单体 patch 仅作 legacy 资料，不与 C2-C4 并列使用。
• A 是独立候选集 L2 精确重排增强，不是主链前置；默认不接入 Milvus 主路径。

验证摘要

环境为单张 Ascend910B3、CANN 9.1.0-beta.3。

• A 当前线上 PR head 为 c07d3de330f839f9209fd436304c29c3c9b72119，parent 为 IndexSDK master e167bddba0ebba36958a82d0c65a7773a5358dfc，恰好 1 个提交；git diff --check 和 git merge-tree --write-tree origin/master candidate 通过，GitCode 主 CI、docs CI 和 CLA 已通过。本机 CMake、C++ 和 NPU GTest 均为 NOT_RUN，不把重放前记录写成该 head 已在本机重新执行。
• B clean custom-op build/package/install/installed-tree 有记录；真实设备 C++/Python 单算子均为 524288/524288，最大误差 0.25，平均误差 3.099442e-05。
• C1 构建、依赖、L2/IP 配置和 Ascend I/O 有记录；pristine Knowhere v2.5.13 apply/reverse/tree 对账一致。
• C2-C4 集成构建 RC 0；milvus、libmilvus_core.so、libknowhere.so 的 ldd -r 无缺库或未定义符号记录。
• C3 同一 standalone/NPU 会话记录：L2 43.920 ms，top1/top10 均 16/16；IP 620.419 ms，top1/top10 均 16/16。
• C4 参数为 nb=100000,nq=64,dim=128,topk=10,warmups=2,repeats=4；CPU raw [437.35849, 473.75171, 442.18976, 439.04052] ms，NPU raw [4.29234, 3.23801, 3.50436, 2.95982] ms；median 为 CPU 440.615 ms、NPU 3.371 ms，speedup 130.700374x，逐轮 recall 和 >1.0 门禁有记录。
• C2 clean-context linux/arm64 最终镜像 SHA-256 为 9649537da03356210c43344725062d0dc600c39e174a3f8a902987fc49e9548d。

明确边界

1. A 当前候选已完成当前 master 单提交重放及 git diff --check、git merge-tree 检查，但 CMake、C++ 和 NPU GTest 均为 NOT_RUN；A 的功能结果只表述候选集重排，不表述全库 exact 或 Milvus 主链结果。
2. C3 carrier 最后加入的 collection 异步清理加固只完成 Go 普通/race 编译，未重新执行真实设备服务级 ST；服务级数值来自该加固之前的有效修订。
3. .run 自解压打包入口因缺少 makeself 组件未完成；provider build/install、OM 和真实运行主链结果分开陈述。
4. 七个原 PR 已按上述当前 head、职责和 revision 更新，当前 head 的 GitCode 主 CI 均已通过；discussion 与人工复核状态以对应页面实时结果为准。本评论不声明已经合入或完成维护者验收。
5. 指标合同固定为 L2/IP，不宣称 COSINE 支持。

请在原有七个 PR 中继续审阅和提出意见；根据评审反馈更新同一 PR，不关单重开。

@chasefhb 老师您好，本次更新按 Issue #13 的五项任务要求补齐材料与验证证据，并根据PR检视意见进行了修改。

Issue 要求与交付材料对照

随 Issue 评论提交的材料

• design-document.md：七 PR 分层、设计边界、运行链、正确性不变量、性能方法和回滚。
• integration-contract.md：ASCEND_FLAT / ASCEND_FLAT_INT8 接入、类型、metric、参数校验和生命周期契约。
• user-manual.md：carrier 校验/应用顺序、构建、启动、SDK、C3/C4 复验、排障和回滚。
• test-report.md：UT/ST 矩阵、精度与性能原始样本、命令、结果和限制。
• self-validation-report.md：revision/环境/数据基线、要求对测试映射、负例、未执行项和提交方结论。
• review-briefing.zip：内含可离线打开的 review-briefing.html 评审简报（GitCode 附件接口不直接接受 .html）。

上述六份材料已随本评论上传。

评审整改更新

本轮按新增评审意见完成三项更新：

• A（!285，head 9c81eaced9ade2548cf54086185fcb5607293add）：私有参数改为 skipRerankCacheValidation，中英文文档补充 remove 后缓存失效以及 reset()/copyFrom() 恢复说明；910B3/CANN 9.1.0-beta.3 上 production 构建、守卫负例、严格链接和候选重排 GTest 18/18 通过。
• C1（!969，head 778e0937e8782e0e247aa5d327f546aaa4dc785c）：删除 Dataset/BruteForce score 旁路，恢复标准 L2/IP 分数语义；设备 mutex 改为自动所有权；异常格式化改为最大 1 MiB 的有界增长。仅在 DEFINED ENV{ASCEND_DEPEND_FAISS_DIR} 时添加 -U__ARM_FEATURE_SVE 并从 AArch64 UTILS_SVE_SRC 排除 distances_sve.cc，未设置时保留普通 AArch64 SVE 源。source 为 77d2f8592f2db3593e27e7f1ee7ed1c4aa3b7c0b，carrier SHA-256 为 9612003bb6f96b632f329a5fa90ec7c828cdb1ed6e01b01dfb3c0e5b967ae6f7。全新 replay 的 git apply --check --whitespace=error、应用后 tree 与 source HEAD 对账、910B3/CANN 9.1.0-beta.3 重新配置和增量构建、严格链接、config 14 assertions、[ascend] 4 cases/22 assertions 均通过。
• C5（!976，head 9831e3f4a9957b03d3ca3762cd59717b73c318ed）：显式 sha256sum --check 只列 C1-C4 四个权威文件，Linux 原样执行 4/4 OK，未使用 *.patch 或混入 legacy 单体 patch。

此前 5ef6f295 C1 与现有 C2-C4 重新链接后，C3 L2/IP top1/top10 均为 16/16；C4 CPU/NPU median 为 316.222/4.080 ms，speedup 77.505192x。完整脚本退出 0，端口与 NPU 进程清理完成。当前 77d2f859 只增加 CMake SVE 条件守卫，已完成 C1 层重新配置、增量构建、严格链接和聚焦 UT，未重复执行 C3/C4。

当前 API 回读 C1/C5 两个 PR 均为 open、mergeable=true，CLA 与主 CI 通过，stat/needs-squash 已清。维护者人工复审仍待完成。

精度与性能结果

• 算子数值层：B 的 DistanceFlatL2 真实设备 C++/Python 单算子验证均为 524288/524288，最大误差 0.25，平均误差 3.099442e-05。
• Milvus 服务正确性层：此前 5ef6f295 C1 与 C2-C4 重链后，同一 standalone/NPU 会话中 L2 与 IP 的 self top1、self top10 均为 16/16，即本固定 self-recall 样本上均为 100%。这是逐 query 硬断言，不是对通用数据集 recall 的外推；当前 SVE guard revision 未重复执行该服务 ST。
• CPU/NPU 对齐层：C4 在同一 Milvus standalone、同一数据规模中对 CPU FLAT 和 NPU ASCEND_FLAT 各自建索引/load/预热；正式四轮每轮均要求两侧 self top1/top10 达到 nq，任一轮不满足即失败。本轮逐轮 recall 门禁全部通过。
• 性能层：参数为 nb=100000,nq=64,dim=128,topk=10,warmups=2,repeats=4；CPU raw 为 [305.32205, 302.06484, 327.12187, 433.824] ms，NPU raw 为 [4.81435, 3.34567, 10.94094, 3.23787] ms；median 分别为 316.222 ms 和 4.080 ms，CPU median / NPU median = 77.505192x。样本有限性、偶数 repeats、逐轮正确性与 speedup > 1.0 硬门禁均通过。

请继续检视，谢谢。