ai-robot-core/spec/ai-service/requirements.md

---
feature_id: "AISVC"
title: "Python AI 中台（ai-service）需求规范"
status: "completed"
version: "0.4.0"
owners:
  - "product"
  - "backend"
last_updated: "2026-02-24"
source:
  type: "conversation"
  ref: ""
---

# Python AI 中台（ai-service）需求规范（AISVC）

## 1. 背景与目标

### 1.1 背景
主框架（Java）需要通过统一的 HTTP 接口调用 Python AI 中台完成对话回复生成，并支持：
- 多租户隔离（tenant 一套知识库/索引、会话与元数据隔离）。
- 流式输出（Java → Python 主通道采用 SSE）。
- RAG 检索增强（检索命中/不中均有明确兜底逻辑与置信度策略）。
- AI 侧上下文与记忆管理（Java 侧仅传 `sessionId + metadata`，`history` 可选）。

### 1.2 目标
- 提供稳定的 Provider API（至少对齐 `java/openapi.deps.yaml` 中 `/ai/chat` 与 `/ai/health` 的契约需求）。
- 在 MVP 期实现可用的对话能力 + 可控的上下文/记忆 + 基础 RAG。
- 预留 GraphRAG/HybridRAG 扩展口（非 MVP 必须项，但接口与模块边界需支持可插拔）。

### 1.3 非目标（Out of Scope）
- 主框架侧的降级策略与超时处理的业务编排实现（由 Java 侧完成；AI 中台只需返回明确错误语义，便于上游处理）。
- 知识图谱构建与 GraphRAG/HybridRAG 的具体算法实现（仅预留扩展点）。
- 渠道接入、用户身份体系、工单/坐席系统等业务系统实现。

## 2. 模块边界（Scope）

### 2.1 覆盖
- 对话生成服务：支持 non-streaming JSON 与 streaming SSE。
- 多租户隔离：知识库（检索范围）、会话历史、元数据读写隔离。
- 上下文管理：基于 `sessionId` 的会话持久化与加载；支持可选 `history`。
- 基础 RAG：检索、拼装上下文、生成与置信度/转人工建议。

### 2.2 不覆盖
- 业务侧路由、工单流转与最终转人工执行。
- Java 侧调用超时与降级策略的实现细节。

## 3. 依赖盘点（Dependencies）

### 3.1 调用方依赖（Consumer）
- Java 主框架调用 AI 中台：依赖契约见 `java/openapi.deps.yaml`。

### 3.2 AI 中台内部可能依赖（实现阶段确定，规范阶段仅声明）
- 向量库：Qdrant 或 Milvus（二选一）。
- 会话存储：PostgreSQL 或 MySQL。
- 缓存（可选）：Redis。
- LLM 提供方（可插拔）：OpenAI / 兼容 OpenAI 的网关 / 本地模型。

## 4. 术语与约定（Definitions）
- `tenantId`：租户标识，用于隔离知识库、会话与元数据。必须贯穿请求与存储分区。
- `sessionId`：会话标识，用于定位同一会话下的对话记忆。
- `history`：调用方提供的历史消息列表（可选）。AI 中台可结合 AI 侧持久化会话一起构建上下文。
- SSE：Server-Sent Events，HTTP 单向流式推送（`text/event-stream`）。

## 5. 用户故事（User Stories）
- [US-AISVC-01] 作为 Java 主框架，我希望通过统一 HTTP 接口调用 AI 中台生成回复，以便对外提供智能对话能力。
- [US-AISVC-02] 作为平台运营者，我希望不同租户的数据严格隔离，以便满足多租户安全与合规要求。
- [US-AISVC-03] 作为终端用户，我希望 AI 回复可以流式呈现，以便更快看到内容并提升交互体验。
- [US-AISVC-04] 作为终端用户，我希望 AI 能结合知识库检索回答问题，并在检索不足时有稳健兜底，以便减少"胡编"。
- [US-AISVC-05] 作为系统维护者，我希望 AI 中台可被健康检查探测，以便稳定运维。

## 6. 验收标准（Acceptance Criteria, EARS）

> 说明：
> - Java 侧既有验收标准以 `AC-MCA-*` 表示（来自依赖契约描述）；本模块新增以 `AC-AISVC-*` 表示。
> - 本模块的 Provider API 必须对齐 `java/openapi.deps.yaml` 中的 `/ai/chat` 与 `/ai/health` 约束。

### 6.1 对齐 Java 契约：/ai/chat（HTTP POST + Response Schema）

- [AC-AISVC-01] WHEN Java 主框架通过 HTTP `POST /ai/chat` 发送包含 `sessionId`、`currentMessage`、`channelType` 的请求 THEN AI 中台 SHALL 返回 200 并给出业务回复结果（兼容 non-streaming JSON）。
  - 对齐：AC-MCA-04（HTTP POST 调用）。

- [AC-AISVC-02] WHEN AI 中台成功生成回复 THEN 响应体（non-streaming） SHALL 至少包含 `reply`、`confidence`、`shouldTransfer` 字段，且字段类型与语义满足 Java 依赖契约。
  - 对齐：AC-MCA-05（Response Schema）。

- [AC-AISVC-03] WHEN 请求参数缺失或格式非法 THEN AI 中台 SHALL 返回 400 且返回结构化错误（至少包含 `code` 与 `message`）。

- [AC-AISVC-04] WHEN AI 中台发生未预期内部错误 THEN AI 中台 SHALL 返回 500 且返回结构化错误（至少包含 `code` 与 `message`）。

- [AC-AISVC-05] WHEN AI 中台暂不可用（例如依赖 LLM/向量库不可用导致无法服务） THEN AI 中台 SHALL 返回 503 且返回结构化错误（至少包含 `code` 与 `message`）。

### 6.2 SSE 流式输出（主通道）

- [AC-AISVC-06] WHEN 调用方以流式方式调用 `POST /ai/chat`（例如通过 `Accept: text/event-stream` 或 `stream=true` 参数） THEN AI 中台 SHALL 以 SSE 推送事件流，直到生成结束或发生错误。

- [AC-AISVC-07] WHEN AI 中台产生可增量输出的回复内容 THEN AI 中台 SHALL 多次发送 `event: message` 事件，每次携带本次增量文本（delta），以便调用方逐步渲染。
  - 返回时机：模型生成过程中持续发送。

- [AC-AISVC-08] WHEN AI 中台完成本次生成（正常结束） THEN AI 中台 SHALL 发送一次 `event: final` 事件，携带最终结构化结果，且其字段集合至少包含 `reply`、`confidence`、`shouldTransfer`（与 non-streaming 响应同构）。
  - 返回时机：生成完成后立即发送，并随后关闭 SSE 连接（或发送结束标记后关闭）。

- [AC-AISVC-09] WHEN 处理过程中发生可判定错误（参数错误/内部错误/依赖不可用等） THEN AI 中台 SHALL 发送 `event: error` 事件，携带结构化错误（至少 `code`、`message`，可含 `details`），并终止事件流。
  - 返回时机：错误发生后立即发送，并关闭连接。

### 6.3 多租户隔离（tenantId）

- [AC-AISVC-10] WHEN 请求的 `metadata` 中包含 `tenantId` THEN AI 中台 SHALL 将 `tenantId` 作为一级隔离维度贯穿：知识库检索范围、会话读写、元数据读写均必须在该 `tenantId` 分区内进行。

- [AC-AISVC-11] WHEN 不同 `tenantId` 的请求使用相同 `sessionId` THEN AI 中台 SHALL 视为两个互相隔离的会话空间，禁止跨租户读取/写入对话历史与记忆。

- [AC-AISVC-12] WHEN 请求缺失 `tenantId`（或 `tenantId` 非法/空） THEN AI 中台 SHALL 按契约返回 400（参数错误），并在错误中明确缺失字段。

### 6.4 上下文管理（sessionId 持久化；history 可选）

- [AC-AISVC-13] WHEN AI 中台收到 `sessionId` THEN AI 中台 SHALL 在服务端持久化该会话的对话记录与必要的摘要/记忆，并可在后续同一 `tenantId + sessionId` 请求中加载用于上下文构建。

- [AC-AISVC-14] WHEN Java 调用方未提供 `history` THEN AI 中台 SHALL 仅基于服务端持久化会话历史（若存在）与本次 `currentMessage` 构建上下文完成生成。

- [AC-AISVC-15] WHEN Java 调用方提供了 `history` THEN AI 中台 SHALL 将其作为"外部补充历史"参与上下文构建，并以确定性的去重/合并规则避免与服务端历史冲突（规则在 design.md 明确）。

### 6.5 RAG 检索（命中/不中的兜底与置信度阈值）

- [AC-AISVC-16] WHEN 请求触发知识库检索（RAG） THEN AI 中台 SHALL 在 `tenantId` 对应的知识库范围内进行检索，并将检索结果用于回答生成。

- [AC-AISVC-17] WHEN 检索结果为空或低质量（定义为：未达到最小命中文档数或相关度阈值，阈值在配置中可调整） THEN AI 中台 SHALL 执行兜底逻辑：
  1) 生成"基于通用知识/无法从知识库确认"的稳健回复（避免编造具体事实），并
  2) 下调 `confidence`，并
  3) 视阈值策略可将 `shouldTransfer=true`（例如用户强诉求或关键信息缺失）。

- [AC-AISVC-18] WHEN 生成完成后计算得到的 `confidence` 低于阈值 `T_low` THEN AI 中台 SHALL 将 `shouldTransfer` 置为 `true` 或提供 `transferReason`，以便上游决定是否转人工。
  - 说明：阈值 `T_low` 为可配置；MVP 可先采用经验值并在 design.md 中定义默认值与可配置项。

- [AC-AISVC-19] WHEN 检索命中且证据充分（达到相关度与覆盖度阈值） THEN AI 中台 SHALL 提升 `confidence`（相对兜底场景）并优先基于检索证据回答；如回答包含事实性结论，应以检索证据为主。

### 6.6 健康检查

- [AC-AISVC-20] WHEN 调用方请求 `GET /ai/health` THEN AI 中台 SHALL 在健康时返回 200 且包含可解析的 `status` 字段；在不健康时返回 503。

## 7. 需求追踪映射（Traceability）

> 说明：本表用于把验收标准映射到 Provider 端点（以及未来的 operationId）。
> 在下一步生成 `openapi.provider.yaml` 时，应保证：
> - `/ai/chat` 的 non-streaming 响应 schema 对齐 Java deps（reply/confidence/shouldTransfer）。
> - streaming SSE 的事件模型在 provider 契约中明确（可作为 `text/event-stream` 响应体描述）。

| AC ID | 对齐外部 AC | Endpoint | 方法 | operationId（拟） | 备注 |
|------|-------------|----------|------|------------------|------|
| AC-AISVC-01 | AC-MCA-04 | /ai/chat | POST | generateReply | HTTP POST 调用对齐 Java deps |
| AC-AISVC-02 | AC-MCA-05 | /ai/chat | POST | generateReply | non-streaming 响应字段对齐（reply/confidence/shouldTransfer） |
| AC-AISVC-03 |  | /ai/chat | POST | generateReply | 400 参数错误 + ErrorResponse |
| AC-AISVC-04 |  | /ai/chat | POST | generateReply | 500 内部错误 |
| AC-AISVC-05 |  | /ai/chat | POST | generateReply | 503 不可用 |
| AC-AISVC-06 |  | /ai/chat | POST | generateReplyStream | SSE 入口（同路径不同协商方式） |
| AC-AISVC-07 |  | /ai/chat | POST | generateReplyStream | event: message |
| AC-AISVC-08 |  | /ai/chat | POST | generateReplyStream | event: final |
| AC-AISVC-09 |  | /ai/chat | POST | generateReplyStream | event: error |
| AC-AISVC-10 |  | /ai/chat | POST | generateReply | tenantId 贯穿隔离 |
| AC-AISVC-11 |  | /ai/chat | POST | generateReply | tenantId + sessionId 组合隔离 |
| AC-AISVC-12 |  | /ai/chat | POST | generateReply | 缺 tenantId 返回 400（本模块约束） |
| AC-AISVC-13 |  | /ai/chat | POST | generateReply | session 持久化 |
| AC-AISVC-14 |  | /ai/chat | POST | generateReply | history 可选 |
| AC-AISVC-15 |  | /ai/chat | POST | generateReply | history 合并规则（design 明确） |
| AC-AISVC-16 |  | /ai/chat | POST | generateReply | RAG 检索 |
| AC-AISVC-17 |  | /ai/chat | POST | generateReply | 检索不中兜底 + 下调置信度 |
| AC-AISVC-18 |  | /ai/chat | POST | generateReply | 置信度阈值触发 shouldTransfer |
| AC-AISVC-19 |  | /ai/chat | POST | generateReply | 证据充分提升 confidence |
| AC-AISVC-20 |  | /ai/health | GET | healthCheck | 健康检查对齐 deps |

## 8. 约束与待澄清（Open Questions）
- `tenantId` 的承载方式：本规范要求在请求 `metadata.tenantId` 中提供；后续 `openapi.provider.yaml` 需将其提升为明确字段（是否提升为顶层字段需评审）。
- streaming 协商方式：`Accept: text/event-stream` vs `stream=true` 参数；下一阶段在 provider OpenAPI 中确定主方案。
- `confidence` 计算方式与默认阈值：MVP 先给默认值与可配置项，后续可基于日志/评测迭代。
- `shouldTransfer` 的策略：AI 中台提供"建议"，最终转人工编排由上游业务实现。

## 9. 迭代需求：前后端联调真实对接（v0.2.0）

> 说明：本节为 v0.2.0 迭代新增，用于支持 ai-service-admin 前端与后端的真实对接，替换原有 Mock 实现。

### 9.1 知识库管理真实对接

- [AC-AISVC-21] WHEN 前端通过 `POST /admin/kb/documents` 上传文档 THEN AI 中台 SHALL 将文档存储到本地文件系统，创建 Document 实体记录，并返回 `jobId` 用于追踪索引任务。

- [AC-AISVC-22] WHEN 文档上传成功后 THEN AI 中台 SHALL 异步启动索引任务，将文档内容分块并向量化存储到 Qdrant（按 tenantId 隔离 Collection）。

- [AC-AISVC-23] WHEN 前端通过 `GET /admin/kb/documents` 查询文档列表 THEN AI 中台 SHALL 从 PostgreSQL 数据库查询 Document 实体，支持按 kbId、status 过滤和分页。

- [AC-AISVC-24] WHEN 前端通过 `GET /admin/kb/index/jobs/{jobId}` 查询索引任务状态 THEN AI 中台 SHALL 返回任务状态（pending/processing/completed/failed）、进度百分比及错误信息。

### 9.2 RAG 实验室真实对接

- [AC-AISVC-25] WHEN 前端通过 `POST /admin/rag/experiments/run` 触发 RAG 实验 THEN AI 中台 SHALL 调用 VectorRetriever 进行真实向量检索，返回检索结果列表（content、score、source）及最终拼接的 Prompt。

- [AC-AISVC-26] WHEN RAG 实验检索失败（如 Qdrant 不可用）THEN AI 中台 SHALL 返回 fallback 结果而非抛出异常，确保前端可正常展示。

### 9.3 会话监控真实对接

- [AC-AISVC-27] WHEN 前端通过 `GET /admin/sessions` 查询会话列表 THEN AI 中台 SHALL 从 PostgreSQL 数据库查询 ChatSession 实体，支持按 status、时间范围过滤和分页，并关联统计消息数量。

- [AC-AISVC-28] WHEN 前端通过 `GET /admin/sessions/{sessionId}` 查询会话详情 THEN AI 中台 SHALL 返回该会话的所有消息记录及追踪信息（trace）。

### 9.4 需求追踪映射（迭代追加）

| AC ID | Endpoint | 方法 | operationId | 备注 |
|------|----------|------|-------------|------|
| AC-AISVC-21 | /admin/kb/documents | POST | uploadDocument | 文档上传真实存储 |
| AC-AISVC-22 | /admin/kb/documents | POST | uploadDocument | 异步索引任务 |
| AC-AISVC-23 | /admin/kb/documents | GET | listDocuments | 文档列表真实查询 |
| AC-AISVC-24 | /admin/kb/index/jobs/{jobId} | GET | getIndexJob | 索引任务状态查询 |
| AC-AISVC-25 | /admin/rag/experiments/run | POST | runRagExperiment | RAG 真实检索 |
| AC-AISVC-26 | /admin/rag/experiments/run | POST | runRagExperiment | 检索失败 fallback |
| AC-AISVC-27 | /admin/sessions | GET | listSessions | 会话列表真实查询 |
| AC-AISVC-28 | /admin/sessions/{sessionId} | GET | getSessionDetail | 会话详情真实查询 |

## 10. 迭代需求：嵌入模型可插拔与文档解析支持（v0.3.0）

> 说明：本节为 v0.3.0 迭代新增，用于支持嵌入模型的灵活配置与多格式文档解析。

### 10.1 嵌入模型可插拔设计

- [AC-AISVC-29] WHEN 系统需要生成文本嵌入向量 THEN 系统 SHALL 通过统一的 `EmbeddingProvider` 抽象接口调用，支持运行时动态切换不同的嵌入模型实现。

- [AC-AISVC-30] WHEN 管理员通过配置或界面指定嵌入模型类型（如 `ollama`、`openai`、`local`）THEN 系统 SHALL 自动加载对应的 EmbeddingProvider 实现，无需修改代码。

- [AC-AISVC-31] WHEN 管理员通过界面配置嵌入模型参数（如 API 地址、模型名称、维度等）THEN 系统 SHALL 动态应用配置，支持热更新（无需重启服务）。

- [AC-AISVC-32] WHEN 嵌入模型调用失败 THEN 系统 SHALL 返回明确的错误信息，并支持配置 fallback 策略（如降级到备用模型或返回错误）。

### 10.2 文档解析服务

- [AC-AISVC-33] WHEN 用户上传 PDF 格式文档 THEN 系统 SHALL 使用文档解析服务提取纯文本内容，用于后续分块和向量化。

- [AC-AISVC-34] WHEN 用户上传 Word（.docx）格式文档 THEN 系统 SHALL 使用文档解析服务提取纯文本内容，保留段落结构。

- [AC-AISVC-35] WHEN 用户上传 Excel（.xlsx）格式文档 THEN 系统 SHALL 使用文档解析服务提取表格内容，转换为结构化文本格式。

- [AC-AISVC-36] WHEN 文档解析失败（如文件损坏、格式不支持）THEN 系统 SHALL 返回明确的错误信息，并标记文档索引任务为 failed 状态。

- [AC-AISVC-37] WHEN 用户上传不支持的文件格式 THEN 系统 SHALL 在上传阶段拒绝并返回 400 错误，提示支持的格式列表。

### 10.3 嵌入模型管理 API

- [AC-AISVC-38] WHEN 前端通过 `GET /admin/embedding/providers` 查询可用的嵌入模型提供者 THEN 系统 SHALL 返回所有已注册的提供者列表及其配置参数定义。

- [AC-AISVC-39] WHEN 前端通过 `GET /admin/embedding/config` 查询当前嵌入模型配置 THEN 系统 SHALL 返回当前激活的提供者及其参数配置。

- [AC-AISVC-40] WHEN 前端通过 `PUT /admin/embedding/config` 更新嵌入模型配置 THEN 系统 SHALL 验证配置有效性，更新配置并返回成功状态。

- [AC-AISVC-41] WHEN 前端通过 `POST /admin/embedding/test` 测试嵌入模型连接 THEN 系统 SHALL 调用嵌入模型生成测试向量，返回连接状态和向量维度信息。

### 10.4 需求追踪映射（迭代追加）

| AC ID | Endpoint | 方法 | operationId | 备注 |
|------|----------|------|-------------|------|
| AC-AISVC-29 | - | - | - | EmbeddingProvider 抽象接口设计 |
| AC-AISVC-30 | - | - | - | 工厂模式动态加载 |
| AC-AISVC-31 | /admin/embedding/config | PUT | updateEmbeddingConfig | 配置热更新 |
| AC-AISVC-32 | - | - | - | 错误处理与 fallback |
| AC-AISVC-33 | /admin/kb/documents | POST | uploadDocument | PDF 解析支持 |
| AC-AISVC-34 | /admin/kb/documents | POST | uploadDocument | Word 解析支持 |
| AC-AISVC-35 | /admin/kb/documents | POST | uploadDocument | Excel 解析支持 |
| AC-AISVC-36 | /admin/kb/documents | POST | uploadDocument | 解析失败处理 |
| AC-AISVC-37 | /admin/kb/documents | POST | uploadDocument | 格式校验 |
| AC-AISVC-38 | /admin/embedding/providers | GET | listEmbeddingProviders | 提供者列表 |
| AC-AISVC-39 | /admin/embedding/config | GET | getEmbeddingConfig | 当前配置查询 |
| AC-AISVC-40 | /admin/embedding/config | PUT | updateEmbeddingConfig | 配置更新 |
| AC-AISVC-41 | /admin/embedding/test | POST | testEmbedding | 连接测试 |

---

## 11. 迭代需求：LLM 模型配置与 RAG 调试输出（v0.4.0）

> 说明：本节为 v0.4.0 迭代新增，用于支持 LLM 模型的界面配置及 RAG 实验室的 AI 输出调试。

### 11.1 LLM 模型配置管理

- [AC-AISVC-42] WHEN 前端通过 `GET /admin/llm/providers` 获取 LLM 提供者列表 THEN 系统 SHALL 返回所有支持的 LLM 提供者及其配置参数定义。

- [AC-AISVC-43] WHEN 前端通过 `GET /admin/llm/config` 获取当前 LLM 配置 THEN 系统 SHALL 返回当前激活的 LLM 提供者及其配置参数（敏感字段脱敏）。

- [AC-AISVC-44] WHEN 前端通过 `PUT /admin/llm/config` 更新 LLM 配置 THEN 系统 SHALL 验证配置有效性，更新配置并立即生效。

- [AC-AISVC-45] WHEN 前端通过 `POST /admin/llm/test` 测试 LLM 连接 THEN 系统 SHALL 调用 LLM 生成测试回复，返回响应内容、Token 消耗和延迟统计。

- [AC-AISVC-46] WHEN LLM 连接测试失败 THEN 系统 SHALL 返回详细错误信息，帮助用户排查配置问题。

### 11.2 RAG 实验室 AI 输出增强

- [AC-AISVC-47] WHEN 前端通过 `POST /admin/rag/experiments/run` 运行 RAG 实验 THEN 系统 SHALL 返回检索结果、最终 Prompt 和 AI 回复。

- [AC-AISVC-48] WHEN 前端通过 `POST /admin/rag/experiments/stream` 运行 RAG 实验 THEN 系统 SHALL 以 SSE 流式输出 AI 回复。

- [AC-AISVC-49] WHEN RAG 实验生成 AI 回复 THEN 系统 SHALL 返回 Token 消耗统计和响应耗时。

- [AC-AISVC-50] WHEN RAG 实验请求指定 `llm_provider` THEN 系统 SHALL 使用指定的 LLM 提供者生成回复。

### 11.3 追踪映射（v0.4.0 迭代）

| AC ID | Endpoint | 方法 | Operation | 描述 |
|-------|----------|------|-----------|------|
| AC-AISVC-42 | /admin/llm/providers | GET | listLLMProviders | LLM 提供者列表 |
| AC-AISVC-43 | /admin/llm/config | GET | getLLMConfig | 当前 LLM 配置查询 |
| AC-AISVC-44 | /admin/llm/config | PUT | updateLLMConfig | LLM 配置更新 |
| AC-AISVC-45 | /admin/llm/test | POST | testLLM | LLM 连接测试 |
| AC-AISVC-46 | /admin/llm/test | POST | testLLM | LLM 测试失败处理 |
| AC-AISVC-47 | /admin/rag/experiments/run | POST | runRagExperiment | RAG 实验含 AI 输出 |
| AC-AISVC-48 | /admin/rag/experiments/stream | POST | runRagExperimentStream | RAG 实验流式输出 |
| AC-AISVC-49 | /admin/rag/experiments/run | POST | runRagExperiment | Token 统计 |
| AC-AISVC-50 | /admin/rag/experiments/run | POST | runRagExperiment | 指定 LLM 提供者 |