本文档对应以下 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"
}
```