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

7.5 KiB
Raw Blame History

feature_id title status version last_updated
AISVC Python AI 中台（ai-service）进度追踪 in_progress 0.1.0 2026-02-24

Python AI 中台进度追踪（AISVC）

Phase 1: 基础设施（FastAPI 框架与多租户基础）

  • T1.1 初始化 FastAPI 项目骨架，配置基础环境与日志（包含 X-Tenant-Id 记录） [AC-AISVC-01]
  • T1.2 实现 X-Tenant-Id Header 拦截器，校验必填性并注入 Request State [AC-AISVC-10, AC-AISVC-12]
  • T1.3 定义基础响应模型 ErrorResponse 与异常处理器（Exception Handler） [AC-AISVC-03, AC-AISVC-04]
  • T1.4 初始化 PostgreSQL 数据库客户端（SQLModel/SQLAlchemy），支持租户隔离查询逻辑 [AC-AISVC-11]
  • T1.5 初始化 Qdrant 客户端，封装按租户动态选择 Collection 的工具函数 [AC-AISVC-10]
  • T1.6 实现 /ai/health 健康检查接口 [AC-AISVC-20]

Phase 2: 存储与检索实现（Memory & Retrieval）

  • T2.1 实现 Memory 层：定义 chat_sessions 与 chat_messages SQLModel 实体 [AC-AISVC-13]
  • T2.2 实现 Memory 层：完成基于 (tenant_id, session_id) 的历史消息加载与追加 API [AC-AISVC-13]
  • T2.3 实现 Retrieval 层：定义 BaseRetriever 抽象基类（插件点预留） [AC-AISVC-16]
  • T2.4 实现 VectorRetriever：集成 qdrant-client 完成向量检索，支持 scoreThreshold 过滤 [AC-AISVC-16, AC-AISVC-17]
  • T2.5 编写 Memory 与 Retrieval 层的独立单元测试（Mock 数据库与向量库） [AC-AISVC-10, AC-AISVC-11]

Phase 3: 核心编排（Orchestrator & LLM Adapter）

  • T3.1 实现 LLM Adapter：封装 langchain-openai 或官方 SDK，支持 generate 与 stream_generate [AC-AISVC-02, AC-AISVC-06]
  • T3.2 实现 Orchestrator：实现上下文合并逻辑（H_local + H_ext 的去重与截断策略） [AC-AISVC-14, AC-AISVC-15]
  • T3.3 实现 Orchestrator：实现 RAG 检索不足时的置信度下调与 shouldTransfer 逻辑 [AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]
  • T3.4 实现 Orchestrator：整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 [AC-AISVC-01, AC-AISVC-02]
  • T3.5 验证 non-streaming 响应字段完全符合 openapi.provider.yaml 契约 [AC-AISVC-02]

Phase 4: 流式响应（SSE 实现与状态机）

  • T4.1 在 API 层实现基于 Accept 头的响应模式自动切换逻辑 [AC-AISVC-06] ✅ 2026-02-24 完成
  • T4.2 实现 SSE 事件生成器：根据 Orchestrator 的增量输出包装 message 事件 [AC-AISVC-07] ✅ 2026-02-24 完成
  • T4.3 实现 SSE 状态机：确保 final 或 error 事件后连接正确关闭，且顺序不乱 [AC-AISVC-08, AC-AISVC-09] ✅ 2026-02-24 完成
  • T4.4 实现流式输出过程中的异常捕获，并转化为 event: error 输出 [AC-AISVC-09] ✅ 2026-02-24 完成

Phase 5: 集成与冒烟测试（Quality Assurance）

  • T5.1 编写集成测试：模拟多租户并发请求，验证数据存储与检索的严格物理/逻辑隔离 [AC-AISVC-10, AC-AISVC-11]
  • T5.2 编写 RAG 冒烟测试：模拟"检索命中"与"检索未命中"两种场景，验证 confidence 变化与回复兜底 [AC-AISVC-17, AC-AISVC-18]
  • T5.3 契约测试：使用外部工具（如 Schemathesis 或 Newman）验证 provider 契约一致性（L2 级自检） [AC-AISVC-01, AC-AISVC-02]

T4.1 完成详情

实现内容

  1. FastAPI 项目骨架 (ai-service/app/)

    • 配置管理 (app/core/config.py)
    • 日志配置
    • 异常处理器 (app/core/exceptions.py)

  2. 数据模型 (app/models/__init__.py)

    • ChatRequest - 请求模型
    • ChatResponse - 响应模型（含 reply/confidence/shouldTransfer）
    • ErrorResponse - 错误响应模型
    • SSE 事件模型（SSEMessageEvent, SSEFinalEvent, SSEErrorEvent）

  3. X-Tenant-Id Header 拦截器 (app/core/middleware.py)

    • [AC-AISVC-10] 租户上下文注入
    • [AC-AISVC-12] 缺失 tenant_id 返回 400 错误

  4. Accept 头响应模式切换 (app/api/chat.py)

    • [AC-AISVC-06] 根据 Accept 头自动切换 JSON/SSE 模式
    • Accept: text/event-stream → SSE 流式响应
    • 其他 → JSON 响应

  5. SSE 基础设施 (app/core/sse.py)

    • SSE 状态机（INIT → STREAMING → FINAL_SENT/ERROR_SENT → CLOSED）
    • 事件生成器（message/final/error）
    • Ping 保活机制（15s 间隔）

  6. 单元测试 (tests/test_accept_switching.py)

    • JSON 响应模式测试
    • SSE 响应模式测试
    • SSE 事件序列测试
    • 租户隔离测试
    • 状态机测试

测试结果

24 passed in 2.52s

验收标准覆盖

  • AC-AISVC-01: HTTP POST /ai/chat 调用
  • AC-AISVC-02: 响应包含 reply/confidence/shouldTransfer
  • AC-AISVC-03: 参数错误返回 400
  • AC-AISVC-06: Accept 头切换 SSE 模式
  • AC-AISVC-10: tenantId 贯穿隔离
  • AC-AISVC-12: 缺 tenantId 返回 400
  • AC-AISVC-20: 健康检查接口

T4.2 完成详情

实现内容

  1. Orchestrator 流式输出优化 (app/services/orchestrator.py)

    • [AC-AISVC-07] 集成 LLM 客户端流式输出
    • 支持依赖注入 LLM 客户端
    • 实现 _stream_from_llm() 方法包装 LLM chunk 为 message 事件
    • 实现 _stream_mock_response() 模拟流式输出
    • SSE 事件序列：message* -> final -> close

  2. SSE 事件生成器 (app/core/sse.py)

    • create_message_event(delta) - 创建 message 事件，包含增量内容
    • create_final_event() - 创建 final 事件，包含完整响应
    • create_error_event() - 创建 error 事件
    • 修复 by_alias=True 确保 JSON 字段使用 camelCase

  3. 单元测试 (tests/test_sse_events.py)

    • message 事件格式测试
    • unicode 内容测试
    • final 事件格式测试
    • error 事件格式测试
    • Orchestrator 流式输出测试
    • LLM 客户端集成测试
    • 状态机集成测试

测试结果

79 passed in 3.11s

验收标准覆盖

  • AC-AISVC-07: AI 中台多次发送 event: message 事件，每次携带增量文本(delta)
  • AC-AISVC-08: 生成完成后发送 event: final 事件
  • AC-AISVC-09: 错误时发送 event: error 事件

T4.3 & T4.4 完成详情

实现内容

  1. API 层状态机集成 (app/api/chat.py)

    • [AC-AISVC-08, AC-AISVC-09] 在 _handle_streaming_request 中集成状态机
    • 状态机确保事件顺序：message* -> final/error -> close
    • 禁止 final/error 后发送任何事件
    • 异常自动转换为 error 事件

  2. 状态机行为保证

    • INIT -> STREAMING: 开始流式输出
    • STREAMING -> FINAL_SENT: 发送 final 后关闭
    • STREAMING -> ERROR_SENT: 发送 error 后关闭
    • FINAL_SENT/ERROR_SENT -> CLOSED: 最终关闭状态
    • 线程安全：使用 asyncio.Lock 保证并发安全

  3. 异常处理机制

    • 流式输出过程中的任何异常都被捕获
    • 异常自动转换为 event: error 事件
    • 确保 error 事件只发送一次
    • 连接在 error 后正确关闭

  4. 单元测试 (tests/test_sse_state_machine.py)

    • 状态机转换测试（9 个测试）
    • SSE 事件序列测试（3 个测试）
    • 错误处理测试（3 个测试）
    • 并发安全测试（2 个测试）
    • Orchestrator 集成测试（2 个测试）

测试结果

117 passed in 4.24s

验收标准覆盖

  • AC-AISVC-08: 生成完成后发送一次 event: final，随后关闭连接
  • AC-AISVC-09: 错误时发送 event: error，并终止事件流