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

---
feature_id: "AISVC"
title: "Python AI 中台（ai-service）进度追踪"
status: "completed"
version: "0.3.0"
last_updated: "2026-02-24"
---

# Python AI 中台进度追踪（AISVC）

## Phase 1: 基础设施（FastAPI 框架与多租户基础）
- [x] T1.1 初始化 FastAPI 项目骨架，配置基础环境与日志（包含 X-Tenant-Id 记录） `[AC-AISVC-01]` ✅ **2026-02-24 完成**
- [x] T1.2 实现 `X-Tenant-Id` Header 拦截器，校验必填性并注入 Request State `[AC-AISVC-10, AC-AISVC-12]` ✅ **2026-02-24 完成**
- [x] T1.3 定义基础响应模型 `ErrorResponse` 与异常处理器（Exception Handler） `[AC-AISVC-03, AC-AISVC-04]` ✅ **2026-02-24 完成**
- [x] T1.4 初始化 PostgreSQL 数据库客户端（SQLModel/SQLAlchemy），支持租户隔离查询逻辑 `[AC-AISVC-11]` ✅ **2026-02-24 完成**
- [x] T1.5 初始化 Qdrant 客户端，封装按租户动态选择 Collection 的工具函数 `[AC-AISVC-10]` ✅ **2026-02-24 完成**
- [x] T1.6 实现 `/ai/health` 健康检查接口 `[AC-AISVC-20]` ✅ **2026-02-24 完成**

## Phase 2: 存储与检索实现（Memory & Retrieval）
- [x] T2.1 实现 Memory 层：定义 `chat_sessions` 与 `chat_messages` SQLModel 实体 `[AC-AISVC-13]` ✅ **2026-02-24 完成**
- [x] T2.2 实现 Memory 层：完成基于 `(tenant_id, session_id)` 的历史消息加载与追加 API `[AC-AISVC-13]` ✅ **2026-02-24 完成**
- [x] T2.3 实现 Retrieval 层：定义 `BaseRetriever` 抽象基类（插件点预留） `[AC-AISVC-16]` ✅ **2026-02-24 完成**
- [x] T2.4 实现 `VectorRetriever`：集成 `qdrant-client` 完成向量检索，支持 scoreThreshold 过滤 `[AC-AISVC-16, AC-AISVC-17]` ✅ **2026-02-24 完成**
- [x] T2.5 编写 Memory 与 Retrieval 层的独立单元测试（Mock 数据库与向量库） `[AC-AISVC-10, AC-AISVC-11]` ✅ **2026-02-24 完成**

## Phase 3: 核心编排（Orchestrator & LLM Adapter）
- [x] T3.1 实现 LLM Adapter：封装 `langchain-openai` 或官方 SDK，支持 `generate` 与 `stream_generate` `[AC-AISVC-02, AC-AISVC-06]` ✅ **2026-02-24 完成**
- [x] T3.2 实现 Orchestrator：实现上下文合并逻辑（H_local + H_ext 的去重与截断策略） `[AC-AISVC-14, AC-AISVC-15]` ✅ **2026-02-24 完成**
- [x] T3.3 实现 Orchestrator：实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ✅ **2026-02-24 完成**
- [x] T3.4 实现 Orchestrator：整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 `[AC-AISVC-01, AC-AISVC-02]` ✅ **2026-02-24 完成**
- [x] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` ✅ **2026-02-24 完成**

## Phase 4: 流式响应（SSE 实现与状态机）
- [x] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]` ✅ **2026-02-24 完成**
- [x] T4.2 实现 SSE 事件生成器：根据 Orchestrator 的增量输出包装 `message` 事件 `[AC-AISVC-07]` ✅ **2026-02-24 完成**
- [x] T4.3 实现 SSE 状态机：确保 `final` 或 `error` 事件后连接正确关闭，且顺序不乱 `[AC-AISVC-08, AC-AISVC-09]` ✅ **2026-02-24 完成**
- [x] T4.4 实现流式输出过程中的异常捕获，并转化为 `event: error` 输出 `[AC-AISVC-09]` ✅ **2026-02-24 完成**

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

---

## 总体进度

| Phase | 描述 | 进度 | 状态 |
|-------|------|------|------|
| Phase 1 | 基础设施 | 100% | ✅ 完成 |
| Phase 2 | 存储与检索 | 100% | ✅ 完成 |
| Phase 3 | 核心编排 | 100% | ✅ 完成 |
| Phase 4 | 流式响应 | 100% | ✅ 完成 |
| Phase 5 | 集成测试 | 100% | ✅ 完成 |
| Phase 6 | 前后端联调 | 100% | ✅ 完成 |
| Phase 7 | 嵌入模型可插拔与文档解析 | 100% | ✅ 完成 |

**测试统计: 184 tests passing**

---

## Phase 3 完成详情 (2026-02-24)

### T3.1 LLM Adapter
- 创建 LLMClient 抽象接口 (`app/services/llm/base.py`)
- 实现 OpenAIClient 使用 httpx (`app/services/llm/openai_client.py`)
- 支持 generate 和 stream_generate
- 使用 tenacity 实现重试逻辑
- 单元测试: 11 tests

### T3.2 上下文合并
- 创建 ContextMerger 类 (`app/services/context.py`)
- 实现消息指纹计算 (SHA256)
- 实现去重策略 (local 优先)
- 实现 token 截断 (使用 tiktoken)
- 单元测试: 20 tests

### T3.3 置信度计算
- 创建 ConfidenceCalculator 类 (`app/services/confidence.py`)
- 实现检索不足判定
- 实现置信度计算策略
- 实现 shouldTransfer 逻辑
- 单元测试: 19 tests

### T3.4 Orchestrator 完整闭环
- 整合 Memory、ContextMerger、Retriever、LLMClient、ConfidenceCalculator
- 实现 8 步生成管道:
  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
- 创建 GenerationContext 数据类追踪生成流程
- 实现 fallback 响应机制
- 单元测试: 21 tests

### T3.5 契约验证
- 验证 ChatResponse 字段与 OpenAPI 契约一致性
- 验证 JSON 序列化使用 camelCase
- 验证必填字段和可选字段
- 验证 confidence 范围约束 [0.0, 1.0]
- 单元测试: 23 tests

---

## 验收标准覆盖

| AC 标记 | 描述 | 状态 |
|---------|------|------|
| AC-AISVC-01 | HTTP POST /ai/chat 调用 | ✅ |
| AC-AISVC-02 | 响应包含 reply/confidence/shouldTransfer | ✅ |
| AC-AISVC-03 | 参数错误返回 400 | ✅ |
| AC-AISVC-04 | 异常处理器 | ✅ |
| AC-AISVC-06 | Accept 头切换 SSE 模式 | ✅ |
| AC-AISVC-07 | SSE message 事件增量输出 | ✅ |
| AC-AISVC-08 | SSE final 事件后关闭连接 | ✅ |
| AC-AISVC-09 | 错误时发送 error 事件 | ✅ |
| AC-AISVC-10 | tenantId 贯穿隔离 | ✅ |
| AC-AISVC-11 | 存储层按 tenant_id 隔离 | ✅ |
| AC-AISVC-12 | 缺 tenantId 返回 400 | ✅ |
| AC-AISVC-13 | Memory 层会话历史管理 | ✅ |
| AC-AISVC-14 | 上下文合并 | ✅ |
| AC-AISVC-15 | 历史去重策略 | ✅ |
| AC-AISVC-16 | Retriever 抽象接口 | ✅ |
| AC-AISVC-17 | RAG 检索质量影响 confidence | ✅ |
| AC-AISVC-18 | 检索不足时 confidence 下调 | ✅ |
| AC-AISVC-19 | shouldTransfer 转人工建议 | ✅ |
| AC-AISVC-20 | 健康检查接口 | ✅ |

---

## 模块结构

```
ai-service/
├── app/
│   ├── api/
│   │   └── chat.py          # FastAPI 路由层
│   ├── core/
│   │   ├── config.py        # 配置管理
│   │   ├── exceptions.py    # 异常定义
│   │   ├── middleware.py    # 中间件 (租户注入)
│   │   ├── qdrant_client.py # Qdrant 客户端
│   │   └── sse.py           # SSE 状态机和事件生成器
│   ├── models/
│   │   ├── __init__.py      # Pydantic 模型
│   │   └── entities.py      # SQLModel 实体
│   └── services/
│       ├── llm/
│       │   ├── base.py      # LLMClient 抽象接口
│       │   └── openai_client.py  # OpenAI 兼容客户端
│       ├── memory.py        # Memory 服务
│       ├── orchestrator.py  # 编排服务
│       ├── context.py       # 上下文合并
│       ├── confidence.py    # 置信度计算
│       └── retrieval/
│           ├── base.py      # Retriever 抽象接口
│           └── vector_retriever.py  # 向量检索实现
└── tests/                   # 单元测试 (184 tests)
```

---

## 关键技术决策

| 决策 | 原因 | 影响 |
|------|------|------|
| LLM Adapter 使用 httpx | 更轻量、更可控、减少依赖 | 需要手动处理 OpenAI API 响应解析 |
| 使用 tenacity 实现重试 | 简单可靠的重试机制 | 提高服务稳定性 |
| Orchestrator 依赖注入模式 | 便于测试和组件替换 | 所有组件可通过构造函数注入 |
| GenerationContext 数据类 | 清晰追踪中间结果和诊断信息 | 便于调试和问题排查 |
| Pydantic alias 实现驼峰命名 | 符合 OpenAPI 契约的 camelCase 要求 | JSON 序列化时自动转换字段名 |

---

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

### 7.1 嵌入服务设计

#### 设计目标
- 支持多种嵌入模型提供者（Ollama、OpenAI、本地模型等）
- 运行时动态切换，无需修改代码
- 支持界面配置和热更新
- 统一的错误处理和 fallback 策略

#### 架构设计
```
EmbeddingProvider (抽象基类)
├── OllamaEmbeddingProvider    # Ollama 本地模型
├── OpenAIEmbeddingProvider    # OpenAI Embedding API
└── LocalEmbeddingProvider     # 本地模型（未来扩展）

EmbeddingProviderFactory       # 工厂类，根据配置创建提供者
EmbeddingConfigManager         # 配置管理，支持热更新
```

#### 接口定义
```python
class EmbeddingProvider(ABC):
    @abstractmethod
    async def embed(self, text: str) -> list[float]:
        """生成单个文本的嵌入向量"""
        pass
    
    @abstractmethod
    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
        """批量生成嵌入向量"""
        pass
    
    @abstractmethod
    def get_dimension(self) -> int:
        """返回向量维度"""
        pass
    
    @abstractmethod
    def get_provider_name(self) -> str:
        """返回提供者名称"""
        pass
```

### 7.2 文档解析服务设计

#### 支持格式
| 格式 | 扩展名 | 解析库 | 说明 |
|------|--------|--------|------|
| PDF | .pdf | PyMuPDF/pdfplumber | 提取文本内容 |
| Word | .docx | python-docx | 保留段落结构 |
| Excel | .xlsx | openpyxl | 表格转结构化文本 |
| 文本 | .txt, .md | 内置 | 直接读取 |

#### 架构设计
```
DocumentParser (抽象基类)
├── PDFParser      # PDF 解析
├── WordParser     # Word 解析
├── ExcelParser    # Excel 解析
└── TextParser     # 纯文本解析

DocumentParserFactory  # 工厂类，根据扩展名选择解析器
```

#### 接口定义
```python
class DocumentParser(ABC):
    @abstractmethod
    def parse(self, file_path: str) -> str:
        """解析文档，返回纯文本内容"""
        pass
    
    @abstractmethod
    def get_supported_extensions(self) -> list[str]:
        """返回支持的文件扩展名列表"""
        pass
```

### 7.3 任务进度

| 任务 | 描述 | 状态 |
|------|------|------|
| T7.1 | EmbeddingProvider 抽象基类 | ✅ 完成 |
| T7.2 | EmbeddingProviderFactory 工厂类 | ✅ 完成 |
| T7.3 | OllamaEmbeddingProvider 实现 | ✅ 完成 |
| T7.4 | OpenAIEmbeddingProvider 实现 | ✅ 完成 |
| T7.5 | 嵌入配置管理 | ✅ 完成 |
| T7.6 | 错误处理与 fallback | ✅ 完成 |
| T7.7 | DocumentParser 抽象接口 | ✅ 完成 |
| T7.8 | PDFParser 实现 | ✅ 完成 |
| T7.9 | WordParser 实现 | ✅ 完成 |
| T7.10 | ExcelParser 实现 | ✅ 完成 |
| T7.11 | DocumentParserFactory | ✅ 完成 |
| T7.12 | 解析错误处理 | ✅ 完成 |
| T7.13 | GET /admin/embedding/providers | ✅ 完成 |
| T7.14 | GET /admin/embedding/config | ✅ 完成 |
| T7.15 | PUT /admin/embedding/config | ✅ 完成 |
| T7.16 | POST /admin/embedding/test | ✅ 完成 |
| T7.17 | 集成到索引流程 | ✅ 完成 |
| T7.18 | 集成到上传流程 | ✅ 完成 |
| T7.19 | 嵌入服务单元测试 | ✅ 完成 |
| T7.20 | 文档解析单元测试 | ✅ 完成 |
| T7.21 | API 集成测试 | ✅ 完成 |

### 7.4 实现详情 (2026-02-24)

#### 嵌入服务实现
- 创建 EmbeddingProvider 抽象基类 (`app/services/embedding/base.py`)
- 实现 OllamaEmbeddingProvider (`app/services/embedding/ollama_provider.py`)
- 实现 OpenAIEmbeddingProvider (`app/services/embedding/openai_provider.py`)
- 创建 EmbeddingProviderFactory 工厂类 (`app/services/embedding/factory.py`)
- 创建 EmbeddingConfigManager 支持配置热更新

#### 文档解析服务实现
- 创建 DocumentParser 抽象基类 (`app/services/document/base.py`)
- 实现 PDFParser 使用 PyMuPDF (`app/services/document/pdf_parser.py`)
- 实现 WordParser 使用 python-docx (`app/services/document/word_parser.py`)
- 实现 ExcelParser 使用 openpyxl (`app/services/document/excel_parser.py`)
- 实现 TextParser (`app/services/document/text_parser.py`)
- 创建 DocumentParserFactory (`app/services/document/factory.py`)

#### API 端点实现
- GET /admin/embedding/providers - 获取可用嵌入提供者列表
- GET /admin/embedding/config - 获取当前嵌入配置
- PUT /admin/embedding/config - 更新嵌入配置
- POST /admin/embedding/test - 测试嵌入连接
- GET /admin/embedding/formats - 获取支持的文档格式

#### 集成更新
- 更新 vector_retriever.py 使用可插拔嵌入提供者
- 更新 kb.py 支持多格式文档上传和解析

---

## v0.3.0 完成总结

**Phase 7 已全部完成**

| 模块 | 文件数 | 状态 |
|------|--------|------|
| 嵌入服务 | 6 | ✅ |
| 文档解析 | 7 | ✅ |
| API 端点 | 1 | ✅ |
| 集成更新 | 2 | ✅ |

**测试统计: 184 tests passing**