RAG 应用 API 接口文档

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

概述

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

基础信息

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

认证方式

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

Authorization: Bearer {your_token}

或

X-API-Key: {your_api_key}

应用调用接口

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

发送对话消息

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

POST /chat/{appId}

路径参数:

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

请求参数:

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

请求示例:

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
  }'

响应示例（非流式）:

{
    "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) 方式推送数据：

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]

错误响应:

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

获取对话历史

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

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

路径参数:

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

响应示例:

{
    "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"
            }
        ]
    }
}

删除对话会话

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

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

响应示例:

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

知识库检索接口

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

单一知识库检索

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

POST /knowledge/{knowledgeId}/search

路径参数:

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

请求参数:

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

请求示例:

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
  }'

响应示例:

{
    "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 节"
                }
            }
        ]
    }
}

多知识库联合检索

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

POST /knowledge/search

请求参数:

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

请求示例:

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
  }'

响应示例:

{
    "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
                    }
                ]
            }
        ]
    }
}

获取知识库文档列表

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

GET /knowledge/{knowledgeId}/documents

查询参数:

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

响应示例:

{
    "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 示例

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 示例

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 模式

API.md 14 KB 文件歷史 原始文件

RAG 应用 API 接口文档

概述

基础信息

认证方式

应用调用接口

发送对话消息

获取对话历史

删除对话会话

知识库检索接口

单一知识库检索

多知识库联合检索

获取知识库文档列表

错误码说明

使用示例

Python 示例

JavaScript 示例

API.md 14 KB

文件歷史原始文件