如果你最近在关注 AI 应用落地大概率绕不开一个词向量检索。从语义搜索、相似图片匹配到 RAG 知识库召回背后几乎都有一个向量搜索引擎在支撑。但很多人第一次接触向量检索都从 Python 生态开始比如faiss、milvus、qdrant的 Python 客户端。用起来确实舒服可一旦数据量上来、延迟要求变苛刻你就会发现瓶颈往往不在算法而在工程侧的底层实现。这里我想聊一个很有意思的开源项目Gram一个用 C 从零构建的向量搜索引擎。它出现在 Hacker News 的 Show HN 上作者直接把它定义为“vector search engine built in C”。这类项目的价值不完全在于它比 FAISS 强多少而在于它展示了向量搜索引擎的核心路径从数据预处理、索引构建到在线检索完全可以用 C 高效实现不依赖重型框架也能跑起来。这篇文章不打算只做项目介绍而是把它拆开来看向量搜索引擎要解决什么问题C 实现的核心优势在哪里如何理解索引、召回、重排这些关键概念以及如果你想自己动手做一个类似的 C 向量检索工具应该从哪几步开始。文章后面还会给出一套可运行的最小实现思路包含完整的 CMake 配置和 C 代码示例方便你直接验证整个流程。1. 向量搜索引擎为什么值得用 C 重写先明确一个判断向量搜索引擎的核心竞争力不是“能检索”而是“快、省、稳”。这三个字几乎由底层语言决定。如果用 Python 写原型几百毫秒的查询时间完全能接受因为脚本语言的数据结构和开发效率确实高。但生产环境往往要面对几百万甚至上亿条向量一条查询要求几十毫秒内返回还给不出算力无限膨胀的预算。这种时候指针、连续内存、无 GC 暂停、手动控制 SIMD 指令就成了实实在在的优势。C 在这类场景重写一次的价值体现在几个层面内存可控向量数据本质上是连续数组用std::vectorfloat或裸指针管理内存比 Python 对象开销小几个数量级。无 GC 停顿向量检索通常是超高 QPS 的在线服务Java 或 Go 的 GC 偶尔停顿还能忍但检索延迟要求极低时C 的无暂停模型更省心。精细控制并发多线程、无锁队列、内存池这些底层能力可以直接作用在索引结构和查询路径上。便于嵌入其他系统C 写的检索引擎可以编译成动态库被 Python、Java、Go 通过 FFI 调用也可以作为独立服务。所以 Gram 这个项目的意义不只是“又一个向量检索库”而是给你展示了一条完整的 C 技术路线。如果你准备做自己的向量检索组件或者想在 RAG 系统中降低检索延迟这类项目是最好的参考起点。当然C 重写也有代价开发效率低、构建系统复杂、线程安全问题容易踩坑。但工程上常说没有银弹只有取舍。像 Gram 这种聚焦向量搜索的 C 项目本质上是用开发复杂度换取运行效率和部署自由度。2. Gram 的定位与向量检索的核心概念在看具体代码前先理清几个概念。很多人会把“向量搜索”和“数据库查询”搞混。传统数据库查的是等值或范围条件比如where name 张三向量搜索查的是“最相似的 TopK”输入是一个向量输出是距离最近的若干条记录。2.1 什么是向量化向量化是指把文本、图片、音频等内容用模型转换成一串浮点数。比如一句话经过 embedding 模型后变成一个 768 维或 1024 维的向量。语义相近的内容在向量空间里的距离也近。这是语义搜索不同于关键词搜索的根本原因它能解决“同义不同词”的检索问题。2.2 什么是 ANN 近似最近邻精确最近邻意味着每次查询都要和库里所有向量计算距离复杂度 O(N)。当 N 达到千万级这个成本完全不可接受。所以工业级向量搜索引擎通常采用 ANN近似最近邻算法牺牲少量召回精度换取数量级上的查询性能提升。常见算法有 HNSW、IVF、PQ 等。HNSW 是目前最流行的一种基于多层跳表思想构建图结构查询时分层次逼近目标节点。IVF 则先对向量聚类再只搜索距离最近的几个聚类桶。Gram 这类 C 项目一般会优先选其中一种做核心索引结构。2.3 Gram 在技术栈中的位置从项目标题看Gram 是一个 C 实现的搜索引擎目标很明确用较低的资源占用提供向量索引和相似度检索能力。它走的是“嵌入式检索引擎”路线和 FAISS 类似而不是像 Milvus 那样把检索、存储、分布式调度都包进来。这意味着它更适合以下场景单机内存能放下的数据量级。需要低延迟、高吞吐的在线检索服务。希望把检索能力以动态库形式嵌入到现有 C 服务中。学习向量索引实现原理的练手项目。如果你的需求是几十亿向量、多副本、水平扩容那直接上分布式数据库更合适。Gram 这类项目解决的是“单机极致性能”的问题。3. 环境准备与工程搭建在开始写代码之前先把环境准备好。下面这套环境适配 C17 及以上重点演示向量检索的通用实现思路不依赖任何第三方权重或专用硬件。3.1 编译工具链操作系统Linux 或 macOS 均可Windows 可以用 WSL 或 MSVC。编译器GCC 9 或 Clang 10需要支持 C17。构建工具CMake 3.14 以上。可选依赖OpenMP用于多线程并行计算距离。检查版本的命令g --version cmake --version如果还没有安装Linux 上可以用包管理器安装sudo apt update sudo apt install -y build-essential cmake libomp-devmacOS 上可以用 Homebrewbrew install cmake gcc libomp这里要提醒一个常见问题g和cmake的版本不要相差太大尤其是老系统自带的 CMake 可能太旧导致无法识别CXX_STANDARD 17。遇到这类问题优先升级 CMake。3.2 项目目录结构我建议用一个干净的目录组织代码后续扩展也比较方便gram_demo/ ├── CMakeLists.txt ├── src/ │ ├── vector_index.h │ ├── vector_index.cpp │ └── main.cpp ├── data/ │ └── vectors.csv └── build/build目录专门存放编译产物不要和源码混在一起。4. 核心流程拆解一个向量搜索引擎最核心的流程可以拆成四步数据预处理、向量化、索引构建、查询召回。这里我不把“向量化”框死在某个模型上因为它可以是文本 embedding、图像特征甚至是你手工构造的特征向量。关键是理解后面的链路。4.1 数据预处理原始数据通常不是向量。比如一堆商品描述、图片路径、用户行为序列。第一步是把它们转换成统一维度的浮点数组同时保留原始 ID。预处理环节最容易出错的是维度不一致和缺失值。一个维度错位后续所有距离计算都会失真。4.2 向量化向量化大多依赖模型推理。Gram 这类 C 项目通常不做模型推理而是接收已经生成的向量。所以实践中常见做法是用 Python 的 embedding 模型批量生成向量导出成二进制文件或 CSV再交给 C 端加载。好处是职责清晰模型升级不会影响索引代码。如果你需要 C 端也能推理可以考虑接入 ONNX Runtime 或 TensorRT但这会显著增加项目复杂度。最小实现里直接用文件加载即可。4.3 索引构建索引构建就是把这些向量组织成合适的数据结构。最简单的实现是暴力线性扫描所有向量放在一个连续数组里查询时逐个计算距离。数据量小的时候这个方案反而最准确、最容易写对。更进阶的是 HNSW 图索引。构建时要为每个新插入的向量找到它在图上的邻居并双向连接。这个过程有大量随机内存访问C 做起来反而有优势因为可以直接操作指针和预分配内存。4.4 查询召回与重排查询时输入向量与索引中的候选集计算距离得到 TopK 结果。这一步包含两个关键操作相似度度量常用余弦相似度、欧氏距离、内积。如果向量已经归一化三者可以互相转换。TopK 排序维护一个大小为 K 的最大堆保证只保留最优的 K 个候选。工程上还会加一步“重排”即先用 ANN 粗召回再用更精确的距离计算重新排序。这一步在 RAG 场景里尤其重要因为粗召回结果可能混入语义不够精准的噪声。5. 一个最小 C 向量检索引擎实现示例下面给出一个可以编译运行的最小示例。它实现了加载向量、余弦相似度计算、暴力 TopK 检索三个核心能力。代码中没有引入任何第三方库方便你理解底层逻辑。5.1 CMake 配置# 文件路径gram_demo/CMakeLists.txt cmake_minimum_required(VERSION 3.14) project(gram_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) if(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Release) endif() add_executable(gram_demo src/main.cpp src/vector_index.cpp ) target_include_directories(gram_demo PRIVATE src) # 可选开启 OpenMP 加速 find_package(OpenMP QUIET) if(OpenMP_CXX_FOUND) target_link_libraries(gram_demo PRIVATE OpenMP::OpenMP_CXX) message(STATUS OpenMP enabled) else() message(STATUS OpenMP not found, use single thread) endif()5.2 头文件定义// 文件路径gram_demo/src/vector_index.h #pragma once #include cstdint #include string #include vector struct Doc { uint64_t id 0; std::vectorfloat vec; }; class VectorIndex { public: void add(uint64_t id, const std::vectorfloat vec); // 返回 TopK 结果的 (id, 相似度) 列表按相似度从高到低排序 std::vectorstd::pairuint64_t, float search( const std::vectorfloat query, size_t top_k) const; size_t size() const { return docs_.size(); } size_t dim() const { return dim_; } private: std::vectorDoc docs_; size_t dim_ 0; };5.3 核心实现// 文件路径gram_demo/src/vector_index.cpp #include vector_index.h #include algorithm #include cmath namespace { float cosine_similarity(const std::vectorfloat a, const std::vectorfloat b) { float dot 0.0f; float norm_a 0.0f; float norm_b 0.0f; for (size_t i 0; i a.size(); i) { dot a[i] * b[i]; norm_a a[i] * a[i]; norm_b b[i] * b[i]; } if (norm_a 0.0f || norm_b 0.0f) { return 0.0f; } return dot / (std::sqrt(norm_a) * std::sqrt(norm_b)); } } // namespace void VectorIndex::add(uint64_t id, const std::vectorfloat vec) { if (dim_ 0) { dim_ vec.size(); } if (vec.size() ! dim_) { throw std::runtime_error(dimension mismatch); } docs_.push_back({id, vec}); } std::vectorstd::pairuint64_t, float VectorIndex::search( const std::vectorfloat query, size_t top_k) const { // 最小堆堆顶是当前候选集中相似度最小的元素 // 这样当堆满时只有相似度更大的新结果才能替换堆顶 using Item std::pairfloat, uint64_t; std::priority_queueItem, std::vectorItem, std::greaterItem min_heap; for (const auto doc : docs_) { float sim cosine_similarity(query, doc.vec); if (min_heap.size() top_k) { min_heap.push({sim, doc.id}); } else if (sim min_heap.top().first) { min_heap.pop(); min_heap.push({sim, doc.id}); } } std::vectorstd::pairuint64_t, float result; result.reserve(min_heap.size()); while (!min_heap.empty()) { result.emplace_back(min_heap.top().second, min_heap.top().first); min_heap.pop(); } std::reverse(result.begin(), result.end()); return result; }这里有一个值得展开的技术点为什么用std::priority_queue而不是std::sort因为 TopK 只需要维持 K 个候选用堆可以把时间复杂度控制在 O(N log K)。当 K 远小于 N 时比整表排序高效得多。如果你的数据量在一万以下直接用std::sort反而代码更简单但一旦数据量涨到百万级堆的优势会非常明显。5.4 主程序示例// 文件路径gram_demo/src/main.cpp #include vector_index.h #include fstream #include iostream #include sstream std::vectorstd::vectorfloat load_vectors(const std::string path, size_t dim) { std::vectorstd::vectorfloat data; std::ifstream fin(path); if (!fin.is_open()) { throw std::runtime_error(cannot open file: path); } std::string line; while (std::getline(fin, line)) { std::stringstream ss(line); std::vectorfloat vec; vec.reserve(dim); std::string token; while (std::getline(ss, token, ,)) { vec.push_back(std::stof(token)); } if (vec.size() ! dim) { std::cerr line dimension mismatch: vec.size() ! dim std::endl; continue; } data.push_back(std::move(vec)); } return data; } int main(int argc, char** argv) { if (argc 3) { std::cerr usage: argv[0] vector_file dim std::endl; return 1; } const std::string path argv[1]; const size_t dim static_castsize_t(std::stoul(argv[2])); auto vectors load_vectors(path, dim); if (vectors.empty()) { std::cerr no valid vectors loaded std::endl; return 1; } VectorIndex index; for (size_t i 0; i vectors.size(); i) { index.add(static_castuint64_t(i), vectors[i]); } std::cout index size: index.size() , dim: index.dim() std::endl; // 用第一条向量作为查询测试检索 const auto query vectors[0]; auto result index.search(query, 5); std::cout Top5 results for vec[0]: std::endl; for (const auto [id, sim] : result) { std::cout id id , sim sim std::endl; } return 0; }这个主程序做了三件事加载向量文件、构建索引、执行一次 Top5 查询。查询用第一条向量作为输入正常情况下第一个结果应该就是它自己相似度接近 1.0。5.5 生成测试数据为了方便测试可以用 Python 生成一份随机向量数据# 文件路径gram_demo/scripts/gen_data.py import random random.seed(42) dim 64 num 2000 with open(data/vectors.csv, w, encodingutf-8) as f: for _ in range(num): vec [round(random.gauss(0, 1), 6) for _ in range(dim)] f.write(,.join(map(str, vec)) \n) print(fgenerated {num} vectors, dim{dim})运行方式mkdir -p data python3 scripts/gen_data.py生成的不是稀疏向量而是 64 维稠密浮点向量足以验证检索流程。5.6 编译与运行mkdir -p build cd build cmake .. make -j$(nproc) ./gram_demo ../data/vectors.csv 64预期会看到类似下面的输出index size: 2000, dim: 64 Top5 results for vec[0]: id0, sim1 id1073, sim0.338647 id785, sim0.330043 id551, sim0.32818 id1797, sim0.317074id0, sim1表示第一条查询向量和自己完全匹配。后面的相似度都很低说明随机向量之间没有明显的语义关系。这正好验证了索引和距离计算逻辑是对的。6. 运行结果与效果验证跑通示例只是第一步。真正的工程验证需要从“能跑”升级到“结果可信”。下面给出几个验证维度。6.1 相似度计算的正确性最简单的方法是在已有数据集里人为构造一个特殊向量。比如取出第 0 条向量把它精确复制一份并赋予新 ID插入索引后查询原向量。如果引擎结果里这个 ID 排在第一位说明检索逻辑没问题。// 伪代码验证精确匹配结果 uint64_t new_id index.size(); index.add(new_id, vectors[0]); // 复制第一个向量 auto result index.search(vectors[0], 3); // 预期result[0].id new_id6.2 召回指标暴力线性扫描的召回率是 100%因为它计算了所有向量。它被当作基准用来衡量 ANN 索引的召回率RecallK 命中真实TopK的数量 / K。如果你想从暴力扫描换成 HNSW不要直接上线先跑一组召回测试确认损失在可接受范围。6.3 延迟和吞吐在 Release 模式下编译然后用几千条查询跑一遍统计平均延迟和 P99 延迟。C 项目如果不开编译优化性能可能比预期差好几倍。记得在 CMake 里设置Release构建类型并用-O3优化。一个常见的误判是只看 QPS不看单次延迟分布。向量检索场景里P99 对用户体验影响更大。建议压测脚本里同时输出平均值、P95 和 P99。7. 常见问题与排查方法从实际经验看这类 C 项目最常踩的坑集中在构建、数据、性能三方面。问题现象可能原因排查方式解决方案CMake 提示不支持 C17系统自带 CMake 版本过旧cmake --version升级 CMake 到 3.14或改用源码安装编译报链接错误undefined reference to omp_*手动开了 OpenMP 但链接阶段没加库检查 CMake 中 OpenMP 的链接配置加载OpenMP::OpenMP_CXX或删除#pragma omp相关代码加载向量时读取行数少了很多数据文件存在空行或维度不一致统计原始文件行数和异常行预处理时过滤空行打印维度不一致的样本检索结果相似度全是 0向量包含全 0 数据余弦公式分母为 0打印范数统计检查向量归一化步骤在加载或查询时过滤无效向量或改用内积距离查询速度很慢编译时用了 Debug 模式查看 CMakeCache 中CMAKE_BUILD_TYPE重新用-DCMAKE_BUILD_TYPERelease构建结果里出现重复 ID插入数据时 ID 没有去重检查 add 逻辑是否允许重复 ID在插入前用unordered_set去重或设计唯一主键这些坑单独看都不复杂但混在一起会消耗大量排查时间。建议调试时先打印index.size()和几条向量的范数确认数据层面没有大问题再去查构建配置。8. 工程落地建议与性能优化方向如果你不满足于演示项目想把它做成真正可用的组件下面这些方向值得深入。8.1 从暴力扫描升级到 ANN 索引暴力扫描在数据量小的时候足够好但数据量一旦超过百万就必须引入 ANN。推荐从 HNSW 入手原因有三个查询延迟稳定、召回率高、实现有大量论文和开源代码参考。在 C 里实现 HNSW核心是维护一张多层图。每层都有节点和边查询从顶层开始贪婪搜索逐层下降。插入时需要随机决定新节点的最大层级。整个结构比暴力扫描复杂不少但查询复杂度可以从 O(N) 降到 O(log N) 量级。如果暂时不想自己实现可以评估一些成熟的 C 库做性能基准对比比如 hnswlib。它们通常被设计成头文件库使用门槛不高。但要注意本地基准测试和生产环境差异很大一定要用自己的数据集测。8.2 内存与缓存优化向量数据如果以 32 位浮点存储1000 万条 768 维向量大约占用 30 GB 内存。生产环境要注意几个优化方向使用float16或int8量化内存直接减半或减到四分之一。把频繁访问的索引热区放入内存冷数据放到磁盘或远端存储。用内存池减少频繁分配和释放带来的碎片。对于低延迟场景尽量保证索引完全驻留内存。一旦落到磁盘随机 IOP99 延迟会大幅上升。8.3 多线程与并发控制C 端做高并发检索时常见做法是“读写分离”索引构建期间不提供查询构建完成后切换只读模式。查询请求使用线程池并行处理每个线程独立执行检索互不干扰。这样可以避免在查询路径上加锁。如果需要在构建过程中支持更新可以考虑 read-write lock 或双缓冲索引切换。但双缓冲会带来双倍内存开销需要根据数据量权衡。8.4 与 Python 生态集成C 引擎写好后最实用的集成方式是用 C API 封装再用 Python 的ctypes或pybind11调用。这样既能享受 C 的性能又能复用 Python 的模型和工具链。一个极简的 C API 设计// 文件路径gram_demo/src/gram_c_api.h #ifdef __cplusplus extern C { #endif typedef void* GramIndex; GramIndex gram_index_create(); void gram_index_add(GramIndex idx, uint64_t id, const float* vec, size_t dim); void gram_index_search(GramIndex idx, const float* query, size_t dim, uint64_t* ids, float* sims, size_t top_k); void gram_index_free(GramIndex idx); #ifdef __cplusplus } #endif对外只暴露create/add/search/free四个接口内部类型全部隐藏在void*后面。这样上层语言只需要拿到句柄不需要知道 C 内部实现。生产环境里这个模式非常常见也是 C 组件嵌入到异构技术栈的标准姿势。8.5 数据安全与生产变更任何检索系统在生产环境都要遵守几条底线索引构建和更新操作先在测试环境验证再灰度到生产。保留旧索引文件至少一个版本以便快速回滚。加载数据前做完整性校验比如维度、数量、范数范围。对无权限的 API 调用做好访问控制避免检索能力被滥用。这些不是可有可无的工程洁癖而是真实事故换来的经验。尤其是“快速回滚”这一步一旦新索引上线后召回质量大幅下降能立刻切回旧版本比临时排查代码省太多时间。9. 总结与下一步学习路线Gram 这个项目的出现说明向量检索并不是大厂专属的“黑科技”。用 C 从零构建一个可用的小型向量搜索引擎路径是清晰的先做暴力扫描跑通全流程再逐步替换成 ANN 索引最后打磨并发、内存和封装接口。这篇文章用一套完整的最小示例帮你理清了向量检索的核心环节。这不是一个玩具项目而是你理解 FAISS、Milvus 等工业级系统的最佳起点。如果你决定继续深入建议按下面的顺序走一遍先替换数据源用真实的文本 embedding 向量测试效果比如BGE或text-embedding-3-small生成的向量。统计数据量增长时的查询延迟曲线找到暴力扫描的性能拐点。阅读 HNSW 原始论文然后在现有代码上尝试实现一个简化版 HNSW。用标准数据集做召回评测比如SIFT1M或GIST对比不同索引参数下的召回率。把 C 内核封装成 C API再用 Python 写一套自动化测试验证跨语言调用的稳定性和性能损耗。如果你之前只熟悉 Python上手 C 向量检索项目时最大的障碍不是语法而是内存管理和编译链接的思维方式。建议先用小数据集跑通再逐步扩大规模。过程中多打印日志把每一步的输入输出都确认清楚。向量检索一旦跑通后续做 RAG、智能问答、多模态检索都会轻松很多。 从零用C++构建向量检索引擎：核心原理与工程实践
如果你最近在关注 AI 应用落地大概率绕不开一个词向量检索。从语义搜索、相似图片匹配到 RAG 知识库召回背后几乎都有一个向量搜索引擎在支撑。但很多人第一次接触向量检索都从 Python 生态开始比如faiss、milvus、qdrant的 Python 客户端。用起来确实舒服可一旦数据量上来、延迟要求变苛刻你就会发现瓶颈往往不在算法而在工程侧的底层实现。这里我想聊一个很有意思的开源项目Gram一个用 C 从零构建的向量搜索引擎。它出现在 Hacker News 的 Show HN 上作者直接把它定义为“vector search engine built in C”。这类项目的价值不完全在于它比 FAISS 强多少而在于它展示了向量搜索引擎的核心路径从数据预处理、索引构建到在线检索完全可以用 C 高效实现不依赖重型框架也能跑起来。这篇文章不打算只做项目介绍而是把它拆开来看向量搜索引擎要解决什么问题C 实现的核心优势在哪里如何理解索引、召回、重排这些关键概念以及如果你想自己动手做一个类似的 C 向量检索工具应该从哪几步开始。文章后面还会给出一套可运行的最小实现思路包含完整的 CMake 配置和 C 代码示例方便你直接验证整个流程。1. 向量搜索引擎为什么值得用 C 重写先明确一个判断向量搜索引擎的核心竞争力不是“能检索”而是“快、省、稳”。这三个字几乎由底层语言决定。如果用 Python 写原型几百毫秒的查询时间完全能接受因为脚本语言的数据结构和开发效率确实高。但生产环境往往要面对几百万甚至上亿条向量一条查询要求几十毫秒内返回还给不出算力无限膨胀的预算。这种时候指针、连续内存、无 GC 暂停、手动控制 SIMD 指令就成了实实在在的优势。C 在这类场景重写一次的价值体现在几个层面内存可控向量数据本质上是连续数组用std::vectorfloat或裸指针管理内存比 Python 对象开销小几个数量级。无 GC 停顿向量检索通常是超高 QPS 的在线服务Java 或 Go 的 GC 偶尔停顿还能忍但检索延迟要求极低时C 的无暂停模型更省心。精细控制并发多线程、无锁队列、内存池这些底层能力可以直接作用在索引结构和查询路径上。便于嵌入其他系统C 写的检索引擎可以编译成动态库被 Python、Java、Go 通过 FFI 调用也可以作为独立服务。所以 Gram 这个项目的意义不只是“又一个向量检索库”而是给你展示了一条完整的 C 技术路线。如果你准备做自己的向量检索组件或者想在 RAG 系统中降低检索延迟这类项目是最好的参考起点。当然C 重写也有代价开发效率低、构建系统复杂、线程安全问题容易踩坑。但工程上常说没有银弹只有取舍。像 Gram 这种聚焦向量搜索的 C 项目本质上是用开发复杂度换取运行效率和部署自由度。2. Gram 的定位与向量检索的核心概念在看具体代码前先理清几个概念。很多人会把“向量搜索”和“数据库查询”搞混。传统数据库查的是等值或范围条件比如where name 张三向量搜索查的是“最相似的 TopK”输入是一个向量输出是距离最近的若干条记录。2.1 什么是向量化向量化是指把文本、图片、音频等内容用模型转换成一串浮点数。比如一句话经过 embedding 模型后变成一个 768 维或 1024 维的向量。语义相近的内容在向量空间里的距离也近。这是语义搜索不同于关键词搜索的根本原因它能解决“同义不同词”的检索问题。2.2 什么是 ANN 近似最近邻精确最近邻意味着每次查询都要和库里所有向量计算距离复杂度 O(N)。当 N 达到千万级这个成本完全不可接受。所以工业级向量搜索引擎通常采用 ANN近似最近邻算法牺牲少量召回精度换取数量级上的查询性能提升。常见算法有 HNSW、IVF、PQ 等。HNSW 是目前最流行的一种基于多层跳表思想构建图结构查询时分层次逼近目标节点。IVF 则先对向量聚类再只搜索距离最近的几个聚类桶。Gram 这类 C 项目一般会优先选其中一种做核心索引结构。2.3 Gram 在技术栈中的位置从项目标题看Gram 是一个 C 实现的搜索引擎目标很明确用较低的资源占用提供向量索引和相似度检索能力。它走的是“嵌入式检索引擎”路线和 FAISS 类似而不是像 Milvus 那样把检索、存储、分布式调度都包进来。这意味着它更适合以下场景单机内存能放下的数据量级。需要低延迟、高吞吐的在线检索服务。希望把检索能力以动态库形式嵌入到现有 C 服务中。学习向量索引实现原理的练手项目。如果你的需求是几十亿向量、多副本、水平扩容那直接上分布式数据库更合适。Gram 这类项目解决的是“单机极致性能”的问题。3. 环境准备与工程搭建在开始写代码之前先把环境准备好。下面这套环境适配 C17 及以上重点演示向量检索的通用实现思路不依赖任何第三方权重或专用硬件。3.1 编译工具链操作系统Linux 或 macOS 均可Windows 可以用 WSL 或 MSVC。编译器GCC 9 或 Clang 10需要支持 C17。构建工具CMake 3.14 以上。可选依赖OpenMP用于多线程并行计算距离。检查版本的命令g --version cmake --version如果还没有安装Linux 上可以用包管理器安装sudo apt update sudo apt install -y build-essential cmake libomp-devmacOS 上可以用 Homebrewbrew install cmake gcc libomp这里要提醒一个常见问题g和cmake的版本不要相差太大尤其是老系统自带的 CMake 可能太旧导致无法识别CXX_STANDARD 17。遇到这类问题优先升级 CMake。3.2 项目目录结构我建议用一个干净的目录组织代码后续扩展也比较方便gram_demo/ ├── CMakeLists.txt ├── src/ │ ├── vector_index.h │ ├── vector_index.cpp │ └── main.cpp ├── data/ │ └── vectors.csv └── build/build目录专门存放编译产物不要和源码混在一起。4. 核心流程拆解一个向量搜索引擎最核心的流程可以拆成四步数据预处理、向量化、索引构建、查询召回。这里我不把“向量化”框死在某个模型上因为它可以是文本 embedding、图像特征甚至是你手工构造的特征向量。关键是理解后面的链路。4.1 数据预处理原始数据通常不是向量。比如一堆商品描述、图片路径、用户行为序列。第一步是把它们转换成统一维度的浮点数组同时保留原始 ID。预处理环节最容易出错的是维度不一致和缺失值。一个维度错位后续所有距离计算都会失真。4.2 向量化向量化大多依赖模型推理。Gram 这类 C 项目通常不做模型推理而是接收已经生成的向量。所以实践中常见做法是用 Python 的 embedding 模型批量生成向量导出成二进制文件或 CSV再交给 C 端加载。好处是职责清晰模型升级不会影响索引代码。如果你需要 C 端也能推理可以考虑接入 ONNX Runtime 或 TensorRT但这会显著增加项目复杂度。最小实现里直接用文件加载即可。4.3 索引构建索引构建就是把这些向量组织成合适的数据结构。最简单的实现是暴力线性扫描所有向量放在一个连续数组里查询时逐个计算距离。数据量小的时候这个方案反而最准确、最容易写对。更进阶的是 HNSW 图索引。构建时要为每个新插入的向量找到它在图上的邻居并双向连接。这个过程有大量随机内存访问C 做起来反而有优势因为可以直接操作指针和预分配内存。4.4 查询召回与重排查询时输入向量与索引中的候选集计算距离得到 TopK 结果。这一步包含两个关键操作相似度度量常用余弦相似度、欧氏距离、内积。如果向量已经归一化三者可以互相转换。TopK 排序维护一个大小为 K 的最大堆保证只保留最优的 K 个候选。工程上还会加一步“重排”即先用 ANN 粗召回再用更精确的距离计算重新排序。这一步在 RAG 场景里尤其重要因为粗召回结果可能混入语义不够精准的噪声。5. 一个最小 C 向量检索引擎实现示例下面给出一个可以编译运行的最小示例。它实现了加载向量、余弦相似度计算、暴力 TopK 检索三个核心能力。代码中没有引入任何第三方库方便你理解底层逻辑。5.1 CMake 配置# 文件路径gram_demo/CMakeLists.txt cmake_minimum_required(VERSION 3.14) project(gram_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) if(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Release) endif() add_executable(gram_demo src/main.cpp src/vector_index.cpp ) target_include_directories(gram_demo PRIVATE src) # 可选开启 OpenMP 加速 find_package(OpenMP QUIET) if(OpenMP_CXX_FOUND) target_link_libraries(gram_demo PRIVATE OpenMP::OpenMP_CXX) message(STATUS OpenMP enabled) else() message(STATUS OpenMP not found, use single thread) endif()5.2 头文件定义// 文件路径gram_demo/src/vector_index.h #pragma once #include cstdint #include string #include vector struct Doc { uint64_t id 0; std::vectorfloat vec; }; class VectorIndex { public: void add(uint64_t id, const std::vectorfloat vec); // 返回 TopK 结果的 (id, 相似度) 列表按相似度从高到低排序 std::vectorstd::pairuint64_t, float search( const std::vectorfloat query, size_t top_k) const; size_t size() const { return docs_.size(); } size_t dim() const { return dim_; } private: std::vectorDoc docs_; size_t dim_ 0; };5.3 核心实现// 文件路径gram_demo/src/vector_index.cpp #include vector_index.h #include algorithm #include cmath namespace { float cosine_similarity(const std::vectorfloat a, const std::vectorfloat b) { float dot 0.0f; float norm_a 0.0f; float norm_b 0.0f; for (size_t i 0; i a.size(); i) { dot a[i] * b[i]; norm_a a[i] * a[i]; norm_b b[i] * b[i]; } if (norm_a 0.0f || norm_b 0.0f) { return 0.0f; } return dot / (std::sqrt(norm_a) * std::sqrt(norm_b)); } } // namespace void VectorIndex::add(uint64_t id, const std::vectorfloat vec) { if (dim_ 0) { dim_ vec.size(); } if (vec.size() ! dim_) { throw std::runtime_error(dimension mismatch); } docs_.push_back({id, vec}); } std::vectorstd::pairuint64_t, float VectorIndex::search( const std::vectorfloat query, size_t top_k) const { // 最小堆堆顶是当前候选集中相似度最小的元素 // 这样当堆满时只有相似度更大的新结果才能替换堆顶 using Item std::pairfloat, uint64_t; std::priority_queueItem, std::vectorItem, std::greaterItem min_heap; for (const auto doc : docs_) { float sim cosine_similarity(query, doc.vec); if (min_heap.size() top_k) { min_heap.push({sim, doc.id}); } else if (sim min_heap.top().first) { min_heap.pop(); min_heap.push({sim, doc.id}); } } std::vectorstd::pairuint64_t, float result; result.reserve(min_heap.size()); while (!min_heap.empty()) { result.emplace_back(min_heap.top().second, min_heap.top().first); min_heap.pop(); } std::reverse(result.begin(), result.end()); return result; }这里有一个值得展开的技术点为什么用std::priority_queue而不是std::sort因为 TopK 只需要维持 K 个候选用堆可以把时间复杂度控制在 O(N log K)。当 K 远小于 N 时比整表排序高效得多。如果你的数据量在一万以下直接用std::sort反而代码更简单但一旦数据量涨到百万级堆的优势会非常明显。5.4 主程序示例// 文件路径gram_demo/src/main.cpp #include vector_index.h #include fstream #include iostream #include sstream std::vectorstd::vectorfloat load_vectors(const std::string path, size_t dim) { std::vectorstd::vectorfloat data; std::ifstream fin(path); if (!fin.is_open()) { throw std::runtime_error(cannot open file: path); } std::string line; while (std::getline(fin, line)) { std::stringstream ss(line); std::vectorfloat vec; vec.reserve(dim); std::string token; while (std::getline(ss, token, ,)) { vec.push_back(std::stof(token)); } if (vec.size() ! dim) { std::cerr line dimension mismatch: vec.size() ! dim std::endl; continue; } data.push_back(std::move(vec)); } return data; } int main(int argc, char** argv) { if (argc 3) { std::cerr usage: argv[0] vector_file dim std::endl; return 1; } const std::string path argv[1]; const size_t dim static_castsize_t(std::stoul(argv[2])); auto vectors load_vectors(path, dim); if (vectors.empty()) { std::cerr no valid vectors loaded std::endl; return 1; } VectorIndex index; for (size_t i 0; i vectors.size(); i) { index.add(static_castuint64_t(i), vectors[i]); } std::cout index size: index.size() , dim: index.dim() std::endl; // 用第一条向量作为查询测试检索 const auto query vectors[0]; auto result index.search(query, 5); std::cout Top5 results for vec[0]: std::endl; for (const auto [id, sim] : result) { std::cout id id , sim sim std::endl; } return 0; }这个主程序做了三件事加载向量文件、构建索引、执行一次 Top5 查询。查询用第一条向量作为输入正常情况下第一个结果应该就是它自己相似度接近 1.0。5.5 生成测试数据为了方便测试可以用 Python 生成一份随机向量数据# 文件路径gram_demo/scripts/gen_data.py import random random.seed(42) dim 64 num 2000 with open(data/vectors.csv, w, encodingutf-8) as f: for _ in range(num): vec [round(random.gauss(0, 1), 6) for _ in range(dim)] f.write(,.join(map(str, vec)) \n) print(fgenerated {num} vectors, dim{dim})运行方式mkdir -p data python3 scripts/gen_data.py生成的不是稀疏向量而是 64 维稠密浮点向量足以验证检索流程。5.6 编译与运行mkdir -p build cd build cmake .. make -j$(nproc) ./gram_demo ../data/vectors.csv 64预期会看到类似下面的输出index size: 2000, dim: 64 Top5 results for vec[0]: id0, sim1 id1073, sim0.338647 id785, sim0.330043 id551, sim0.32818 id1797, sim0.317074id0, sim1表示第一条查询向量和自己完全匹配。后面的相似度都很低说明随机向量之间没有明显的语义关系。这正好验证了索引和距离计算逻辑是对的。6. 运行结果与效果验证跑通示例只是第一步。真正的工程验证需要从“能跑”升级到“结果可信”。下面给出几个验证维度。6.1 相似度计算的正确性最简单的方法是在已有数据集里人为构造一个特殊向量。比如取出第 0 条向量把它精确复制一份并赋予新 ID插入索引后查询原向量。如果引擎结果里这个 ID 排在第一位说明检索逻辑没问题。// 伪代码验证精确匹配结果 uint64_t new_id index.size(); index.add(new_id, vectors[0]); // 复制第一个向量 auto result index.search(vectors[0], 3); // 预期result[0].id new_id6.2 召回指标暴力线性扫描的召回率是 100%因为它计算了所有向量。它被当作基准用来衡量 ANN 索引的召回率RecallK 命中真实TopK的数量 / K。如果你想从暴力扫描换成 HNSW不要直接上线先跑一组召回测试确认损失在可接受范围。6.3 延迟和吞吐在 Release 模式下编译然后用几千条查询跑一遍统计平均延迟和 P99 延迟。C 项目如果不开编译优化性能可能比预期差好几倍。记得在 CMake 里设置Release构建类型并用-O3优化。一个常见的误判是只看 QPS不看单次延迟分布。向量检索场景里P99 对用户体验影响更大。建议压测脚本里同时输出平均值、P95 和 P99。7. 常见问题与排查方法从实际经验看这类 C 项目最常踩的坑集中在构建、数据、性能三方面。问题现象可能原因排查方式解决方案CMake 提示不支持 C17系统自带 CMake 版本过旧cmake --version升级 CMake 到 3.14或改用源码安装编译报链接错误undefined reference to omp_*手动开了 OpenMP 但链接阶段没加库检查 CMake 中 OpenMP 的链接配置加载OpenMP::OpenMP_CXX或删除#pragma omp相关代码加载向量时读取行数少了很多数据文件存在空行或维度不一致统计原始文件行数和异常行预处理时过滤空行打印维度不一致的样本检索结果相似度全是 0向量包含全 0 数据余弦公式分母为 0打印范数统计检查向量归一化步骤在加载或查询时过滤无效向量或改用内积距离查询速度很慢编译时用了 Debug 模式查看 CMakeCache 中CMAKE_BUILD_TYPE重新用-DCMAKE_BUILD_TYPERelease构建结果里出现重复 ID插入数据时 ID 没有去重检查 add 逻辑是否允许重复 ID在插入前用unordered_set去重或设计唯一主键这些坑单独看都不复杂但混在一起会消耗大量排查时间。建议调试时先打印index.size()和几条向量的范数确认数据层面没有大问题再去查构建配置。8. 工程落地建议与性能优化方向如果你不满足于演示项目想把它做成真正可用的组件下面这些方向值得深入。8.1 从暴力扫描升级到 ANN 索引暴力扫描在数据量小的时候足够好但数据量一旦超过百万就必须引入 ANN。推荐从 HNSW 入手原因有三个查询延迟稳定、召回率高、实现有大量论文和开源代码参考。在 C 里实现 HNSW核心是维护一张多层图。每层都有节点和边查询从顶层开始贪婪搜索逐层下降。插入时需要随机决定新节点的最大层级。整个结构比暴力扫描复杂不少但查询复杂度可以从 O(N) 降到 O(log N) 量级。如果暂时不想自己实现可以评估一些成熟的 C 库做性能基准对比比如 hnswlib。它们通常被设计成头文件库使用门槛不高。但要注意本地基准测试和生产环境差异很大一定要用自己的数据集测。8.2 内存与缓存优化向量数据如果以 32 位浮点存储1000 万条 768 维向量大约占用 30 GB 内存。生产环境要注意几个优化方向使用float16或int8量化内存直接减半或减到四分之一。把频繁访问的索引热区放入内存冷数据放到磁盘或远端存储。用内存池减少频繁分配和释放带来的碎片。对于低延迟场景尽量保证索引完全驻留内存。一旦落到磁盘随机 IOP99 延迟会大幅上升。8.3 多线程与并发控制C 端做高并发检索时常见做法是“读写分离”索引构建期间不提供查询构建完成后切换只读模式。查询请求使用线程池并行处理每个线程独立执行检索互不干扰。这样可以避免在查询路径上加锁。如果需要在构建过程中支持更新可以考虑 read-write lock 或双缓冲索引切换。但双缓冲会带来双倍内存开销需要根据数据量权衡。8.4 与 Python 生态集成C 引擎写好后最实用的集成方式是用 C API 封装再用 Python 的ctypes或pybind11调用。这样既能享受 C 的性能又能复用 Python 的模型和工具链。一个极简的 C API 设计// 文件路径gram_demo/src/gram_c_api.h #ifdef __cplusplus extern C { #endif typedef void* GramIndex; GramIndex gram_index_create(); void gram_index_add(GramIndex idx, uint64_t id, const float* vec, size_t dim); void gram_index_search(GramIndex idx, const float* query, size_t dim, uint64_t* ids, float* sims, size_t top_k); void gram_index_free(GramIndex idx); #ifdef __cplusplus } #endif对外只暴露create/add/search/free四个接口内部类型全部隐藏在void*后面。这样上层语言只需要拿到句柄不需要知道 C 内部实现。生产环境里这个模式非常常见也是 C 组件嵌入到异构技术栈的标准姿势。8.5 数据安全与生产变更任何检索系统在生产环境都要遵守几条底线索引构建和更新操作先在测试环境验证再灰度到生产。保留旧索引文件至少一个版本以便快速回滚。加载数据前做完整性校验比如维度、数量、范数范围。对无权限的 API 调用做好访问控制避免检索能力被滥用。这些不是可有可无的工程洁癖而是真实事故换来的经验。尤其是“快速回滚”这一步一旦新索引上线后召回质量大幅下降能立刻切回旧版本比临时排查代码省太多时间。9. 总结与下一步学习路线Gram 这个项目的出现说明向量检索并不是大厂专属的“黑科技”。用 C 从零构建一个可用的小型向量搜索引擎路径是清晰的先做暴力扫描跑通全流程再逐步替换成 ANN 索引最后打磨并发、内存和封装接口。这篇文章用一套完整的最小示例帮你理清了向量检索的核心环节。这不是一个玩具项目而是你理解 FAISS、Milvus 等工业级系统的最佳起点。如果你决定继续深入建议按下面的顺序走一遍先替换数据源用真实的文本 embedding 向量测试效果比如BGE或text-embedding-3-small生成的向量。统计数据量增长时的查询延迟曲线找到暴力扫描的性能拐点。阅读 HNSW 原始论文然后在现有代码上尝试实现一个简化版 HNSW。用标准数据集做召回评测比如SIFT1M或GIST对比不同索引参数下的召回率。把 C 内核封装成 C API再用 Python 写一套自动化测试验证跨语言调用的稳定性和性能损耗。如果你之前只熟悉 Python上手 C 向量检索项目时最大的障碍不是语法而是内存管理和编译链接的思维方式。建议先用小数据集跑通再逐步扩大规模。过程中多打印日志把每一步的输入输出都确认清楚。向量检索一旦跑通后续做 RAG、智能问答、多模态检索都会轻松很多。