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

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

# 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-7 已全部完成，Phase 8 进行中**

| 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 | ⏳ 进行中 |

**已完成: 53 个任务 | 进行中: 10 个任务**

---

### 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 实验增强接口 ✅
-												docs: confirm open questions and update design [AC-AISVC-01]

											
										
										
											2026-02-24 05:00:08 +00:00
+								---
 								feature_id: "AISVC"
 								title: "Python AI 中台（ai-service）任务清单"
-												docs(ai-service): update progress files [AISVC-ALL] all phases completed

- Update spec/ai-service/progress.md with Phase 3 completion details
- Update spec/ai-service/tasks.md status to completed
- All 5 phases (23 tasks) completed: T1.1-T1.6, T2.1-T2.5, T3.1-T3.5, T4.1-T4.4, T5.1-T5.3
- 184 tests passing
- All AC markers covered: AC-AISVC-01~AC-AISVC-20

											
										
										
											2026-02-24 06:00:02 +00:00
+								status: "completed"
-												feat(AISVC-T8): LLM配置管理与RAG调试输出支持 [AC-AISVC-42, AC-AISVC-43, AC-AISVC-44, AC-AISVC-45, AC-AISVC-46, AC-AISVC-47, AC-AISVC-48, AC-AISVC-49, AC-AISVC-50]

- 新增 LLMProviderFactory 工厂类支持 OpenAI/Ollama/Azure [AC-AISVC-42]
- 新增 LLMConfigManager 支持配置热更新 [AC-AISVC-43, AC-AISVC-44]
- 新增 LLM 管理 API 端点 [AC-AISVC-42~AC-AISVC-46]
- 更新 RAG 实验接口支持 AI 回复生成 [AC-AISVC-47, AC-AISVC-49]
- 新增 RAG 实验流式输出 SSE [AC-AISVC-48]
- 支持指定 LLM 提供者 [AC-AISVC-50]
- 更新 OpenAPI 契约添加 LLM 管理接口
- 更新前后端规范文档 v0.4.0 迭代

											
										
										
											2026-02-24 17:25:53 +00:00
+								version: "0.4.0"
-												docs: confirm open questions and update design [AC-AISVC-01]

											
										
										
											2026-02-24 05:00:08 +00:00
+								last_updated: "2026-02-24"
 								---
 								# Python AI 中台任务清单（AISVC）
 								## 1. 任务拆分原则
 								- **原子性**：每个任务仅解决一个具体技术点或功能逻辑。
 								- **可验证性**：任务完成后必须可通过单元测试、接口冒烟或契约校验。
 								- **弱模型可执行**：任务描述清晰，不依赖 AI 猜测业务逻辑。
 								## 2. 任务执行计划
 								### Phase 1: 基础设施（FastAPI 框架与多租户基础）
-												docs: mark Phase 1 and Phase 2 tasks as completed [AC-AISVC-01~AC-AISVC-20]

											
										
										
											2026-02-24 05:22:56 +00:00
+								- [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]` ✅
-												docs: confirm open questions and update design [AC-AISVC-01]

											
										
										
											2026-02-24 05:00:08 +00:00
 								### Phase 2: 存储与检索实现（Memory & Retrieval）
-												docs: mark Phase 1 and Phase 2 tasks as completed [AC-AISVC-01~AC-AISVC-20]

											
										
										
											2026-02-24 05:22:56 +00:00
+								- [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]` ✅
-												docs: confirm open questions and update design [AC-AISVC-01]

											
										
										
											2026-02-24 05:00:08 +00:00
 								### Phase 3: 核心编排（Orchestrator & LLM Adapter）
-												docs: mark Phase 1 and Phase 2 tasks as completed [AC-AISVC-01~AC-AISVC-20]

											
										
										
											2026-02-24 05:22:56 +00:00
+								- [x] T3.1 实现 LLM Adapter：封装 `langchain-openai` 或官方 SDK，支持 `generate` 与 `stream_generate` `[AC-AISVC-02, AC-AISVC-06]` ✅
-												feat(ai-service): implement SSE event generator for message events [AC-AISVC-07]

- Optimize Orchestrator streaming output with LLM client integration
- Implement _stream_from_llm() to wrap LLM chunks as message events
- Implement _stream_mock_response() for demo/testing
- Add SSE event format tests (message/final/error)
- Fix by_alias=True for final event JSON output
- 79 tests passing

											
										
										
											2026-02-24 05:28:10 +00:00
+								- [x] T3.2 实现 Orchestrator：实现上下文合并逻辑（H_local + H_ext 的去重与截断策略） `[AC-AISVC-14, AC-AISVC-15]` ✅
-												feat(ai-service): implement SSE state machine and error handling [AC-AISVC-08, AC-AISVC-09]

- Integrate state machine in API layer for proper event sequencing
- Ensure message* -> final/error -> close sequence
- Prevent events after final/error
- Convert streaming exceptions to error events
- Add comprehensive state machine tests
- 117 tests passing

											
										
										
											2026-02-24 05:32:59 +00:00
+								- [x] T3.3 实现 Orchestrator：实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ✅
-												feat(ai-service): implement complete Orchestrator generation pipeline for T3.4 [AC-AISVC-01, AC-AISVC-02]

- Integrate Memory, ContextMerger, Retriever, LLMClient, ConfidenceCalculator
- Implement 8-step generation pipeline:
  1. Load local history from Memory
  2. Merge with external history (dedup + truncate)
  3. RAG retrieval (optional)
  4. Build prompt with context and evidence
  5. LLM generation
  6. Calculate confidence
  7. Save messages to Memory
  8. Return ChatResponse
- Add GenerationContext dataclass for tracking intermediate results
- Implement fallback response mechanism for error handling
- Add 21 unit tests for OrchestratorService
- All 138 tests passing

											
										
										
											2026-02-24 05:47:12 +00:00
+								- [x] T3.4 实现 Orchestrator：整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 `[AC-AISVC-01, AC-AISVC-02]` ✅
-												feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02]

- Verify ChatResponse fields match OpenAPI contract
- Test required fields: reply, confidence, shouldTransfer
- Test optional fields: transferReason, metadata
- Test JSON serialization uses camelCase (by_alias=True)
- Test confidence range validation [0.0, 1.0]
- Test ChatRequest contract compliance
- Test ErrorResponse contract compliance
- Test SSEFinalEvent matches ChatResponse structure
- Test SSEErrorEvent matches ErrorResponse structure
- Add end-to-end contract validation with OrchestratorService
- All 184 tests passing

											
										
										
											2026-02-24 05:55:17 +00:00
+								- [x] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` ✅
-												docs: confirm open questions and update design [AC-AISVC-01]

											
										
										
											2026-02-24 05:00:08 +00:00
 								### Phase 4: 流式响应（SSE 实现与状态机）
-												docs(ai-service): update progress files [AISVC-ALL] all phases completed

- Update spec/ai-service/progress.md with Phase 3 completion details
- Update spec/ai-service/tasks.md status to completed
- All 5 phases (23 tasks) completed: T1.1-T1.6, T2.1-T2.5, T3.1-T3.5, T4.1-T4.4, T5.1-T5.3
- 184 tests passing
- All AC markers covered: AC-AISVC-01~AC-AISVC-20

											
										
										
											2026-02-24 06:00:02 +00:00
+								- [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]` ✅
-												docs: confirm open questions and update design [AC-AISVC-01]

											
										
										
											2026-02-24 05:00:08 +00:00
 								### Phase 5: 集成与冒烟测试（Quality Assurance）
-												docs(ai-service): update progress files [AISVC-ALL] all phases completed

- Update spec/ai-service/progress.md with Phase 3 completion details
- Update spec/ai-service/tasks.md status to completed
- All 5 phases (23 tasks) completed: T1.1-T1.6, T2.1-T2.5, T3.1-T3.5, T4.1-T4.4, T5.1-T5.3
- 184 tests passing
- All AC markers covered: AC-AISVC-01~AC-AISVC-20

											
										
										
											2026-02-24 06:00:02 +00:00
+								- [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]` ✅
-												docs: confirm open questions and update design [AC-AISVC-01]

											
										
										
											2026-02-24 05:00:08 +00:00
-												feat(ai-service): v0.2.0 前后端联调真实对接

实现内容:
- 新增知识库实体模型 (KnowledgeBase, Document, IndexJob)
- 新增 KBService 服务层，支持文档上传、存储、索引任务管理
- 实现知识库管理 API 真实对接 (POST/GET /admin/kb/documents)
- 实现索引任务状态查询 API (GET /admin/kb/index/jobs/{jobId})
- 实现 RAG 实验室真实向量检索 (POST /admin/rag/experiments/run)
- 实现会话监控真实数据库查询 (GET /admin/sessions)

规范更新:
- requirements.md: v0.1.0 -> v0.2.0, 新增 AC-AISVC-21~28
- tasks.md: v0.1.0 -> v0.2.0, 新增 Phase 6 (9个任务)
- openapi.admin.yaml: L0 -> L1, 更新 x-requirements 映射

验收标准: AC-AISVC-21, AC-AISVC-22, AC-AISVC-23, AC-AISVC-24,
          AC-AISVC-25, AC-AISVC-26, AC-AISVC-27, AC-AISVC-28

											
										
										
											2026-02-24 10:16:29 +00:00
+								### 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 前后端联调验证：确认前端页面正常调用后端真实接口 ✅
-												docs: confirm open questions and update design [AC-AISVC-01]

											
										
										
											2026-02-24 05:00:08 +00:00
+								---
 								## 3. 待澄清（Open Questions）
 								> ✅ 已确认：以下事项均已由产品/架构反馈确认，可直接作为实现基准。
 . ✅ **Collection 初始化**：采用**提前预置**模式，不通过业务请求动态创建。
 . ✅ **超时策略**：Python 内部设置 **20s 硬超时**，防止资源泄露与请求堆积。
 . ✅ **SSE 心跳**：必须实现 `: ping` 机制（Keep-alive），防止网关/中间件断开连接。
 . ✅ **置信度**：MVP 优先基于 RAG 检索分数（Score）计算 `confidence`。
 . ✅ **Token 计数**：统一使用 `tiktoken` 库进行精确 Token 计数（用于 history 截断与证据预算）。
 								---
 								## 4. 任务状态说明
 								- ⏳ 待处理 (Pending)
 								- 🔄 进行中 (In Progress)
 								- ✅ 已完成 (Completed)
 								- ❌ 已取消 (Cancelled)
-												docs(ai-service): update progress files [AISVC-ALL] all phases completed

- Update spec/ai-service/progress.md with Phase 3 completion details
- Update spec/ai-service/tasks.md status to completed
- All 5 phases (23 tasks) completed: T1.1-T1.6, T2.1-T2.5, T3.1-T3.5, T4.1-T4.4, T5.1-T5.3
- 184 tests passing
- All AC markers covered: AC-AISVC-01~AC-AISVC-20

											
										
										
											2026-02-24 06:00:02 +00:00
 								---
 								## 5. 完成总结
-												feat(AISVC-T8): LLM配置管理与RAG调试输出支持 [AC-AISVC-42, AC-AISVC-43, AC-AISVC-44, AC-AISVC-45, AC-AISVC-46, AC-AISVC-47, AC-AISVC-48, AC-AISVC-49, AC-AISVC-50]

- 新增 LLMProviderFactory 工厂类支持 OpenAI/Ollama/Azure [AC-AISVC-42]
- 新增 LLMConfigManager 支持配置热更新 [AC-AISVC-43, AC-AISVC-44]
- 新增 LLM 管理 API 端点 [AC-AISVC-42~AC-AISVC-46]
- 更新 RAG 实验接口支持 AI 回复生成 [AC-AISVC-47, AC-AISVC-49]
- 新增 RAG 实验流式输出 SSE [AC-AISVC-48]
- 支持指定 LLM 提供者 [AC-AISVC-50]
- 更新 OpenAPI 契约添加 LLM 管理接口
- 更新前后端规范文档 v0.4.0 迭代

											
										
										
											2026-02-24 17:25:53 +00:00
+								**Phase 1-7 已全部完成，Phase 8 进行中**
-												docs(ai-service): update progress files [AISVC-ALL] all phases completed

- Update spec/ai-service/progress.md with Phase 3 completion details
- Update spec/ai-service/tasks.md status to completed
- All 5 phases (23 tasks) completed: T1.1-T1.6, T2.1-T2.5, T3.1-T3.5, T4.1-T4.4, T5.1-T5.3
- 184 tests passing
- All AC markers covered: AC-AISVC-01~AC-AISVC-20

											
										
										
											2026-02-24 06:00:02 +00:00
 								| Phase | 描述 | 任务数 | 状态 |
 								|-------|------|--------|------|
 								| Phase 1 | 基础设施 | 6 | ✅ 完成 |
 								| Phase 2 | 存储与检索 | 5 | ✅ 完成 |
 								| Phase 3 | 核心编排 | 5 | ✅ 完成 |
 								| Phase 4 | 流式响应 | 4 | ✅ 完成 |
 								| Phase 5 | 集成测试 | 3 | ✅ 完成 |
-												feat(ai-service): v0.2.0 前后端联调真实对接

实现内容:
- 新增知识库实体模型 (KnowledgeBase, Document, IndexJob)
- 新增 KBService 服务层，支持文档上传、存储、索引任务管理
- 实现知识库管理 API 真实对接 (POST/GET /admin/kb/documents)
- 实现索引任务状态查询 API (GET /admin/kb/index/jobs/{jobId})
- 实现 RAG 实验室真实向量检索 (POST /admin/rag/experiments/run)
- 实现会话监控真实数据库查询 (GET /admin/sessions)

规范更新:
- requirements.md: v0.1.0 -> v0.2.0, 新增 AC-AISVC-21~28
- tasks.md: v0.1.0 -> v0.2.0, 新增 Phase 6 (9个任务)
- openapi.admin.yaml: L0 -> L1, 更新 x-requirements 映射

验收标准: AC-AISVC-21, AC-AISVC-22, AC-AISVC-23, AC-AISVC-24,
          AC-AISVC-25, AC-AISVC-26, AC-AISVC-27, AC-AISVC-28

											
										
										
											2026-02-24 10:16:29 +00:00
+								| Phase 6 | 前后端联调真实对接 | 9 | ✅ 完成 |
-												feat(AISVC-T7): 嵌入模型可插拔设计与文档解析支持 [AC-AISVC-29, AC-AISVC-30, AC-AISVC-31, AC-AISVC-32, AC-AISVC-33, AC-AISVC-34, AC-AISVC-35, AC-AISVC-36, AC-AISVC-37, AC-AISVC-38, AC-AISVC-39, AC-AISVC-40, AC-AISVC-41]

- 新增 EmbeddingProvider 抽象基类和工厂模式 [AC-AISVC-29, AC-AISVC-30]
- 实现 OllamaEmbeddingProvider 和 OpenAIEmbeddingProvider [AC-AISVC-29, AC-AISVC-30]
- 新增 EmbeddingConfigManager 支持配置热更新 [AC-AISVC-31, AC-AISVC-32]
- 新增 DocumentParser 抽象接口和工厂类 [AC-AISVC-33]
- 实现 PDF/Word/Excel/Text 文档解析器 [AC-AISVC-33, AC-AISVC-34, AC-AISVC-35]
- 新增嵌入管理 API 端点 [AC-AISVC-38, AC-AISVC-39, AC-AISVC-40, AC-AISVC-41]
- 更新文档上传流程支持多格式文档解析 [AC-AISVC-36, AC-AISVC-37]
- 更新 OpenAPI 契约添加嵌入管理接口
- 添加数据库初始化脚本
- 更新规范文档标记 Phase 7 完成

											
										
										
											2026-02-24 15:08:08 +00:00
+								| Phase 7 | 嵌入模型可插拔与文档解析 | 21 | ✅ 完成 |
-												feat(AISVC-T8): LLM配置管理与RAG调试输出支持 [AC-AISVC-42, AC-AISVC-43, AC-AISVC-44, AC-AISVC-45, AC-AISVC-46, AC-AISVC-47, AC-AISVC-48, AC-AISVC-49, AC-AISVC-50]

- 新增 LLMProviderFactory 工厂类支持 OpenAI/Ollama/Azure [AC-AISVC-42]
- 新增 LLMConfigManager 支持配置热更新 [AC-AISVC-43, AC-AISVC-44]
- 新增 LLM 管理 API 端点 [AC-AISVC-42~AC-AISVC-46]
- 更新 RAG 实验接口支持 AI 回复生成 [AC-AISVC-47, AC-AISVC-49]
- 新增 RAG 实验流式输出 SSE [AC-AISVC-48]
- 支持指定 LLM 提供者 [AC-AISVC-50]
- 更新 OpenAPI 契约添加 LLM 管理接口
- 更新前后端规范文档 v0.4.0 迭代

											
										
										
											2026-02-24 17:25:53 +00:00
+								| Phase 8 | LLM 配置与 RAG 调试输出 | 10 | ⏳ 进行中 |
-												docs(ai-service): update progress files [AISVC-ALL] all phases completed

- Update spec/ai-service/progress.md with Phase 3 completion details
- Update spec/ai-service/tasks.md status to completed
- All 5 phases (23 tasks) completed: T1.1-T1.6, T2.1-T2.5, T3.1-T3.5, T4.1-T4.4, T5.1-T5.3
- 184 tests passing
- All AC markers covered: AC-AISVC-01~AC-AISVC-20

											
										
										
											2026-02-24 06:00:02 +00:00
-												feat(AISVC-T8): LLM配置管理与RAG调试输出支持 [AC-AISVC-42, AC-AISVC-43, AC-AISVC-44, AC-AISVC-45, AC-AISVC-46, AC-AISVC-47, AC-AISVC-48, AC-AISVC-49, AC-AISVC-50]

- 新增 LLMProviderFactory 工厂类支持 OpenAI/Ollama/Azure [AC-AISVC-42]
- 新增 LLMConfigManager 支持配置热更新 [AC-AISVC-43, AC-AISVC-44]
- 新增 LLM 管理 API 端点 [AC-AISVC-42~AC-AISVC-46]
- 更新 RAG 实验接口支持 AI 回复生成 [AC-AISVC-47, AC-AISVC-49]
- 新增 RAG 实验流式输出 SSE [AC-AISVC-48]
- 支持指定 LLM 提供者 [AC-AISVC-50]
- 更新 OpenAPI 契约添加 LLM 管理接口
- 更新前后端规范文档 v0.4.0 迭代

											
										
										
											2026-02-24 17:25:53 +00:00
+								**已完成: 53 个任务 | 进行中: 10 个任务**
-												docs(ai-service): update progress files [AISVC-ALL] all phases completed

- Update spec/ai-service/progress.md with Phase 3 completion details
- Update spec/ai-service/tasks.md status to completed
- All 5 phases (23 tasks) completed: T1.1-T1.6, T2.1-T2.5, T3.1-T3.5, T4.1-T4.4, T5.1-T5.3
- 184 tests passing
- All AC markers covered: AC-AISVC-01~AC-AISVC-20

											
										
										
											2026-02-24 06:00:02 +00:00
-												feat(AISVC-T7): 嵌入模型可插拔设计与文档解析支持 [AC-AISVC-29, AC-AISVC-30, AC-AISVC-31, AC-AISVC-32, AC-AISVC-33, AC-AISVC-34, AC-AISVC-35, AC-AISVC-36, AC-AISVC-37, AC-AISVC-38, AC-AISVC-39, AC-AISVC-40, AC-AISVC-41]

- 新增 EmbeddingProvider 抽象基类和工厂模式 [AC-AISVC-29, AC-AISVC-30]
- 实现 OllamaEmbeddingProvider 和 OpenAIEmbeddingProvider [AC-AISVC-29, AC-AISVC-30]
- 新增 EmbeddingConfigManager 支持配置热更新 [AC-AISVC-31, AC-AISVC-32]
- 新增 DocumentParser 抽象接口和工厂类 [AC-AISVC-33]
- 实现 PDF/Word/Excel/Text 文档解析器 [AC-AISVC-33, AC-AISVC-34, AC-AISVC-35]
- 新增嵌入管理 API 端点 [AC-AISVC-38, AC-AISVC-39, AC-AISVC-40, AC-AISVC-41]
- 更新文档上传流程支持多格式文档解析 [AC-AISVC-36, AC-AISVC-37]
- 更新 OpenAPI 契约添加嵌入管理接口
- 添加数据库初始化脚本
- 更新规范文档标记 Phase 7 完成

											
										
										
											2026-02-24 15:08:08 +00:00
+								---
 								### 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]` ✅
-												feat(AISVC-T8): LLM配置管理与RAG调试输出支持 [AC-AISVC-42, AC-AISVC-43, AC-AISVC-44, AC-AISVC-45, AC-AISVC-46, AC-AISVC-47, AC-AISVC-48, AC-AISVC-49, AC-AISVC-50]

- 新增 LLMProviderFactory 工厂类支持 OpenAI/Ollama/Azure [AC-AISVC-42]
- 新增 LLMConfigManager 支持配置热更新 [AC-AISVC-43, AC-AISVC-44]
- 新增 LLM 管理 API 端点 [AC-AISVC-42~AC-AISVC-46]
- 更新 RAG 实验接口支持 AI 回复生成 [AC-AISVC-47, AC-AISVC-49]
- 新增 RAG 实验流式输出 SSE [AC-AISVC-48]
- 支持指定 LLM 提供者 [AC-AISVC-50]
- 更新 OpenAPI 契约添加 LLM 管理接口
- 更新前后端规范文档 v0.4.0 迭代

											
										
										
											2026-02-24 17:25:53 +00:00
 								---
 								### 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 实验增强接口 ✅