跳到主要内容

使用指南

知识库支持存储、组织和检索文档，实现 RAG（检索增强生成），让 AI 智能体能够基于您的特定文档回答问题。

📋 目录​

🎯 概述​

什么是知识库？​

知识库是一个文档存储和检索系统，支持 RAG（检索增强生成）。它允许 AI 智能体搜索您的文档，并提供基于您特定内容的答案。

核心价值​

价值描述
有据可依的回答AI 基于您的文档回答，而非仅靠通用知识
来源引用每个答案都包含对源文档的引用
智能分块针对检索优化的自动文档分割
灵活检索向量、关键词或混合搜索模式

🏗 架构说明​

RAG 流程​

下图展示了 RAG（检索增强生成）的工作原理：

关键组件​

组件用途
知识库包含文档和检索配置的容器
文档单个文件或内容项
文档块为检索优化的文档片段
检索器搜索后端服务（Elasticsearch/Qdrant）
嵌入模型将文本转换为向量用于相似度搜索

查找知识库​

知识页只列出您当前可以直接访问的有效知识库。

入口内容
全部当前列表接口返回的所有可访问库，包含公司库
我创建的您创建的个人和团队库，不包含公司库
与我共享非本人创建、通过人员或团队等授权可访问的库，不包含公司空间的库
公司知识实际归属公司空间的库

空间筛选按库的实际归属选择个人空间或团队；“全部”还可筛选公司空间，“公司知识”不显示空间筛选。共享给团队不会改变库的归属。同一库命中多种授权只显示一行；侧栏数量不随局部筛选变化，筛选选项数量与当前入口、搜索和类型条件一致。退出团队后，不额外发现原列表接口未返回的库。

手机上可展开导航，并从纵向列表查看库名、空间及操作。无法确认实际空间类别时显示未知；无法确认有效权限时，列表不显示权限信息。点击权限入口可通过服务端确认自己的有效权限和来源；有管理权限时可管理成员和角色。旧库链接、代码知识库及原有迁移入口继续可用。

🆕 创建知识库​

步骤 1：导航到知识库​

  1. 登录 Wegent
  2. 在侧边栏导航到 知识库 部分
  3. 点击 创建知识库

步骤 2：配置基本设置​

字段描述示例
名称显示名称（1-100 字符）"产品文档"
描述可选描述（最多 500 字符）"内部产品文档和指南"
类型笔记本或经典笔记本

步骤 3：配置检索设置​

检索器选择​

选择已配置的检索器（后端搜索服务）：

检索器类型描述
Elasticsearch支持向量的全文搜索
Qdrant专用向量数据库

嵌入模型​

选择用于向量转换的嵌入模型：

模型维度适用场景
text-embedding-3-small1536通用场景，性价比高
text-embedding-3-large3072更高准确度

检索模式​

模式描述适用场景
向量语义相似度搜索自然语言查询
关键词传统 BM25 文本搜索精确词条匹配
混合向量 + 关键词组合综合最佳效果

检索参数​

参数范围默认值描述
top_k1-105返回结果数量
score_threshold0.0-1.00.5最低相关度分数

所在空间与创建后授权​

普通创建默认使用个人空间，其他有权创建的空间可在“更多设置”中选择。已筛选有创建权限的团队时，创建窗口默认选择该团队，并提示继承团队权限。若无权在所选空间创建，系统会显示原因，需由您明确选择个人或其他有权空间。

创建成功后会显示“库已创建”，可立即给人员、团队等对象授权，也可稍后配置；关闭授权窗口不会删除库。部分授权失败时只重试失败项；结果不明时先核验已有授权。列表刷新失败可单独重试，不必重新创建。角色选择和权限限制沿用现有规则。

⚙️ 检索配置​

配置说明​

检索配置决定如何从知识库中查找信息：

  1. 检索器：选择后端搜索服务
  2. 嵌入模型：选择文本向量化模型
  3. 检索模式：向量、关键词或混合
  4. 参数调整：top_k、score_threshold 等

无 RAG 模式​

您可以在不配置检索器的情况下创建和使用知识库。在此模式下，AI 使用浏览工具（kb_ls、kb_head）来查看文档内容，而不是语义搜索。

直注入补充路径​

对于内容规模较小的知识库，系统可能会使用 all-chunks 路径直接读取整库 chunks，再交给模型处理。这条路径主要用于补足向量检索在部分场景下召回不稳定的问题，尤其适合需要整体归纳、诊断、总结的提问。

更多说明见 检索与直注入。

🧪 检索测试​

检索测试功能允许您在保存配置前测试检索效果。

使用检索测试​

  1. 在知识库页面点击 检索测试 按钮
  2. 输入测试查询
  3. 选择检索模式（向量/关键词/混合）
  4. 调整参数：
    • score_threshold：相关度阈值
    • top_k：返回结果数量
  5. 查看检索结果和相关度分数

🤖 与智能体集成​

在对话中选择知识库​

与智能体对话时：

  1. 点击聊天输入框附近的 上下文选择器
  2. 从选项中选择 知识库
  3. 选择您想使用的知识库
  4. 发送您的问题

智能体会搜索知识库并提供有据可依的答案。

知识库提示模式​

严格模式​

当您明确选择知识库时，AI 必须 仅基于知识库内容回答，不能使用通用知识。

宽松模式​

当知识库从任务上下文继承时，AI 将知识库作为 可选资源，可以回退到通用知识。

📑 引用机制​

引用格式​

AI 响应包含链接到源文档的编号引用：

根据您的产品文档 [1]，该功能的工作方式是...
此外，故障排除指南 [2] 建议...

来源：
[1] product-overview.pdf（第 3 节）
[2] troubleshooting-guide.md（分块 15）

查看源内容​

  1. 点击响应中的引用编号
  2. 查看原始分块内容
  3. 查看周围上下文

📝 摘要功能​

文档摘要​

启用后，系统会自动为每个文档生成摘要，与文档元数据一起存储，可用于快速参考。

知识库摘要​

整个知识库的聚合摘要：

  • 导航到知识库设置
  • 查看所有文档的综合摘要
  • 包含核心主题标签
  • 支持手动刷新

手动编辑知识库摘要​

知识库摘要支持手动编辑，用于修正 AI 自动摘要、补充背景信息，或将摘要改写为更适合团队使用的表述。

  • 手动摘要会优先用于页面展示
  • 手动摘要会优先注入知识库对话上下文
  • AI 自动摘要仍会继续在后台更新，不会因为手动摘要而停止
  • 如果希望回到最新的 AI 摘要，可使用“恢复 AI 摘要”

注意：

  • 当前仅支持手动编辑知识库的长摘要
  • 文档摘要仍然保持自动生成
  • 关闭“自动生成摘要”后，新的自动摘要不会继续生成，但已保存的手动摘要仍可展示

📊 使用限制​

调用限制​

为防止过度 API 使用，知识库实现了调用限制：

参数范围默认值描述
maxCallsPerConversation2-5010每对话最大知识库搜索次数
exemptCallsBeforeCheck0-492限制生效前的免费调用次数

🔐 权限管理​

知识库通过 Share Service 架构支持细粒度的访问控制。您可以管理成员、分配角色，并授权外部实体（如群组）访问您的知识库。

成员角色​

角色权限
Owner（所有者）完全控制，可转移所有权并管理所有成员
Maintainer（维护者）可管理文档、设置和邀请成员
Developer（开发者）可阅读和贡献文档
Reporter（报告者）只读访问

管理成员​

从知识库列表的 权限详情、文档管理的 权限管理 或创建后的 库已创建 页面，均可使用相同的成员管理和添加流程。手机端从列表的 更多 打开权限详情。

  1. 搜索已授权协作者，查看成员及其角色；待审批申请不受搜索影响。
  2. 点击 添加协作者，按用户名或邮箱选择人员，也可搜索并选择群组。
  3. 为选中对象选择管理员、开发者、使用者或访客角色。创建者身份不可通过添加流程分配。
  4. 点击 授权。部分成功时，仅保留失败项供重试；结果不明时先核验已有授权。

成员列表支持修改角色、移除成员及处理待审批申请。仅有查看权限时，只展示自己的有效权限和来源。

创建后可以选择 完成／稍后配置，不会删除知识库。列表刷新失败可单独重试，不必重新创建或重复授权。

群组授权​

在 添加协作者 中选择群组并分配角色，该群组成员将继承对应权限；已授权群组可在管理主体的 群组 标签页查看。

注意： 通过群组授权获得的知识库显示在成员的 与我共享 区域，而非接收群组的本地知识库列表下。

权限来源可视化​

在查看成员列表时，系统会显示每个成员的访问来源：

  • 直接 — 直接添加为成员
  • 实体 — 通过群组或命名空间获得访问权限
  • 链接 — 通过分享链接获得访问权限

角色冲突解决​

当用户通过多种途径访问同一知识库（例如同时拥有直接成员身份和群组成员身份）时，系统会自动选择最高权限的角色进行冲突解决。

所有权转移​

所有者可以将知识库所有权转移给其他成员：

  1. 在 权限管理 中找到目标成员
  2. 点击其名称旁的 转移所有权
  3. 在确认对话框中确认转移

原所有者将被降级为维护者，新所有者获得完全控制权。

🔄 钉钉文档自动更新​

在新建或编辑知识库的「高级设置」中开启「自动更新钉钉文档」（默认关闭）。系统每天扫描一次，检查该库已有及以后导入的钉钉文档更新时间；已成功且可用的副本，若来源时间与已保存基线相同，或来源未给出更新时间而本地已有基线，则跳过；其余副本重新导入（含尚无基线者），且只有钉钉给出更新时间时才会建立基线。扫描固定在北京时间每天 02:00（UTC 18:00）执行；该时刻服务不可用时本轮顺延到下一次调度，不会补跑。

  • 使用每篇文档原导入人的钉钉授权；该账号须仍有效且拥有目标知识库的文档维护权限。
  • 副本继续按目标知识库权限共享。文件夹中新出现的文档不会自动导入，钉钉删除或撤权不会自动删除 Wegent 文档记录。
  • 自动更新沿用手动再次导入的处理方式：更新期间内容可能暂不可用，失败后可查看现有错误并手动重试，系统也会在后续周期再次尝试。
  • 关闭开关后，尚未开始的自动更新会跳过；已经开始的处理继续完成。手动再次导入不受开关影响。
  • 更新时间探测失败时保留当前可用副本；处理失败的副本不会因为来源时间相同而跳过重试。手动再次导入始终执行更新，并清除旧的自动判变基线。

文档列表中的钉钉副本提供「立即同步」入口，用于不等每日扫描立即重新拉取来源正文；来源不可访问或索引失败时该入口显示「重试同步」，处理期间禁用并显示「同步中」。来源已被删除或权限被收回时，副本标记为「来源不可访问」；最近一次同步失败时标记为「同步失败」。来源探测或正文读取失败时，已成功导入的副本保留原有正文与索引；新正文写入后若转换或索引失败，副本可能暂时不可用。恢复访问并同步成功后标记自动清除。

刷新正文仍要求原导入人的本地钉钉目录中存在该节点。目录记录缺失时同步会失败；请先重新同步钉钉目录，再重试副本同步。仅凭本地目录记录缺失不能判定钉钉源文件已删除。

第一版接受钉钉 MCP updateTime 的延迟：正文可能已变化而元信息时间尚未变化，导致本轮跳过；若来源此后不再给出更新时间，副本会保留已有基线并持续跳过，直到来源重新给出时间。上线后需关注不同格式的时间延迟、长期未变化的节点和实际内容新鲜度；此前在线文档实测出现过该现象，不保证下一周期必然恢复。需要立即更新时可手动再次导入，后台同步测试接口仍遵循相同的时间判变规则。

部署需要启用现有的定时任务配置 SCHEDULED_TASKS_ENABLED，并额外开启 DINGTALK_SYNC_SCHEDULE_ENABLED（默认关闭）以注册每日调度；两者都开启后运行 Celery Beat 和消费默认队列的 Worker。升级后应重启这些进程以加载新增任务。手动触发接口不依赖 DINGTALK_SYNC_SCHEDULE_ENABLED。无需数据库迁移。

测试时可使用已登录用户的授权调用 POST /api/knowledge-bases/{knowledge_base_id}/dingtalk-sync（无需请求体）。调用者须有该库管理权限，且已开启自动更新。接口只触发指定知识库，复用每日扫描和 Worker 处理逻辑，仍使用各副本原导入人的来源授权。返回 HTTP 202 和 {"task_id":"...","status":"queued"} 表示任务已排队，不代表正文更新成功；请在文档列表查看处理结果。开关关闭返回 400、管理权限不足返回 403、排队失败返回 503。此接口需要 Worker，但无需等待下一次 Beat 调度。

❓ 常见问题​

上传问题​

文件上传失败​

可能原因： 文件超过大小限制、不支持的文件格式、文件已损坏

解决方案： 检查文件大小限制（通常 50MB）、转换为支持的格式、尝试重新导出文档

检索问题​

没有返回结果​

可能原因： 查询与文档内容不匹配、分数阈值太高、文档未启用

解决方案： 尝试不同的查询措辞、降低 score_threshold、验证文档状态

🔗 相关资源​

用您自己的知识赋能 AI 智能体！ 📚