Skip to content

知识库 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
跨用户列私有 KBtenant.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/retrieve
python
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_idstring当前数字员工 ID;服务端按 token 中的 tenant/runtime 校验。
querystring当前问题,不能为空。

返回:

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"
  }
}

数字员工没有关联知识库或没有命中时,接口返回 200items=[]

2. 列出本租户的知识库

GET /api/external/v1/knowledge-bases

返回本租户租户级知识库(不含员工个人 KB)。

bash
curl -H "Authorization: Bearer ek_a1b2..." \
  https://zhiban.creditease.corp/api/external/v1/knowledge-bases
python
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_kindvisibility 由系统强制设为 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-bases
python
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)

请求字段:

字段类型必填说明
namestring知识库名称。
descriptionstring知识库描述。

返回:

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_idpathstring知识库 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.../documents
python
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_idpathstring知识库 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.../documents
bash
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"])  # ingesting
go
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_idpathstring知识库 ID。
filemultipartfilemultipart 方式必填上传文件内容。
titlemultipart 或 querystring文档标题;未传时通常使用文件名。
mime_typemultipart 或 query / headerstringMIME 类型;裸 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_idpathstring知识库 ID。
document_idpathstring文档 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.../retrieve
python
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}"

请求字段:

字段类型默认说明
querystring必填,用户提问 / 查询关键词
top_kint5返回多少条 chunk,建议 1-20
thresholdfloat0.2相似度阈值;小于此值的 chunk 不返回
rerankboolfalse是否走二次重排(提升相关性,可选)

返回:

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_idpathstring目标用户账号 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_idpathstring目标用户账号 ID。
knowledge_base_idpathstring私有知识库 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_idpathstring目标用户账号 ID。
knowledge_base_idpathstring私有知识库 ID。

请求示例:

bash
curl -H "Authorization: Bearer ek_..." \
  https://zhiban.creditease.corp/api/external/v1/users/u-aaa.../knowledge-bases/kb-a1b2.../documents

出参:data.items[] 为文档对象,字段同“列出知识库的文档”。

错误处理

HTTPcode含义怎么处理
401invalid_api_key / invalid_session_token凭证不对 / 已撤销 / 过期后台查凭证状态;Session Token 重新换
403scope_denied凭证范围不含目标 scope改 API Key 的 scope 或换一把
404kb.not_foundKB 不存在 / 跨租户 / 私有不可见检查 knowledge_base_id 是否在本租户、可见性允许
404kb.document_not_found文档不存在检查 document_id
400invalid_params参数缺失或格式错看 message 字段定位
413payload_too_large上传文档超过 4 MiB拆分文件
429rate_limited触发限流退避重试,遵守 Retry-After
500internal_error服务端异常联系运维,附上响应里的 traceId
503service_unavailable后端 KB 服务(RAGFlow)不可用等待 + 重试;多次失败联系运维

401 错误不暴露具体原因

出于安全(防爆破),401 统一返 invalid api key / invalid session token,不区分「不存在」/「过期」/「撤销」。本地排查时对照后台凭证状态。

限流与配额

维度默认配额
单 API Key100 QPS
单 Session Token50 QPS
同租户聚合500 QPS
上传文档单文件 4 MiB
检索 top_k1-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 重传新内容)当前要删后重传

跟产品对优先级时把上面列出来。

相关链接

© 知办AI Team — 开发者公开文档. 平台运维 / 内部架构文档见内部 wiki.