182 lines
5.8 KiB
Markdown
182 lines
5.8 KiB
Markdown
# 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)
|
||
|
||
- [x] Phase 1: 基础设施（FastAPI 框架与多租户基础） (100%) ✅
|
||
- [x] Phase 2: 存储与检索实现（Memory & Retrieval） (100%) ✅
|
||
- [ ] Phase 3: 核心编排（Orchestrator & LLM Adapter） (80%) 🔄
|
||
- [ ] Phase 4: 流式响应（SSE 实现与状态机） (0%) ⏳
|
||
- [ ] Phase 5: 集成与冒烟测试（Quality Assurance） (0%) ⏳
|
||
|
||
---
|
||
|
||
## 🔄 Current Phase
|
||
|
||
### Goal
|
||
实现核心编排层，包括 LLM Adapter 和 Orchestrator 的完整功能。
|
||
|
||
### 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]` ⏳
|
||
|
||
### Next Action (Must be Specific)
|
||
|
||
**Immediate**: 执行 T3.5 - 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约。
|
||
|
||
**Details**:
|
||
1. 验证 ChatResponse 字段与 OpenAPI 契约一致性
|
||
2. 确保 reply、confidence、shouldTransfer 必填字段正确
|
||
3. 验证 transferReason、metadata 可选字段处理
|
||
4. 编写契约验证测试
|
||
|
||
---
|
||
|
||
## 🏗️ 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/` - 单元测试
|
||
|
||
### 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: 便于调试和问题排查
|
||
|
||
### 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,
|
||
)
|
||
response = await orchestrator.generate(tenant_id, request)
|
||
```
|
||
|
||
---
|
||
|
||
## 🧾 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)
|
||
|
||
---
|
||
|
||
## 🚀 Startup Guide
|
||
|
||
1. 读取本进度文档，定位当前 Phase 与 Next Action。
|
||
2. 打开并阅读 Spec References 指向的模块规范。
|
||
3. 直接执行 Next Action；遇到缺口先更新 spec 再编码。
|