222 lines
4.0 KiB
Markdown
222 lines
4.0 KiB
Markdown
|
||
本文档对应以下 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"
|
||
}
|
||
``` |