📚 索引引擎
概述
索引引擎是知识库的核心——它将文本内容转换为向量，建立语义索引，让搜索不再局限于关键词匹配。你可以把它理解为"为知识建立了一张语义地图"，当用户提问时，系统在这张地图上找到最相关的位置。
一句话理解
向量化就是把"猫"和"猫咪"这样的近义词映射到向量空间中相近的位置，让搜索能理解语义而非字面。
核心流程
用户导入条目 → 计算内容哈希 → 生成向量 → 持久化到磁盘 → 加载到内存索引 → 可被检索- 内容哈希校验：系统会计算条目的内容哈希（Content Hash）。如果内容没有变化，即使重新触发向量化也会被跳过，避免浪费
- 向量生成：调用配置的 Embedding 模型将文本转换为向量
- 向量缓存：利用
vectorCache缓存已生成的向量，相同内容不会重复调用 API - 持久化存储：向量以
{entryId}.vec文件形式存入按模型隔离的目录 - 内存加载：搜索时后端将向量索引加载至内存，进行实时计算
索引策略
自动索引 vs 手动索引
自动索引（推荐）
在 设置 > 检索与索引策略 中开启"自动触发向量化"后：
- 新建条目时自动开始向量化
- 编辑条目保存后自动重新计算向量
- 批量导入时自动处理
手动索引
关闭自动索引后，你需要手动控制：
- 单条索引：在条目列表中点击某条目的向量化按钮
- 批量索引：点击 索引全部待处理条目，系统会逐个处理未向量化的条目
- 手动模式适合需要精细控制资源消耗的场景（如 API 调用次数有限）
增量索引
系统采用增量索引策略——不是每次索引都全量重建，而是只处理变化的内容：
- 内容未变：哈希一致，跳过向量化
- 内容改变：重新生成向量并覆盖旧文件
- 新增条目：仅对新条目进行向量化
- 删除条目：同时清理对应的向量文件
这种策略大幅减少了重复 API 调用和磁盘 IO。
索引时的前置处理
在向量化之前，系统会对条目内容进行预处理：
- 哈希计算：为每个条目生成内容哈希，用于变更检测
- Key 提取：从 Markdown 内容中提取第一个一级标题作为 Key（如果导入时未指定）
- 标签提取：从内容中识别
Tags: xxx或标签: xxx标记自动添加标签 - 长度校验：单个 CAIU 有 12,000 字符的长度限制（可在设置中调整），超出会跳过并记录失败
嵌入模型配置
选择模型
知识库使用 Embedding 模型来生成向量。选择时建议考虑：
- 维度一致性：同一个知识库建议使用同一维度（Dimension）的模型。切换模型后，旧向量不会自动失效，但新生成的向量会使用新维度
- 模型性能：轻量级模型速度快但语义理解能力弱，大规模模型效果好但速度慢、成本高
- 供应商：支持所有已配置的 LLM 服务供应商
TODO: 截图 - 设置页面中的模型选择器
探测维度
不同 Embedding 模型的输出维度不同（如 OpenAI text-embedding-3-small 为 1536 维，text-embedding-3-large 为 3072 维）。配置后建议点击 探测模型维度 按钮，系统会自动调用模型 API 检测其维度并填入配置。
向量维度配置
在 设置 > 存储与安全 中可以手动调整向量维度（128~4096）：
- 必须与所选模型实际输出的维度一致
- 较小的维度节省存储和计算资源
- 较大的维度保留更多语义信息
向量化请求配置
在 设置 > 向量化请求配置 中可以精细控制向量化过程：
| 配置项 | 说明 | 建议值 |
|---|---|---|
| 最大并发请求数 | 同时发起的 API 请求数量 | 2-5（根据 API 限制调整） |
| 单次请求批次大小 | 一次请求中包含的文本数量 | 8-16（大模型通常支持批量） |
| 内容长度限制 | 单个条目字符上限 | 12000（超出会跳过） |
| 请求超时 | 单次请求最长等待时间 | 60000ms |
| 最大重试次数 | 失败后的自动重试次数 | 2 |
| 重试间隔 | 重试间的等待时间 | 3000ms |
| 重试模式 | 固定间隔/指数退避 | fixed |
TODO: 截图 - 向量化请求配置面板
重新索引
何时需要重新索引
以下情况建议触发重新索引：
- 更换 Embedding 模型：新模型的向量与新条目的向量在同一空间，但旧条目仍使用旧模型
- 内容批量修改：通过外部工具直接修改了知识库文件
- 向量文件丢失或损坏：检索引擎提示向量文件不存在
如何操作
方式一：校验向量状态
在知识库设置中点击 校验向量状态，系统会检查所有条目的向量文件状态，刷新 UI 显示。
方式二：全部重新索引
开启自动向量化后，逐个编辑条目保存即可触发重新索引。如果需要全量重建，可以：
- 在知识库目录中删除对应的向量目录（谨慎操作）
- 回到应用点击 索引全部待处理条目
方式三：清理冗余向量
如果切换过模型，磁盘上会残留旧模型的向量文件。可以使用 清理冗余向量（当前库）或 全局清理（所有库）功能一键清理。
TODO: 截图 - 设置页面中的清理按钮
索引状态监控
在 监控 标签页可以实时查看索引引擎的运行状态：
RAG Trace
记录每一次检索的详细耗时分解：
- 向量化查询耗时
- 后端检索耗时
- 结果排序耗时
通过分析这些耗时数据，可以诊断性能瓶颈。
TODO: 截图 - RAG Trace 列表，展示各阶段的耗时
Index Trace
记录向量化任务的运行情况：
- 吞吐量：单位时间处理的条目数
- 成功/失败条目数及失败原因
- 当前队列长度和预估剩余时间
统计视图
在 统计 标签页可以查看全局索引概览：
| 指标 | 说明 |
|---|---|
| 总条目数 | 所有知识库的条目总数 |
| 已向量化条目 | 成功生成向量的条目数及百分比 |
| 总 Token 消耗 | 所有向量化操作累计消耗的 Token 数 |
| 全局标签池 | 已注册的标签总数和已向量化标签数 |
| 各库统计 | 每个知识库的独立统计数据 |
TODO: 截图 - 统计页面展示全局数据和各库详情
常见问题
Q：搜索不到内容是怎么回事？
- 检查模型一致性：当前选中的 Embedding 模型是否与向量化时一致？切换模型后旧向量不会被自动迁移
- 点击校验向量状态：在设置中强制同步磁盘和 UI 状态
- 检查条目状态：确认条目已经完成向量化（状态为"已就绪"）
Q：向量化速度太慢怎么办？
- 在设置中增加"最大并发请求数"
- 检查 API 服务是否存在限流
- 确认内容长度未超限（超长条目会重试多次）
- 使用轻量级的 Embedding 模型
Q：切换 Embedding 模型后需要做什么？
切换模型后建议：
- 点击 校验向量状态 确认哪些条目使用了新模型
- 对新模型下未向量化的条目执行批量索引
- 完成后在 清理冗余向量 中一键清理旧模型向量以释放磁盘空间
Q：如何避免向量化失败？
- 确保 API 配置正确，在 LLM Chat 中测试同一模型是否正常工作
- 适当缩短"内容长度限制"防止超长内容
- 增加"最大重试次数"和"请求超时"以应对偶发网络问题
- 检查 API 账户余额和调用限额