豆包知识库如何开启API接口供外部调用？
功能定位与版本演进
豆包知识库API（Knowledge Base API，官方简称 KB-API）面向需要将「深度搜索 2.0」与「智能体商店」内容外接到自有系统的开发者。与 2025 年开放的「对话 API」相比，KB-API 额外提供分钟级头条索引、256k 上下文缓存、以及按引用颗粒度计费的账单模型。截至当前的最新版本（v5.4.0）仅对完成企业认证的主体开放，个人账号可在「体验沙盒」中调试，但 QPS 与额度均受限。
经验性观察：KB-API 的延迟表现与「深度搜索 2.0」是否开启「12 引擎并行」强相关。关闭并行时，首包返回时间约缩短 30%，但引用数量同步下降；若对实时性要求高于溯源完整度，建议优先关闭并行。
准入检查：账号、额度与合规
1. 企业认证路径
桌面端：右上角头像 → 设置 → 账号安全 → 企业认证 → 上传营业执照 + 法人身份证正反面 → 审核平均 2 小时。移动端入口隐藏较深：我的 → 设置 ⚙️ → 账号与安全 → 企业认证（位于菜单底部）。
2. 服务协议与数据合规
KB-API 默认返回带引用链接的 JSON，若用于公网展示，需在「合规中心」勾选「自动添加引用免责声明」，否则可能因版权投诉被强制下线。勾选后，豆包会在每条引用前追加「内容来源：xxx，版权归原作者」字样。
开启流程（最短路径）
桌面端操作
- 登录企业账号 → 左侧导航栏「开发者中心」→「知识库 API」→「立即开通」。若未看到该卡片，说明账号未通过企业认证。
- 阅读《KB-API 特别条款》→ 勾选「已阅读并同意」→ 点击「下一步」。
- 在「接口范围」页选择所需模块：A. 深度搜索 2.0；B. 智能体商店付费内容；C. AI 记忆云（跨设备长记忆）。模块 B 需额外确认「第三方付费分成比例」，默认 3:7（开发者 7）。
- 生成密钥对：系统提供「Access Key」+「Secret Key」→ 点击「下载 CSV」保存，关闭弹窗后 Secret Key 不再显示。
- 切换到「额度与告警」标签 → 设置日调用上限（默认 5 万次）→ 添加告警阈值（80% 与 95% 两档）。
移动端操作
由于屏幕限制，仅提供只读面板。路径：我的 → 开发者 → 知识库 API →「申请开通」按钮将引导跳转到桌面端网页，建议直接在 PC 完成。
鉴权方式与签名算法
KB-API 使用「短时效签名」模式：用 Secret Key 对「HTTP 方法 + 相对路径 + 时间戳」做 HMAC-SHA256，生成 Signature 后放入请求头 X-Doubao-Signature。签名有效期 900 秒，逾期返回 403。
经验性观察：若调用端与标准时间相差超过 300 秒，即使签名算法正确也会 403。建议在服务器启用 NTP 自动校时，或在代码里读取 response header Date 字段做漂移补偿。
额度模型与费用边界
| 模块 | 计费单元 | 免费额度/日 | 超额单价 |
|---|---|---|---|
| 深度搜索 2.0 | 1 次搜索请求 | 1000 | 0.015 元 |
| 智能体商店付费内容 | 1 次 Agent 调用 | 0 | 按 Agent 定价分成 |
| AI 记忆云 | 1k tokens 存储 | 500k | 0.002 元 |
注意：免费额度按自然日重置，未用完不累积；超额后系统默认「继续扣费不停服」，若需硬封顶，请在「额度与告警」里打开「超限熔断」。
代码示例：最小可运行请求
以下示例基于 Python 3.9，使用官方推荐的分页参数 page_size=10，避免一次性拉回 256k 上下文导致超时。
若返回 429，表示触发分钟级限流；可在 header 中读取 Retry-After 字段，按建议秒数退避后再重试。
常见失败分支与回退方案
- 失败：返回 401「Access Key 不存在」 → 原因：复制 CSV 时多了空格。回退：重新下载 CSV，使用 strip() 去除首尾空白。
- 失败：返回 403「Signature 无效」 → 原因：服务器时间漂移。回退：用 NTP 校准，或在代码里动态读取 response header Date 做偏移。
- 失败：返回 200 但内容为空 → 原因：query 命中「高敏感」关键词被过滤。回退：在「合规中心」申请「白名单模板」，将业务 query 预先报备。
监控与验收指标
上线前建议先跑 24 小时灰度，收集以下三项指标：①首包延迟 P95 ≤ 2.5s（深度搜索开启并行）；②引用链接可访问率 ≥ 98%；③费用告警准确率 100%（确保 80% 与 95% 两档均触达）。验收通过后再全量切换，避免额度突增导致「凌晨账单惊呆」。
不适用场景与替代方案
工作假设：若业务需要「毫秒级实时对话」，KB-API 并非最佳选项。深度搜索 2.0 即使关闭并行，首 token 延迟仍在亚秒级，无法与端侧 7B 模型 <300ms 的表现相比。
替代：可改用豆包「端侧模型离线包」或「对话 API」流式接口，后者首 token 延迟约降低 60%，但代价是失去分钟级全网索引与引用溯源。
最佳实践 10 条速查表
- 永远保存原始 CSV，Secret Key 只存于可信密钥管理服务。
- 使用 900 秒过期窗口，不要本地缓存 Signature 超过 15 分钟。
- 对高并发场景启用「超限熔断」，避免账单失控。
- 开启「引用免责声明」，减少版权投诉风险。
- page_size 建议 10~20，平衡带宽与超时。
- 若需长记忆，先调用「AI 记忆云」写入，再调用 KB-API 关联 session_id，减少重复计费。
- 监控 Retry-After 并做指数退避，降低 429 概率。
- 灰度阶段先关闭「12 引擎并行」，费用约降 25%。
- 引用链接务必在 24 小时内回测可访问性，死链超过 2% 时向官方提 ticket。
- 每月初定期轮换 Access Key，降低泄露风险。
FAQ（使用 Schema.org）
个人开发者能否开通 KB-API？
目前仅支持完成企业认证的账号。个人可在「体验沙盒」调试，但 QPS 限制为 1，日调用上限 500 次。
引用链接打不开怎么办？
关闭「省流模式」即可恢复完整 URL；若仍失败，检查是否被浏览器广告拦截插件替换。
如何关闭「12 引擎并行」以节省费用？
在请求 JSON 里将 "deep_search" 设为 false，即可回落到 3 引擎模式，单条成本约降 25%。
收尾与下一步
KB-API 的核心价值在于把「深度搜索 + 长记忆」一次性打包给外部系统，适合需要溯源、合规、且能接受亚秒级延迟的场景。完成开通后，建议先用灰度环境跑完 24 小时监控，确认费用与延迟都在预期范围，再全量切换。若你的业务对实时性要求更高，可评估「端侧模型离线包」或「对话 API」流式接口作为互补方案。
下一步：下载官方 Postman 集合，导入示例环境变量，把 Access Key 与 Secret Key 写入，跑通第一条搜索请求；随后打开「额度与告警」面板，把日上限调整到业务峰值 1.5 倍，并绑定钉钉群机器人，确保凌晨突增也能第一时间收到通知。