知识库 API · RAG 检索与问答

鉴权与限流

所有数据接口需携带请求头 Authorization: Bearer <token>，Token 由管理员在「知识生产 → 对外 API」发放； 限流 60 次/分钟/IP，超限返回 429。站内已登录账号免 Token。

POST /api/kb/v1/search — 向量检索

curl -s https://data.straightship.com/api/kb/v1/search \
  -H "Authorization: Bearer $KB_TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"美森快船限重","top_k":5}'

返回 hits[]：text 命中片段、title 所属文档、score 相似度(0~1)、doc_id/source/seq 定位信息。 可选 doc_id 限定单篇文档、tags（如 ["LTL"]）按产品标签过滤。 每条命中另含 track（raw 原文 / wiki 整理稿）、heading_path（所在章节）、 ktype（知识类型）、tags；顶层 refused=true 表示知识库未覆盖该问题（相关度低于阈值）。

POST /api/kb/v1/ask — RAG 问答

curl -s https://data.straightship.com/api/kb/v1/ask \
  -H "Authorization: Bearer $KB_TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"电池货运有什么要求？","top_k":5}'

返回 answer（依据检索片段生成的回答）+ sources[]（引用来源）+ hits[]（完整片段）。知识库未覆盖的内容会明确说明，不编造；此时 refused=true、hits 为空。

内容范围：只返回经人工审核发布的知识条目；审核中的新内容不会出现在对外接口里。

GET /api/kb/v1 — 服务发现

免 Token 探活（开启后）：返回服务名、端点清单与当前向量条数。