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

8.2 KiB
Raw Blame History

feature_id title status version last_updated
AISVC Python AI 中台（ai-service）任务清单 completed 0.3.0 2026-02-24

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-7 已全部完成

Phase 描述 任务数 状态
Phase 1 基础设施 6 ✅ 完成
Phase 2 存储与检索 5 ✅ 完成
Phase 3 核心编排 5 ✅ 完成
Phase 4 流式响应 4 ✅ 完成
Phase 5 集成测试 3 ✅ 完成
Phase 6 前后端联调真实对接 9 ✅ 完成
Phase 7 嵌入模型可插拔与文档解析 21 ✅ 完成

已完成: 53 个任务

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