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

8.4 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] ✅ 2026-02-24 完成
  • T1.2 实现 X-Tenant-Id Header 拦截器，校验必填性并注入 Request State [AC-AISVC-10, AC-AISVC-12] ✅ 2026-02-24 完成
  • T1.3 定义基础响应模型 ErrorResponse 与异常处理器（Exception Handler） [AC-AISVC-03, AC-AISVC-04] ✅ 2026-02-24 完成
  • T1.4 初始化 PostgreSQL 数据库客户端（SQLModel/SQLAlchemy），支持租户隔离查询逻辑 [AC-AISVC-11] ✅ 2026-02-24 完成
  • T1.5 初始化 Qdrant 客户端，封装按租户动态选择 Collection 的工具函数 [AC-AISVC-10] ✅ 2026-02-24 完成
  • T1.6 实现 /ai/health 健康检查接口 [AC-AISVC-20] ✅ 2026-02-24 完成

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

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

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

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

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] ✅ 2026-02-24 完成
  • T5.2 编写 RAG 冒烟测试：模拟"检索命中"与"检索未命中"两种场景，验证 confidence 变化与回复兜底 [AC-AISVC-17, AC-AISVC-18] ✅ 2026-02-24 完成
  • T5.3 契约测试：验证 provider 契约一致性 [AC-AISVC-01, AC-AISVC-02] ✅ 2026-02-24 完成

总体进度

Phase 描述 进度 状态
Phase 1 基础设施 100% ✅ 完成
Phase 2 存储与检索 100% ✅ 完成
Phase 3 核心编排 100% ✅ 完成
Phase 4 流式响应 100% ✅ 完成
Phase 5 集成测试 100% ✅ 完成

测试统计: 184 tests passing

Phase 3 完成详情 (2026-02-24)

T3.1 LLM Adapter

  • 创建 LLMClient 抽象接口 (app/services/llm/base.py)
  • 实现 OpenAIClient 使用 httpx (app/services/llm/openai_client.py)
  • 支持 generate 和 stream_generate
  • 使用 tenacity 实现重试逻辑
  • 单元测试: 11 tests

T3.2 上下文合并

  • 创建 ContextMerger 类 (app/services/context.py)
  • 实现消息指纹计算 (SHA256)
  • 实现去重策略 (local 优先)
  • 实现 token 截断 (使用 tiktoken)
  • 单元测试: 20 tests

T3.3 置信度计算

  • 创建 ConfidenceCalculator 类 (app/services/confidence.py)
  • 实现检索不足判定
  • 实现置信度计算策略
  • 实现 shouldTransfer 逻辑
  • 单元测试: 19 tests

T3.4 Orchestrator 完整闭环

  • 整合 Memory、ContextMerger、Retriever、LLMClient、ConfidenceCalculator
  • 实现 8 步生成管道:
    1. Load local history from Memory
    2. Merge with external history (dedup + truncate)
    3. RAG retrieval (optional)
    4. Build prompt with context and evidence
    5. LLM generation
    6. Calculate confidence
    7. Save messages to Memory
    8. Return ChatResponse
  • 创建 GenerationContext 数据类追踪生成流程
  • 实现 fallback 响应机制
  • 单元测试: 21 tests

T3.5 契约验证

  • 验证 ChatResponse 字段与 OpenAPI 契约一致性
  • 验证 JSON 序列化使用 camelCase
  • 验证必填字段和可选字段
  • 验证 confidence 范围约束 [0.0, 1.0]
  • 单元测试: 23 tests

验收标准覆盖

AC 标记 描述 状态
AC-AISVC-01 HTTP POST /ai/chat 调用 ✅
AC-AISVC-02 响应包含 reply/confidence/shouldTransfer ✅
AC-AISVC-03 参数错误返回 400 ✅
AC-AISVC-04 异常处理器 ✅
AC-AISVC-06 Accept 头切换 SSE 模式 ✅
AC-AISVC-07 SSE message 事件增量输出 ✅
AC-AISVC-08 SSE final 事件后关闭连接 ✅
AC-AISVC-09 错误时发送 error 事件 ✅
AC-AISVC-10 tenantId 贯穿隔离 ✅
AC-AISVC-11 存储层按 tenant_id 隔离 ✅
AC-AISVC-12 缺 tenantId 返回 400 ✅
AC-AISVC-13 Memory 层会话历史管理 ✅
AC-AISVC-14 上下文合并 ✅
AC-AISVC-15 历史去重策略 ✅
AC-AISVC-16 Retriever 抽象接口 ✅
AC-AISVC-17 RAG 检索质量影响 confidence ✅
AC-AISVC-18 检索不足时 confidence 下调 ✅
AC-AISVC-19 shouldTransfer 转人工建议 ✅
AC-AISVC-20 健康检查接口 ✅

模块结构

ai-service/
├── app/
│   ├── api/
│   │   └── chat.py          # FastAPI 路由层
│   ├── core/
│   │   ├── config.py        # 配置管理
│   │   ├── exceptions.py    # 异常定义
│   │   ├── middleware.py    # 中间件 (租户注入)
│   │   ├── qdrant_client.py # Qdrant 客户端
│   │   └── sse.py           # SSE 状态机和事件生成器
│   ├── models/
│   │   ├── __init__.py      # Pydantic 模型
│   │   └── entities.py      # SQLModel 实体
│   └── services/
│       ├── llm/
│       │   ├── base.py      # LLMClient 抽象接口
│       │   └── openai_client.py  # OpenAI 兼容客户端
│       ├── memory.py        # Memory 服务
│       ├── orchestrator.py  # 编排服务
│       ├── context.py       # 上下文合并
│       ├── confidence.py    # 置信度计算
│       └── retrieval/
│           ├── base.py      # Retriever 抽象接口
│           └── vector_retriever.py  # 向量检索实现
└── tests/                   # 单元测试 (184 tests)

关键技术决策

决策 原因 影响
LLM Adapter 使用 httpx 更轻量、更可控、减少依赖 需要手动处理 OpenAI API 响应解析
使用 tenacity 实现重试 简单可靠的重试机制 提高服务稳定性
Orchestrator 依赖注入模式 便于测试和组件替换 所有组件可通过构造函数注入
GenerationContext 数据类 清晰追踪中间结果和诊断信息 便于调试和问题排查
Pydantic alias 实现驼峰命名 符合 OpenAPI 契约的 camelCase 要求 JSON 序列化时自动转换字段名