diff --git a/docs/progress/ai-service-progress.md b/docs/progress/ai-service-progress.md index 3fac815..155180d 100644 --- a/docs/progress/ai-service-progress.md +++ b/docs/progress/ai-service-progress.md @@ -25,7 +25,7 @@ - [x] Phase 1: 基础设施(FastAPI 框架与多租户基础) (100%) ✅ - [x] Phase 2: 存储与检索实现(Memory & Retrieval) (100%) ✅ -- [ ] Phase 3: 核心编排(Orchestrator & LLM Adapter) (80%) 🔄 +- [x] Phase 3: 核心编排(Orchestrator & LLM Adapter) (100%) ✅ - [ ] Phase 4: 流式响应(SSE 实现与状态机) (0%) ⏳ - [ ] Phase 5: 集成与冒烟测试(Quality Assurance) (0%) ⏳ @@ -34,26 +34,27 @@ ## 🔄 Current Phase ### Goal -实现核心编排层,包括 LLM Adapter 和 Orchestrator 的完整功能。 +实现 SSE 流式响应,包括 Accept 头切换、事件生成和状态机管理。 ### Sub Tasks -#### Phase 3: 核心编排(Orchestrator & LLM Adapter) -- [x] T3.1 实现 LLM Adapter:封装 `langchain-openai` 或官方 SDK,支持 `generate` 与 `stream_generate` `[AC-AISVC-02, AC-AISVC-06]` ✅ -- [x] T3.2 实现 Orchestrator:实现上下文合并逻辑(H_local + H_ext 的去重与截断策略) `[AC-AISVC-14, AC-AISVC-15]` ✅ -- [x] T3.3 实现 Orchestrator:实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ✅ -- [x] 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]` +- [ ] 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**: 执行 T3.5 - 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约。 +**Immediate**: Phase 3 已完成!准备执行 Phase 4。 -**Details**: -1. 验证 ChatResponse 字段与 OpenAPI 契约一致性 -2. 确保 reply、confidence、shouldTransfer 必填字段正确 -3. 验证 transferReason、metadata 可选字段处理 -4. 编写契约验证测试 +**Note**: Phase 4 的 SSE 功能大部分已在 Phase 1-3 中提前实现: +- Accept 头切换已在 `test_accept_switching.py` 测试 +- SSE 状态机已在 `app/core/sse.py` 实现 +- SSE 事件生成器已实现 +- Orchestrator 流式生成已实现 + +**建议**: 跳过 Phase 4,直接执行 Phase 5 集成测试。 --- @@ -75,7 +76,7 @@ - `context.py` - 上下文合并 ✅ - `confidence.py` - 置信度计算 ✅ - `retrieval/` - 检索层 - - `tests/` - 单元测试 + - `tests/` - 单元测试 (184 tests) ### Key Decisions (Why / Impact) @@ -95,25 +96,21 @@ reason: 清晰追踪中间结果和诊断信息 impact: 便于调试和问题排查 +- decision: Pydantic 模型使用 alias 实现驼峰命名 + reason: 符合 OpenAPI 契约的 camelCase 要求 + impact: JSON 序列化时自动转换字段名 + ### Code Snippets ```python -# [AC-AISVC-02] LLM Response generation -response = await llm_client.generate(messages, config=LLMConfig(...)) - -# [AC-AISVC-06] Streaming generation -async for chunk in llm_client.stream_generate(messages): - yield create_message_event(delta=chunk.delta) - -# [AC-AISVC-01] Complete generation pipeline -orchestrator = OrchestratorService( - llm_client=llm_client, - memory_service=memory_service, - retriever=retriever, - context_merger=context_merger, - confidence_calculator=confidence_calculator, +# [AC-AISVC-02] ChatResponse with contract-compliant field names +response = ChatResponse( + reply="AI response", + confidence=0.85, + should_transfer=False, ) -response = await orchestrator.generate(tenant_id, request) +json_str = response.model_dump_json(by_alias=True) +# Output: {"reply": "AI response", "confidence": 0.85, "shouldTransfer": false, ...} ``` --- @@ -172,6 +169,18 @@ response = await orchestrator.generate(tenant_id, request) - 新增 `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 diff --git a/spec/ai-service/tasks.md b/spec/ai-service/tasks.md index 7b0e182..7938f84 100644 --- a/spec/ai-service/tasks.md +++ b/spec/ai-service/tasks.md @@ -35,7 +35,7 @@ last_updated: "2026-02-24" - [x] T3.2 实现 Orchestrator:实现上下文合并逻辑(H_local + H_ext 的去重与截断策略) `[AC-AISVC-14, AC-AISVC-15]` ✅ - [x] T3.3 实现 Orchestrator:实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ✅ - [x] T3.4 实现 Orchestrator:整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 `[AC-AISVC-01, AC-AISVC-02]` ✅ -- [ ] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` +- [x] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` ✅ ### Phase 4: 流式响应(SSE 实现与状态机) - [ ] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]`