ai-contract-platform/project-docs/V2-database-postgresql-explain-baseline-2026-06-24.md

AI 合同平台 V2 PostgreSQL EXPLAIN ANALYZE 基线

日期：2026-06-24

结论

本轮完成 DB-5 第二阶段：在 192.168.3.90 的 V2 smoke Docker 环境中，对真实 PostgreSQL/pgvector 数据库执行测试数据造数、ANALYZE、EXPLAIN ANALYZE 和 warm-cache 复测。

整体结论：

• 合同主列表、文件仓库按合同查询、审查 worker 队列、合同审计时间线、AI Trace、AI 质量看板、知识库列表、知识库 worker 队列整体可用。
• 当前最大性能风险不在普通列表，而在“统一搜索/审查搜索”这类跨表、多字段、OR + ILIKE '%keyword%' 查询。
• AI 向量检索的 HNSW 索引已可用，但当前代码形态使用 embedding <=> query_vector，不会命中本轮建立的表达式 HNSW 索引；需要把代码查询表达式调整为 embedding::vector(64) <=> query_vector::vector(64) 或在后续 schema 中把 embedding 固定为 vector(64)。
• 本轮只是 DB-5 基线，不等同于最终生产压测；后续仍需 DB-6 的安全、备份、RLS 和慢查询监控。

测试环境

• Server：192.168.3.90
• Compose project：yuqei-contract-v2-smoke
• Contract DB：yuqei_contract
• AI DB：yuqei_ai
• PostgreSQL image：pgvector/pgvector:pg16
• 验证目录：project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59

测试数据量

合同库：

• contracts：12,000
• contract_files：18,000
• review_tasks：16,000
• approval_timeline_items：36,000
• contract_audit_events：48,000

AI 库：

• ai_run_audits：50,000
• knowledge_documents：10,000
• knowledge_chunks：60,000
• knowledge_ingestion_jobs：20,000
• ai_quality_improvement_actions：8,000
• 另有模型配置、Prompt 变更、重建索引记录、worker 执行记录等辅助数据。

所有测试数据都使用 perf- 前缀，后续可以重复清理和重建。

关键结果

合同库

查询	warm-cache 执行时间	计划	结论
合同列表按状态	0.233 ms	ix_contracts_updated_at	通过，但规划器未选 ix_contracts_status_updated_id
合同状态计数	0.692 ms	ix_contracts_status index only	通过
合同标题/编号/相对方关键词	1.598 ms	ix_contracts_updated_at + filter	当前量级可接受
合同正文统一搜索	1574.955 ms	Seq Scan	需优化
文件仓库按合同	0.113 ms	ix_contract_files_contract_uploaded_id	通过
文件仓库关键词跨合同	60.220 ms	uploaded_at index + nested loop	中风险
审查 worker 领取	0.053 ms	ix_review_tasks_created_at	通过，但未选组合索引
审查任务统一搜索	472.446 ms	Seq Scan + Hash Join	需优化
合同审计时间线	0.110 ms	ix_contract_audit_events_contract_id	通过
审批时间线	0.090 ms	ix_approval_timeline_items_contract_id	通过

合同库主要问题：

1. 合同正文统一搜索走全表扫描，原因是跨多个字段的 OR + ILIKE，并且包含 body_content 大文本字段。
2. 审查任务搜索走 review_tasks 和 contracts 的全量 hash join，后续数据量扩大后会明显拖慢统一搜索页。
3. 时间线和 worker 查询虽然很快，但规划器优先使用单列索引；这不是当前瓶颈，但后续可以逐步减少重复单列索引，让组合索引更明确。

AI 库

查询	warm-cache 执行时间	计划	结论
AI Trace 最新列表	0.168 ms	ix_ai_run_audits_created_at	通过
AI Trace 按 operation	0.215 ms	created_at index + filter	通过
AI 质量看板 14 天窗口	8.959 ms	ix_ai_run_audits_created_at	通过
AI Trace 按 provider/model	0.336 ms	ix_ai_run_audits_provider_model_created	通过
AI Trace 问题关键词	2.263 ms	created_at index + filter	当前量级可接受
质量改进项待处理队列	0.283 ms	updated_at index + filter	通过
质量改进项按 owner/status	0.120 ms	ix_quality_actions_owner_status_updated	通过
知识库文档按 base/status	0.248 ms	ix_knowledge_documents_kb_status_created	通过
知识库关键词检索	0.296 ms	ix_knowledge_chunks_kb_created + filter	当前量级可接受
当前代码形态向量检索	18.221 ms	bitmap + sort	可用但未命中 HNSW
HNSW 表达式形态向量检索	1.051 ms	ix_knowledge_chunks_embedding_hnsw	通过
知识导入 worker 领取	0.045 ms	updated_at index + filter	通过
知识导入列表按 base/status	0.043 ms	ix_ingestion_jobs_kb_status_updated index only	通过
worker 执行时间线	0.256 ms	started_at index + filter	通过

AI 库主要问题：

1. HNSW 索引有效，但当前 repository 中 _search_knowledge_chunks_with_pgvector 的 SQL 形态没有使用表达式 cast，因此没有命中 ix_knowledge_chunks_embedding_hnsw。
2. 当前向量检索在 60,000 chunk、单知识库 3,000 chunk 规模下仍可接受；如果知识库扩大到百万 chunk，必须让查询命中 HNSW 或改成固定维度 vector(64) 列。
3. AI Trace 和质量看板目前表现良好，短期不用优先继续加索引。

优先优化项

P0：统一搜索改造

当前合同正文搜索和审查任务搜索是最大风险。

建议下一轮做：

• 合同搜索从多字段 OR + ILIKE 改为 PostgreSQL tsvector 搜索列或独立 search document 表。
• 把 contracts、contract_files、review_tasks 的搜索统一写入 contract_search_documents：
  • id
  • source_type
  • source_id
  • title
  • summary
  • search_text
  • status
  • updated_at
  • search_vector
• 对 search_vector 建 GIN 索引。
• 统一搜索页先查 search document，再按结果类型回表取详情。

这样可以避免跨表 OR 和大文本全表扫描。

P1：pgvector 查询形态改造

当前 HNSW 索引已经存在并可用，但代码未命中。

建议：

• 短期：把 _search_knowledge_chunks_with_pgvector 的 SQL 改为 embedding::vector(64) <=> CAST(:query_vector AS vector(64))。
• 中期：固定 knowledge_chunks.embedding 为 vector(64) 或按 embedding dimension 拆表/分区，避免表达式索引长期存在。
• 长期：按 knowledge_base_id 做分区或加检索候选召回策略，避免全局 HNSW 先召回再过滤知识库导致返回不足。

P2：索引策略整理

本轮发现一些查询仍选旧单列索引。

短期不需要马上删除旧索引，因为当前性能可接受；但后续 DB-2/DB-3 清洁模型落地后，应统一整理：

• 保留确实被查询使用的组合索引。
• 删除重复、低收益单列索引。
• 让迁移和模型中的 index=True 不再随意生成单列索引。

本轮产物

• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/seed-contract.sql
• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/seed-ai.sql
• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/explain-contract.sql
• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/explain-ai.sql
• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/explain-contract.log
• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/explain-contract-warm.log
• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/explain-ai.log
• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/explain-ai-warm.log
• project-docs/qa-artifacts/v2-database-explain-baseline/2026-06-24T18-45-59/explain-summary.tsv

下一步

建议继续 DB-5 第三阶段：实现统一搜索专用表或 tsvector 搜索列，先解决合同正文搜索和审查任务搜索的全表扫描问题。

之后再做 pgvector 查询形态改造，让线上法律问答和合同审查的 RAG 检索真正稳定命中 HNSW。