162 lines
8.3 KiB
Markdown
162 lines
8.3 KiB
Markdown
---
|
||
feature_id: "ASA"
|
||
title: "AI 中台管理界面（ai-service-admin）需求规范"
|
||
status: "draft"
|
||
version: "0.3.0"
|
||
owners:
|
||
- "product"
|
||
- "frontend"
|
||
- "backend"
|
||
last_updated: "2026-02-24"
|
||
source:
|
||
type: "conversation"
|
||
ref: "Scoping Result Confirmed"
|
||
---
|
||
|
||
# AI 中台管理界面（ASA）
|
||
|
||
## 1. 背景与目标
|
||
- **背景**：随着 AI 中台（ai-service）功能的增强，需要一套专业的管理后台来支持知识库运维、Prompt 工程迭代及 RAG 效果调优。
|
||
- **目标**：提供租户维度的 AI 资产管理能力，实现 RAG 链路的可视化调试与全链路监控。
|
||
- **非目标**：不包含推理引擎实现，不包含面向 C 端的交互 UI。
|
||
|
||
## 2. 模块边界（Scope）
|
||
- **覆盖**：知识库空间与文档管理、索引任务监控、租户级 Prompt 模板版本管理、RAG 实验对比、全局会话审计。
|
||
- **不覆盖**：底层向量数据库维护、模型微调训练。
|
||
|
||
## 3. 依赖盘点（Dependencies）
|
||
- **依赖模块**：
|
||
- `ai-service`：提供所有的管理类 RESTful API（见 `openapi.admin.yaml`）。
|
||
- `RuoYi-Vue-Plus` (或类似基座)：提供用户认证、权限校验及菜单框架。
|
||
|
||
## 4. 用户故事（User Stories）
|
||
|
||
### 4.1 知识库管理
|
||
- [US-ASA-01] 作为租户管理员，我希望能够上传不同格式的文档到指定的知识空间，以便为特定的 AI 场景提供上下文。
|
||
- [US-ASA-02] 作为运维人员，我希望实时查看索引构建任务的进度和错误原因，以便及时处理构建失败的情况。
|
||
|
||
### 4.2 Prompt 工程
|
||
- [US-ASA-03] 作为 Prompt 工程师，我希望对不同场景的 Prompt 进行版本化管理，以便在效果下降时能够快速回滚。
|
||
|
||
### 4.3 RAG 效果实验室
|
||
- [US-ASA-04] 作为 AI 开发者，我希望在后台直接输入问题并查看检索到的文档分片和原始上下文，以便定位召回不准确的问题。
|
||
|
||
### 4.4 监控审计
|
||
- [US-ASA-05] 作为安全合规人员，我希望审计所有租户的会话记录，并查看单次回答的耗时与资源消耗，以便进行成本核算与安全管控。
|
||
|
||
## 5. 验收标准（Acceptance Criteria, EARS）
|
||
|
||
### 知识库管理（KB）
|
||
- [AC-ASA-01] WHEN 提交文档上传 THEN 系统 SHALL 异步启动索引任务，并返回任务 ID。
|
||
- [AC-ASA-02] WHEN 索引任务失败 THEN 系统 SHALL 在管理界面高亮显示，并提供“详细错误”查询入口。
|
||
|
||
### Prompt 管理（Prompt）
|
||
- [AC-ASA-03] WHEN 发布新版 Prompt THEN 系统 SHALL 自动将旧版标记为“历史版本”，且同一时间只有一个“已发布”版本。
|
||
- [AC-ASA-04] WHEN 编辑 Prompt 时 THEN 系统 SHALL 提供内置变量提示（如 `{{context}}`, `{{query}}`）。
|
||
|
||
### RAG 实验室（RAG Lab）
|
||
- [AC-ASA-05] WHEN 运行 RAG 实验 THEN 系统 SHALL 展示 Top-K 检索片段、得分、来源文档及最终生成的提示词。
|
||
- [AC-ASA-06] WHEN 多版本对比时 THEN 系统 SHALL 支持在同一屏幕展示不同配置下的召回差异。
|
||
|
||
### 会话监控（Audit）
|
||
- [AC-ASA-07] WHEN 查看会话详情 THEN 系统 SHALL 展示完整的消息链路，包括中间的工具调用（Tool Calls）和检索命中记录。
|
||
|
||
## 6. 追踪映射（Traceability）
|
||
|
||
| AC ID | Endpoint | 方法 | 备注 |
|
||
|------|----------|------|-----|
|
||
| AC-ASA-01 | /admin/kb/documents | POST | 上传文档并创建任务 |
|
||
| AC-ASA-02 | /admin/kb/index/jobs/{jobId} | GET | 查询任务详情与错误 |
|
||
| AC-ASA-03 | /admin/config/prompt-templates/{tplId}/publish | POST | 发布指定版本 |
|
||
| AC-ASA-05 | /admin/rag/experiments/run | POST | 触发调试实验 |
|
||
| AC-ASA-07 | /admin/sessions/{sessionId} | GET | 获取全链路详情 |
|
||
|
||
---
|
||
|
||
## 7. 迭代需求：嵌入模型管理（v0.2.0）
|
||
|
||
> 说明：本节为 v0.2.0 迭代新增，用于支持嵌入模型的界面配置与管理。
|
||
|
||
### 7.1 嵌入模型配置管理
|
||
|
||
- [AC-ASA-08] WHEN 用户访问嵌入模型配置页面 THEN 系统 SHALL 展示当前激活的嵌入模型提供者及其配置参数。
|
||
|
||
- [AC-ASA-09] WHEN 用户切换嵌入模型提供者 THEN 系统 SHALL 动态展示该提供者的配置参数表单，并保留当前配置值。
|
||
|
||
- [AC-ASA-10] WHEN 用户修改嵌入模型配置并保存 THEN 系统 SHALL 验证配置有效性，更新配置并提示操作结果。
|
||
|
||
- [AC-ASA-11] WHEN 用户点击"测试连接"按钮 THEN 系统 SHALL 调用嵌入模型生成测试向量，展示连接状态、向量维度和响应延迟。
|
||
|
||
- [AC-ASA-12] WHEN 嵌入模型连接测试失败 THEN 系统 SHALL 展示详细错误信息，帮助用户排查配置问题。
|
||
|
||
### 7.2 文档格式支持展示
|
||
|
||
- [AC-ASA-13] WHEN 用户查看嵌入模型配置页面 THEN 系统 SHALL 展示当前支持的文档格式列表（PDF、Word、Excel、TXT 等）。
|
||
|
||
### 7.3 用户故事（迭代追加）
|
||
|
||
- [US-ASA-06] 作为系统管理员，我希望在界面上配置和切换嵌入模型，以便快速适配不同的业务场景而无需修改代码。
|
||
|
||
- [US-ASA-07] 作为系统管理员，我希望在保存配置前测试嵌入模型连接，以便确保配置正确后再正式启用。
|
||
|
||
### 7.4 追踪映射（迭代追加）
|
||
|
||
| AC ID | Endpoint | 方法 | 备注 |
|
||
|------|----------|------|-----|
|
||
| AC-ASA-08 | /admin/embedding/config | GET | 获取当前配置 |
|
||
| AC-ASA-09 | /admin/embedding/providers | GET | 获取提供者列表及配置定义 |
|
||
| AC-ASA-10 | /admin/embedding/config | PUT | 更新配置 |
|
||
| AC-ASA-11 | /admin/embedding/test | POST | 测试连接 |
|
||
| AC-ASA-12 | /admin/embedding/test | POST | 测试失败错误展示 |
|
||
| AC-ASA-13 | /admin/embedding/formats | GET | 获取支持格式 |
|
||
|
||
---
|
||
|
||
## 8. 迭代需求：LLM 模型配置与 RAG 调试输出（v0.3.0）
|
||
|
||
> 说明：本节为 v0.3.0 迭代新增，用于支持 LLM 模型的界面配置及 RAG 实验室的 AI 输出调试。
|
||
|
||
### 8.1 LLM 模型配置管理
|
||
|
||
- [AC-ASA-14] WHEN 用户访问 LLM 模型配置页面 THEN 系统 SHALL 展示当前激活的 LLM 提供者及其配置参数（API Key、Base URL、模型名称等）。
|
||
|
||
- [AC-ASA-15] WHEN 用户切换 LLM 提供者 THEN 系统 SHALL 动态展示该提供者的配置参数表单，并保留当前配置值。
|
||
|
||
- [AC-ASA-16] WHEN 用户修改 LLM 模型配置并保存 THEN 系统 SHALL 验证配置有效性，更新配置并提示操作结果。
|
||
|
||
- [AC-ASA-17] WHEN 用户点击"测试连接"按钮 THEN 系统 SHALL 调用 LLM 生成测试回复，展示连接状态、模型响应和耗时。
|
||
|
||
- [AC-ASA-18] WHEN LLM 连接测试失败 THEN 系统 SHALL 展示详细错误信息，帮助用户排查配置问题。
|
||
|
||
### 8.2 RAG 实验室 AI 输出展示
|
||
|
||
- [AC-ASA-19] WHEN 用户运行 RAG 实验后 THEN 系统 SHALL 在结果区域新增"AI 回复"展示区，显示基于检索结果生成的 AI 最终输出。
|
||
|
||
- [AC-ASA-20] WHEN AI 回复生成中 THEN 系统 SHALL 展示 Loading 状态，支持流式输出展示（SSE）。
|
||
|
||
- [AC-ASA-21] WHEN AI 回复生成完成 THEN 系统 SHALL 展示完整的回复内容、Token 消耗统计、响应耗时。
|
||
|
||
- [AC-ASA-22] WHEN 用户选择不同的 LLM 配置 THEN 系统 SHALL 使用选定的 LLM 模型生成回复，便于对比不同模型效果。
|
||
|
||
### 8.3 用户故事（迭代追加）
|
||
|
||
- [US-ASA-08] 作为系统管理员，我希望在界面上配置和切换不同的 LLM 提供者（如 OpenAI、Ollama、Azure 等），以便快速适配不同的业务场景。
|
||
|
||
- [US-ASA-09] 作为 AI 开发者，我希望在 RAG 实验室中看到 AI 的最终输出，以便完整调试 RAG 链路效果，而不仅仅是检索结果。
|
||
|
||
- [US-ASA-10] 作为 Prompt 工程师，我希望对比不同 LLM 模型在相同检索结果下的回复效果，以便选择最适合业务场景的模型。
|
||
|
||
### 8.4 追踪映射（迭代追加）
|
||
|
||
| AC ID | Endpoint | 方法 | 备注 |
|
||
|------|----------|------|-----|
|
||
| AC-ASA-14 | /admin/llm/config | GET | 获取当前 LLM 配置 |
|
||
| AC-ASA-15 | /admin/llm/providers | GET | 获取 LLM 提供者列表 |
|
||
| AC-ASA-16 | /admin/llm/config | PUT | 更新 LLM 配置 |
|
||
| AC-ASA-17 | /admin/llm/test | POST | 测试 LLM 连接 |
|
||
| AC-ASA-18 | /admin/llm/test | POST | LLM 测试失败错误展示 |
|
||
| AC-ASA-19 | /admin/rag/experiments/run | POST | RAG 实验增加 AI 输出 |
|
||
| AC-ASA-20 | /admin/rag/experiments/stream | POST | RAG 实验流式输出（SSE） |
|
||
| AC-ASA-21 | /admin/rag/experiments/run | POST | Token 统计与耗时 |
|
||
| AC-ASA-22 | /admin/rag/experiments/run | POST | 支持指定 LLM 配置 |
|