rag/wwwroot/api

RAG 对外 API

供其他系统（非 Bricks 前端）以 HTTP JSON 调用的知识库接口。与 UI 通道共用同一套 RBAC 鉴权、机构隔离与底层入库/检索实现（rag/api_core.py + rag/ingest.py）。

鉴权

二选一，均由 RBAC 中间件统一把关（端点注册为 logined 权限）：

1. Cookie 会话：先 POST /rbac/user/up_login.dspy 登录，携带 AIOHTTP_SESSION cookie。
2. Bearer API Key：Authorization: Bearer <key>。 Key 由平台 dapi 模块统一管理（downapp + downapikey 表），不在本模块自建。 发放方式：
   • UI：API Key 管理页（dapi 的 apikey_manage.ui）为目标用户按 downapp 创建；
   • 代码：from dapi import create_user_apikey → 传入 (sor, dappid, user_id, user_orgid)， 返回 {'status','apikey',...}。create_user_apikey 内部按 (dappid,userid) 幂等， 已存在则返回现有 key。
   • 校验链：register_auth_method('Bearer ', bearer_auth) 在 load_dapi() 时挂载； key 命中后解析出绑定的 RBAC 用户与机构，org 身份与 UI 通道完全一致 （session_env(request) 统一注入），因此知识库/标签/文档天然按机构隔离。

匿名请求返回 401；跨机构访问他人 kb_id 返回业务 error（查不到即拒绝，不泄露存在性）。

通用返回格式

{"status": "ok",    "data": { ... }}
{"status": "error", "message": "原因", "data": null}

HTTP 状态码恒为 200（除鉴权失败 401），业务成败看 status 字段。

端点一览（POST，参数走 JSON body，也兼容 query）

端点	参数	返回 data
/rag/api/kb_create.dspy	name*, description?, embedding_engine?(默认 bge-m3)	{kb_id, name, embedding_engine}
/rag/api/kb_delete.dspy	kb_id*	{kb_id, documents, files_removed, ...}（级联删 chunks/向量/文件）
/rag/api/doc_upload.dspy	query: kb_id, file_name, folder_id?；body=文件原始字节（Content-Type: application/octet-stream）	{doc_id, kb_id, file_name, file_size, status:"pending", ingest:"running_in_background"}
/rag/api/doc_delete.dspy	doc_id*	{doc_id, kb_id, chunks_deleted, file_removed}
/rag/api/tag_create.dspy	kb_id, name, color?	{tag_id, name, color}（同名幂等返回已有并带 duplicate:true）
/rag/api/doc_set_tags.dspy	kb_id, doc_id, tags(名称列表) | tag_ids(ID列表)	{doc_id, added, removed, tags:[{id,name,color}]}（全量语义，空数组=清空）
/rag/api/search.dspy	query, kb_id?(缺省=本机构全部KB), top_k?(默认10), recall_k?(默认top_k3)	{results:[{chunk_id, text, score, kb_id, doc:{id,file_name,file_type,kb_id}}], total, recall, kbs_searched}

* 为必填。缺失/非法一律返回 {"status":"error","message":...}，不会产生 500。

调用示例

BASE=https://<host>/rag/api
KEY=*** 1. 建知识库
curl -s -X POST $BASE/kb_create.dspy -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' \
     -d '{"name":"标书资料库","embedding_engine":"bge-m3"}'

# 2. 上传文件（原始字节；kb_id/file_name 走 query）
curl -s -X POST "$BASE/doc_upload.dspy?kb_id=$KB&file_name=tender.pdf" \
     -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/octet-stream' \
     --data-binary @tender.pdf

# 3. 检索（上传后等待后台入库完成，status 变 done 才可被召回）
curl -s -X POST $BASE/search.dspy -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' \
     -d '{"query":"投标人资质要求","kb_id":"'$KB'","top_k":5}'

# 4. 标签：创建 + 全量设置（tags 里的新名字自动建标签；空数组=清空）
curl -s -X POST $BASE/tag_create.dspy -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"kb_id":"'$KB'","name":"技术标"}'
curl -s -X POST $BASE/doc_set_tags.dspy -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' \
     -d '{"kb_id":"'$KB'","doc_id":"'$DOC'","tags":["技术标","2026"]}'

# 5. 删除
curl -s -X POST $BASE/doc_delete.dspy -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"doc_id":"'$DOC'"}'
curl -s -X POST $BASE/kb_delete.dspy -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"kb_id":"'$KB'"}'

入库与检索说明

• doc_upload 立即返回（status:"pending"），后台 asyncio 任务完成 解析→分块→向量化→VDB upsert→chunks 落库；成功置 done， 任何失败置 failed 并把真实原因写 rag_documents.error_msg（不静默）。 文本类（txt/md/pdf/docx/pptx/xlsx/csv…）可被检索召回；图片/音视频走多模态/embedding 引擎配置。
• 检索向量引擎按知识库 embedding_engine 选择（bge-m3 在线文本 / qwen3-vl-embedding 在线多模态）， 配置在 rag_engine_configs（endpoint + RC4 加密 key）。召回后自动重排（若 rerank 引擎可用）。
• 依赖基础设施：embedding/rerank 在线 API 与 VDB 服务 （upapp.rag-vdb 的 baseurl）必须从部署机网络可达；不可达时 ingest/search 会明确报错而非假成功。

内部助手（非 HTTP）

同一套能力封装为 OpenAI function-calling schema 供宿主 Agent 直调，不绕 HTTP： 见 rag/tools.py（rag_kb_create 等 7 个）。宿主 env 需具备 db / get_user / get_userorgid / password_encode / get_module_dbname； org 由宿主注入，与 API 通道的机构隔离语义一致。