vault backup: 2026-04-29 10:08:12

2026-04-29 10:08:12 +08:00
parent 93736b5495
commit 5d42988185
6 changed files with 292 additions and 145 deletions
--- a/美洽AI/Rag/RAG对外接口文档.md
+++ b/美洽AI/Rag/RAG对外接口文档.md
@@ -0,0 +1,222 @@
+
+本文档对应以下 3 个内部接口：
+
+- `POST /rag/index`
+- `POST /rag/query`
+- `POST /rag/delete`
+
+baseURL: http://api-gateway.meiqia.cn/openapi/
+
+请求头使用：
+
+```http
+Content-Type: application/json
+OrgName: {org_name}
+Token: {token}
+```
+org_name和token一一对应
+org_name枚举：meiqia、laigu
+token等开发之后会提供
+
+## 通用响应格式
+
+接口成功时：
+
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+说明：
+
+- 成功时 HTTP 状态码通常为 `200`
+- 如果接口返回为空，响应可能只有 `{"success": true}`
+
+接口失败时：
+
+```json
+{
+  "success": false,
+  "message": "missing required fields"
+}
+```
+
+说明：
+
+- 参数错误默认返回 `400`
+- 部分服务内部错误可能返回 `500`
+
+## 1. 索引文档
+
+### 接口地址
+
+```http
+POST /rag/index
+```
+
+### 接口说明
+
+将指定知识库文档下载后切分为 RAG chunk，并写入 RAG 检索集合。
+
+补充说明：
+
+- `file_url` 为服务端可访问的文件下载地址
+- 文件类型主要根据 `file_name` 后缀或 `file_url` 路径后缀识别
+- 当前代码中明确支持的文件类型有：`.md`、`.pdf`、`.txt`、`.docx`、`.xlsx`、`.xls`、`.csv`
+
+### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ent_id` | `int64` | 是 | 企业 ID |
+| `knowledge_id` | `string` | 是 | 知识库 ID |
+| `knowledge_doc_id` | `string` | 是 | 知识文档 ID |
+| `file_name` | `string` | 否 | 文件名，建议传真实文件名及后缀，便于识别文件类型 |
+| `file_url` | `string` | 是 | 文件下载地址 |
+
+### 请求示例
+
+```json
+{
+  "ent_id": 10001,
+  "knowledge_id": "kb_001",
+  "knowledge_doc_id": "doc_001",
+  "file_name": "产品使用手册.pdf",
+  "file_url": "https://example.com/files/doc_001.pdf"
+}
+```
+
+### 成功响应示例
+
+```json
+{
+  "success": true
+}
+```
+
+### 失败响应示例
+
+```json
+{
+  "success": false,
+  "message": "unsupported file type: .zip"
+}
+```
+
+## 2. 查询 RAG 文本
+
+### 接口地址
+
+```http
+POST 
+/rag/query
+```
+
+### 接口说明
+
+根据问题和知识库 ID 列表检索最相关的 RAG 文本片段。
+
+补充说明：
+
+- `knowledge_ids` 至少需要传 1 个
+- 当 `top_k <= 0` 时，服务端会自动使用默认值 `10`
+- 当前接口只返回文本内容，不返回分数、文档 ID、chunk 索引等元数据
+
+### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ent_id` | `int64` | 是 | 企业 ID |
+| `knowledge_ids` | `[]string` | 是 | 待检索的知识库 ID 列表 |
+| `query` | `string` | 是 | 用户查询问题 |
+| `top_k` | `int` | 否 | 返回条数，未传或小于等于 `0` 时默认取 `10` |
+
+### 请求示例
+
+```json
+{
+  "ent_id": 10001,
+  "knowledge_ids": ["kb_001", "kb_002"],
+  "query": "如何重置管理员密码？",
+  "top_k": 5
+}
+```
+
+### 成功响应示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "texts": [
+      "管理员可以在设置中心的账号安全页面重置密码。",
+      "如果开启了双重验证，重置密码后需要重新绑定验证设备。"
+    ]
+  }
+}
+```
+
+### 失败响应示例
+
+```json
+{
+  "success": false,
+  "message": "missing required fields"
+}
+```
+
+## 3. 删除文档索引
+
+### 接口地址
+
+```http
+POST /rag/delete
+```
+
+### 接口说明
+
+删除指定知识文档的索引数据。
+
+实际行为如下：
+
+- 删除指定知识文档的 RAG 索引数据
+- `knowledge_id` 不是必填
+- 当 `knowledge_id` 为空时，会按 `ent_id + knowledge_doc_id` 删除
+- 当 `knowledge_id` 不为空时，会按 `ent_id + knowledge_id + knowledge_doc_id` 精确删除
+
+### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ent_id` | `int64` | 是 | 企业 ID |
+| `knowledge_id` | `string` | 否 | 知识库 ID；传入后删除范围更精确 |
+| `knowledge_doc_id` | `string` | 是 | 知识文档 ID |
+
+### 请求示例
+
+```json
+{
+  "ent_id": 10001,
+  "knowledge_id": "kb_001",
+  "knowledge_doc_id": "doc_001"
+}
+```
+
+### 成功响应示例
+
+```json
+{
+  "success": true
+}
+```
+
+### 失败响应示例
+
+```json
+{
+  "success": false,
+  "message": "missing required fields"
+}
+```