# V2 AI Platform Knowledge Retrieval Enhancement

日期：2026-06-22

## 本轮目标

本轮推进 AI 中台知识库检索增强，把早期“整篇知识文档关键词检索”升级为更接近生产 RAG 的基础结构：

- 导入批次。
- 文档切分 chunk。
- chunk 级检索结果。
- 关键词分、向量分、混合分。
- 来源定位。
- 法律问答返回结构化主要依据。
- AI 审计记录命中的 chunk ids、来源、分数和检索策略。

## 已完成

1. 数据模型
   - 新增 `KnowledgeImportBatchModel`。
   - 新增 `KnowledgeChunkModel`。
   - `KnowledgeDocumentModel` 增加 `import_batch_id`、`index_status`。
   - `KnowledgeChunkModel` 增加本地 embedding 字段：`embedding_model`、`embedding_dimension`、`embedding_json`。
   - `AiRunAuditModel` 增加检索追踪字段：`retrieval_query`、`retrieval_strategy`、`retrieved_chunk_ids_json`、`retrieved_sources_json`。

2. 数据库迁移
   - `20260622_0002_add_knowledge_batches_and_chunks.py`
   - `20260622_0003_add_hybrid_retrieval_audit.py`
   - 支持升级/回滚。

3. Repository 能力
   - 创建和列出知识导入批次。
   - 新增知识文档时自动切分 chunk。
   - chunk 持久化本地 hash embedding。
   - 支持 `keyword`、`vector`、`hybrid` 三种检索策略。
   - 搜索结果返回 `score`、`keyword_score`、`vector_score`、`hybrid_score`、`matched_terms`、`locator`、`document_id`、`chunk_id`。
   - 增加泛化词过滤，避免“这个合同需要注意什么”这类泛问误命中具体法条。

4. API 能力
   - `GET /api/v1/knowledge-import-batches`
   - `POST /api/v1/knowledge-import-batches`
   - `GET /api/v1/knowledge-documents/{document_id}/chunks`
   - `GET /api/v1/knowledge-chunks/search?strategy=keyword|vector|hybrid`
   - `GET /api/v1/knowledge-documents/search`
   - `POST /api/v1/legal/qa`
   - `GET /api/v1/audit/ai-runs`

5. 法律问答增强
   - 默认使用 `hybrid` 检索。
   - `LegalQaResponse.primary_sources` 返回结构化主要依据。
   - `LegalCitation` 增加检索分数、定位、chunk id、document id、knowledge base id、命中词和检索策略。
   - AI 审计记录保留本次命中的 chunk ids 和结构化来源。
   - 清理规则兜底回答里的历史乱码文本，改为可读 UTF-8 中文。

6. SDK 能力
   - Python SDK 同步知识批次、chunk、混合检索和审计来源字段。
   - `search_knowledge_chunks(..., strategy="hybrid")` 支持策略参数。
   - `AiRunAudit` 支持读取 `retrieved_chunk_ids` 和 `retrieved_sources`。

## 验证结果

已通过：

```powershell
python -m pytest yuqei-ai-platform/services/ai-platform-api/tests yuqei-ai-sdk-python/tests
```

当前结果：

```text
16 passed
```

覆盖点：

- 知识导入批次创建和统计更新。
- 文档自动切分 chunk。
- chunk 返回 embedding 元数据。
- chunk 搜索返回关键词分、向量分、混合分和命中词。
- 法律问答返回 `primary_sources`。
- AI 审计记录命中的 chunk ids 和结构化来源。
- SQLite 持久化后可重新读取 batch、chunk、audit。
- SDK 覆盖新增检索和审计字段。

## 当前边界

本轮采用确定性的本地 hash embedding，目的是先稳定 API、数据结构、审计链路和测试闭环。它不是最终生产级语义向量模型。

尚未完成：

- 接入真实 embedding 模型。
- 引入 pgvector 或独立向量库。
- 大规模文档解析、OCR、DOCX/PDF 智能切分。
- provider token、费用、错误详情的完整审计。
- 检索 explain 面板和质量评测集。

## 下一轮建议

下一步进入生产级 RAG 基础设施：

1. 选择并接入 embedding provider。
2. 增加 pgvector 迁移和向量索引。
3. 把当前 hash embedding 作为测试/离线 fallback，生产使用真实向量。
4. 增加检索 explain API，展示关键词分、向量分、混合分、过滤原因。
5. 建立法律问答评测集，检查“回答是否有依据、依据是否匹配问题、是否误引法条”。