8744ade474
- 鉴权：cookie 会话 或 dapi Bearer key（load_dapi 注册，RBAC logined 统一把关） - 返回格式、参数、示例；标注 VDB/embedding 网络可达为运行前置
98 lines
5.5 KiB
Markdown
98 lines
5.5 KiB
Markdown
# 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（查不到即拒绝，不泄露存在性）。
|
||
|
||
## 通用返回格式
|
||
|
||
```json
|
||
{"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_k*3) | `{results:[{chunk_id, text, score, kb_id, doc:{id,file_name,file_type,kb_id}}], total, recall, kbs_searched}` |
|
||
|
||
`*` 为必填。缺失/非法一律返回 `{"status":"error","message":...}`，不会产生 500。
|
||
|
||
## 调用示例
|
||
|
||
```bash
|
||
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 通道的机构隔离语义一致。
|