Appearance
知识库 API 指南
知办AI 的知识库对外开放:列、查、建、上传文档、语义检索。本文按典型场景串起核心接口,并给出 curl / Python / Go 调用示例。审计场景下的 3 个跨用户接口在文末单独列。
资源标识统一使用 id / *_id;开发期字段切换要求见 API 资源标识字段切换通知。
想直接试一下?
API 在线调试 (Scalar) 顶部填 Bearer ek_...,左侧选 knowledge → Try it out。
能力总览
┌─────────────────────────────────────────────────────────┐
│ 知识库 (KB) 对外能力 │
└─────────────────────────────────────────────────────────┘
列 / 查 ┌────────────────┐
┌──────────────▶│ GET /kbs │
│ │ GET /kbs/{id} │
你的系统 └────────────────┘
│
│ 建 / 写 ┌────────────────────────────────┐
├──────────────▶│ POST /kbs │
│ │ POST /kbs/{id}/documents │
│ └────────────────────────────────┘
│
│ 读文档 ┌────────────────────────────────┐
├──────────────▶│ GET /kbs/{id}/documents │
│ │ GET /kbs/{id}/documents/{doc} │
│ └────────────────────────────────┘
│
│ RAG 检索 ┌────────────────────────────────┐
└──────────────▶│ POST /knowledge/retrieve │
│ POST /kbs/{id}/retrieve │
└────────────────────────────────┘路径前缀都是
/api/external/v1/knowledge-bases(下文简写为/kbs)。改 / 删后端暂未开放,见 API 列表 · 路线图。
鉴权与权限范围
所有 KB 接口都需要 Authorization: Bearer <token>,凭证可以是 API Key (ek_) 或 Session Token (st_),详见 鉴权与凭证。
按操作对凭证范围(scope)的要求:
| 操作 | 需要 scope |
|---|---|
| 列 / 查 / 读文档 / 检索 | tenant.kb.read |
| 创建 KB / 上传文档 | tenant.kb.write |
| 跨用户列私有 KB | tenant.kb.list_user_private |
| 跨用户读私有 KB 文档 | tenant.kb.read_user_private |
申请凭证时按最小权限勾选。
SDK 方法映射
Python SDK 的 client.kb 模块覆盖了本页全部接口,不想手写 HTTP 时直接用:
| SDK 方法 | API | 用途 |
|---|---|---|
client.kb.retrieve_associated(agent_id=..., query=...) | POST /knowledge/retrieve | 按请求中的数字员工检索其关联知识库;tenant/runtime 来自 st_ |
client.kb.list() | GET /knowledge-bases | 列出租户级知识库 |
client.kb.get(knowledge_base_id) | GET /knowledge-bases/{knowledge_base_id} | 查看知识库详情 |
client.kb.list_documents(knowledge_base_id) | GET /knowledge-bases/{knowledge_base_id}/documents | 列出文档 |
client.kb.retrieve(knowledge_base_id, query=..., top_k=...) | POST /knowledge-bases/{knowledge_base_id}/retrieve | 语义检索 |
client.kb.list_user_private(user_id) | GET /users/{user_id}/knowledge-bases | 审计场景列用户私有 KB |
SDK 安装与初始化见 租户自定义 Agent Runtime 接入。
典型场景
场景 1:外部系统同步知识库
业务系统(CRM / BI / 文档管理)想把自家数据持续推到知办AI 的知识库里。
1. 一次性:创建 KB POST /kbs (kb.write)
2. 持续:每来一份新文档:
- 上传 POST /kbs/{id}/docs (kb.write)
- 查状态 GET /kbs/{id}/docs/{doc} (kb.read)
3. 偶尔:检查 KB 文档总数 GET /kbs/{id}/documents上传后异步切片,初始
status: ingesting,几秒到几分钟后变ready。可轮询单文档详情查状态,或通过 监控运维 看后端处理队列。
场景 2:接入方 Agent 服务检索本租户知识库
接入方 Agent 服务在处理知办AI数字员工会话时,根据用户提问检索相关知识。
1. 按当前 tenant_id
换 Runtime Access Token POST /oauth/token (runtime_access + kb.read)
2. 用户提问 → 接入方 Agent 服务内部:
- 提交 agent_id + query POST /knowledge/retrieve (kb.read)
- Bus 校验 Agent 与 token tenant/runtime
聚合检索后台已关联的 KB
- 把 chunks 作为 context 喂模型
3. 模型回答用户Agent 运行时不应自己列 KB 决定知识范围。检索 body 传当前
agent_id,服务端结合st_的 tenant/runtime 做授权,并按后台装配关系返回相关 chunks。单库/kbs/{id}/retrieve继续用于外部系统或明确指定 KB 的通用集成。
场景 3:审计租户管理员查私有 KB
合规场景:租户管理员要审计某用户的私有 KB 元信息(不读内容)。
1. 拿管理员 API Key(scope=tenant.kb.list_user_private)
2. 列该用户的私有 KB GET /users/{user_id}/knowledge-bases
3. 必要时查单个 KB 详情 GET /users/{user_id}/knowledge-bases/{knowledge_base_id}
4. (需更高权限才能读文档列表) GET /users/.../documents (kb.read_user_private)跨用户接口自动写审计日志(事件
tenant.admin.user_kb_inspect),用户的「我的会话」里也能看到管理员查过。
完整接口详解
1. 按数字员工检索关联知识库(Agent 运行时入口)
POST /api/external/v1/knowledge/retrieve
接入方 Agent 服务处理数字员工会话时,传当前 agent_id + query。服务端从 Runtime Access Token(st_)读取 tenant/runtime,校验数字员工归属、发布状态和 Runtime 绑定,再按 agent_kb_bindings 聚合检索该数字员工关联的全部平台知识库和租户知识库。调用方不需要也不应该自行维护知识库 ID 列表。
该接口只接受 runtime_access 换出的 st_,并需要 tenant.kb.read(兼容 kb.read / zhiban.kb.search)scope。agent_id 不放在换取 st_ 的鉴权请求中,而是在本次检索请求中传入;若 st_ 已绑定数字员工,请求中的 agent_id 必须与 token 一致。
bash
curl -X POST -H "Authorization: Bearer st_..." \
-H "Content-Type: application/json" \
-d '{"agent_id":"agent-a1b2...","query":"年假如何折算?"}' \
https://zhiban.creditease.corp/api/external/v1/knowledge/retrievepython
r = httpx.post(
f"{BASE}/api/external/v1/knowledge/retrieve",
headers={"Authorization": f"Bearer {SESSION_TOKEN}"},
json={"agent_id": agent_id, "query": "年假如何折算?"},
)
items = r.json()["data"]["items"]
context = "\n---\n".join(item["content"] for item in items)请求字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
agent_id | string | 是 | 当前数字员工 ID;服务端按 token 中的 tenant/runtime 校验。 |
query | string | 是 | 当前问题,不能为空。 |
返回:
json
{
"success": true,
"code": 200,
"data": {
"tool_name": "zhiban.kb.search",
"query": "年假如何折算?",
"items": [
{
"reference_id": "kb:kb-a1b2...:1",
"knowledge_base_id": "kb-a1b2...",
"kb_name": "HR 制度库",
"document_id": "doc-c3d4...",
"score": 0.82,
"content": "年假折算规则..."
}
],
"sources": [],
"result_quality": "hit"
}
}数字员工没有关联知识库或没有命中时,接口返回 200 且 items=[]。
2. 列出本租户的知识库
GET /api/external/v1/knowledge-bases
返回本租户租户级知识库(不含员工个人 KB)。
bash
curl -H "Authorization: Bearer ek_a1b2..." \
https://zhiban.creditease.corp/api/external/v1/knowledge-basespython
import httpx
r = httpx.get(
"https://zhiban.creditease.corp/api/external/v1/knowledge-bases",
headers={"Authorization": f"Bearer {API_KEY}"},
)
for kb in r.json()["data"]["items"]:
print(kb["id"], kb["name"], kb["document_count"])go
req, _ := http.NewRequest("GET",
base+"/api/external/v1/knowledge-bases", nil)
req.Header.Set("Authorization", "Bearer "+apiKey)
resp, _ := http.DefaultClient.Do(req)返回:
json
{
"success": true, "code": 200, "data": {
"items": [
{
"id": "kb-a1b2...",
"name": "产品资料库",
"description": "产品白皮书 / 销售话术",
"space_kind": "tenant",
"visibility": "tenant",
"status": "active",
"document_count": 23,
"created_at": "2026-05-20T10:00:00Z"
}
]
}
}3. 创建知识库
POST /api/external/v1/knowledge-bases
外部 API 只能创建租户级 KB(个人 KB 走客户端自助)。space_kind 和 visibility 由系统强制设为 tenant。
bash
curl -X POST -H "Authorization: Bearer ek_..." \
-H "Content-Type: application/json" \
-d '{"name":"Q4 销售文档库","description":"销售话术 + 客户案例"}' \
https://zhiban.creditease.corp/api/external/v1/knowledge-basespython
r = httpx.post(
f"{BASE}/api/external/v1/knowledge-bases",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"name": "Q4 销售文档库", "description": "销售话术 + 客户案例"},
)
kb = r.json()["data"]
print("created:", kb["id"])go
body := strings.NewReader(`{"name":"Q4 销售文档库","description":"销售话术 + 客户案例"}`)
req, _ := http.NewRequest("POST", base+"/api/external/v1/knowledge-bases", body)
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)请求字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 知识库名称。 |
description | string | 否 | 知识库描述。 |
返回:
json
{
"success": true,
"code": 200,
"data": {
"id": "kb-a1b2...",
"name": "Q4 销售文档库",
"description": "销售话术 + 客户案例",
"space_kind": "tenant",
"visibility": "tenant",
"status": "active",
"document_count": 0,
"created_at": "2026-06-23T10:00:00Z"
}
}4. 查看知识库详情
GET /api/external/v1/knowledge-bases/{knowledge_base_id}
bash
curl -H "Authorization: Bearer ek_..." \
https://zhiban.creditease.corp/api/external/v1/knowledge-bases/kb-a1b2...python
r = httpx.get(
f"{BASE}/api/external/v1/knowledge-bases/{knowledge_base_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
print(r.json()["data"])入参:
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
knowledge_base_id | path | string | 是 | 知识库 ID。 |
返回:知识库对象,字段同“列出本租户的知识库”的 data.items[]。
5. 列出知识库的文档
GET /api/external/v1/knowledge-bases/{knowledge_base_id}/documents
bash
curl -H "Authorization: Bearer ek_..." \
https://zhiban.creditease.corp/api/external/v1/knowledge-bases/kb-a1b2.../documentspython
r = httpx.get(
f"{BASE}/api/external/v1/knowledge-bases/{knowledge_base_id}/documents",
headers={"Authorization": f"Bearer {API_KEY}"},
)
for doc in r.json()["data"]["items"]:
print(doc["id"], doc["title"], doc["status"], doc["chunk_count"])入参:
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
knowledge_base_id | path | string | 是 | 知识库 ID。 |
返回:
json
{
"success": true, "code": 200, "data": {
"items": [
{
"id": "doc-...",
"knowledge_base_id": "kb-a1b2...",
"title": "产品白皮书 v3.pdf",
"mime_type": "application/pdf",
"size_bytes": 2048576,
"chunk_count": 87,
"status": "ready",
"created_at": "2026-05-20T10:30:00Z"
}
]
}
}6. 上传文档
POST /api/external/v1/knowledge-bases/{knowledge_base_id}/documents
支持两种格式,multipart 推荐(带文件名):
bash
curl -X POST -H "Authorization: Bearer ek_..." \
-F "file=@./Q4-report.pdf" \
-F "title=Q4 季报" \
-F "mime_type=application/pdf" \
https://zhiban.creditease.corp/api/external/v1/knowledge-bases/kb-a1b2.../documentsbash
curl -X POST -H "Authorization: Bearer ek_..." \
-H "Content-Type: application/pdf" \
--data-binary "@./Q4-report.pdf" \
"https://zhiban.creditease.corp/api/external/v1/knowledge-bases/kb-a1b2.../documents?title=Q4%20%E5%AD%A3%E6%8A%A5&mime_type=application/pdf"python
with open("Q4-report.pdf", "rb") as f:
r = httpx.post(
f"{BASE}/api/external/v1/knowledge-bases/{knowledge_base_id}/documents",
headers={"Authorization": f"Bearer {API_KEY}"},
files={"file": ("Q4-report.pdf", f, "application/pdf")},
data={"title": "Q4 季报"},
)
doc = r.json()["data"]
print("uploaded:", doc["id"], "status:", doc["status"]) # ingestinggo
var buf bytes.Buffer
w := multipart.NewWriter(&buf)
fw, _ := w.CreateFormFile("file", "Q4-report.pdf")
data, _ := os.ReadFile("Q4-report.pdf")
fw.Write(data)
w.WriteField("title", "Q4 季报")
w.Close()
req, _ := http.NewRequest("POST", base+"/api/external/v1/knowledge-bases/"+kbID+"/documents", &buf)
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", w.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)入参:
| 参数 / 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
knowledge_base_id | path | string | 是 | 知识库 ID。 |
file | multipart | file | multipart 方式必填 | 上传文件内容。 |
title | multipart 或 query | string | 否 | 文档标题;未传时通常使用文件名。 |
mime_type | multipart 或 query / header | string | 否 | MIME 类型;裸 body 方式建议通过 query 或 Content-Type 提供。 |
返回:
json
{
"success": true,
"code": 200,
"data": {
"id": "doc-c3d4...",
"knowledge_base_id": "kb-a1b2...",
"title": "Q4 季报",
"mime_type": "application/pdf",
"size_bytes": 2048576,
"chunk_count": 0,
"status": "ingesting",
"created_at": "2026-06-23T10:30:00Z"
}
}注意
- 文件大小上限 4 MiB
- 上传异步切片,初始
status: ingesting,完成后变ready;轮询单文档详情查进度 - MIME 类型不识别会失败(如纯图扫描件需先 OCR)
7. 查看文档详情
GET /api/external/v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}
用来轮询上传后的切片状态。
bash
curl -H "Authorization: Bearer ek_..." \
https://zhiban.creditease.corp/api/external/v1/knowledge-bases/kb-a1b2.../documents/doc-c3d4...python
import time
while True:
r = httpx.get(
f"{BASE}/api/external/v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
doc = r.json()["data"]
if doc["status"] == "ready":
print("ingested:", doc["chunk_count"], "chunks")
break
if doc["status"] == "failed":
raise Exception("ingest failed")
time.sleep(2)入参:
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
knowledge_base_id | path | string | 是 | 知识库 ID。 |
document_id | path | string | 是 | 文档 ID。 |
返回:文档对象,字段同“列出知识库的文档”的 data.items[]。
8. 检索指定知识库(通用集成)
POST /api/external/v1/knowledge-bases/{knowledge_base_id}/retrieve
给一个 query,返回指定知识库中 top-K 最相关的 chunks。该接口用于外部系统或明确指定某个知识库的通用集成;数字员工运行时应使用上面的 POST /knowledge/retrieve,由服务端按 agent_id 聚合已关联知识库。
bash
curl -X POST -H "Authorization: Bearer ek_..." \
-H "Content-Type: application/json" \
-d '{"query":"年假规定","top_k":5,"threshold":0.3}' \
https://zhiban.creditease.corp/api/external/v1/knowledge-bases/kb-a1b2.../retrievepython
def retrieve(query, knowledge_base_id, top_k=5):
r = httpx.post(
f"{BASE}/api/external/v1/knowledge-bases/{knowledge_base_id}/retrieve",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"query": query, "top_k": top_k, "threshold": 0.2},
)
return r.json()["data"]["chunks"]
# 拼到 prompt 里喂模型
chunks = retrieve("年假规定", knowledge_base_id="kb-a1b2...")
context = "\n---\n".join(c["content"] for c in chunks)
prompt = f"基于以下知识库内容回答问题:\n{context}\n\n用户问题:{user_question}"请求字段:
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
query | string | — | 必填,用户提问 / 查询关键词 |
top_k | int | 5 | 返回多少条 chunk,建议 1-20 |
threshold | float | 0.2 | 相似度阈值;小于此值的 chunk 不返回 |
rerank | bool | false | 是否走二次重排(提升相关性,可选) |
返回:
json
{
"success": true, "code": 200, "data": {
"knowledge_base_id": "kb-a1b2...",
"total": 3,
"chunks": [
{
"content": "员工每年享有 10 天带薪年假,可在任何时段使用...",
"document_id": "doc-...",
"document_title": "员工手册.pdf",
"similarity": 0.87
},
{ "...": "..." }
]
}
}调优技巧
- 检索效果不佳时,先试调高
top_k(多给模型一些上下文),再调threshold - query 写得越具体效果越好(「年假规定」 优于 「年假」)
- 启用
rerank能进一步提升精度,但延迟略增
跨用户审计接口
仅限合规审计场景使用,所有调用自动写审计日志(事件 tenant.admin.user_kb_inspect)。
列指定用户的私有 KB
GET /api/external/v1/users/{user_id}/knowledge-bases
需要 tenant.kb.list_user_private scope,只返回元信息(不含文档内容)。
入参:
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
user_id | path | string | 是 | 目标用户账号 ID。 |
bash
curl -H "Authorization: Bearer ek_..." \
https://zhiban.creditease.corp/api/external/v1/users/u-aaa.../knowledge-bases出参:data.items[] 为知识库对象,字段同“列出本租户的知识库”。
查指定用户的私有 KB 详情
GET /api/external/v1/users/{user_id}/knowledge-bases/{knowledge_base_id}
同样需要 tenant.kb.list_user_private。
入参:
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
user_id | path | string | 是 | 目标用户账号 ID。 |
knowledge_base_id | path | string | 是 | 私有知识库 ID。 |
请求示例:
bash
curl -H "Authorization: Bearer ek_..." \
https://zhiban.creditease.corp/api/external/v1/users/u-aaa.../knowledge-bases/kb-a1b2...出参:知识库对象,字段同“列出本租户的知识库”的 data.items[]。
读指定用户私有 KB 的文档列表
GET /api/external/v1/users/{user_id}/knowledge-bases/{knowledge_base_id}/documents
需要更高权限 tenant.kb.read_user_private(比上面两个范围更严)。
入参:
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
user_id | path | string | 是 | 目标用户账号 ID。 |
knowledge_base_id | path | string | 是 | 私有知识库 ID。 |
请求示例:
bash
curl -H "Authorization: Bearer ek_..." \
https://zhiban.creditease.corp/api/external/v1/users/u-aaa.../knowledge-bases/kb-a1b2.../documents出参:data.items[] 为文档对象,字段同“列出知识库的文档”。
错误处理
| HTTP | code | 含义 | 怎么处理 |
|---|---|---|---|
| 401 | invalid_api_key / invalid_session_token | 凭证不对 / 已撤销 / 过期 | 后台查凭证状态;Session Token 重新换 |
| 403 | scope_denied | 凭证范围不含目标 scope | 改 API Key 的 scope 或换一把 |
| 404 | kb.not_found | KB 不存在 / 跨租户 / 私有不可见 | 检查 knowledge_base_id 是否在本租户、可见性允许 |
| 404 | kb.document_not_found | 文档不存在 | 检查 document_id |
| 400 | invalid_params | 参数缺失或格式错 | 看 message 字段定位 |
| 413 | payload_too_large | 上传文档超过 4 MiB | 拆分文件 |
| 429 | rate_limited | 触发限流 | 退避重试,遵守 Retry-After 头 |
| 500 | internal_error | 服务端异常 | 联系运维,附上响应里的 traceId |
| 503 | service_unavailable | 后端 KB 服务(RAGFlow)不可用 | 等待 + 重试;多次失败联系运维 |
401 错误不暴露具体原因
出于安全(防爆破),401 统一返 invalid api key / invalid session token,不区分「不存在」/「过期」/「撤销」。本地排查时对照后台凭证状态。
限流与配额
| 维度 | 默认配额 |
|---|---|
| 单 API Key | 100 QPS |
| 单 Session Token | 50 QPS |
| 同租户聚合 | 500 QPS |
| 上传文档 | 单文件 4 MiB |
| 检索 top_k | 1-50 |
超限返 429 rate_limited,响应头 Retry-After 给建议退避秒数。需要更高配额联系运维提配。
最佳实践
1. 鉴权
- 生产用 HTTPS,HTTP 仅限本地测试
- API Key 放环境变量 / Vault / KMS,不要进 Git
- 按最小权限勾 scope——只读就别勾 write,只查公共 KB 就别勾跨用户
2. 上传文档
- 优先 multipart 格式(能带文件名)
- 上传后异步切片,不要同步等 200;轮询单文档详情查状态
- MIME 不识别会失败,纯图扫描件先 OCR 再传
3. 检索
- query 写具体比写宽泛好(「年假怎么请」 比 「年假」 效果好)
- 检索结果不理想时先调
top_k,再调threshold,最后试rerank - 把检索结果当作 LLM 的 context,不是答案本身——还要走模型生成
4. 错误处理
- 5xx / 429 加指数退避重试(如 1s / 2s / 4s)
- 4xx 不要重试(参数错),先看
message改请求 - 所有响应里都带
traceId,跟运维报问题时附上
5. 同步任务设计
- 长跑同步任务把进度写到自家 DB,断点续传
- 大批量上传串行或小并发(≤ 5),别一次开 100 个并发——会被限流
- 定期巡检自家 DB 的「已上传」记录和知办AI 的实际 KB 文档数对账
路线图
后端尚未实现的能力(仅 docs 不够,需要研发补):
| 能力 | 影响 | 优先级 |
|---|---|---|
PATCH /knowledge-bases/{knowledge_base_id} 改 KB 名 / 描述 | 创建后没法改名 | 中 |
DELETE /knowledge-bases/{knowledge_base_id} 删 KB | 只能客户端删,外部 API 没暴露 | 中 |
DELETE /knowledge-bases/{knowledge_base_id}/documents/{document_id} 删文档 | 误传文档无法外部删 | 高 |
| 批量上传 | 当前要逐个传 | 中 |
| 文档替换(同 ID 重传新内容) | 当前要删后重传 | 低 |
跟产品对优先级时把上面列出来。
相关链接
- API 列表 — 全部对外接口(含鉴权 / KB / 路线图)
- API 在线调试 (Scalar) — 浏览器里发请求
- OpenAPI 规范 — 机器可读 YAML
- 鉴权与凭证 — API Key vs Session Token / 错误码
- 租户自定义 Agent Runtime 接入 — 接入方 Agent 服务用 Session Token 检索 KB 的完整流程
- 知识库管理(操作手册) — 租户管理员视角
- 监控运维(操作手册) — KB 后端健康度