ai-contract-platform/project-docs/V2-ai-platform-embedding-pgvector-2026-06-22.md

V2 AI Platform Embedding + pgvector 闭环记录

日期：2026-06-22

本轮目标

把知识库检索从 local-hash-v1 的可验证 fallback，升级为可接入真实 embedding provider 的生产级向量检索路径，并保留本地 fallback，保证测试、离线开发和临时 provider 故障时仍可运行。

已落地内容

1. 新增 embedding provider 抽象。

   • local-hash：默认 fallback，固定 64 维，便于测试和离线验证。
   • openai-compatible：按 /embeddings 接口调用真实模型，支持 OpenAI、DeepSeek 兼容网关、通义兼容网关或私有兼容服务。

2. 新增热配置项。

   • AI_PLATFORM_EMBEDDING_PROVIDER
   • AI_PLATFORM_EMBEDDING_MODEL
   • AI_PLATFORM_EMBEDDING_API_KEY
   • AI_PLATFORM_EMBEDDING_BASE_URL
   • AI_PLATFORM_EMBEDDING_REQUEST_TIMEOUT_SECONDS
   • AI_PLATFORM_EMBEDDING_FALLBACK_ENABLED
   • AI_PLATFORM_VECTOR_SEARCH_BACKEND

3. 新增数据库迁移。

   • 20260622_0004_add_embedding_provider_and_pgvector.py
   • knowledge_chunks.embedding_provider
   • PostgreSQL 环境自动 CREATE EXTENSION IF NOT EXISTS vector
   • PostgreSQL 环境新增 knowledge_chunks.embedding vector

4. Repository 检索路径升级。

   • 新增知识 chunk 时写入 provider/model/dimension 元数据。
   • PostgreSQL + pgvector 可用时优先走 embedding <=> query_vector。
   • 非 PostgreSQL、未启用 pgvector、pgvector 查询失败时回退 JSON embedding 排序。
   • 关键词、向量、混合分数继续返回，法律问答审计仍记录 chunk ids、来源、分数。

5. 契约同步。

   • OpenAPI KnowledgeChunk 新增 embedding_provider。
   • Python SDK KnowledgeChunk 新增 embedding_provider。

6. 重建索引闭环。

   • 新增 POST /api/v1/knowledge-documents/reindex。
   • 支持按 document_id、knowledge_base_id、import_batch_id 过滤。
   • 使用当前 embedding provider 重新切分和生成 chunk。
   • PostgreSQL + pgvector 环境会重新写入 knowledge_chunks.embedding。
   • Python SDK 新增 reindex_knowledge_documents(...)。

7. 检索 explain 闭环。

   • 新增 GET /api/v1/knowledge-chunks/search/explain。
   • 返回 normalized terms、候选 chunk 数、命中数、keyword/vector/hybrid 分数。
   • 返回每个候选项的 included、rank、filter_reason。
   • Python SDK 新增 explain_knowledge_search(...)。
   • JSON fallback 的向量分改为 cosine 口径，便于和 pgvector cosine 距离保持一致。

8. AI run trace 审计增强。

   • AiRunAudit 新增 provider、model、provider_status、provider_error。
   • 记录 prompt_tokens、completion_tokens、total_tokens。
   • 支持按 AI_PLATFORM_PROVIDER_PROMPT_TOKEN_COST_PER_1K 和 AI_PLATFORM_PROVIDER_COMPLETION_TOKEN_COST_PER_1K 估算费用。
   • OpenAPI 和 Python SDK 同步新增审计字段。

生产配置建议

$env:AI_PLATFORM_REPOSITORY_BACKEND="sqlalchemy"
$env:AI_PLATFORM_DATABASE_URL="postgresql+psycopg://ai:ai@localhost:5432/yuqei_ai"
$env:AI_PLATFORM_EMBEDDING_PROVIDER="openai-compatible"
$env:AI_PLATFORM_EMBEDDING_MODEL="text-embedding-3-small"
$env:AI_PLATFORM_EMBEDDING_API_KEY="真实 embedding key"
$env:AI_PLATFORM_EMBEDDING_BASE_URL="https://api.openai.com/v1"
$env:AI_PLATFORM_EMBEDDING_FALLBACK_ENABLED="true"
$env:AI_PLATFORM_VECTOR_SEARCH_BACKEND="pgvector"
python -m alembic upgrade head

运维注意

• pgvector 是数据库扩展，需要 PostgreSQL 实例支持 CREATE EXTENSION vector。
• 迁移只新增列，不会自动把历史 JSON embedding 转成真实向量；启用真实 embedding 后需要重导入或重建索引。
• 启用真实 embedding 后优先调用 POST /api/v1/knowledge-documents/reindex，避免历史 chunk 继续停留在 local-hash-v1。
• local-hash-v1 继续作为 fallback，不作为最终生产语义向量模型。
• AI_PLATFORM_VECTOR_SEARCH_BACKEND=json 可强制关闭 pgvector，用于排障。
• AI_PLATFORM_EMBEDDING_FALLBACK_ENABLED=false 会在 embedding 参数缺失或 provider 失败时返回空向量，更适合严格生产验收；默认 true 更适合平滑上线。

验收口径

• provider 成功时：chunk 记录真实 embedding_provider=openai-compatible、真实模型名和真实维度。
• provider 不可用且允许 fallback 时：chunk 仍可写入，检索仍可用，但 provider 显示 local-hash。
• pgvector 可用时：优先使用数据库向量距离排序。
• pgvector 不可用时：回退 JSON embedding，不影响法律问答主链路。
• explain 接口可说明命中依据和过滤原因，用于法律问答可信度展示和检索调参。
• AI run 审计可用于排查模型错误、统计 token、估算成本和后续质量评测。