Skip to content

ODINANN_CHECKLIST.md

Latest commit

 

History

History
executable file
·
283 lines (207 loc) · 7.01 KB

ODINANN_CHECKLIST.md

File metadata and controls

executable file
·
283 lines (207 loc) · 7.01 KB

OdinANN 集成 - 快速参考清单

✅ 已完成

1. 核心代码文件（3个）

  • odinann_config.h (z:\knowhere\src\index\odinann\odinann_config.h)

    • 定义 OdinANNConfig 配置类
    • 参数包括：max_degree, search_list_size, pq_code_budget_gb 等
    • 实现 CheckAndAdjust 参数验证

  • OdinANN.h (z:\knowhere\include\knowhere\feder\OdinANN.h)

    • 定义 OdinANNBuildConfig, OdinANNMeta 结构体
    • 定义 OdinANNVisitInfo 等可观测性结构
    • Namespace: knowhere::feder::odinann

  • odinann.cc (z:\knowhere\src\index\odinann\odinann.cc)

    • 实现 OdinANNIndexNode 模板类
    • 实现 Build()、Deserialize()、GetIndexMeta()
    • 集成 FileManager 用于文件管理
    • 待完成：Search()、GetVectorByIds()

2. 文档和改造方案

  • ODINANN_BUILD_INTERFACE_REFACTORING.h

    • 分析当前 OdinANN API 的问题
    • 提出三阶段改造方案
    • 给出使用示例

  • ODINANN_IMPLEMENTATION_DETAILS.h

    • 完整的代码实现片段
    • 适用于 thirdparty/OdinANN 的改造
    • 包括 CMakeLists.txt 配置建议

  • ODINANN_INTEGRATION_GUIDE.md

    • 完整的集成指南
    • 详细的步骤说明
    • 常见问题解答

⏳ 待完成

1. thirdparty/OdinANN 改造

文件：thirdparty/OdinANN/include/aux_utils.h 和 src/aux_utils.cpp

任务：

□ 添加 DiskIndexBuildConfig 结构体 (参考 ODINANN_IMPLEMENTATION_DETAILS.h)
□ 添加 BuildResult 结构体
□ 实现 build_disk_index_from_config() 函数
□ 实现 build_disk_index_with_result() 函数
□ 保持向后兼容（保留旧 API）

预计代码量：~200 行

2. odinann.cc 完成

文件：z:\knowhere\src\index\odinann\odinann.cc

任务：

□ 实现 Search() 方法
  - 参考：DiskANNIndexNode<DataType>::Search() 
  - 需要：OdinANN 的查询接口理解
  
□ 实现 GetVectorByIds() 方法
  - 参考：DiskANNIndexNode<DataType>::GetVectorByIds()
  - 需要：通过 ID 访问向量的接口
  
□ 实现 Size() 方法
  - 返回索引大小（字节数）

预计代码量：~300-400 行

3. 单元测试

文件：z:\knowhere\tests\ut\test_odinann.cc

任务：

□ 创建测试文件
□ 编写 Build 单元测试
□ 编写 Deserialize 单元测试  
□ 编写 Search 单元测试
□ 编写参数验证测试
□ 编写并发安全测试

参考：test_diskann.cc 中的模式

预计代码量：~500-800 行

4. CMake 配置

文件：z:\knowhere\CMakeLists.txt

任务：

□ 添加 OdinANN 子模块编译配置
□ 链接 thirdparty/OdinANN 库
□ 配置包含路径
□ 设置编译标志（如 C++17）

5. 集成测试

任务：

□ 验证 Build 流程
□ 验证 FileManager 集成（文件上传到 Minio）
□ 验证 Deserialize 和 Search 流程
□ 性能基准测试
□ 与 DiskANN 性能对比

📋 关键配置参数对照表

OdinANN API 参数 OdinANNConfig 含义
R max_degree 图的最大度数
L search_list_size 搜索列表大小
M (不使用) DiskANN 特定
PQ_bytes disk_pq_dims PQ 压缩维度
(新增) build_dram_budget_gb 构建内存预算
(新增) accelerate_build 快速构建模式

🔧 快速命令参考

编译 Knowhere（启用 OdinANN）

cd z:\knowhere
mkdir build && cd build
cmake .. -DWITH_ODINANN=ON
make -j8

运行单元测试

cd z:\knowhere\build
ctest -R odinann -V

查看关键文件

# 配置定义
cat z:\knowhere\src\index\odinann\odinann_config.h

# 核心实现
cat z:\knowhere\src\index\odinann\odinann.cc

# 改造指南
cat z:\knowhere\docs\ODINANN_IMPLEMENTATION_DETAILS.h

📊 代码量估计

组件 已完成行数 待完成行数 总计
odinann_config.h 150 0 150
odinann.h (Feder) 80 0 80
odinann.cc 250 400 650
thirdparty/OdinANN 改造 0 200 200
单元测试 0 700 700
文档 400 0 400
合计 880 1,300 2,180

🎯 优先级建议

必做（P0）

  1. ✅ 实现三个核心代码文件
  2. ❌ 改造 thirdparty/OdinANN API
  3. ❌ 完成 Search() 和 GetVectorByIds()
  4. ❌ 编写基础单元测试

推荐（P1）

  1. ❌ 性能基准测试
  2. ❌ 与 DiskANN 对比测试
  3. ❌ Minio 集成验证

可选（P2）

  1. ❌ 支持更多距离度量
  2. ❌ 增量更新支持
  3. ❌ GPU 加速

📝 注意事项

编译注意

// odinann.cc 中需要链接 OdinANN 库
#include "aux_utils.h"  // pipeann::build_disk_index_py

// CMakeLists.txt 中配置
target_link_libraries(knowhere_odinann pipeann_lib)

文件管理注意

// Build() 后，需要注册所有生成的文件
// 单文件模式：{prefix}.odinann
// 多文件模式：{prefix}_mem.index, {prefix}_disk.index 等

// 确保调用 AddFile() 将文件添加到 FileManager
for (auto& filename : index_files) {
    if (!AddFile(filename)) {
        return Status::disk_file_error;  // 重要！
    }
}

并发安全注意

// Build() 和 Deserialize() 都使用 preparation_lock_
std::lock_guard<std::mutex> lock(preparation_lock_);
// 确保同一实例的操作互斥

// 不同实例需要确保 index_prefix 不同，否则会相互覆盖

🔗 参考资源

  • DiskANN 实现参考：z:\knowhere\src\index\diskann\diskann.cc
  • Config 框架参考：z:\knowhere\include\knowhere\config.h
  • OdinANN 源码：z:\knowhere\thirdparty\OdinANN\include\index.h
  • 测试模板参考：z:\knowhere\tests\ut\test_diskann.cc

💡 常见问题速答

Q: 为什么要改造 OdinANN 的 API？ A: 当前 API 参数名不清晰（R、L、M），无法返回详细结果。改造后更易维护和扩展。

Q: Search() 为什么还没实现？ A: 需要深入理解 OdinANN 的查询接口。建议先完成 Build/Deserialize 验证框架。

Q: 如何测试 FileManager 集成？ A: 在 Build() 后检查 FileManager 是否成功添加了所有文件，以及是否能上传到 Minio。

Q: 是否支持多个 Segment 并行 Build？ A: 支持，只要每个 Segment 使用不同的 index_prefix 即可。

✨ 下一步建议

  1. 立即执行：

    • 应用 thirdparty/OdinANN 改造方案
    • 完成 odinann.cc 的 Search() 实现
    • 编写 3-5 个核心单元测试

  2. 1 周内：

    • 所有单元测试通过
    • FileManager 集成验证
    • 基础性能测试

  3. 2 周内：

    • 与 DiskANN 性能对标
    • 文档完善
    • 准备上线

生成时间：2025-12-02 状态：核心代码完成，等待 thirdparty/OdinANN 改造和测试