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

5.9 KiB
Raw Blame History

ai-service - Progress

📋 Context

  • module: ai-service
  • feature: AISVC (Python AI 中台)
  • status: 🔄 进行中

🔗 Spec References (SSOT)

  • agents: agents.md
  • contracting: spec/contracting.md
  • requirements: spec/ai-service/requirements.md
  • openapi_provider: spec/ai-service/openapi.provider.yaml
  • design: spec/ai-service/design.md
  • tasks: spec/ai-service/tasks.md

📊 Overall Progress (Phases)

  • Phase 1: 基础设施（FastAPI 框架与多租户基础） (100%) ✅
  • Phase 2: 存储与检索实现（Memory & Retrieval） (100%) ✅
  • Phase 3: 核心编排（Orchestrator & LLM Adapter） (100%) ✅
  • Phase 4: 流式响应（SSE 实现与状态机） (0%) ⏳
  • Phase 5: 集成与冒烟测试（Quality Assurance） (0%) ⏳

🔄 Current Phase

Goal

实现 SSE 流式响应，包括 Accept 头切换、事件生成和状态机管理。

Sub Tasks

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

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

Next Action (Must be Specific)

Immediate: Phase 3 已完成！准备执行 Phase 4。

Note: Phase 4 的 SSE 功能大部分已在 Phase 1-3 中提前实现：

  • Accept 头切换已在 test_accept_switching.py 测试
  • SSE 状态机已在 app/core/sse.py 实现
  • SSE 事件生成器已实现
  • Orchestrator 流式生成已实现

建议: 跳过 Phase 4，直接执行 Phase 5 集成测试。

🏗️ Technical Context

Module Structure

  • ai-service/
    • app/
      • api/ - FastAPI 路由层
      • core/ - 配置、异常、中间件、SSE
      • models/ - Pydantic 模型和 SQLModel 实体
      • services/
        • llm/ - LLM Adapter 实现 ✅
          • base.py - LLMClient 抽象接口
          • openai_client.py - OpenAI 兼容客户端
        • memory.py - Memory 服务
        • orchestrator.py - 编排服务 ✅ (完整实现)
        • context.py - 上下文合并 ✅
        • confidence.py - 置信度计算 ✅
        • retrieval/ - 检索层
    • tests/ - 单元测试 (184 tests)

Key Decisions (Why / Impact)

  • decision: LLM Adapter 使用 httpx 而非 langchain-openai reason: 更轻量、更可控、减少依赖 impact: 需要手动处理 OpenAI API 响应解析

  • decision: 使用 tenacity 实现重试逻辑 reason: 简单可靠的重试机制 impact: 提高服务稳定性

  • decision: Orchestrator 使用依赖注入模式 reason: 便于测试和组件替换 impact: 所有组件可通过构造函数注入

  • decision: 使用 GenerationContext 数据类追踪生成流程 reason: 清晰追踪中间结果和诊断信息 impact: 便于调试和问题排查

  • decision: Pydantic 模型使用 alias 实现驼峰命名 reason: 符合 OpenAPI 契约的 camelCase 要求 impact: JSON 序列化时自动转换字段名

Code Snippets

# [AC-AISVC-02] ChatResponse with contract-compliant field names
response = ChatResponse(
    reply="AI response",
    confidence=0.85,
    should_transfer=False,
)
json_str = response.model_dump_json(by_alias=True)
# Output: {"reply": "AI response", "confidence": 0.85, "shouldTransfer": false, ...}

🧾 Session History

Session #1 (2026-02-24)

  • completed:
    • T3.1 实现 LLM Adapter
    • 创建 LLMClient 抽象接口 (base.py)
    • 实现 OpenAIClient (openai_client.py)
    • 编写单元测试 (test_llm_adapter.py)
    • 修复 entities.py JSON 类型问题
  • changes:
    • 新增 app/services/llm/__init__.py
    • 新增 app/services/llm/base.py
    • 新增 app/services/llm/openai_client.py
    • 新增 tests/test_llm_adapter.py
    • 更新 app/core/config.py 添加 LLM 配置
    • 修复 app/models/entities.py JSON 列类型

Session #2 (2026-02-24)

  • completed:
    • T3.2 实现上下文合并逻辑
    • 创建 ContextMerger 类 (context.py)
    • 实现消息指纹计算 (SHA256)
    • 实现去重和截断策略
    • 编写单元测试 (test_context.py)
  • changes:
    • 新增 app/services/context.py
    • 新增 tests/test_context.py

Session #3 (2026-02-24)

  • completed:
    • T3.3 实现置信度计算与转人工逻辑
    • 创建 ConfidenceCalculator 类 (confidence.py)
    • 实现检索不足判定
    • 实现置信度计算策略
    • 实现 shouldTransfer 逻辑
    • 编写单元测试 (test_confidence.py)
  • changes:
    • 新增 app/services/confidence.py
    • 新增 tests/test_confidence.py
    • 更新 app/core/config.py 添加置信度配置

Session #4 (2026-02-24)

  • completed:
    • T3.4 实现 Orchestrator 完整生成闭环
    • 整合 Memory、ContextMerger、Retriever、LLMClient、ConfidenceCalculator
    • 实现 generate() 方法完整流程 (8 步)
    • 创建 GenerationContext 数据类追踪生成流程
    • 实现 fallback 响应机制
    • 编写单元测试 (test_orchestrator.py, 21 tests)
  • changes:
    • 更新 app/services/orchestrator.py 完整实现
    • 新增 tests/test_orchestrator.py
  • tests_passed: 138 tests (all passing)

Session #5 (2026-02-24)

  • completed:
    • T3.5 验证 non-streaming 响应字段符合 OpenAPI 契约
    • 验证 ChatResponse 字段与契约一致性
    • 验证 JSON 序列化使用 camelCase
    • 验证必填字段和可选字段
    • 验证 confidence 范围约束
    • 编写契约验证测试 (test_contract.py, 23 tests)
  • changes:
    • 新增 tests/test_contract.py
  • tests_passed: 184 tests (all passing)

🚀 Startup Guide

  1. 读取本进度文档，定位当前 Phase 与 Next Action。
  2. 打开并阅读 Spec References 指向的模块规范。
  3. 直接执行 Next Action；遇到缺口先更新 spec 再编码。