知识库：让本地资料可检索、可问答
知识库用于管理一组本地文档，并把它们转换成可以检索的内容索引。你可以把产品文档、会议记录、项目资料、技术规范等目录加入 Pipora，然后通过问题检索相关片段，验证知识库是否覆盖了需要的内容。
知识库模块与 Agent 模块相互独立。你可以先单独创建、索引和测试知识库，确认资料质量后，再把它作为 Agent 或工作流的上下文来源。创建后，知识库也会自动导出为可被工具页、Agent 和 Workflow 调用的检索工具。
知识库是什么
一个知识库对应一个本地目录。Pipora 会读取目录中的文档，先用 Docling 转换成可处理的文本，再按配置切分成适合检索的片段，最后生成向量索引和关键词索引。
知识库包含几类核心信息：
- 基础信息：名称、描述、源目录
- 向量化配置：分块策略、分块大小、重叠长度、embedding 模型
- 文件过滤：需要包含哪些文件类型，哪些目录或临时文件需要排除
- 检索配置：标准检索或关系检索、是否启用重排序、返回多少条结果
- 索引状态：是否已索引、文档数、分块数、上次索引时间和错误信息
- 索引文件：已索引、等待索引、失败、已移出目录的文件列表
知识库的显示名称可以修改，底层索引标识保持不变。改名不会影响已经生成的向量数据。
什么时候使用知识库
管理本地资料
如果资料已经按目录保存在本机，例如产品方案、项目文档、客户资料或团队规范，可以直接把目录作为知识库来源。Pipora 会在本地读取和索引这些文件。
验证资料是否可被检索
知识库详情页提供检索测试。你可以输入问题，查看返回的文档片段、来源文件和分数，判断索引结果是否符合预期。
为 Agent 提供稳定上下文
Agent 需要长期使用同一批资料时，不适合每次临时上传或复制文本。先把资料做成知识库，可以让内容来源更稳定，也便于后续更新和重新索引。
如何创建知识库
1. 填写基础信息
创建知识库时，先填写名称、描述，并选择一个本地源目录。源目录是知识库的数据来源，后续索引会从这个目录读取文件。
名称用于界面展示，同一工作空间内需要唯一。源目录建议选择边界清晰的资料目录，避免把无关文件一起索引进去。
2. 配置向量化参数
向量化参数决定文档如何被切分，以及使用哪个 embedding 模型生成索引。
常见配置包括：
- Chunk 策略：默认使用递归切分，适合大多数文档
- 分块大小：默认 512，控制每个片段的长度
- 重叠长度：默认 50，用于保留相邻片段之间的上下文
- Embedding 模型：选择用于生成向量的模型
Pipora 会提供常用 embedding 模型配置。选择预设模型后，维度会自动填充；如果列表里没有目标模型，也可以添加自定义模型。
3. 设置文件过滤
文件过滤用于控制哪些文件会进入索引。默认适合常见文档场景：
- 包含：
.md、.txt、.docx、.pdf、.xlsx
如果目录里有临时文件、构建产物或大体积无关文件，建议先排除，避免影响索引速度和检索质量。
4. 选择检索模式
知识库支持两种检索模式：
| 模式 | 适合场景 |
|---|---|
| 标准检索 | 默认推荐。先做向量检索和 BM25 关键词检索，再融合排序，适合大多数知识库 |
| 关系检索 | 在标准检索的候选结果上继续做 GraphRAG，适合需要跨章节、跨文档串联信息的场景 |
标准检索通常更稳、更适合日常问答。关系检索会进一步做关系扩展，适合复杂问题，但耗时也更高。
你还可以按需开启重排序。重排序会对检索候选再排一次，让前几条结果更准确，但也会增加一点耗时。
如何索引
创建知识库后，需要点击开始索引。索引会读取源目录中的文件，解析内容、切分片段、生成向量，并保存索引状态。
索引完成后，你可以看到：
- 已索引文档数
- 分块数量
- 上次索引时间
- 是否有解析或向量化错误
- 索引文件列表和每个文件的状态
索引支持增量更新。重新索引时，Pipora 会对比文件的修改时间和大小，只处理新增、变更或删除的文件。若文件在索引过程中被移除，也会跳过，不会中断整个任务。
如何检索测试
进入知识库详情页后，可以在检索测试中输入问题，选择检索模式并执行查询。
结果通常包含：
- 命中文本
- 来源文件路径
- 分数
- 命中方式，例如语义、BM25 关键词、语义 + BM25、关系扩展
- 检索耗时
分数用于同一次检索结果内部排序。标准检索和关系检索的分数计算方式不同，不建议直接跨模式比较。
常见使用建议
先从小目录开始
第一次使用时，建议先选择一个内容明确、文件数量适中的目录。确认索引和检索效果后，再扩展到更大的资料库。
修改配置后重新索引
如果修改了分块策略、embedding 模型、文件过滤规则或检索配置，需要重新索引。否则检索结果仍可能来自旧索引，或者仍保持旧的检索行为。
源目录变更后手动重新索引
知识库不会实时监听文件系统。源目录新增、删除或修改文件后，需要手动触发重新索引，才能让检索结果反映最新内容。
注意文档解析依赖
PDF、Word、Excel、PPT 等格式需要文档解析能力支持。如果本机缺少解析依赖，索引时会显示错误提示，并引导你安装对应组件。
查看索引文件状态
如果你想确认哪些文件已经进入索引，哪些文件还在等待或失败，可以打开索引文件 tab。这里会直接展示文件状态、最近索引时间和错误信息，适合在大目录里排查问题。
知识库会自动变成可调用工具
创建知识库后，Pipora 会自动生成对应的知识库工具。你可以在工具页、Agent 或 Workflow 中引用它，不需要额外手动“开启”。
一句话总结
知识库 = 本地目录 + 文档解析 + 混合检索 + 可选重排序 + 检索测试。它把本地资料整理成可检索的内容基础，让你先验证资料质量，再把它接入 Agent 或工作流使用。