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

---
feature_id: "AISVC"
title: "Python AI 中台（ai-service）需求规范"
status: "draft"
version: "0.2.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 | 会话详情真实查询 |