ai-robot-core/spec/ai-service/tasks.md

250 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
feature_id: "AISVC"
title: "Python AI 中台ai-service任务清单"
status: "in-progress"
version: "0.6.0"
last_updated: "2026-02-27"
---
# Python AI 中台任务清单AISVC
## 1. 任务拆分原则
- **原子性**:每个任务仅解决一个具体技术点或功能逻辑。
- **可验证性**:任务完成后必须可通过单元测试、接口冒烟或契约校验。
- **弱模型可执行**:任务描述清晰,不依赖 AI 猜测业务逻辑。
## 2. 任务执行计划
### 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]`
- [x] T1.4 初始化 PostgreSQL 数据库客户端SQLModel/SQLAlchemy支持租户隔离查询逻辑 `[AC-AISVC-11]`
- [x] T1.5 初始化 Qdrant 客户端,封装按租户动态选择 Collection 的工具函数 `[AC-AISVC-10]`
- [x] T1.6 实现 `/ai/health` 健康检查接口 `[AC-AISVC-20]`
### Phase 2: 存储与检索实现Memory & Retrieval
- [x] T2.1 实现 Memory 层:定义 `chat_sessions``chat_messages` SQLModel 实体 `[AC-AISVC-13]`
- [x] T2.2 实现 Memory 层:完成基于 `(tenant_id, session_id)` 的历史消息加载与追加 API `[AC-AISVC-13]`
- [x] T2.3 实现 Retrieval 层:定义 `BaseRetriever` 抽象基类(插件点预留) `[AC-AISVC-16]`
- [x] T2.4 实现 `VectorRetriever`:集成 `qdrant-client` 完成向量检索,支持 scoreThreshold 过滤 `[AC-AISVC-16, AC-AISVC-17]`
- [x] T2.5 编写 Memory 与 Retrieval 层的独立单元测试Mock 数据库与向量库) `[AC-AISVC-10, AC-AISVC-11]`
### 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]`
- [x] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]`
### Phase 4: 流式响应SSE 实现与状态机)
- [x] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]`
- [x] T4.2 实现 SSE 事件生成器:根据 Orchestrator 的增量输出包装 `message` 事件 `[AC-AISVC-07]`
- [x] T4.3 实现 SSE 状态机:确保 `final``error` 事件后连接正确关闭,且顺序不乱 `[AC-AISVC-08, AC-AISVC-09]`
- [x] T4.4 实现流式输出过程中的异常捕获,并转化为 `event: error` 输出 `[AC-AISVC-09]`
### Phase 5: 集成与冒烟测试Quality Assurance
- [x] T5.1 编写集成测试:模拟多租户并发请求,验证数据存储与检索的严格物理/逻辑隔离 `[AC-AISVC-10, AC-AISVC-11]`
- [x] T5.2 编写 RAG 冒烟测试:模拟"检索命中"与"检索未命中"两种场景,验证 confidence 变化与回复兜底 `[AC-AISVC-17, AC-AISVC-18]`
- [x] T5.3 契约测试:验证 provider 契约一致性 `[AC-AISVC-01, AC-AISVC-02]`
### Phase 6: 前后端联调真实对接v0.2.0 迭代)
- [x] T6.1 定义知识库相关实体:`KnowledgeBase`、`Document`、`IndexJob` SQLModel 实体 `[AC-AISVC-21, AC-AISVC-22, AC-AISVC-23, AC-AISVC-24]`
- [x] T6.2 实现 `KBService`:文档上传、存储、列表查询、索引任务状态查询 `[AC-AISVC-21, AC-AISVC-23, AC-AISVC-24]`
- [x] T6.3 实现知识库管理 API`POST /admin/kb/documents` 真实文件存储与异步索引 `[AC-AISVC-21, AC-AISVC-22]`
- [x] T6.4 实现知识库管理 API`GET /admin/kb/documents` 真实数据库查询 `[AC-AISVC-23]`
- [x] T6.5 实现知识库管理 API`GET /admin/kb/index/jobs/{jobId}` 真实任务状态查询 `[AC-AISVC-24]`
- [x] T6.6 实现 RAG 实验室 API`POST /admin/rag/experiments/run` 真实向量检索 `[AC-AISVC-25, AC-AISVC-26]`
- [x] T6.7 实现会话监控 API`GET /admin/sessions` 真实会话列表查询 `[AC-AISVC-27]`
- [x] T6.8 实现会话监控 API`GET /admin/sessions/{sessionId}` 真实会话详情查询 `[AC-AISVC-28]`
- [x] T6.9 前后端联调验证:确认前端页面正常调用后端真实接口 ✅
---
## 3. 待澄清Open Questions
> ✅ 已确认:以下事项均已由产品/架构反馈确认,可直接作为实现基准。
1.**Collection 初始化**:采用**提前预置**模式,不通过业务请求动态创建。
2.**超时策略**Python 内部设置 **20s 硬超时**,防止资源泄露与请求堆积。
3.**SSE 心跳**:必须实现 `: ping` 机制Keep-alive防止网关/中间件断开连接。
4.**置信度**MVP 优先基于 RAG 检索分数Score计算 `confidence`
5.**Token 计数**:统一使用 `tiktoken` 库进行精确 Token 计数(用于 history 截断与证据预算)。
---
## 4. 任务状态说明
- ⏳ 待处理 (Pending)
- 🔄 进行中 (In Progress)
- ✅ 已完成 (Completed)
- ❌ 已取消 (Cancelled)
---
## 5. 完成总结
**Phase 1-10 已全部完成Phase 12 部分完成**
| Phase | 描述 | 任务数 | 状态 |
|-------|------|--------|------|
| Phase 1 | 基础设施 | 6 | ✅ 完成 |
| Phase 2 | 存储与检索 | 5 | ✅ 完成 |
| Phase 3 | 核心编排 | 5 | ✅ 完成 |
| Phase 4 | 流式响应 | 4 | ✅ 完成 |
| Phase 5 | 集成测试 | 3 | ✅ 完成 |
| Phase 6 | 前后端联调真实对接 | 9 | ✅ 完成 |
| Phase 7 | 嵌入模型可插拔与文档解析 | 21 | ✅ 完成 |
| Phase 8 | LLM 配置与 RAG 调试输出 | 10 | ✅ 完成 |
| Phase 9 | 租户管理与 RAG 优化 | 10 | ✅ 完成 |
| Phase 10 | Prompt 模板化 | 10 | 🔄 进行中 (8/10) |
| Phase 11 | 多知识库管理 | 8 | 🔄 进行中 (5/8) |
| Phase 12 | 意图识别与规则引擎 | 7 | 🔄 进行中 (5/7) |
| Phase 13 | 话术流程引擎 | 7 | ⏳ 待处理 |
| Phase 14 | 输出护栏 | 8 | ⏳ 待处理 |
| Phase 15 | 智能 RAG 增强与编排升级 | 8 | ⏳ 待处理 |
**已完成: 91 个任务**
---
### Phase 7: 嵌入模型可插拔与文档解析支持v0.3.0 迭代)
- [x] T7.1 设计 `EmbeddingProvider` 抽象基类:定义 `embed()`、`embed_batch()`、`get_dimension()` 接口 `[AC-AISVC-29]`
- [x] T7.2 实现 `EmbeddingProviderFactory` 工厂类:支持根据配置动态加载提供者 `[AC-AISVC-30]`
- [x] T7.3 实现 `OllamaEmbeddingProvider`:封装 Ollama API 调用 `[AC-AISVC-29, AC-AISVC-30]`
- [x] T7.4 实现 `OpenAIEmbeddingProvider`:封装 OpenAI Embedding API `[AC-AISVC-29, AC-AISVC-30]`
- [x] T7.5 实现嵌入配置管理:支持动态配置与热更新 `[AC-AISVC-31]`
- [x] T7.6 实现嵌入模型错误处理与 fallback 策略 `[AC-AISVC-32]`
- [x] T7.7 实现 `DocumentParser` 抽象接口:定义 `parse()` 方法返回纯文本 `[AC-AISVC-33]`
- [x] T7.8 实现 `PDFParser`:使用 PyMuPDF/pdfplumber 解析 PDF `[AC-AISVC-33]`
- [x] T7.9 实现 `WordParser`:使用 python-docx 解析 Word 文档 `[AC-AISVC-34]`
- [x] T7.10 实现 `ExcelParser`:使用 openpyxl 解析 Excel 文档 `[AC-AISVC-35]`
- [x] T7.11 实现 `DocumentParserFactory`:根据文件扩展名选择解析器 `[AC-AISVC-33, AC-AISVC-34, AC-AISVC-35]`
- [x] T7.12 实现文档解析错误处理与格式校验 `[AC-AISVC-36, AC-AISVC-37]`
- [x] T7.13 实现 `GET /admin/embedding/providers` API返回可用提供者列表 `[AC-AISVC-38]`
- [x] T7.14 实现 `GET /admin/embedding/config` API返回当前配置 `[AC-AISVC-39]`
- [x] T7.15 实现 `PUT /admin/embedding/config` API更新配置 `[AC-AISVC-40]`
- [x] T7.16 实现 `POST /admin/embedding/test` API测试嵌入连接 `[AC-AISVC-41]`
- [x] T7.17 集成嵌入服务到索引流程:替换现有硬编码 Ollama 调用 `[AC-AISVC-29]`
- [x] T7.18 集成文档解析到上传流程:支持多格式文档上传 `[AC-AISVC-33, AC-AISVC-34, AC-AISVC-35]`
- [x] T7.19 编写嵌入服务单元测试 `[AC-AISVC-29, AC-AISVC-30, AC-AISVC-31, AC-AISVC-32]`
- [x] T7.20 编写文档解析单元测试 `[AC-AISVC-33, AC-AISVC-34, AC-AISVC-35, AC-AISVC-36, AC-AISVC-37]`
- [x] T7.21 编写嵌入管理 API 集成测试 `[AC-AISVC-38, AC-AISVC-39, AC-AISVC-40, AC-AISVC-41]`
---
### Phase 8: LLM 配置与 RAG 调试输出v0.4.0 迭代)
- [x] T8.1 设计 `LLMProviderFactory` 工厂类:支持根据配置动态加载提供者 `[AC-AISVC-42]`
- [x] T8.2 实现 `LLMConfigManager` 配置管理:支持动态配置与热更新 `[AC-AISVC-43, AC-AISVC-44]`
- [x] T8.3 实现 `GET /admin/llm/providers` API返回可用提供者列表 `[AC-AISVC-42]`
- [x] T8.4 实现 `GET /admin/llm/config` API返回当前配置 `[AC-AISVC-43]`
- [x] T8.5 实现 `PUT /admin/llm/config` API更新配置 `[AC-AISVC-44]`
- [x] T8.6 实现 `POST /admin/llm/test` API测试 LLM 连接 `[AC-AISVC-45, AC-AISVC-46]`
- [x] T8.7 更新 RAG 实验接口:支持 AI 回复生成 `[AC-AISVC-47, AC-AISVC-49]`
- [x] T8.8 实现 RAG 实验流式输出SSE 流式 AI 回复 `[AC-AISVC-48]`
- [x] T8.9 支持指定 LLM 提供者RAG 实验可选择不同 LLM `[AC-AISVC-50]`
- [x] T8.10 更新 OpenAPI 契约:添加 LLM 管理和 RAG 实验增强接口 ✅
---
### Phase 9: 租户管理与 RAG 优化v0.5.0 迭代)
- [x] T9.1 实现 `Tenant` 实体:定义租户数据模型 `[AC-AISVC-10]`
- [x] T9.2 实现租户 ID 格式校验:`name@ash@year` 格式验证 `[AC-AISVC-10, AC-AISVC-12]`
- [x] T9.3 实现租户自动创建:请求时自动创建不存在的租户 `[AC-AISVC-10]`
- [x] T9.4 实现 `GET /admin/tenants` API返回租户列表 `[AC-AISVC-10]`
- [x] T9.5 前端租户选择器:实现租户切换功能 `[AC-ASA-01]`
- [x] T9.6 文档多编码支持:支持 UTF-8、GBK、GB2312 等编码解码 `[AC-AISVC-21]`
- [x] T9.7 按行分块功能:实现 `chunk_text_by_lines` 函数 `[AC-AISVC-22]`
- [x] T9.8 实现 `NomicEmbeddingProvider`:支持多维度向量 `[AC-AISVC-29]`
- [x] T9.9 实现多向量存储:支持 full/256/512 三种维度 `[AC-AISVC-16]`
- [x] T9.10 实现 `KnowledgeIndexer`:优化的知识库索引服务 `[AC-AISVC-22]`
---
### Phase 10: Prompt 模板化v0.6.0 迭代)
> 目标:将硬编码的 SYSTEM_PROMPT 改为数据库驱动的模板系统,支持按租户配置人设、版本管理、热更新。
- [x] T10.1 定义 `PromptTemplate``PromptTemplateVersion` SQLModel 实体,创建数据库表 `[AC-AISVC-51, AC-AISVC-52]`
- [x] T10.2 实现 `PromptTemplateService`:模板 CRUD创建、查询列表、查询详情、更新 `[AC-AISVC-52, AC-AISVC-57, AC-AISVC-58]`
- [x] T10.3 实现模板版本管理:更新时自动创建新版本,保留历史版本 `[AC-AISVC-53]`
- [x] T10.4 实现模板发布与回滚:`publish` 将指定版本标记为已发布,`rollback` 恢复历史版本 `[AC-AISVC-54, AC-AISVC-55]`
- [x] T10.5 实现 `VariableResolver`内置变量注入persona_name/current_time/channel_type 等)+ 自定义变量替换 `[AC-AISVC-56]`
- [x] T10.6 实现模板缓存:内存缓存 + TTL 过期 + 发布/回滚时主动失效fallback 到硬编码 SYSTEM_PROMPT `[AC-AISVC-51]`
- [x] T10.7 实现 Prompt 模板管理 API`POST/GET/PUT /admin/prompt-templates``GET /admin/prompt-templates/{tplId}` `[AC-AISVC-52, AC-AISVC-57, AC-AISVC-58]`
- [x] T10.8 实现 Prompt 模板发布/回滚 API`POST /admin/prompt-templates/{tplId}/publish``POST /admin/prompt-templates/{tplId}/rollback` `[AC-AISVC-54, AC-AISVC-55]`
- [ ] T10.9 修改 Orchestrator 的 `_build_llm_messages()`:从模板服务加载系统指令替代硬编码 `[AC-AISVC-56]`
- [ ] T10.10 编写 Prompt 模板服务单元测试 `[AC-AISVC-51~AC-AISVC-58]`
---
### Phase 11: 多知识库管理v0.6.0 迭代)
> 目标:从单个 kb_default 升级为多知识库分类管理,支持按类型和优先级组织知识。
- [x] T11.1 扩展 `KnowledgeBase` 实体:新增 `kb_type`、`priority`、`is_enabled`、`doc_count` 字段 `[AC-AISVC-59]`
- [x] T11.2 实现知识库 CRUD 服务:创建时初始化 Qdrant Collection删除时清理 Collection `[AC-AISVC-59, AC-AISVC-61, AC-AISVC-62]`
- [x] T11.3 实现知识库管理 API`POST/GET/PUT/DELETE /admin/kb/knowledge-bases` `[AC-AISVC-59, AC-AISVC-60, AC-AISVC-61, AC-AISVC-62]`
- [x] T11.4 升级 Qdrant Collection 命名:`kb_{tenant_id}_{kb_id}`,兼容现有 `kb_{tenant_id}` `[AC-AISVC-63]`
- [x] T11.5 修改文档上传流程:支持指定 `kbId` 参数,索引到对应 Collection `[AC-AISVC-63]`
- [ ] T11.6 修改 `OptimizedRetriever`:支持 `target_kb_ids` 参数,实现多 Collection 并行检索 `[AC-AISVC-64]`
- [ ] T11.7 实现 `kb_default` 自动迁移:首次启动时为现有数据创建默认知识库记录 `[AC-AISVC-59]`
- [ ] T11.8 编写多知识库服务单元测试 `[AC-AISVC-59~AC-AISVC-64]`
---
### Phase 12: 意图识别与规则引擎v0.6.0 迭代)
> 目标:实现基于关键词+正则的意图识别,根据意图路由到不同处理链路。
- [x] T12.1 定义 `IntentRule` SQLModel 实体,创建数据库表 `[AC-AISVC-65]`
- [x] T12.2 实现 `IntentRuleService`:规则 CRUD + 命中统计更新 `[AC-AISVC-65, AC-AISVC-66, AC-AISVC-67, AC-AISVC-68]`
- [x] T12.3 实现 `IntentRouter`:按优先级遍历规则,关键词匹配 + 正则匹配,返回 `IntentMatchResult` `[AC-AISVC-69]`
- [x] T12.4 实现规则缓存:按 tenant_id 缓存规则列表CRUD 操作时主动失效 `[AC-AISVC-69]`
- [x] T12.5 实现意图规则管理 API`POST/GET/PUT/DELETE /admin/intent-rules` `[AC-AISVC-65, AC-AISVC-66, AC-AISVC-67, AC-AISVC-68]`
- [ ] T12.6 在 Orchestrator 中集成 IntentRouterRAG 检索前执行意图识别,按 response_type 路由 `[AC-AISVC-69, AC-AISVC-70]`
- [ ] T12.7 编写意图识别服务单元测试 `[AC-AISVC-65~AC-AISVC-70]`
---
### Phase 13: 话术流程引擎v0.6.0 迭代)
> 目标:实现固定话术步骤的状态机引擎,支持多轮引导对话。
- [x] T13.1 定义 `ScriptFlow``FlowInstance` SQLModel 实体,创建数据库表 `[AC-AISVC-71, AC-AISVC-74]`
- [x] T13.2 实现 `ScriptFlowService`:流程定义 CRUD `[AC-AISVC-71, AC-AISVC-72, AC-AISVC-73]`
- [x] T13.3 实现 `FlowEngine.check_active_flow()`:检查会话是否有活跃流程实例 `[AC-AISVC-75]`
- [x] T13.4 实现 `FlowEngine.start()`:创建流程实例,返回第一步话术 `[AC-AISVC-74]`
- [x] T13.5 实现 `FlowEngine.advance()`:根据用户输入匹配条件,推进步骤或重复当前步骤 `[AC-AISVC-75, AC-AISVC-76]`
- [x] T13.6 实现话术流程管理 API`POST/GET/PUT /admin/script-flows` `[AC-AISVC-71, AC-AISVC-72, AC-AISVC-73]`
- [ ] T13.7 编写话术流程引擎单元测试 `[AC-AISVC-71~AC-AISVC-77]`
---
### Phase 14: 输出护栏v0.6.0 迭代)
> 目标:实现禁词检测与内容过滤,保障 AI 输出合规可控。
- [ ] T14.1 定义 `ForbiddenWord``BehaviorRule` SQLModel 实体,创建数据库表 `[AC-AISVC-78, AC-AISVC-84]`
- [ ] T14.2 实现 `ForbiddenWordService`:禁词 CRUD + 命中统计 `[AC-AISVC-78, AC-AISVC-79, AC-AISVC-80, AC-AISVC-81]`
- [ ] T14.3 实现 `BehaviorRuleService`:行为规则 CRUD `[AC-AISVC-84, AC-AISVC-85]`
- [ ] T14.4 实现 `InputScanner`:用户输入前置禁词检测(仅记录,不阻断) `[AC-AISVC-83]`
- [ ] T14.5 实现 `OutputFilter`LLM 输出后置过滤mask/replace/block 三种策略) `[AC-AISVC-82]`
- [ ] T14.6 实现 Streaming 模式下的滑动窗口禁词检测 `[AC-AISVC-82]`
- [ ] T14.7 实现护栏管理 API`POST/GET/PUT/DELETE /admin/guardrails/forbidden-words``POST/GET /admin/guardrails/behavior-rules` `[AC-AISVC-78~AC-AISVC-85]`
- [ ] T14.8 编写输出护栏服务单元测试 `[AC-AISVC-78~AC-AISVC-85]`
---
### Phase 15: 智能 RAG 增强与编排升级v0.6.0 迭代)
> 目标Query 改写、分层排序、行为规则注入、Orchestrator 升级为 12 步 pipeline。
- [ ] T15.1 实现 `QueryRewriter`:基于 LLM 的 Query 改写(解析指代词、补全语义),支持配置开关 `[AC-AISVC-86]`
- [ ] T15.2 实现 `ResultRanker`:按知识库类型优先级 + 自定义权重 + 相似度分数的多维排序 `[AC-AISVC-87]`
- [ ] T15.3 实现话术模板优先匹配script 类型高分命中时优先作为回复参考 `[AC-AISVC-88]`
- [ ] T15.4 实现行为规则注入到 Prompt从 BehaviorRuleService 加载规则,追加到系统指令末尾 `[AC-AISVC-84]`
- [ ] T15.5 升级 Orchestrator整合 InputScanner → FlowEngine → IntentRouter → QueryRewriter → 多知识库检索 → ResultRanker → PromptBuilder → LLM → OutputFilter 完整 12 步 pipeline `[AC-AISVC-69, AC-AISVC-64, AC-AISVC-82, AC-AISVC-86, AC-AISVC-87]`
- [ ] T15.6 预留 `AudioParser``VideoParser` 扩展点(仅接口定义,不实现) `[AC-AISVC-89]`
- [ ] T15.7 预留对话记录结构化导入接口(仅接口定义,不实现) `[AC-AISVC-90]`
- [ ] T15.8 编写 Orchestrator 升级集成测试:验证意图路由 → 流程引擎 → 多知识库检索 → 护栏过滤的完整链路 `[AC-AISVC-51~AC-AISVC-90]`