# 知识库“建立语义索引”是做什么的？

> Cube Agent 2.2.0 正式版（构建 2002007）使用说明。
> 分类：模型与 AI 能力。内容基准：2026-11-07。
> 网页：https://cubeagent.app/docs/knowledge_indexing/

## 先说结论

建立语义索引会把知识库正文切成片段，再用 Embedding 模型生成向量，供按需检索理解“意思相近但用词不同”的问题。**它不会修改知识库原始正文。**

## 不建立索引还能用吗

能：

- 使用 **全量灌入** 时，助手仍会直接读取知识库正文，不依赖语义索引。
- 使用 **按需检索** 时，仍可降级为关键词搜索。
- 区别是没有语义向量检索。用户换一种说法、正文里没有相同关键词时，更容易漏掉相关片段。

## 和“优化正文为 Markdown”有什么区别

- **优化正文为 Markdown**可在导入预览或知识库详情的单篇/多选操作中进行，由对话模型清理段落、标题、列表和表格。导入预览会先保存原文再创建后台任务，离开页面后继续。优化结果先生成审核稿，确认采用后才替换正文；可以预览、重试或恢复原文。
- **建立语义索引**可在知识库列表顶部一键处理全部知识库，也可在单个知识库详情里进行，只生成检索用的分块和向量文件，不改原文。

## 什么时候需要建立或重建

- 知识库较大，并使用按需检索时，建议建立索引。
- 新导入或修改正文后，需要为相应文件建立索引。
- 更换 Embedding 模型后，旧向量与新模型不匹配，需要重新建立。修改全局默认向量模型时，跟随默认模型的知识库会标记索引过期；单独指定覆盖模型的库不受这次默认切换影响。只标记过期，不自动删除原文或立即重新建立索引。
- 只使用短资料的全量灌入时，可以暂时不建立。

## 一键为全部知识库建立

有文件还没建立索引时，知识库列表顶部会显示待处理数量。点 **全部建立**，会按列表顺序逐个处理所有知识库里未建立、上次失败或被中断的文件：

- 卡片上的圆环显示本轮进度，下方显示正在处理的知识库和文件。离开页面也会继续；切到后台时会尽量保持运行，若被系统中断，再点一次即可接着处理。
- 可以随时点 **停止**。已完成的文件会保留；处理到一半的文件下次从已保存的分段继续，已保存的分段不会重复请求。
- 遇到向量服务鉴权、额度或限流等问题时会自动暂停，使用同一模型的其余知识库不再继续请求；处理好后点 **继续** 即可。
- 个别文件失败不影响其他文件，失败原因可在对应知识库的文件上查看。

## 需要什么

语义索引需要先配置可用的 Embedding 模型。入口在 **设置 → 模型与用量 → 默认模型 → 知识库向量化**，也可以在单个知识库详情里指定覆盖模型。未配置时，点击建立索引会先打开模型选择器；在知识库列表顶部选好模型后，会自动开始为全部知识库建立索引。