pgvector-setup 是一个面向 Supabase 数据库的 pgvector 配置技能，用于为 AI 应用、RAG 系统和语义搜索启用向量检索能力。它按阶段组织，提供脚本、SQL 模板和示例文件。
用途 该技能用于在 Supabase 中完成 pgvector 的完整搭建，包括启用扩展、创建嵌入表、建立向量索引、实现语义搜索与混合搜索，并进行测试验证。
主要能力
- 启用 pgvector 扩展并创建基础嵌入表。
- 根据嵌入模型选择向量维度，例如 OpenAI text-embedding-3-small 为 1536 维、text-embedding-3-large 为 3072 维、Cohere embed-english-v3.0 为 1024 维，自定义模型需查阅模型文档。
- 创建嵌入表模板，可调整向量维度、添加元数据列（标签、时间戳、user_id 等）并配置 RLS 策略。
- 创建向量索引：HNSW 适合小于 100 万向量、高召回需求；IVFFlat 适合大于 100 万向量、写入密集场景。
- 提供性能调优参数：HNSW 的 m（默认 16）与 ef_construction（默认 64）；IVFFlat 的 lists（默认 sqrt(rows)）。
- 实现语义搜索：创建 match 函数并通过 supabase.rpc 调用。
- 可选配置混合搜索：结合全文搜索（tsvector 与 GIN 索引）、向量搜索（HNSW 索引）、RRF 融合以及加权评分。
- 提供测试验证脚本，检查扩展、维度、索引使用、查询性能和相似度函数结果。
使用方式 按阶段执行：
- 运行 bash scripts/setup-pgvector.sh [SUPABASE_DB_URL] 启用扩展并创建基础表。
- 复制并自定义 templates/embedding-table-schema.sql，然后通过 psql $SUPABASE_DB_URL < templates/embedding-table-schema.sql 应用。
- 创建索引：bash scripts/create-indexes.sh hnsw [TABLE_NAME] [DIMENSION] 或 bash scripts/create-indexes.sh ivfflat [TABLE_NAME] [DIMENSION]。
- 创建 match 函数（参考 templates/match-function.sql），并在应用中通过 supabase.rpc('match_documents', {...}) 查询。
- 可选：运行 bash scripts/setup-hybrid-search.sh [TABLE_NAME] 配置混合搜索，并使用 hybrid_search 函数。
- 运行 bash scripts/test-vector-search.sh [TABLE_NAME] 进行验证。
适用场景
- 文档搜索：存储文档分块与元数据，使用 HNSW 索引，可加入全文搜索实现混合搜索。
- 用户偏好匹配：存储用户画像嵌入，使用余弦相似度匹配，随偏好变化更新嵌入。
- 产品推荐：存储产品特征嵌入，使用混合搜索并按热度或评分加权。
限制与注意事项
- 距离度量选择：余弦距离（<=>）为安全默认；内积（<#>）适合归一化向量；欧氏距离（<->）适合绝对距离重要的场景。
- 索引选择：多数应用从 HNSW 开始；仅当向量超过 100 万、插入性能关键且可接受较低召回时改用 IVFFlat。
- 维度需与嵌入模型完全匹配，不可截断。
- 安全方面：在所有嵌入表上启用 RLS，按 user_id 或 organization_id 过滤，防止嵌入泄漏；不要暴露嵌入 API 密钥，建议使用 Supabase Edge Functions 生成嵌入，密钥存入 Supabase secrets，并对嵌入请求限流。
- 常见问题排查：查询慢可检查索引使用（EXPLAIN ANALYZE）、增大 HNSW ef_search、减少结果数或添加 WHERE 条件；召回差可增大 match_count、降低 match_threshold 或调整索引参数；内存高可降低 m 或改用 IVFFlat；插入慢可在批量加载时禁用索引后重建。
文件参考 脚本：scripts/setup-pgvector.sh、scripts/create-indexes.sh、scripts/setup-hybrid-search.sh、scripts/test-vector-search.sh。 模板：templates/embedding-table-schema.sql、templates/hnsw-index-config.sql、templates/ivfflat-index-config.sql、templates/hybrid-search-function.sql、templates/match-function.sql。 示例：examples/embedding-strategies.md、examples/vector-search-examples.md、examples/document-search-pattern.md、examples/preference-matching-pattern.md、examples/product-recommendations-pattern.md。
插件：supabase；版本：1.0.0；最后更新：2025-10-26。