---
feature_id: "ASA"
title: "AI 中台管理界面（ai-service-admin）需求规范"
status: "draft"
version: "0.1.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 | 获取全链路详情 |