MerCry
/
ai-robot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-core/spec/ai-service/tasks.md

18 KiB
Raw Blame History

feature_id title status version last_updated
AISVC Python AI 中台（ai-service）任务清单 in-progress 0.6.0 2026-02-27

Python AI 中台任务清单（AISVC）

1. 任务拆分原则

  • 原子性：每个任务仅解决一个具体技术点或功能逻辑。
  • 可验证性：任务完成后必须可通过单元测试、接口冒烟或契约校验。
  • 弱模型可执行：任务描述清晰，不依赖 AI 猜测业务逻辑。

2. 任务执行计划

Phase 1: 基础设施（FastAPI 框架与多租户基础）

  • T1.1 初始化 FastAPI 项目骨架，配置基础环境与日志（包含 X-Tenant-Id 记录） [AC-AISVC-01] ✅
  • T1.2 实现 X-Tenant-Id Header 拦截器，校验必填性并注入 Request State [AC-AISVC-10, AC-AISVC-12] ✅
  • 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] ✅
  • 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 实现与状态机）

  • 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] ✅

Phase 5: 集成与冒烟测试（Quality Assurance）

  • T5.1 编写集成测试：模拟多租户并发请求，验证数据存储与检索的严格物理/逻辑隔离 [AC-AISVC-10, AC-AISVC-11] ✅
  • T5.2 编写 RAG 冒烟测试：模拟"检索命中"与"检索未命中"两种场景，验证 confidence 变化与回复兜底 [AC-AISVC-17, AC-AISVC-18] ✅
  • T5.3 契约测试：验证 provider 契约一致性 [AC-AISVC-01, AC-AISVC-02] ✅

Phase 6: 前后端联调真实对接（v0.2.0 迭代）

  • T6.1 定义知识库相关实体：KnowledgeBase、Document、IndexJob SQLModel 实体 [AC-AISVC-21, AC-AISVC-22, AC-AISVC-23, AC-AISVC-24] ✅
  • T6.2 实现 KBService：文档上传、存储、列表查询、索引任务状态查询 [AC-AISVC-21, AC-AISVC-23, AC-AISVC-24] ✅
  • T6.3 实现知识库管理 API：POST /admin/kb/documents 真实文件存储与异步索引 [AC-AISVC-21, AC-AISVC-22] ✅
  • T6.4 实现知识库管理 API：GET /admin/kb/documents 真实数据库查询 [AC-AISVC-23] ✅
  • T6.5 实现知识库管理 API：GET /admin/kb/index/jobs/{jobId} 真实任务状态查询 [AC-AISVC-24] ✅
  • T6.6 实现 RAG 实验室 API：POST /admin/rag/experiments/run 真实向量检索 [AC-AISVC-25, AC-AISVC-26] ✅
  • T6.7 实现会话监控 API：GET /admin/sessions 真实会话列表查询 [AC-AISVC-27] ✅
  • T6.8 实现会话监控 API：GET /admin/sessions/{sessionId} 真实会话详情查询 [AC-AISVC-28] ✅
  • 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 ⏳ 待处理
Phase 12 意图识别与规则引擎 7 🔄 进行中 (5/7)
Phase 13 话术流程引擎 7 ⏳ 待处理
Phase 14 输出护栏 8 ⏳ 待处理
Phase 15 智能 RAG 增强与编排升级 8 ⏳ 待处理

已完成: 86 个任务

Phase 7: 嵌入模型可插拔与文档解析支持（v0.3.0 迭代）

  • T7.1 设计 EmbeddingProvider 抽象基类：定义 embed()、embed_batch()、get_dimension() 接口 [AC-AISVC-29] ✅
  • T7.2 实现 EmbeddingProviderFactory 工厂类：支持根据配置动态加载提供者 [AC-AISVC-30] ✅
  • T7.3 实现 OllamaEmbeddingProvider：封装 Ollama API 调用 [AC-AISVC-29, AC-AISVC-30] ✅
  • T7.4 实现 OpenAIEmbeddingProvider：封装 OpenAI Embedding API [AC-AISVC-29, AC-AISVC-30] ✅
  • T7.5 实现嵌入配置管理：支持动态配置与热更新 [AC-AISVC-31] ✅
  • T7.6 实现嵌入模型错误处理与 fallback 策略 [AC-AISVC-32] ✅
  • T7.7 实现 DocumentParser 抽象接口：定义 parse() 方法返回纯文本 [AC-AISVC-33] ✅
  • T7.8 实现 PDFParser：使用 PyMuPDF/pdfplumber 解析 PDF [AC-AISVC-33] ✅
  • T7.9 实现 WordParser：使用 python-docx 解析 Word 文档 [AC-AISVC-34] ✅
  • T7.10 实现 ExcelParser：使用 openpyxl 解析 Excel 文档 [AC-AISVC-35] ✅
  • T7.11 实现 DocumentParserFactory：根据文件扩展名选择解析器 [AC-AISVC-33, AC-AISVC-34, AC-AISVC-35] ✅
  • T7.12 实现文档解析错误处理与格式校验 [AC-AISVC-36, AC-AISVC-37] ✅
  • T7.13 实现 GET /admin/embedding/providers API：返回可用提供者列表 [AC-AISVC-38] ✅
  • T7.14 实现 GET /admin/embedding/config API：返回当前配置 [AC-AISVC-39] ✅
  • T7.15 实现 PUT /admin/embedding/config API：更新配置 [AC-AISVC-40] ✅
  • T7.16 实现 POST /admin/embedding/test API：测试嵌入连接 [AC-AISVC-41] ✅
  • T7.17 集成嵌入服务到索引流程：替换现有硬编码 Ollama 调用 [AC-AISVC-29] ✅
  • T7.18 集成文档解析到上传流程：支持多格式文档上传 [AC-AISVC-33, AC-AISVC-34, AC-AISVC-35] ✅
  • T7.19 编写嵌入服务单元测试 [AC-AISVC-29, AC-AISVC-30, AC-AISVC-31, AC-AISVC-32] ✅
  • T7.20 编写文档解析单元测试 [AC-AISVC-33, AC-AISVC-34, AC-AISVC-35, AC-AISVC-36, AC-AISVC-37] ✅
  • T7.21 编写嵌入管理 API 集成测试 [AC-AISVC-38, AC-AISVC-39, AC-AISVC-40, AC-AISVC-41] ✅

Phase 8: LLM 配置与 RAG 调试输出（v0.4.0 迭代）

  • T8.1 设计 LLMProviderFactory 工厂类：支持根据配置动态加载提供者 [AC-AISVC-42] ✅
  • T8.2 实现 LLMConfigManager 配置管理：支持动态配置与热更新 [AC-AISVC-43, AC-AISVC-44] ✅
  • T8.3 实现 GET /admin/llm/providers API：返回可用提供者列表 [AC-AISVC-42] ✅
  • T8.4 实现 GET /admin/llm/config API：返回当前配置 [AC-AISVC-43] ✅
  • T8.5 实现 PUT /admin/llm/config API：更新配置 [AC-AISVC-44] ✅
  • T8.6 实现 POST /admin/llm/test API：测试 LLM 连接 [AC-AISVC-45, AC-AISVC-46] ✅
  • T8.7 更新 RAG 实验接口：支持 AI 回复生成 [AC-AISVC-47, AC-AISVC-49] ✅
  • T8.8 实现 RAG 实验流式输出：SSE 流式 AI 回复 [AC-AISVC-48] ✅
  • T8.9 支持指定 LLM 提供者：RAG 实验可选择不同 LLM [AC-AISVC-50] ✅
  • T8.10 更新 OpenAPI 契约：添加 LLM 管理和 RAG 实验增强接口 ✅

Phase 9: 租户管理与 RAG 优化（v0.5.0 迭代）

  • T9.1 实现 Tenant 实体：定义租户数据模型 [AC-AISVC-10] ✅
  • T9.2 实现租户 ID 格式校验：name@ash@year 格式验证 [AC-AISVC-10, AC-AISVC-12] ✅
  • T9.3 实现租户自动创建：请求时自动创建不存在的租户 [AC-AISVC-10] ✅
  • T9.4 实现 GET /admin/tenants API：返回租户列表 [AC-AISVC-10] ✅
  • T9.5 前端租户选择器：实现租户切换功能 [AC-ASA-01] ✅
  • T9.6 文档多编码支持：支持 UTF-8、GBK、GB2312 等编码解码 [AC-AISVC-21] ✅
  • T9.7 按行分块功能：实现 chunk_text_by_lines 函数 [AC-AISVC-22] ✅
  • T9.8 实现 NomicEmbeddingProvider：支持多维度向量 [AC-AISVC-29] ✅
  • T9.9 实现多向量存储：支持 full/256/512 三种维度 [AC-AISVC-16] ✅
  • T9.10 实现 KnowledgeIndexer：优化的知识库索引服务 [AC-AISVC-22] ✅

Phase 10: Prompt 模板化（v0.6.0 迭代）

目标：将硬编码的 SYSTEM_PROMPT 改为数据库驱动的模板系统，支持按租户配置人设、版本管理、热更新。

  • T10.1 定义 PromptTemplate 和 PromptTemplateVersion SQLModel 实体，创建数据库表 [AC-AISVC-51, AC-AISVC-52] ✅
  • T10.2 实现 PromptTemplateService：模板 CRUD（创建、查询列表、查询详情、更新） [AC-AISVC-52, AC-AISVC-57, AC-AISVC-58] ✅
  • T10.3 实现模板版本管理：更新时自动创建新版本，保留历史版本 [AC-AISVC-53] ✅
  • T10.4 实现模板发布与回滚：publish 将指定版本标记为已发布，rollback 恢复历史版本 [AC-AISVC-54, AC-AISVC-55] ✅
  • T10.5 实现 VariableResolver：内置变量注入（persona_name/current_time/channel_type 等）+ 自定义变量替换 [AC-AISVC-56] ✅
  • T10.6 实现模板缓存：内存缓存 + TTL 过期 + 发布/回滚时主动失效，fallback 到硬编码 SYSTEM_PROMPT [AC-AISVC-51] ✅
  • T10.7 实现 Prompt 模板管理 API：POST/GET/PUT /admin/prompt-templates，GET /admin/prompt-templates/{tplId} [AC-AISVC-52, AC-AISVC-57, AC-AISVC-58] ✅
  • 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 升级为多知识库分类管理，支持按类型和优先级组织知识。

  • T11.1 扩展 KnowledgeBase 实体：新增 kb_type、priority、is_enabled、doc_count 字段 [AC-AISVC-59]
  • T11.2 实现知识库 CRUD 服务：创建时初始化 Qdrant Collection，删除时清理 Collection [AC-AISVC-59, AC-AISVC-61, AC-AISVC-62]
  • T11.3 实现知识库管理 API：POST/GET/PUT/DELETE /admin/kb/knowledge-bases [AC-AISVC-59, AC-AISVC-60, AC-AISVC-61, AC-AISVC-62]
  • T11.4 升级 Qdrant Collection 命名：kb_{tenant_id}_{kb_id}，兼容现有 kb_{tenant_id} [AC-AISVC-63]
  • 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 迭代）

目标：实现基于关键词+正则的意图识别，根据意图路由到不同处理链路。

  • T12.1 定义 IntentRule SQLModel 实体，创建数据库表 [AC-AISVC-65] ✅
  • T12.2 实现 IntentRuleService：规则 CRUD + 命中统计更新 [AC-AISVC-65, AC-AISVC-66, AC-AISVC-67, AC-AISVC-68] ✅
  • T12.3 实现 IntentRouter：按优先级遍历规则，关键词匹配 + 正则匹配，返回 IntentMatchResult [AC-AISVC-69] ✅
  • T12.4 实现规则缓存：按 tenant_id 缓存规则列表，CRUD 操作时主动失效 [AC-AISVC-69] ✅
  • 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 中集成 IntentRouter：RAG 检索前执行意图识别，按 response_type 路由 [AC-AISVC-69, AC-AISVC-70]
  • T12.7 编写意图识别服务单元测试 [AC-AISVC-65~AC-AISVC-70]

Phase 13: 话术流程引擎（v0.6.0 迭代）

目标：实现固定话术步骤的状态机引擎，支持多轮引导对话。

  • T13.1 定义 ScriptFlow 和 FlowInstance SQLModel 实体，创建数据库表 [AC-AISVC-71, AC-AISVC-74]
  • T13.2 实现 ScriptFlowService：流程定义 CRUD [AC-AISVC-71, AC-AISVC-72, AC-AISVC-73]
  • T13.3 实现 FlowEngine.check_active_flow()：检查会话是否有活跃流程实例 [AC-AISVC-75]
  • T13.4 实现 FlowEngine.start()：创建流程实例，返回第一步话术 [AC-AISVC-74]
  • T13.5 实现 FlowEngine.advance()：根据用户输入匹配条件，推进步骤或重复当前步骤 [AC-AISVC-75, AC-AISVC-76]
  • 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]