15 KiB

Raw Blame History

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

Python AI 中台进度追踪（AISVC）

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

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

Phase 2: 存储与检索实现（Memory & Retrieval）

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

Phase 3: 核心编排（Orchestrator & LLM Adapter）

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

Phase 4: 流式响应（SSE 实现与状态机）

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

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

T5.1 编写集成测试：模拟多租户并发请求，验证数据存储与检索的严格物理/逻辑隔离 [AC-AISVC-10, AC-AISVC-11] ✅ 2026-02-24 完成
T5.2 编写 RAG 冒烟测试：模拟"检索命中"与"检索未命中"两种场景，验证 confidence 变化与回复兜底 [AC-AISVC-17, AC-AISVC-18] ✅ 2026-02-24 完成
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         # 配置管理，支持热更新

接口定义

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  # 工厂类，根据扩展名选择解析器

接口定义

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

15 KiB Raw Blame History Unescape Escape

Python AI 中台进度追踪（AISVC）

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

Phase 2: 存储与检索实现（Memory & Retrieval）

Phase 3: 核心编排（Orchestrator & LLM Adapter）

Phase 4: 流式响应（SSE 实现与状态机）

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

总体进度

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

8.1 设计目标

8.2 实现详情 (2026-02-24)

LLM 服务实现

API 端点实现

RAG 实验增强

8.3 任务进度

v0.4.0 完成总结

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

T3.1 LLM Adapter

T3.2 上下文合并

T3.3 置信度计算

T3.4 Orchestrator 完整闭环

T3.5 契约验证

验收标准覆盖

模块结构

关键技术决策

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

7.1 嵌入服务设计

设计目标

架构设计

接口定义

7.2 文档解析服务设计

支持格式

架构设计

接口定义

7.3 任务进度

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

嵌入服务实现

文档解析服务实现

API 端点实现

集成更新

v0.3.0 完成总结

15 KiB

Raw Blame History