guxz/my-springboot-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1.修复创建多个向量库

Browse Source
This commit is contained in:
guxz
2026-06-09 13:34:21 +08:00
parent 6cdb38df68
commit f3543f4188
74 changed files with 19636 additions and 3514 deletions
Download Patch File Download Diff File Expand all files Collapse all files

331
docs/完整接口文档.md
View File

@@ -5,8 +5,8 @@
| 项目 | 内容 |
| ---------- | ------------------ |
| **文档名称** | 知识库管理系统完整接口文档 |
| **版本号** | V2.15.0 |
| **发布日期** | 2026-05-29 |
| **版本号** | V2.16.0 |
| **发布日期** | 2026-06-05 |
| **文档状态** | 正式发布 |
| **接口基础路径** | `/api` |
| **认证方式** | Bearer Token (JWT) |
@@ -656,24 +656,264 @@ Authorization: Bearer <token>
### 6.3 流式事件类型
| 事件类型 | 说明 |
| ------------- | --------- |
| start | 对话开始事件 |
| connected | RAG服务连接成功 |
| thinking | AI思考中 |
| searching | 知识库检索中 |
| sources | 检索到的来源信息 |
| chunk | 流式内容片段 |
| result/finish | 最终结果 |
| error | 错误信息 |
| 事件类型 | 说明 |
| ------------- | ------------------------------------------------------------ |
| start | 对话开始事件 |
| connected | RAG服务连接成功 |
| thinking | AI思考中 |
| searching | 知识库检索中 |
| sources | 检索到的来源信息（仅前端展示用，**不写入引用表**） |
| chunk | 流式内容片段 |
| result/finish | 最终结果（包含 answer / citations / images，将写入数据库） |
| error | 错误信息 |
**finish 事件核心字段说明**：
| 字段 | 类型 | 说明 |
| ------------ | -------- | ------------------------------------------------------------ |
| answer | String | AI生成的回答文本（含 `[ref:chunk_id]` 引用标记，前端可解析为可点击引用） |
| citations | Array | 真正被引用的切片列表，将写入 `context_reference` 表；每个元素包含 `chunk_id`、`chunk_index`、`source`、`collection`、`doc_type`、`section`、`chunk_type`、`page` 等字段 |
| images | Array | 回答中包含的图片列表，将写入 `context_image` 表；每个元素包含 `image_id`、`url`、`source`、`page`、`section`、`description`、`score`、`collection` 等字段 |
| duration_ms | Integer | 回答耗时（毫秒），写入 `context_message.duration_ms` |
**重要数据流程（保存时自动执行）**：
1. **context_reference.preview 自动填充**：对 `citations` 中每个引用，系统自动调用 RAG 预览接口 `GET /documents/{path}/preview?chunk_index=N&context=0`，将目标切片的完整正文写入 `preview` 字段，供前端定位展示。若接口失败，`preview` 写入失败信息。
2. **context_message 无 sources 字段**：旧版 `sources` 已移除，仅在流式事件中返回来源提示信息用于前端展示。
3. **context_image 字段精简**：仅保留 `image_id`、`path`、`source`、`page`、`section`、`chunk_type`、`description`、`score`、`collection`、`create_time`；已移除 `filename`、`size_bytes`、`format`、`page_end`、`type`、`full_description` 等冗余字段。
---
## 七、AI数据接口
## 七、AI 会话管理接口
**基础路径**：`/api/ai`
### 7.1 获取用户会话列表
**接口路径**: `GET /api/ai/sessions?page=1&pageSize=10`
**请求参数**:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| page | Integer | 否 | 1 | 页码 |
| pageSize | Integer | 否 | 10 | 每页数量 |
**返回结构**:
```json
{
"success": true,
"data": [
{
"id": 1,
"sessionId": "sess_1780410472658_9qg9a9hhp",
"userId": 1,
"createTime": "2026-06-02T14:27:53"
}
],
"total": 5,
"page": 1,
"pageSize": 10,
"pages": 1
}
```
---
### 7.2 获取会话详情
**接口路径**: `GET /api/ai/session/{sessionId}?page=1&pageSize=20`
**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sessionId | String | 是 | 会话ID |
**请求参数**:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| page | Integer | 否 | 1 | 页码 |
| pageSize | Integer | 否 | 20 | 每页消息数 |
**返回结构**:
```json
{
"success": true,
"data": [
{
"id": 175,
"conversationId": 65,
"role": "assistant",
"content": "用户问: xxx",
"messageType": "rag",
"isFinished": 1,
"answer": "根据参考资料...",
"images": "[{\"image_id\":\"xxx\",\"url\":\"/api/image/xxx/data\"}]",
"durationMs": 75512,
"createTime": "2026-06-02T14:29:09"
}
],
"total": 3,
"page": 1,
"pageSize": 20,
"pages": 1
}
```
**说明**：`context_message` 无 `sources` 字段；图片信息在 `images` 字段中（JSON数组字符串）。
---
### 7.3 获取消息文件来源列表
**接口路径**: `GET /api/ai/message/{messageId}/sources`
**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| messageId | Long | 是 | 消息ID（来自 context_message.id） |
**返回结构**（按文档名称聚合，去重显示）:
```json
{
"success": true,
"data": [
{
"docName": "1.docx",
"docType": "other",
"referenceCount": 5,
"pages": "1-86"
},
{
"docName": "2.docx",
"docType": "other",
"referenceCount": 3,
"pages": "1"
}
],
"total": 2
}
```
**说明**：此接口从 `context_reference` 表按文档聚合查询，不依赖已移除的 `context_message.sources` 字段。
---
### 7.4 获取消息引用信息
**接口路径**: `GET /api/ai/message/{messageId}/references?docName=xxx`
**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| messageId | Long | 是 | 消息ID |
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| docName | String | 否 | 按文档名称过滤 |
**返回结构**:
```json
{
"success": true,
"data": [
{
"id": 440,
"messageId": 178,
"chunkId": "1.docx_86",
"chunkIndex": 86,
"collection": "dept_1_kb",
"docName": "1.docx",
"docType": "other",
"page": 1,
"section": "3.1 权重计算公式",
"chunkType": "text",
"excerpt": "一级指标合计权重不低于70%。",
"preview": "完整的目标切片正文内容...",
"score": 0.838,
"createTime": "2026-06-04T15:52:49"
}
],
"total": 5
}
```
**关键字段说明**：
| 字段 | 说明 |
|------|------|
| `chunkId` | 切片唯一标识，格式：`{docName}_{chunkIndex}` |
| `preview` | 目标切片完整正文（通过 RAG 预览接口自动获取），若接口失败则写入失败信息 |
| `score` | 相关性评分 |
| `excerpt` | 切片摘要内容 |
---
### 7.5 获取会话所有引用
**接口路径**: `GET /api/ai/session/{sessionId}/references`
**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sessionId | String | 是 | 会话ID |
**说明**：返回会话内所有消息关联的全部引用信息，结构同 7.4。
---
### 7.6 删除会话
**接口路径**: `DELETE /api/ai/session/{sessionId}`
**说明**：删除指定会话及其所有消息和引用数据。
---
### 7.7 批量删除会话
**接口路径**: `DELETE /api/ai/sessions/batch?ids=1,2,3`
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | String | 是 | 会话ID列表，逗号分隔 |
---
### 7.8 中断AI流式问答
**接口路径**: `POST /api/ai/chat/stop?sessionId=sess_xxx`
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sessionId | String | 是 | 会话ID |
**返回**:
```json
{
"success": true,
"message": "已中断AI回答"
}
```
---
## 八、AI数据接口
**基础路径**：`/api/ai/data`
### 7.1 获取会话消息
### 8.1 获取会话消息
**接口路径**: `GET /api/ai/data/session/{sessionId}/messages`
@@ -702,11 +942,11 @@ Authorization: Bearer <token>
---
## 八、反馈管理接口
## 九、反馈管理接口
**基础路径**：`/api/feedback`
### 8.1 提交反馈
### 9.1 提交反馈
**接口路径**: `POST /api/feedback`
@@ -886,24 +1126,27 @@ POST /api/ai/chat/stream
"answer": "根据【参考资料】...",
"images": [
{
"id": "ab77281e7913.jpg",
"score": 7.8,
"type": "chart",
"image_id": "ab77281e7913.jpg",
"path": "/api/image/ab77281e7913.jpg/data",
"source": "三峡公报_1-15页.pdf",
"page": 12,
"section": "3.1 数据图表",
"chunk_type": "image",
"description": "这是一张柱状图...",
"full_description": "这是一张柱状图，展示了...",
"url": "/images/ab77281e7913.jpg"
"score": 0.85,
"collection": "public_kb"
}
]
}
```
**步骤3：系统自动处理**
- ✅ 提取图片元数据（id, score, type, source, page, description, full_description）
- ✅ 提取图片元数据（image_id, path, source, page, section, chunk_type, description, score, collection）
- ✅ 从AI服务下载图片到本地目录
- ✅ 保存图片元数据到 `context_image` 表
- ✅ 保存图片到本地文件系统（`/tmp/img/` 或 `./img/`）
- ✅ 保存图片到本地文件系统
**已移除的旧字段**：`filename`、`size_bytes`、`format`、`page_end`、`type`、`full_description`
**步骤4：前端获取图片数据**
```bash
@@ -954,14 +1197,9 @@ images.forEach(image => {
<div className="image-info">
<p><strong>来源：</strong>{image.source}</p>
<p><strong>页码：</strong>第 {image.page} 页</p>
<p><strong>类型：</strong>{image.type}</p>
<p><strong>类型：</strong>{image.chunk_type}</p>
<p><strong>描述：</strong>{image.description}</p>
{image.full_description && (
<details>
<summary>查看完整描述</summary>
<p>{image.full_description}</p>
</details>
)}
<p><strong>相关性评分：</strong>{image.score}</p>
</div>
</div>
))}
@@ -978,8 +1216,9 @@ images.forEach(image => {
<div class="image-info">
<p><strong>来源：</strong>{{ image.source }}</p>
<p><strong>页码：</strong>第 {{ image.page }} 页</p>
<p><strong>类型：</strong>{{ image.type }}</p>
<p><strong>类型：</strong>{{ image.chunk_type }}</p>
<p><strong>描述：</strong>{{ image.description }}</p>
<p><strong>相关性评分：</strong>{{ image.score }}</p>
</div>
</div>
</div>
@@ -1000,16 +1239,19 @@ export default {
```json
{
"image_id": "图片唯一标识",
"filename": "原始文件名（可选）",
"path": "存储路径",
"size_bytes": 1024000,
"format": "图片格式（可选）",
"path": "存储路径/图片URL",
"source": "来源文档（可选）",
"page": 1,
"section": "所在章节（可选）",
"chunk_type": "切片类型（可选）如:image/table",
"description": "图片描述（可选）",
"score": 0.85,
"collection": "所属向量库（可选）"
}
```
**字段说明**：`filename`、`size_bytes`、`format`、`page_end`、`type`、`full_description` 已移除。
---
### 10.2 获取图片列表
@@ -1045,9 +1287,14 @@ export default {
**请求体**:
```json
{
"filename": "更新后的文件名（可选）",
"path": "更新后的路径（可选）",
"format": "更新后的格式（可选）"
"source": "更新后的来源文档（可选）",
"page": 2,
"section": "更新后的章节（可选）",
"chunk_type": "更新后的切片类型（可选）",
"description": "更新后的描述（可选）",
"score": 0.9,
"collection": "更新后的向量库（可选）"
}
```
@@ -2022,7 +2269,7 @@ export default {
## 二十、接口权限说明
### 20.1 权限层级
### 21.1 权限层级
| 用户类型 | 类型值 | 权限说明 |
| ----- | --- | ------------------- |
@@ -2055,7 +2302,7 @@ export default {
## 二十一、错误码详解
### 21.1 认证相关错误
### 22.1 认证相关错误
| 错误码 | 错误信息 | 解决方案 |
| --- | -------- | -------------- |
@@ -2064,7 +2311,7 @@ export default {
| 401 | Token已过期 | 请重新登录 |
| 403 | 权限不足 | 联系管理员提升权限 |
### 21.2 业务逻辑错误
### 22.2 业务逻辑错误
| 错误码 | 错误信息 | 解决方案 |
| --- | -------------------- | -------------- |
@@ -2077,7 +2324,7 @@ export default {
## 二十二、使用限制
### 22.1 通用限制
### 23.1 通用限制
| 限制项 | 限制值 | 说明 |
| -------- | ---- | ----------- |
@@ -2087,7 +2334,7 @@ export default {
| 每页最大记录数 | 100 | 超过后建议优化查询 |
| Token有效期 | 24小时 | 登录Token有效期 |
### 22.2 频率限制
### 23.2 频率限制
| 接口类型 | 限制 | 时间窗口 |
| ------- | ---- | ---- |