知识库(RAG)

给喵喵一套你自己的资料:把文档传进知识库,之后调 /v1/agent 对话时,平台自动检索相关片段注入上下文——喵喵基于你的资料回答,并在流里告诉你引用了哪几段。

概念(30 秒)

上传文档

控制台「知识库」区粘贴即可;程序化走 API(Bearer key):

bash
curl -X POST "$BASE/v1/kb/docs" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "产品手册", "text": "……正文,可以很长……"}'

成功 201:

json
{ "id": "…", "title": "产品手册", "char_count": 5230, "chunk_count": 11,
  "created_at": "2026-06-12T13:00:00.000Z",
  "note": "已入库;向量索引异步生效(约数秒),稍候可检索" }

新文档生效约数秒:向量索引是异步构建的——201 表示已入库,但刚传完立刻提问可能还查不到。等几秒再问(或用 /v1/kb/search 轮询到命中)即可。

管理端点(双面同形,控制台把 /v1 换成 /console 并用登录会话):

动作端点
列文档GET /v1/kb/docs
上传POST /v1/kb/docs {title, text}
删除DELETE /v1/kb/docs/:id
检索测试POST /v1/kb/search {q} → top-5 块 + 分数

检索注入行为(对话时发生什么)

调 /v1/agent 时:

  1. 本租户没有任何文档 → 完全零开销零变化(不嵌入、不检索,行为与没有本特性时一致);
  2. 有文档 → 你的提问被嵌入,在本租户的块里查 top-5;相似度 ≥0.45 的片段(总长 ≤2000 字)以「知识库参考」块注入本轮系统提示,每段带 〔标题#块号〕 来源标注;
  3. 注入只影响当轮,不写进会话历史——下一轮按下一轮的提问重新检索;
  4. 不想用时请求体带 "kb": false(仅本轮关闭);
  5. 降级不崩:检索 / 嵌入任何环节抖动,平台直接跳过注入照常对话——知识库是增益,绝不挡你的主流程。

SSE 事件 kb_refs

命中注入时,流里会在一切 llm_* 事件之前多一帧 kb_refs(没命中就没有这帧):

code
event: kb_refs
data: {"type":"kb_refs","refs":[{"doc_id":"…","title":"产品手册","seq":3,"score":0.71}]}

删除语义

DELETE /v1/kb/docs/:id 同步删除文本与发起向量删除;删除后该文档立刻不再被检索 / 注入(文本行已删,即便残留向量短暂存在也查不出内容)。删除不可恢复。

配额(公测)

项上限超限响应
单篇正文100KB413「文档过大(单篇上限 100KB)」
每租户文档数50 篇403「文档数已达上限(每租户 50 篇)」
标题200 字400「标题过长」

实践建议