diff --git a/spec/ai-service/progress.md b/spec/ai-service/progress.md new file mode 100644 index 0000000..a9d82b7 --- /dev/null +++ b/spec/ai-service/progress.md @@ -0,0 +1,93 @@ +--- +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]` +- [x] T1.2 实现 `X-Tenant-Id` Header 拦截器,校验必填性并注入 Request State `[AC-AISVC-10, AC-AISVC-12]` +- [x] 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]` +- [x] 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 实现与状态机) +- [x] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]` ✅ **2026-02-24 完成** +- [ ] 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]` + +## 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 +``` + +### 验收标准覆盖 +- [x] AC-AISVC-01: HTTP POST /ai/chat 调用 +- [x] AC-AISVC-02: 响应包含 reply/confidence/shouldTransfer +- [x] AC-AISVC-03: 参数错误返回 400 +- [x] AC-AISVC-06: Accept 头切换 SSE 模式 +- [x] AC-AISVC-10: tenantId 贯穿隔离 +- [x] AC-AISVC-12: 缺 tenantId 返回 400 +- [x] AC-AISVC-20: 健康检查接口