AI Vector Brain 是一个用于构建向量检索大脑（vector brain）的技能，主要面向代码仓库、文档中心、政策语料库等场景，帮助将这些语料转化为可重复使用的检索层。其 V1 默认实现采用 Postgres + pgvector，因为该方案持久、可脚本化、易于检查，且足以支撑大多数仓库、文档和合规类大脑。
用途 该技能适用于以下请求：构建向量大脑、RAG 大脑、LLM 大脑、仓库大脑、文档大脑或合规大脑；将仓库、文档中心、政策语料库、指南集或生成的上下文产物转化为可重复的检索层；选择向量大脑后端并产出具体实现路径；创建 SQL、清单文件、摄取脚本、评估种子或智能体检索工具契约。
边界契约 该技能负责“如何构建”：语料盘点、清单文件、DDL、摄取脚本、嵌入、混合搜索、评估种子和后端配方。它不负责宽泛的 RAG 理论、应用上下文策略、智能体拓扑或机器人 UX。相关职责由 ai-context-layer、ai-rag、ai-agents、ai-bot-builder 等技能分担。
主要能力 提供快速参考索引，覆盖存储范式选择、默认大脑构建、后端选择矩阵、各后端深入分析（S3 Vectors、Turbopuffer、Pinecone Serverless、Bedrock KB、OpenSearch、Vertex、Azure、边缘）、成本估算、语料剧本、可移植清单、智能体工具契约、评估门禁、时间事实与 RLS 验证、精确搜索基线、后端公平比较、生产检索追踪、质量下降调试、检索安全红队、上下文摘要、交叉编码器重排序、词法/向量/混合检索选择、BM25 补充、学习稀疏/SPLADE 支路、嵌入式本地大脑、Postgres 全文搜索调优、开发上下文中心向量配方、大规模图理论、量化与重打分、嵌入运行时、延迟扩展、生产运行手册、嵌入漂移缓解等。
V1 工作流
- 使用 scripts/inventory_corpus.py 盘点语料。2. 分类语料类型：仓库/代码库、文档中心或合规/政策。3. 使用 scripts/prepare_documents.py 准备规范化文档。4. 使用 scripts/chunk_corpus_files.py（混合仓库/上下文语料）或 scripts/chunk_markdown.py（纯 Markdown 语料）进行带稳定锚点的分块。5. 选择检索单元：源块、父子块或类型化知识包。6. 当语料存在重复版本、复制流程或近似重复文档时，在嵌入前对规范事实去重。7. 从 assets/sql/ 创建模式和索引。8. 使用 scripts/embed_and_load.py 嵌入并加载检索单元（提供商无关）。9. 可选：按 contextual-retrieval.md 在索引时对块进行上下文化。10. 使用 scripts/retrieve.py 运行混合检索（词法 + 向量 + RRF）。11. 可选：按 reranking-recipe.md 使用交叉编码器对前 N 个候选重排序。12. 使用 scripts/build_eval_seed.py 播种评估，然后人工标注预期证据。13. 通过 retrieve_context 契约暴露检索。14. 使用摄取账本、语料版本、墓碑、查询日志和指标门禁运营新鲜度。15. 仅在后端通过行为检查后推广到生产环境。
后端立场 Postgres + pgvector 是 V1 默认，但不是该技能的身份。后端选择矩阵覆盖四个层级：SQL 原生（pgvector、pgvectorscale、ParadeDB）、专用服务（Qdrant、Weaviate、Milvus/Zilliz、Vespa、LanceDB、Chroma）、无服务器/对象存储支持（AWS S3 Vectors、Turbopuffer、Pinecone Serverless、Cloudflare Vectorize、Upstash Vector）、超大规模托管（AWS Bedrock Knowledge Bases、Azure AI Search、Vertex AI Vector Search、OpenAI File Search）以及搜索引擎 k-NN（Elasticsearch/OpenSearch、Redis Stack、MongoDB Atlas Vector）。
语料剧本 V1 提供三种剧本：仓库/代码库大脑（精确路径、符号、模块、所有权、结构化配置、模式及选定源检索，从 examples/repo-brain.manifest.json 开始）；文档中心大脑（架构、指南、生成文档及跨页导航，从 examples/docs-hub-brain.manifest.json 开始）；合规/政策大脑（权威性、生效时间、引用精度及无证据拒绝，从 examples/policy-brain.manifest.json 开始）。支持 KB、笔记库和生成的图 + Markdown 剧本为后续增量。
操作默认值 将源真相与块和嵌入分开；存储稳定证据 ID、源 URI、内容哈希、新鲜度、ACL 范围和引用锚点；将块视为默认传输单元而非总是最佳知识单元；在嵌入前将近似重复单元折叠为规范记录；从第一个生产版本起使用词法 + 向量混合检索；采用上下文检索时在索引时而非查询时上下文化；在应用层用交叉编码器重排序，绝不在数据库内；从第一天起为嵌入添加 model_id；保持清单 embedding_model 维度与 SQL 资产和 CLI --dim 对齐；对陈旧或删除内容打墓碑；在调优前构建语料特定评估集；将检索到的块视为不可信外部内容。
语料就绪门禁 在语料具备稳定源 ID、租户或 ACL 范围、生效时间戳、确定性提取、重复处理和删除或墓碑路径之前，不要嵌入。先构建词法或精确搜索基线以及带证据 ID 的黄金集。仅当向量路径改善目标检索切片并保持授权和删除行为时才推进。
常见反模式 包括：先向量数据库后源真相模型；对代码、文档和政策使用一种分块配方；将任意令牌窗口视为事实；让重复版本在嵌入空间中竞争；嵌入和原始源文本在同一张未区分表中；纯向量搜索无词法支路；将 HNSW 视为无限规模；在查询时而非索引时上下文化；丢弃原始块导致引用无法指向源文本；在数据库内重排序；无删除/墓碑/取代路径；无语料版本失效的语义缓存；凭感觉调优；无稳定源锚点引用；隐藏操作 SQL；FinOps 模型无重新索引行；向量表无 embedding_model 列；假设“同一模型”永远意味着“同一邻域”；在过滤密集型工作负载上按原始 k-NN 吞吐量选择向量数据库；因存储便宜而摄取数千万向量；将全文搜索视为标识符相等；将 unaccent() 包装为 IMMUTABLE；假设 RRF 使词法排名无关；假设“已索引”意味着“已排名”。
限制 该技能不涵盖设备端 iOS/Swift 检索（路由至 software-ios-ai-engine）；不涵盖非 iOS 对话界面（见 conversational-surfaces-cross-platform.md）；不涵盖宽泛 RAG 理论、应用上下文策略、智能体拓扑或机器人 UX。支持 KB、笔记库和生成的图 + Markdown 剧本为后续增量，除非用户明确要求。