创建知识库

知识库必须归属于一个团队。创建时的两个决定最难回头：嵌入模型决定向量维度（文档处理后不可更换），可见性决定谁能在没有共享的情况下读到它。名称在团队内必须唯一。

权限与可见性

可见性在创建/编辑对话框中设置：

跨团队访问只能通过共享获得，且始终是只读的——见下文「跨团队共享（只读）」。

创建知识库

1. 前往知识库，选择创建知识库。
2. 填写基本信息：
   • 名称：1-100 字符，团队内唯一，重名会报 kb_name_exists。
   • 描述：最多 500 字符，说明用途与内容范围。
   • 团队：使用当前团队（管理后台的创建表单可指定其他团队）。
3. 选择模型：
   • 嵌入模型：团队已授权的 embedding 模型。embedding_model_id 创建后不可更改。
   • 重排序模型：可选，绑定后可在检索时对召回结果二次打分。
4. 配置分块与重排序：
   • 分块大小 chunk_size：默认 1000 字符，最小 100（界面建议上限 2000）。
   • 分块重叠 chunk_overlap：默认 100 字符，最小 0（界面建议上限 500）。
   • 自定义分隔符：可填 \n\n 等转义序列，作为硬切分边界。
   • 启用重排序：默认开启；重排序候选数 默认 10（1-100）；重排序分数阈值 默认留空（0-1）。
5. 选择可见性（private 或 team）。
6. 点击创建知识库，随后进入知识库详情页；确认状态为启用。

编辑已有知识库时，对话框额外提供启用知识库开关（关闭即 archived，归档后的知识库不参与检索）。

模型与向量维度

嵌入模型

平台 model_type = embedding 的模型，通过模型授权分配给团队后才能在创建表单中出现。知识库只引用一个嵌入模型；没有可用模型时，文档处理与检索都无法进行。

向量维度

embedding_dimension 在首批文档完成向量化时写入并固化。此后：

• 维度一致的文档正常入库；
• 维度不一致的向量写入抛出维度不匹配错误，检索请求会返回 configuration_mismatch 分类提示核对模型与索引维度；
• 更换嵌入模型不会自动重建索引，需要新建知识库或执行完整的重新处理流程。

分块与检索设置

分块的字符语义、Markdown 与纯文本差异、预览与失败重试见分块与文档处理。

跨团队共享（只读）

共享让其他团队获得对某个知识库的读取与检索能力，但不能编辑。这是唯一一种跨团队访问方式。

操作步骤

1. 在知识库列表中，把鼠标移到知识库卡片上，打开右上角 ⋯ 菜单，选择共享。
   • 该入口只对「自己团队拥有」的知识库显示，且需要团队 owner/admin 角色。
2. 在共享对话框中选择团队。
   • 候选列表来自你加入的团队，并自动排除当前团队与已共享过的团队。
   • 权限级别只有只读一个选项且不可修改。
3. 点击共享。列表出现该团队、只读徽章与「由某人共享」的说明。
4. 需要撤销时，在已共享给列表中点击该条目的删除图标并确认，对方团队的列表会立即移除该知识库。

规则与失败原因

共享后在双方列表上的标识：

• 接收方：来自 + 团队名的徽章，进入详情后所有写入入口禁用（is_owned = false）。
• 拥有方：已共享 N 个团队 徽章；徽章数量来自 shared_with_count。

通过 API 共享

# 共享给其他团队（permission 只有一个合法值 read_only）
curl -X POST "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/share" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"team_id": "TARGET_TEAM_UUID", "permission": "read_only"}'

# 查看已共享给哪些团队（仅所属团队成员可读）
curl "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/shares" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 取消共享
curl -X DELETE "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/share/$TARGET_TEAM_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

接收方要过滤列表时，GET /api/v1/knowledge-bases 支持 include_shared（默认 true）与 own_only（默认 false）；设为 include_shared=false 或 own_only=true 即可只看到自己团队的知识库。

文档管理

文档管理包括上传、处理、重新处理和删除，详细步骤见导入文档与分块与文档处理。

统计

知识库详情页顶部显示统计卡片（文档数、分块数、Token 数、各状态计数）；下拉菜单中的命中测试进入检索实验室。

GET /api/v1/knowledge-bases/{kb_id}/stats 返回：

• document_count（按实际文档数重新计算，而非缓存值）
• total_chunks、total_tokens（按文档汇总，并回写知识库缓存字段）
• documents_by_status、documents_by_type
• embedding_dimension 与 embedding_stats

故障排除

文档处理失败

1. 确认文件格式受支持、文件未损坏、大小未超限。
2. 打开文档详情查看错误信息，确认是提取、切分还是嵌入阶段失败。
3. 常见原因与处理：

检索无结果或结果无关

1. 确认文档状态为 completed。
2. 用命中测试验证分数：0 条结果时先降低 score_threshold，再切换检索模式。
3. 检查知识库是否被 Agent 关联参数覆盖（Agent 上的 retrieval_top_k、score_threshold、search_mode）。
4. 检查向量库与 pg_search 是否健康；必要时重新处理文档。

成本或性能异常

• 成本偏高：减少不必要的重新处理，优化分块（更大的分块、更少的重叠），换用更经济的嵌入模型，删除冗余文档。
• 检索慢：降低 top_k、对简单查询关闭重排序、缩小文档范围，并检查向量库资源。

最佳实践

• ✅ 名称写清楚内容范围，避免「文档」「资料」这类无信息量的名字。
• ✅ 先用默认分块（1000/100）跑通一条代表性文档，再用命中测试对比调整。
• ✅ 定期清理过期文档；重复内容会互相竞争排名。
• ✅ 私有知识库只用于个人草稿；团队共用的内容用 team 可见性。
• ❌ 不要指望手工「添加元数据」提升检索——metadata 由处理管线自动生成，没有编辑入口。
• ❌ 不要在生产环境直接更换嵌入模型，也不要跳过检索验证直接放大分块。

API 访问

通过 API 管理知识库，端点清单见 知识库 API。知识库端点只接受已登录用户的 JWT 会话（Authorization: Bearer <ACCESS_TOKEN>），不接受 clou_ 开头的 API Key。

# 列出知识库 — 支持 team_id、search、status、own_only、include_shared
kbs = api.get("/api/v1/knowledge-bases", params={"team_id": "team-123", "include_shared": True})

# 为团队创建知识库
kb = api.post("/api/v1/knowledge-bases", json={
    "name": "Product Docs",
    "team_id": "team-123",
    "embedding_model_id": "model-456",
    "visibility": "team",
    "settings": {"chunk_size": 1000, "chunk_overlap": 100, "rerank_enabled": True}
})

# 上传文档
with open("document.pdf", "rb") as f:
    doc = api.post(
        f"/api/v1/knowledge-bases/{kb_id}/documents/upload",
        files={"file": f}
    )

# 检索知识库
results = api.post(f"/api/v1/knowledge-bases/{kb_id}/search", json={
    "query": "How to reset password?",
    "top_k": 5
})

文档处理 API：

相关页面

• 导入文档 — 上传、URL 导入与失败重试
• 分块与文档处理 — 预览、处理与编辑分块
• 浏览文档与元数据 — 共享徽章与系统字段
• 检索与质量调优 — 检索实验室与诊断
• 知识库设置参考 — 全部字段与限制