目录
一、embedding_function（向量模型）
可选方式
选型建议
二、HNSW 参数选择（核心影响搜索速度与准确率）
2.1 参数解释和推荐值
2.2 配置模板参考
1、推荐默认配置（适合大多数项目）：
2、如果你数据量不大，追求速度：
3、如果你是海量数据 + 精确语义搜索（例如 10w+ 向量）：
三、 如何验证设置是否合理？
一、embedding_function（向量模型）
可选方式
| 模型 | 来源 | 优点 | 适用场景 |
|---|---|---|---|
DefaultEmbeddingFunction | 本地 | 免费、快速、不联网 | 本地原型、快速测试 |
OpenAIEmbeddingFunction | 云端（OpenAI） | 高质量语义表达、支持多语言 | 生产环境、中文或多语言场景 |
| 自定义 HuggingFace 模型 | 本地/云端 | 灵活，适配行业语料 | 医疗、法律、金融定制需求 |
选型建议
-
原型阶段 / 离线工具 → 用
DefaultEmbeddingFunction()（MiniLM） -
中小型项目上线 → 用 OpenAI
text-embedding-3-small（速度快，质量高） -
大模型私有部署 / 内网不联网 → 自建向量模型
二、HNSW 参数选择（核心影响搜索速度与准确率）
2.1 参数解释和推荐值
| 参数名 | 含义 | 推荐值（中小数据量） | 推荐值（大数据量） | 建议说明 |
|---|---|---|---|---|
space | 向量相似度度量方式 | "cosine" | "cosine" | 一般都选余弦相似度，除非特殊场景 |
ef_construction | 构建索引时的探索范围（越大索引越准） | 100 | 200~300 | 构建阶段，时间换准确 |
ef_search | 查询时探索节点数（越大越准） | 50~100 | 100~300 | 越大查得越准但越慢 |
max_neighbors | 每个节点连接的邻居数量（影响索引质量） | 16 | 32 | 一般设为 16 或 32 |
num_threads | 构建索引使用的线程数 | 根据 CPU 核心数 | 根据 CPU 核心数 | 多线程加速构建 |
2.1.1 关键参数：ef_construction
1、概述
构建索引时的“探索范围”指的是参数 ef_construction，这是构建 HNSW 索引时的核心参数之一，它决定了每个新节点在添加到图中时，会“看”多少个已有节点来寻找最相似的邻居。
一句话解释：
ef_construction控制新节点在加入图时会探索多少个已有节点。值越大，索引越准确，但构建时间和内存开销也越高。
2、原理简述
-
构建 HNSW 索引时，每插入一个向量，就要为它选择一批“邻居”。
-
选择邻居的方法是：从已有的图中搜索
ef_construction个候选节点，然后从中选出最相似的max_neighbors个建立连接。
3、参数选择建议（常用范围：64 ~ 512）
| 数据规模 | 推荐 ef_construction |
|---|---|
| < 1 万条 | 64 ~ 100 |
| 1 万 ~ 10 万条 | 100 ~ 200 |
| 10 万 ~ 100 万条 | 200 ~ 300 |
| > 100 万条 | 300 ~ 512（视内存而定） |
4、 设置越大/越小的影响
ef_construction 值 | 优点 | 缺点 |
|---|---|---|
| 小（如 64） | 构建快、内存省 | 索引质量差、影响查准率 |
| 中（如 100~200） | 平衡 | 推荐值 |
| 大（如 300~512） | 检索更准 | 构建慢、内存占用高 |
5、举个例子
假设你用 10 万条文本向量构建搜索系统：
"hnsw": {"ef_construction": 200,"max_neighbors": 32,"num_threads": 4
}
含义是：每个新向量会先从已有图中探索 200 个节点，然后从中选出 32 个相似度高的作为邻居。
6、小结
| 参数 | 说明 | 推荐值范围 |
|---|---|---|
ef_construction | 构建索引时，每个新向量探索的候选节点数 | 100 ~ 300（中大型项目） |
2.1.2 关键参数：ef_search
1、概述
-
f_search就是你设置的 搜索过程中最多会探索的节点数。 -
默认值可能是
10或100，你可以设更高以提升查准率。
ef_search 值 | 探索节点数 | 检索速度 | 检索精度 |
|---|---|---|---|
10 | 少 | 非常快 | 精度可能不高 |
100 | 多 | 较慢 | 精度更高 |
300 | 非常多 | 更慢 | 几乎等于精确搜索 |
可以理解为搜索时你愿意“走几步路”去找最近的东西，走得越多，找到的可能越准。
2、怎么选 ef_search？
| 应用场景 | 推荐值 |
|---|---|
| 实时性要求高、数据不多 | ef_search = 20~50 |
| 通用语义检索、常规精度 | ef_search = 100 |
| 准确率优先、如推荐系统 | ef_search = 200~300 |
想象你在地图上找“最近的加油站”：
-
ef_search = 10→ 你只看周围 10 个路口（很快，但可能错过） -
ef_search = 300→ 你查看方圆 5 公里所有站点（更准，但耗时）
| 名词 | 含义 | 建议 |
|---|---|---|
| 搜索节点 | 检索时要比较距离的向量节点数 | ef_search 控制，越多越准但慢 |
| 构建节点 | 建索引时访问过的节点数 | 由 ef_construction 控制 |
2.1.3 关键参数：max_neighbors
1、概述
“每个节点连接的邻居数量”是指在 HNSW（Hierarchical Navigable Small World）索引构建阶段，每个向量节点最多会连接多少个“相似的节点”作为它的邻居。这由参数 max_neighbors（有时叫 M）控制。
一句话解释：
每个向量点会主动维护max_neighbors个最相似的其他向量，作为图结构中的“朋友节点”，用来辅助导航搜索。
2、举个例子（假设 max_neighbors = 4）：
假设你有一个向量 A，它与周围其他向量计算了相似度，系统会选择其中最相似的 4 个节点作为 A 的“邻居”。
在图中，A 将连向这 4 个节点，形成双向或单向的边。这些边形成了一个小世界图（Small World Graph），为后续搜索提供跳跃路径。
3、这些邻居有什么用？
-
它们就是**“搜索路线图”**的一部分。
-
查询时从某个节点开始，沿着它的邻居跳转（而不是全量比较），从而快速接近最相似的向量。
4、参数建议
| 数据规模 | 推荐 max_neighbors（M） |
|---|---|
| < 10 万条 | 8 ~ 16 |
| 10 万 ~ 100 万 | 16 ~ 32 |
| > 100 万条 | 32 ~ 64（根据内存可调高） |
5、数量设置影响
| 数量 | 优点 | 缺点 |
|---|---|---|
| 少（如 8） | 节省空间，速度快 | 精度差、图稀疏 |
| 多（如 32） | 更高检索精度 | 占内存，构建慢 |
| 极多（如 64+） | 接近精确搜索效果 | 内存大增，不适合轻量部署 |
6、类别理解
把节点想成一个人，邻居就是他最熟的朋友。一个人朋友越多，消息传播（搜索）效率越高，但也更复杂、更占资源。
7、总结
| 概念 | 含义 |
|---|---|
max_neighbors | 构建索引时，每个节点最多连接多少“相似节点” |
| 更大值 | 图更密集，搜索路径更多，准确率提高但资源开销增大 |
| 通常值 | 16 或 32 足够大多数任务 |
2.1.4 关键参数：num_threads
1、 选择依据
你应该根据 本机的 CPU 核心数 来合理设置 num_threads：
| 机器配置 | 建议设置（num_threads） |
|---|---|
| 单核 CPU / 低性能机器 | 1 |
| 4 核 CPU | 2~4 |
| 8 核 CPU | 4~6 |
| 16 核服务器 | 8~12（最多不超过 75% 使用率） |
2、查看你机器的 CPU 核心数（命令行）
▲Linux/macOS：
lscpu | grep "^CPU(s):"
# 或者
nproc
▲Windows（PowerShell）：
Get-WmiObject -Class Win32_ComputerSystem | Select-Object NumberOfLogicalProcessors
3、设置建议
| 设置 | 优点 | 缺点 |
|---|---|---|
| 线程数小（如 1） | 占用低 | 构建时间长 |
| 线程数中等（如 2~4） | 平衡 | 适合开发测试环境 |
| 线程数多（如 8+） | 构建快 | 占 CPU 多，其他进程变慢 |
4、 示例设置（实际代码）
"hnsw": {"ef_construction": 200,"max_neighbors": 16,"num_threads": 4 # 如果你的机器是 8 核，可以设为 4~6
}
5、小结
| 参数名 | 含义 | 如何选择 |
|---|---|---|
num_threads | 构建 HNSW 索引时的线程数 | 设为不超过 CPU 核心数的 70% 较稳妥 |
| 构建快慢取决于线程数；查询阶段不影响 |
2.2 配置模板参考
1、推荐默认配置（适合大多数项目）：
"hnsw": { "space": "cosine","ef_search": 100, "ef_construction": 200,"max_neighbors": 16, "num_threads": 4 # 或根据你机器核心数
}2、如果你数据量不大，追求速度：
"hnsw": { "space": "cosine", "ef_search": 50, "ef_construction": 100, "max_neighbors": 8, "num_threads": 2
}3、如果你是海量数据 + 精确语义搜索（例如 10w+ 向量）：
"hnsw": { "space": "cosine", "ef_search": 300, "ef_construction": 300, "max_neighbors": 32, "num_threads": 8
}▲"space": "cosine"：向量之间使用余弦相似度来衡量相似度。
▲ef_search: 搜索时的探索范围，越大越准，越小越快。
▲ef_construction: 构建索引时的精度控制参数，越大越好。
▲max_neighbors: 每个节点最多连接的邻居数量。
▲num_threads: 使用线程数（用于并发构建索引）。
三、 如何验证设置是否合理？
你可以从以下角度做 A/B 测试：
| 指标 | 评估方式 |
|---|---|
| 检索精度 | 查询后返回的 top-3 是否与你预期语义相关 |
| 响应速度 | 用 time 或日志记录搜索耗时 |
| 资源占用 | 构建和搜索时 CPU 占用是否合理 |
| 内存开销 | 是否容易 OOM（内存溢出） |
总之需要根据数据量级（比如有多少条文本、是不是中文内容）、部署环境（是否联网）以及用途（问答、推荐、对话等），构建定制化的参数
)
