AI 知识库 RAG 功能 - 前端联调方案

涉及页面

API 密钥管理：ai/views/apikey/ — 管理 AI 平台 API 密钥
模型管理：ai/views/model/ — 管理 AI 模型配置（聊天、向量化等）
知识库管理：ai/views/knowledge/ — 知识库 CRUD、文档上传、分段管理、RAG 检索

业务流程与数据带入

步1: 配置 API 密钥（一次性）
  └─ 在「API 密钥管理」页配置通义千问 API Key → 获得 apiKeyId

步2: 配置向量化模型（一次性）
  └─ 在「模型管理」页新建 Embedding 模型 → keyId 从步1带入
  └─ 模型标识填 "text-embedding-v3"，平台选 "TongYi"，类型选 "EMBEDDING(5)"
  └─ 获得 embeddingModelId

步3: 创建知识库
  └─ 在「知识库管理」页新建知识库 → embeddingModelId 从步2带入
  └─ 可设置 topK 和相似度阈值

步4: 创建文档
  └─ 在知识库详情页上传文档（提供名称和 URL）
  └─ 后端自动下载文档、提取文本内容（Tika 解析）

步5: 处理文档（分段+向量化）
  └─ 在文档列表点击「处理」按钮
  └─ 后端将文档内容切片、调用向量模型生成 Embedding、写入 Milvus

步6: RAG 检索
  └─ 在知识库详情页输入检索内容 → 后端向量检索 + 相似度过滤
  └─ 返回最匹配的分段及相似度分数

API 接口

1. API 密钥管理

基础路径：/ai/api-key

方法	路径	说明
POST	`/ai/api-key/create`	创建 API 密钥
PUT	`/ai/api-key/update`	更新 API 密钥
DELETE	`/ai/api-key/delete`	删除 API 密钥
GET	`/ai/api-key/get`	获取单个 API 密钥
GET	`/ai/api-key/page`	分页查询 API 密钥

POST /create 请求参数：

参数	类型	必填	说明
name	String	是	密钥名称，如"通义千问"
apiKey	String	是	API 密钥字符串
platform	String	是	平台：`TongYi`（通义千问）
url	String	否	API 地址（一般留空）
status	Integer	否	状态：0=启用，1=禁用

响应： { "code": 0, "data": 1 } (返回密钥 ID)

2. 模型管理

基础路径：/ai/model

方法	路径	说明
POST	`/ai/model/create`	创建 AI 模型
PUT	`/ai/model/update`	更新 AI 模型
DELETE	`/ai/model/delete`	删除 AI 模型
GET	`/ai/model/get`	获取单个模型
GET	`/ai/model/page`	分页查询模型

POST /create 请求参数：

参数	类型	必填	说明
keyId	Long	是	API 密钥 ID（从上一步带入）
name	String	是	模型名称，如"通义千问向量化"
model	String	是	模型标识，向量化模型填 `text-embedding-v3`
platform	String	是	平台，固定 `TongYi`
type	Integer	是	模型类型：1=CHAT，5=EMBEDDING
sort	Integer	否	排序
status	Integer	否	状态：0=启用
temperature	Double	否	温度（Embedding 类型不需要）
maxTokens	Integer	否	最大 Token
maxContexts	Integer	否	最大上下文

模型类型枚举：

type 值	说明
1	CHAT（聊天）
5	EMBEDDING（向量化）

平台枚举：

platform	说明
TongYi	通义千问

3. 知识库管理

基础路径：/ai/knowledge

方法	路径	说明
POST	`/ai/knowledge/create`	创建知识库
PUT	`/ai/knowledge/update`	更新知识库
DELETE	`/ai/knowledge/delete`	删除知识库
GET	`/ai/knowledge/get`	获取单个知识库
GET	`/ai/knowledge/page`	分页查询知识库
POST	`/ai/knowledge/document/create`	创建文档（批量）

POST /create 请求参数：

参数	类型	必填	说明
name	String	是	知识库名称
description	String	否	知识库描述
embeddingModelId	Long	是	向量模型 ID（从模型管理页带入）
topK	Integer	否	检索返回条数，默认 3
similarityThreshold	Double	否	相似度阈值，默认 0.7
status	Integer	否	状态：0=启用

提示：创建知识库前，需要先有一个 type=5 (EMBEDDING) 的模型。前端应在选择向量模型时过滤只显示 type=5 的模型。

POST /document/create 请求参数：

参数	类型	必填	说明
knowledgeId	Long	是	知识库 ID
names	List<String>	是	文档名称列表，如 `["产品手册.pdf", "API文档.docx"]`
urls	List<String>	是	文档 URL 列表（与 names 一一对应）

4. 文档管理

基础路径：/ai/knowledge/document

方法	路径	说明
PUT	`/ai/knowledge/document/update`	更新文档
DELETE	`/ai/knowledge/document/delete`	删除文档（含分段+向量）
GET	`/ai/knowledge/document/get`	获取单个文档
GET	`/ai/knowledge/document/page`	分页查询文档
PUT	`/ai/knowledge/document/update-status`	更新文档状态
POST	`/ai/knowledge/document/process/{id}`	处理文档（分段+向量化）
GET	`/ai/knowledge/document/progress`	查询文档处理进度

PUT /update 请求参数：

参数	类型	必填	说明
id	Long	是	文档 ID
name	String	否	文档名称
url	String	否	文档 URL

POST /process/{id}：将文档内容切片并写入 Milvus 向量库。处理完才能被检索到。

GET /progress 请求参数：

参数	类型	必填	说明
documentIds	List<Long>	是	文档 ID 列表

GET /progress 响应新增字段：

字段	类型	说明
documentId	Long	文档 ID
count	Long	分段总数
embeddingCount	Long	已向量化数量

5. 分段管理 & RAG 检索

基础路径：/ai/knowledge/segment

方法	路径	说明
GET	`/ai/knowledge/segment/get`	获取单个分段
GET	`/ai/knowledge/segment/page`	分页查询分段
GET	`/ai/knowledge/segment/split`	文档切分预览（处理前预览切分效果）
PUT	`/ai/knowledge/segment/update-status`	更新分段状态
POST	`/ai/knowledge/segment/search`	RAG 向量检索（核心接口）

GET /ai/knowledge/segment/split

用于在文档处理前预览切分效果，不保存任何数据。

请求参数：

参数	类型	必填	说明
url	String	是	文档 URL
name	String	是	文档名称（用于判断文件类型）
segmentMaxTokens	Integer	否	分段最大 Token 数，默认 800

响应示例：

{
  "code": 0,
  "data": [
    {
      "content": "第一段内容...",
      "contentLength": 256,
      "tokens": 180
    },
    {
      "content": "第二段内容...",
      "contentLength": 300,
      "tokens": 210
    }
  ]
}

RAG 检索（核心功能）

POST /ai/knowledge/segment/search

请求参数：

参数	类型	必填	说明
knowledgeId	Long	是	知识库 ID
content	String	是	检索内容（自然语言）
topK	Integer	否	返回条数，默认取知识库配置的 topK
similarityThreshold	Double	否	相似度阈值，默认取知识库配置的阈值

响应：

{
  "code": 0,
  "data": [
    {
      "id": 100,
      "documentId": 10,
      "knowledgeId": 1,
      "content": "分段内容文本...",
      "contentLength": 256,
      "tokens": 180,
      "score": 0.85
    }
  ]
}

响应字段说明：

字段	类型	说明
id	Long	分段 ID
documentId	Long	所属文档 ID
knowledgeId	Long	所属知识库 ID
content	String	分段内容文本
contentLength	Integer	内容字符长度
tokens	Integer	估算 Token 数
score	Double	相似度分数（0~1），越高越相关

字段展示规则

知识库列表/详情

字段	展示位置	说明
name	列表、详情	知识库名称
description	详情	知识库描述
embeddingModel	列表、详情	显示模型标识如 `text-embedding-v3`
topK	详情	检索返回最大条数
similarityThreshold	详情	相似度阈值（0~1）
status	列表、详情	启用/禁用
createTime	列表	创建时间

文档列表/详情

字段	展示位置	说明
name	列表、详情	文档名称
url	详情	文档 URL
contentLength	详情	内容长度
tokens	详情	Token 数
retrievalCount	详情	被检索命中次数
status	列表（tag）	状态标签

分段列表

字段	展示位置	说明
documentId	列表	所属文档 ID
content	列表（截断）	分段内容（可截断显示前 100 字）
contentLength	列表	内容长度
tokens	列表	Token 数
vectorId	列表/详情	向量 ID（非空表示已向量化）
retrievalCount	列表	检索命中次数

RAG 检索结果

字段	展示位置	说明
content	结果卡片	分段全文内容
score	结果卡片	相似度分数，建议用进度条或颜色标识（>0.8 绿色，0.6~0.8 黄色，<0.6 灰色）
documentId	辅助信息	可点击跳转到来源文档
contentLength	辅助信息	内容长度

业务规则说明

场景	规则
创建文档	后端自动下载 URL 文件并提取文本。支持 `txt/md/json/xml/csv/yaml/yml`（直接读取）和其他格式（Tika 解析）
文档处理	必须先 `POST /process/{id}` 处理后，文档内容才会被检索到
文档分段	后端使用 `TokenTextSplitter` 自动切片，默认每段 800 tokens
向量写入	处理文档时自动调用 Embedding 模型生成向量并写入 Milvus
删除文档	同时删除文档记录、所有分段记录和 Milvus 中对应向量
检索相似度	返回结果按相似度降序排列，低于 `similarityThreshold` 的结果不会被返回
检索计数器	每次检索命中后，自动更新对应分段和文档的 `retrievalCount`
API 密钥	创建知识库前，必须先创建 API 密钥和 Embedding 模型

接口调用时序

创建知识库完整流程

1. POST /ai/api-key/create          → apiKeyId
2. POST /ai/model/create            → modelId (type=5, keyId=apiKeyId)
3. POST /ai/knowledge/create        → knowledgeId (embeddingModelId=modelId)
4. POST /ai/knowledge/document/create → documentIds
5. POST /ai/knowledge/document/process/{documentId} → 向量化
6. GET  /ai/knowledge/document/progress?documentIds=... → 检查进度
7. POST /ai/knowledge/segment/search → RAG 检索

检索流程（已配置好的知识库）

1. POST /ai/knowledge/segment/search
   { knowledgeId, content, topK?, similarityThreshold? }
   ↓
   后端: 查询向量 → Milvus相似度检索 → 过滤低于阈值的结果 → 更新检索计数
   ↓
   返回搜索结果列表

注意事项

知识库创建时必须选择 type=5 (EMBEDDING) 的模型，前端获取模型列表后需要过滤
文档上传后**不会自动处理**，需要在文档列表点击「处理」按钮调用 POST /process/{id}
处理进度可通过 GET /progress 轮询查询（embeddingCount >= count 表示处理完成）
检索的 similarityThreshold 建议默认 0.7，可根据实际效果调整
vectorId 为空（""）的分段表示尚未写入向量库，不会被检索到
删除知识库时，后端当前实现只删除知识库记录本身，需确认是否需要级联删除文档和分段