387 lines
15 KiB
Markdown
387 lines
15 KiB
Markdown
---
|
||
feature_id: "AISVC"
|
||
title: "Python AI 中台（ai-service）进度追踪"
|
||
status: "completed"
|
||
version: "0.4.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% | ✅ 完成 |
|
||
| Phase 8 | LLM 配置与 RAG 调试输出 | 100% | ✅ 完成 |
|
||
|
||
**测试统计: 184 tests passing**
|
||
|
||
---
|
||
|
||
## Phase 8: LLM 配置与 RAG 调试输出（v0.4.0 迭代）
|
||
|
||
### 8.1 设计目标
|
||
|
||
- LLM 提供者可插拔设计
|
||
- 支持界面配置不同供应商的 AI
|
||
- RAG 实验室支持 AI 输出调试
|
||
|
||
### 8.2 实现详情 (2026-02-24)
|
||
|
||
#### LLM 服务实现
|
||
- 创建 LLMProviderFactory 工厂类 (`app/services/llm/factory.py`)
|
||
- 支持 OpenAI、Ollama、Azure OpenAI 三种提供者
|
||
- 实现 LLMConfigManager 配置热更新
|
||
- 实现连接测试功能
|
||
|
||
#### API 端点实现
|
||
- GET /admin/llm/providers - 获取 LLM 提供者列表
|
||
- GET /admin/llm/config - 获取当前 LLM 配置
|
||
- PUT /admin/llm/config - 更新 LLM 配置
|
||
- POST /admin/llm/test - 测试 LLM 连接
|
||
|
||
#### RAG 实验增强
|
||
- 更新 POST /admin/rag/experiments/run - 支持 AI 回复生成
|
||
- 新增 POST /admin/rag/experiments/stream - SSE 流式输出
|
||
- 支持 Token 统计和响应耗时
|
||
- 支持指定 LLM 提供者
|
||
|
||
### 8.3 任务进度
|
||
|
||
| 任务 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| T8.1 | LLMProviderFactory 工厂类 | ✅ 完成 |
|
||
| T8.2 | LLMConfigManager 配置管理 | ✅ 完成 |
|
||
| T8.3 | GET /admin/llm/providers | ✅ 完成 |
|
||
| T8.4 | GET /admin/llm/config | ✅ 完成 |
|
||
| T8.5 | PUT /admin/llm/config | ✅ 完成 |
|
||
| T8.6 | POST /admin/llm/test | ✅ 完成 |
|
||
| T8.7 | RAG 实验支持 AI 回复 | ✅ 完成 |
|
||
| T8.8 | RAG 实验流式输出 | ✅ 完成 |
|
||
| T8.9 | 支持指定 LLM 提供者 | ✅ 完成 |
|
||
| T8.10 | 更新 OpenAPI 契约 | ✅ 完成 |
|
||
|
||
---
|
||
|
||
## v0.4.0 完成总结
|
||
|
||
**Phase 8 已全部完成**
|
||
|
||
| 模块 | 文件数 | 状态 |
|
||
|------|--------|------|
|
||
| LLM 服务 | 1 | ✅ |
|
||
| API 端点 | 2 | ✅ |
|
||
| OpenAPI 契约 | 1 | ✅ |
|
||
|
||
**测试统计: 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**
|