174 lines
8.4 KiB
Markdown
174 lines
8.4 KiB
Markdown
---
|
||
feature_id: "AISVC"
|
||
title: "Python AI 中台（ai-service）进度追踪"
|
||
status: "in_progress"
|
||
version: "0.1.0"
|
||
last_updated: "2026-02-24"
|
||
---
|
||
|
||
# Python AI 中台进度追踪（AISVC）
|
||
|
||
## Phase 1: 基础设施（FastAPI 框架与多租户基础）
|
||
- [x] T1.1 初始化 FastAPI 项目骨架，配置基础环境与日志（包含 X-Tenant-Id 记录） `[AC-AISVC-01]` ✅ **2026-02-24 完成**
|
||
- [x] T1.2 实现 `X-Tenant-Id` Header 拦截器，校验必填性并注入 Request State `[AC-AISVC-10, AC-AISVC-12]` ✅ **2026-02-24 完成**
|
||
- [x] T1.3 定义基础响应模型 `ErrorResponse` 与异常处理器（Exception Handler） `[AC-AISVC-03, AC-AISVC-04]` ✅ **2026-02-24 完成**
|
||
- [x] T1.4 初始化 PostgreSQL 数据库客户端（SQLModel/SQLAlchemy），支持租户隔离查询逻辑 `[AC-AISVC-11]` ✅ **2026-02-24 完成**
|
||
- [x] T1.5 初始化 Qdrant 客户端，封装按租户动态选择 Collection 的工具函数 `[AC-AISVC-10]` ✅ **2026-02-24 完成**
|
||
- [x] T1.6 实现 `/ai/health` 健康检查接口 `[AC-AISVC-20]` ✅ **2026-02-24 完成**
|
||
|
||
## Phase 2: 存储与检索实现（Memory & Retrieval）
|
||
- [x] T2.1 实现 Memory 层：定义 `chat_sessions` 与 `chat_messages` SQLModel 实体 `[AC-AISVC-13]` ✅ **2026-02-24 完成**
|
||
- [x] T2.2 实现 Memory 层：完成基于 `(tenant_id, session_id)` 的历史消息加载与追加 API `[AC-AISVC-13]` ✅ **2026-02-24 完成**
|
||
- [x] T2.3 实现 Retrieval 层：定义 `BaseRetriever` 抽象基类（插件点预留） `[AC-AISVC-16]` ✅ **2026-02-24 完成**
|
||
- [x] T2.4 实现 `VectorRetriever`：集成 `qdrant-client` 完成向量检索，支持 scoreThreshold 过滤 `[AC-AISVC-16, AC-AISVC-17]` ✅ **2026-02-24 完成**
|
||
- [x] T2.5 编写 Memory 与 Retrieval 层的独立单元测试（Mock 数据库与向量库） `[AC-AISVC-10, AC-AISVC-11]` ✅ **2026-02-24 完成**
|
||
|
||
## Phase 3: 核心编排（Orchestrator & LLM Adapter）
|
||
- [x] T3.1 实现 LLM Adapter：封装 `langchain-openai` 或官方 SDK，支持 `generate` 与 `stream_generate` `[AC-AISVC-02, AC-AISVC-06]` ✅ **2026-02-24 完成**
|
||
- [x] T3.2 实现 Orchestrator：实现上下文合并逻辑（H_local + H_ext 的去重与截断策略） `[AC-AISVC-14, AC-AISVC-15]` ✅ **2026-02-24 完成**
|
||
- [x] T3.3 实现 Orchestrator：实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ✅ **2026-02-24 完成**
|
||
- [x] T3.4 实现 Orchestrator：整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 `[AC-AISVC-01, AC-AISVC-02]` ✅ **2026-02-24 完成**
|
||
- [x] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` ✅ **2026-02-24 完成**
|
||
|
||
## Phase 4: 流式响应（SSE 实现与状态机）
|
||
- [x] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]` ✅ **2026-02-24 完成**
|
||
- [x] T4.2 实现 SSE 事件生成器：根据 Orchestrator 的增量输出包装 `message` 事件 `[AC-AISVC-07]` ✅ **2026-02-24 完成**
|
||
- [x] T4.3 实现 SSE 状态机：确保 `final` 或 `error` 事件后连接正确关闭，且顺序不乱 `[AC-AISVC-08, AC-AISVC-09]` ✅ **2026-02-24 完成**
|
||
- [x] T4.4 实现流式输出过程中的异常捕获，并转化为 `event: error` 输出 `[AC-AISVC-09]` ✅ **2026-02-24 完成**
|
||
|
||
## Phase 5: 集成与冒烟测试（Quality Assurance）
|
||
- [x] T5.1 编写集成测试：模拟多租户并发请求，验证数据存储与检索的严格物理/逻辑隔离 `[AC-AISVC-10, AC-AISVC-11]` ✅ **2026-02-24 完成**
|
||
- [x] T5.2 编写 RAG 冒烟测试：模拟"检索命中"与"检索未命中"两种场景，验证 confidence 变化与回复兜底 `[AC-AISVC-17, AC-AISVC-18]` ✅ **2026-02-24 完成**
|
||
- [x] 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 序列化时自动转换字段名 |
|