Cookie 会话：先 POST /rbac/user/up_login.dspy 登录，携带 AIOHTTP_SESSION cookie。
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?`(缺省=本机构全部知识库), `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}`
`/rag/api/kb_list.dspy`	（无参数）	`{kbs:[{id, name, description, embedding_engine, doc_count, status}], total}`（调用者可见知识库：机构隔离+检索角色过滤）
`/rag/api/embed.dspy`	`texts`*（字符串数组，单批≤10）	`{vectors:[[float,...],...], model, dim, count}`（与 ingest 同一 embedding 引擎；失败返回业务 error 不静默）

* 为必填。缺失/非法一律返回 {"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 会明确报错而非假成功。

内部助手（宿主 Agent）

不提供同进程直调通道——宿主 Agent（如产线平台）一律走 HTTP API（Bearer key）：见 wwwroot/api/README.md 与 rag/api_core.py。key 由平台 dapi 模块按用户发放，检索范围受用户机构 + 知识库 search_roles 约束。（2026-09-04 原 rag/tools.py 直调通道已删除：未投产，且与「接口统一 API 模式」冲突。）

README.md Unescape Escape

RAG 对外 API

鉴权

通用返回格式

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

调用示例

入库与检索说明

内部助手（宿主 Agent）

README.md