MerCry
/
ai-robot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-core/spec/ai-service/requirements.md

14 KiB
Raw Blame History

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

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 会话详情真实查询