100 lines
6.0 KiB
Markdown
100 lines
6.0 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?`(缺省=本机构全部知识库), `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}` |
|
||
| `/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。
|
||
|
||
## 调用示例
|
||
|
||
```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 会明确报错而非假成功。
|
||
|
||
## 内部助手（宿主 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 模式」冲突。）
|