# RAG 应用 API 接口文档

**项目**: 建科小智开放平台
**版本**: v3.8
**最后更新**: 2026-04-02

---

## 概述

本文档介绍如何通过 API 调用 RAG 应用和知识库检索功能。

### 基础信息

- **Base URL**: `http://your-domain.com/bigmodel/api`
- **认证方式**: API Key / Token
- **数据格式**: JSON

### 认证方式

在请求头中携带认证信息：

```http
Authorization: Bearer {your_token}
```

或

```http
X-API-Key: {your_api_key}
```

---

## 应用调用接口

通过应用 ID 调用 RAG 应用，实现智能问答功能。

### 发送对话消息

向指定应用发送消息并获取回复。

```http
POST /chat/{appId}
```

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| appId | string | 是 | RAG 应用 ID |

**请求参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | - | 用户问题内容 |
| conversationId | string | 否 | - | 会话 ID（用于多轮对话） |
| userId | string | 否 | - | 用户 ID（用于区分不同用户） |
| streaming | boolean | 否 | false | 是否使用流式响应 |

**请求示例**:

```bash
curl -X POST http://your-domain.com/bigmodel/api/chat/app_001 \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "如何申请年假？",
    "userId": "user_123",
    "streaming": false
  }'
```

**响应示例**（非流式）:

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "conversationId": "conv_abc123",
        "answer": "申请年假的流程如下：\n\n1. 登录公司 OA 系统\n2. 进入\"请假申请\"页面\n3. 选择请假类型为\"年假\"\n4. 填写请假日期和天数\n5. 提交申请等待审批",
        "sources": [
            {
                "documentId": "doc_001",
                "documentName": "员工手册.pdf",
                "sliceId": "slice_001",
                "content": "员工年假申请需提前 3 个工作日在 OA 系统提交...",
                "score": 0.92
            },
            {
                "documentId": "doc_002",
                "documentName": "考勤管理制度.pdf",
                "sliceId": "slice_045",
                "content": "年假天数根据工龄计算：1-3 年 5 天，3-5 年 10 天...",
                "score": 0.85
            }
        ],
        "usage": {
            "promptTokens": 156,
            "completionTokens": 89,
            "totalTokens": 245
        }
    }
}
```

**流式响应示例**:

当 `streaming: true` 时，服务器会以 SSE (Server-Sent Events) 方式推送数据：

```text
data: {"answer": "申", "conversationId": "conv_abc123"}

data: {"answer": "请年假", "conversationId": "conv_abc123"}

data: {"answer": "的流程如下：\n\n", "conversationId": "conv_abc123"}

data: {"answer": "1. 登录 OA 系统", "conversationId": "conv_abc123"}

data: [DONE]
```

**错误响应**:

```json
{
    "code": 400,
    "message": "应用不存在或已下线",
    "data": null
}
```

---

### 获取对话历史

获取指定会话的完整对话历史。

```http
GET /chat/{appId}/history/{conversationId}
```

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| appId | string | 是 | RAG 应用 ID |
| conversationId | string | 是 | 会话 ID |

**响应示例**:

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "conversationId": "conv_abc123",
        "appId": "app_001",
        "userId": "user_123",
        "createdAt": "2026-04-02 10:30:00",
        "updatedAt": "2026-04-02 11:45:00",
        "messages": [
            {
                "id": "msg_001",
                "role": "user",
                "content": "如何申请年假？",
                "createdAt": "2026-04-02 10:30:00"
            },
            {
                "id": "msg_002",
                "role": "assistant",
                "content": "申请年假的流程如下：\n\n1. 登录公司 OA 系统\n2. 进入\"请假申请\"页面...",
                "createdAt": "2026-04-02 10:30:05",
                "sources": [
                    {
                        "documentName": "员工手册.pdf",
                        "content": "员工年假申请需提前 3 个工作日..."
                    }
                ]
            },
            {
                "id": "msg_003",
                "role": "user",
                "content": "年假有多少天？",
                "createdAt": "2026-04-02 10:31:00"
            },
            {
                "id": "msg_004",
                "role": "assistant",
                "content": "年假天数根据工龄计算：\n- 1-3 年：5 天\n- 3-5 年：10 天\n- 5-10 年：15 天",
                "createdAt": "2026-04-02 10:31:05"
            }
        ]
    }
}
```

---

### 删除对话会话

删除指定的对话会话及其所有历史记录。

```http
DELETE /chat/{appId}/history/{conversationId}
```

**响应示例**:

```json
{
    "code": 200,
    "message": "删除成功",
    "data": {
        "conversationId": "conv_abc123"
    }
}
```

---

## 知识库检索接口

直接调用知识库进行文档检索，不经过应用层。

### 单一知识库检索

在单个知识库中进行语义检索。

```http
POST /knowledge/{knowledgeId}/search
```

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| knowledgeId | string | 是 | 知识库 ID |

**请求参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | - | 检索关键词或问题 |
| topK | number | 否 | 5 | 返回结果数量（1-20） |
| scoreThreshold | number | 否 | 0.5 | 相似度阈值（0-1） |
| documentIds | array | 否 | - | 指定检索的文档 ID 列表 |

**请求示例**:

```bash
curl -X POST http://your-domain.com/bigmodel/api/knowledge/kb_001/search \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "年假申请流程",
    "topK": 10,
    "scoreThreshold": 0.7
  }'
```

**响应示例**:

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "knowledgeId": "kb_001",
        "knowledgeName": "人力资源知识库",
        "query": "年假申请流程",
        "total": 5,
        "results": [
            {
                "sliceId": "slice_001",
                "documentId": "doc_001",
                "documentName": "员工手册.pdf",
                "content": "员工年假申请需提前 3 个工作日在 OA 系统提交申请，经部门经理审批后方可休假。",
                "score": 0.92,
                "metadata": {
                    "pageNumber": 15,
                    "position": "第 3 章 第 2 节"
                }
            },
            {
                "sliceId": "slice_045",
                "documentId": "doc_002",
                "documentName": "考勤管理制度.pdf",
                "content": "年假天数根据工龄计算：1-3 年 5 天，3-5 年 10 天，5-10 年 15 天，10 年以上 20 天。",
                "score": 0.85,
                "metadata": {
                    "pageNumber": 8,
                    "position": "第 2 章 第 5 条"
                }
            },
            {
                "sliceId": "slice_112",
                "documentId": "doc_001",
                "documentName": "员工手册.pdf",
                "content": "未休年假可在当年申请折现，折现标准按日工资的 300% 计算。",
                "score": 0.78,
                "metadata": {
                    "pageNumber": 16,
                    "position": "第 3 章 第 3 节"
                }
            }
        ]
    }
}
```

---

### 多知识库联合检索

在多个知识库中进行联合语义检索。

```http
POST /knowledge/search
```

**请求参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | - | 检索关键词或问题 |
| knowledgeIds | array | 是 | - | 知识库 ID 列表 |
| topK | number | 否 | 5 | 每个知识库返回结果数量 |
| scoreThreshold | number | 否 | 0.5 | 相似度阈值 |
| rerank | boolean | 否 | false | 是否启用重排序 |

**请求示例**:

```bash
curl -X POST http://your-domain.com/bigmodel/api/knowledge/search \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "项目报销流程",
    "knowledgeIds": ["kb_001", "kb_003", "kb_005"],
    "topK": 5,
    "rerank": true
  }'
```

**响应示例**:

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "query": "项目报销流程",
        "knowledgeBaseCount": 3,
        "total": 12,
        "results": [
            {
                "knowledgeId": "kb_003",
                "knowledgeName": "财务知识库",
                "slices": [
                    {
                        "sliceId": "slice_201",
                        "documentId": "doc_050",
                        "documentName": "项目费用报销管理办法.pdf",
                        "content": "项目报销流程：1. 填写报销单 2. 附上发票和明细 3. 项目经理审批 4. 财务审核 5. 出纳付款",
                        "score": 0.95,
                        "rerankScore": 0.98
                    },
                    {
                        "sliceId": "slice_205",
                        "documentId": "doc_050",
                        "documentName": "项目费用报销管理办法.pdf",
                        "content": "差旅费报销需提供往返交通票据和住宿发票，市内交通按每天 80 元包干。",
                        "score": 0.82,
                        "rerankScore": 0.85
                    }
                ]
            },
            {
                "knowledgeId": "kb_001",
                "knowledgeName": "人力资源知识库",
                "slices": [
                    {
                        "sliceId": "slice_078",
                        "documentId": "doc_015",
                        "documentName": "员工福利手册.pdf",
                        "content": "项目奖金发放与报销是独立的流程，奖金随工资发放，报销单独走财务流程。",
                        "score": 0.71,
                        "rerankScore": 0.72
                    }
                ]
            }
        ]
    }
}
```

---

### 获取知识库文档列表

获取指定知识库中的文档列表。

```http
GET /knowledge/{knowledgeId}/documents
```

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| pageNum | number | 否 | 1 | 页码 |
| pageSize | number | 否 | 20 | 每页数量 |
| keyword | string | 否 | - | 文件名关键词 |

**响应示例**:

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "knowledgeId": "kb_001",
        "knowledgeName": "人力资源知识库",
        "total": 15,
        "pageNum": 1,
        "pageSize": 20,
        "documents": [
            {
                "documentId": "doc_001",
                "fileName": "员工手册.pdf",
                "fileSize": 2048576,
                "fileType": "pdf",
                "status": "active",
                "sliceCount": 45,
                "createdAt": "2026-01-15 09:30:00",
                "updatedAt": "2026-01-20 14:20:00"
            },
            {
                "documentId": "doc_002",
                "fileName": "考勤管理制度.pdf",
                "fileSize": 1536000,
                "fileType": "pdf",
                "status": "active",
                "sliceCount": 32,
                "createdAt": "2026-01-16 10:00:00",
                "updatedAt": "2026-01-22 11:30:00"
            }
        ]
    }
}
```

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 认证失败（Token 无效或过期） |
| 403 | 无权限访问 |
| 404 | 资源不存在（应用/知识库不存在） |
| 429 | 请求频率超限 |
| 500 | 服务器内部错误 |

---

## 使用示例

### Python 示例

```python
import requests

BASE_URL = "http://your-domain.com/bigmodel/api"
TOKEN = "your_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# 调用 RAG 应用
response = requests.post(
    f"{BASE_URL}/chat/app_001",
    headers=headers,
    json={
        "query": "如何申请年假？",
        "userId": "user_123"
    }
)
result = response.json()
print(result["data"]["answer"])

# 知识库检索
response = requests.post(
    f"{BASE_URL}/knowledge/kb_001/search",
    headers=headers,
    json={
        "query": "年假申请流程",
        "topK": 5
    }
)
result = response.json()
for item in result["data"]["results"]:
    print(f"[{item['score']:.2f}] {item['content']}")
```

### JavaScript 示例

```javascript
const BASE_URL = 'http://your-domain.com/bigmodel/api';
const TOKEN = 'your_token';

const headers = {
    'Authorization': `Bearer ${TOKEN}`,
    'Content-Type': 'application/json'
};

// 调用 RAG 应用
async function chat(appId, query, userId) {
    const response = await fetch(`${BASE_URL}/chat/${appId}`, {
        method: 'POST',
        headers,
        body: JSON.stringify({ query, userId })
    });
    const result = await response.json();
    return result.data.answer;
}

// 知识库检索
async function searchKnowledge(knowledgeId, query, topK = 5) {
    const response = await fetch(`${BASE_URL}/knowledge/${knowledgeId}/search`, {
        method: 'POST',
        headers,
        body: JSON.stringify({ query, topK })
    });
    const result = await response.json();
    return result.data.results;
}

// 使用示例
chat('app_001', '如何申请年假？', 'user_123')
    .then(answer => console.log(answer));
```

---

**备注**:
- 所有接口的 Mock 数据位于 `src/mock/` 目录下
- 在 `src/apis/api.ts` 中通过 `USE_MOCK` 标志切换 Mock/真实 API
- 生产环境请关闭 Mock 模式