ai-contract-platform/project-docs/V2-ai-platform-knowledge-retrieval-enhancement-2026-06-22.md

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。

验证结果

已通过：

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

当前结果：

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. 建立法律问答评测集，检查“回答是否有依据、依据是否匹配问题、是否误引法条”。