FAISS C++ 初始化索引必须显式指定维度d和距离类型metric，否则易致段错误或搜索结果异常；向量需连续float*存储且16字节对齐；IVF类索引须先train()，多线程需加锁。
FAISS C++ 初始化索引前必须指定维度和类型
FAISS 不会自动推断向量维度，IndexFlatL2、IndexIVFFlat 这类索引构造时必须显式传入 d（维度）和 metric（距离类型），漏掉或传错会导致段错误或搜索结果全为零。
常见错误现象：Segmentation fault (core dumped) 或 search() 返回的 distances 全是极大值（如 1e30）。
- 确保训练/添加向量前，
d与实际向量每行元素个数严格一致（例如 768 维 BERT 向量，就传768，不能是sizeof(float) * 768） -
metric推荐用faiss::METRIC_L2（欧氏距离）或faiss::METRIC_INNER_PRODUCT（内积，需先归一化） - 使用
IndexIVFFlat时，nlist（聚类中心数）建议设为sqrt(N)（N是总向量数），太小会漏召回，太大内存暴涨
向量必须按行连续存储，且用 float*
FAISS C++ API 只接受 float* 指针，不支持 std::vector<float></float> 直接传参，也不接受跨行跳读（如每行后留 padding）。
使用场景：从模型输出（如 ONNX Runtime 的 std::vector<float></float>）或文件读取后，必须展平为紧凑的 float 数组。
立即学习“C++免费学习笔记（深入）”；
- 错误写法：
std::vector<:vector>> data;</:vector>→ 不能直接喂给add() - 正确做法：申请一块连续内存，用
memcpy拷贝所有向量，保证第i个向量起始位置是vecs + i * d - 注意字节对齐：FAISS 内部可能调用 SIMD 指令，若
float*地址未 16 字节对齐（尤其在IndexIVFPQ中），某些 CPU 上会触发SIGBUS
search() 前必须 ensure_index_is_trained()（仅 IVF/PQ 类索引）
IndexFlatL2 可跳过训练，但 IndexIVFFlat、IndexIVFPQ 等必须先调用 train()，否则 search() 行为未定义 —— 可能 crash，也可能返回随机 ID 和距离。
参数差异：train() 输入是 n * d 的 float*，n 建议 ≥ nlist * 40（FAISS 官方推荐），太少会导致聚类质量差、召回率骤降。
- 训练数据不必是最终库数据，可用独立样本集（比如 10 万条代表性的向量）
-
train()只需调一次，后续add()新向量无需重训 - 若训练后
index->is_trained == false，检查输入指针是否为空、n是否为 0、d是否匹配索引维度
多线程搜索需手动加锁或用 ThreadLocalIndex
FAISS C++ 索引对象本身不是线程安全的：search() 和 add() 同时调用会破坏内部状态，典型表现为 distance 与 label 错位、重复 ID 或 nan 距离。
性能影响：加粗粒度锁（如整个 search() 调用）会严重限制吞吐；完全不用锁则必出错。
- 简单方案：对单个
Index*加std::mutex，适用于 QPS - 高并发方案：用
faiss::ThreadLocalIndex包装，每个线程持有一份轻量级副本（不复制向量数据，只复制搜索时的临时缓冲区） - 绝对避免：多个线程共用同一
float*数据指针并同时调用search()—— 即使索引只读，FAISS 内部临时数组也非线程安全
FAISS C++ 的坑主要藏在内存布局、生命周期和线程边界上，而不是算法逻辑本身。维度错一位、指针少一个 const、训练样本凑不够，都可能让搜索结果看起来“正常”却完全不可靠。
