Appearance
租户 · 知识库（F07）
目标读者：租户管理员。 场景：在 admin web 创建租户级 KB、上传文档、配置 API Key 给外部系统、跨用户查私有 KB。
1 · 概念
| 概念 | 一句话 |
|---|---|
| 租户级 KB（tenant） | 你创建的 KB，全租户所有员工可读（销售FAQ、退款政策这种） |
| 个人 KB（personal） | 员工自己在 zhiban-app 创的 KB，仅 owner 自己可读（除非你显式勾跨用户 scope） |
| API Key | 给外部系统用 Bearer ek_xxx 程序化调 KB 的长期凭证 |
| 数字员工绑 KB | 在数字员工编辑页里勾要绑的 KB，对话时数字员工自动检索 |
2 · 创建租户级 KB
admin web → 知识库 → 新建知识库：
截图占位:新建 KB
| 字段 | 必填 | 说明 | |---|---|---| | 名称 | ✓ | 显示名，e.g. "销售退款政策" | | 描述 | ✗ | 帮助同事理解此 KB 用途 | | 图标 | ✗ | emoji 或上传 | | 空间类型 | ✓ | **选"租户级"** | | 召回参数 | ✗ | 高级用户可调 top_k / 阈值 / 是否 rerank（默认值通常够用） | 点"创建" → 后台 ~600ms 自动 provision RAGFlow dataset → 列表里 status 变 active。
3 · 上传文档
KB 详情页 → 顶部 上传 按钮：
- 支持格式：PDF / Word / Markdown / Excel / TXT 等
- 单文件 ≤ 128 MB（默认）
- 异步解析：上传后 status 进
ingesting→ ~30s/MB 解析 + 向量化 →ready - 解析失败时 status 显示
failed+ 错误信息；点"重试"重新解析
4 · 召回测试
KB 详情页顶部 召回测试 标签 → 输入一段 query → 立刻看 chunks 命中。 用于上线前验证：搜常见问题能不能找到对应文档片段。
5 · 创建 API Key（对外集成）
admin web → API Keys → 创建新 Key：
截图占位:创建 API Key
### 5.1 Scope 字典 | Scope | 含义 | 默认勾 | 触发审计？ |
|---|---|---|---|
tenant.kb.read | 列租户级 KB + 检索 | ✓ | 否 |
tenant.kb.write | 上传 / 删 KB / 文档 | ✗ | 否 |
tenant.kb.admin | = read + write + 两个 user_private | ✗ | 是（跨用户时） |
tenant.kb.list_user_private | 跨 user 查私有 KB metadata | ✗ | 每次写 audit |
tenant.kb.read_user_private | 跨 user 读私有 KB 内容（最敏感） | ✗ | 每次写 audit |
⚠️ 跨用户 scope（list_user_private / read_user_private）勾选时会弹"知情同意"对话框。 这两个 scope 让你能查任意员工的个人 KB —— 合规场景（员工离职、纠纷）必要；但同时每次调用都会写审计事件
tenant.admin.user_kb_inspect，员工有质疑权。不要给外部系统勾这两个 scope，除非业务真需要跨用户访问。
5.2 创建后
平台一次性显示完整 key：
ek_a1b2c3d4_qwertyuiopasdfghjklzxcvbnm123456关闭弹窗后此 key 不可再次查看（仅显示 ek_a1b2c3d4_****）。立即复制保存到密码管理器，给外部系统用。
5.3 撤销 / 改 scope
随时在 API Keys 列表撤销（key 立即失效）。 不能改已发 key 的 scope —— 想换 scope 就撤旧 key 创新 key。
6 · 给外部系统用 SDK 集成
完整接入指南待 F07 对外文档站章节补全。
Quick start (Python):
python
from zhiban_agent_sdk import ZhibanClient
# 用上面创的 ek_xxx
client = ZhibanClient.from_api_key(
base_url="https://zhiban.creditease.corp",
api_key="ek_a1b2c3d4_qwertyuiopasdfghjklzxcvbnm123456",
)
# 列租户级 KB
kbs = client.kb.list()
# 检索
resp = client.kb.retrieve("kb_abc", query="退款政策最长几天", top_k=5)
for chunk in resp.chunks:
print(f"[相似度 {chunk.similarity:.2f}] {chunk.content}")Quick start (Go): 见 sdks/zhiban-sdk-go/README.md。
curl 直接调：
bash
curl -X POST -H "Authorization: Bearer ek_a1b2c3d4_..." \
-H "Content-Type: application/json" \
-d '{"query":"退款政策最长几天","top_k":5}' \
https://zhiban.creditease.corp/api/external/v1/knowledge-bases/<knowledge_base_id>/retrieve7 · 跨用户查看私有 KB（D13 敏感操作）
仅在合规 / 业务必要时使用。两条路径：
7.1 通过 admin web UI
admin web → 知识库 → 顶部 跨用户查看 标签：
截图占位:跨用户查看
1. 系统弹"知情同意"对话框告知"此操作会被审计" 2. 输入目标员工的工号 / 邮箱 3. 看到该员工所有 personal KB metadata（**name / document_count，不含内容**） 4. 想看内容：点单个 KB → 弹二次确认 → 进只读 KB 详情（也写审计） 7.2 通过 API Key + SDK
需 API Key 显式勾 tenant.kb.list_user_private 或 tenant.kb.read_user_private：
python
client = ZhibanClient.from_api_key(base_url, "ek_with_user_private_scope")
private_kbs = client.kb.list_user_private("acc_alice_uuid")7.3 审计
每次调用 agent-bus 自动写入 auth_audit_events：
event_kind = 'tenant.admin.user_kb_inspect'
actor_kind = 'external_api_key' / 'admin_web'
tenant_id = 你的租户
metadata = {
"api_key_prefix": "ek_a1b2", (走 API Key 时)
"target_user_id": "acc_alice_id",
"scopes_used": ["tenant.kb.list_user_private"],
"result_count": 12
}员工可在自己的"账号安全"页查看是否被查过。
8 · 故障排查
| 现象 | 排查 |
|---|---|
| 创 KB 后一直 status=pending | 等 30s；超时看 admin web "Provider 健康"页 → 联系平台运维 |
| 上传文档 status=failed | 看 error_message；常见：文件超 128 MB / 格式不支持 |
| 召回返空 | 1. 文档解析未完 (status=ingesting)？等几分钟 2. query 太冷僻？尝试不同关键词 3. 检查 KB 默认 threshold 是不是太严 |
| API Key 调用返 401 | key 被撤销 / 创建时密码复制错；admin web 重看 prefix 比对 |
API Key 调用返 403 scope_denied | key 没勾足够 scope；撤旧创新 |
API Key 调用返 503 kb.provider_degraded | RAGFlow 不可用；联系平台运维 |
9 · 关联文档
- F07 spec 完整版（设计/契约/数据模型）
- API Key 管理通用指南（F01 §3.5 跨 feature 通用）
- 对外 API OpenAPI（程序员对接用）
- 终端用户：
docs/handbook/end-user/knowledge-base.md