Supabase Vector基于 Postgres 与 pgvector 的向量存储、索引与相似度检索实践【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabaseSupabase Vector 是把向量嵌入vector embeddings直接存储在与业务事务数据同一个 Postgres 数据库中的 AI 向量检索工具包底层由开源扩展 pgvector 驱动。本篇围绕仓库中的产品说明 vector.md 展开结合官方文档apps/docs/content/guides/ai/目录与examples/ai/下的可运行示例完整讲解从生成嵌入、建表建索引到带元数据过滤的混合 SQL 查询的全流程读完你可以直接在 Supabase 项目中落地语义搜索、RAG 与图像相似度检测等场景。什么是 Supabase VectorSupabase Vector 的定位可以概括为一句话用你已经拥有的数据库做向量数据库。它让你无需引入独立的向量数据库就能在生产级 Postgres 中获得向量存储、索引与近似最近邻ANN检索能力。产品说明文档给出了它的核心特性逐条对应仓库中可验证的实现如下特性说明仓库中的对应证据pgvector 集成直接在 Postgres 中存储、索引和查询向量嵌入pgvector 扩展文档 介绍了启用vector扩展及建表用法数据共置Co-located向量嵌入与关系型数据同库存放可用标准 SQL 做 JOINedge-functions 示例迁移 与业务表同 schema并启用了 RLS多种索引类型IVFFlat 与 HNSW 两种 ANN 索引HNSW 索引文档、IVFFlat 索引文档多种距离度量余弦距离、L2欧氏距离、最大内积Vector columns 文档 给出三个距离算子与对应算子类元数据过滤可按任意列或 JSONB 元数据过滤相似度查询语义搜索文档 提供按元数据过滤的完整 JS 示例Python 客户端vecs管理 collection、upsert 向量与查询的专用 Python 库vecs 客户端文档LLM 集成支持 OpenAI、Hugging Face、Amazon SageMaker、LangChain 等AI 指南 的 Integrations 章节及examples/ai/下的 Bedrock 图像搜索示例、LlamaIndex 示例Edge Functions 生成嵌入在 Edge Functions 中直接用开源模型生成嵌入generate-embedding 函数 使用Supabase.ai.Session(gte-small)可自托管整套技术栈可运行在自己的基础设施上仓库根目录的 docker/docker-compose.yml 即自托管部署入口SOC2 Type 2 合规企业级安全合规产品说明声明常见使用场景产品文档列出的典型场景本质上都归结为用距离度量代替关键字匹配语义搜索对文档、知识库或工单按含义而非关键字检索参见 语义搜索指南RAG检索增强生成为大模型应用建立可检索的外部知识层官方文档还覆盖了带权限控制的 RAG with permissions图像相似度检测将图片编码为向量后按余弦距离检索仓库内提供 image_search 示例 与 face_similarity 笔记本推荐引擎基于用户/物品向量找最近邻自动打标签与内容分类带长期记忆的 ChatGPT 插件building-chatgpt-plugins 文档 讲解把 Supabase 作为插件检索存储。工作原理五步流水线产品文档将工作机制归纳为五步下面逐步展开并给出仓库中真实可复现的 SQL 与代码。第一步用任意模型生成嵌入嵌入模型不限于某一个供应商可选 OpenAI、Hugging Face、Cohere 等。仓库 edge-functions 示例 展示的是开源模型 Edge Functions路线在 Deno 运行时中直接实例化模型会话// examples/ai/edge-functions/supabase/functions/generate-embedding/index.ts节选 const model new Supabase.ai.Session(gte-small) // 生成嵌入mean pooling 归一化到单位长度 const embedding await model.run(content, { mean_pool: true, normalize: true, })这里有两个关键参数mean_pool: true对 token 向量做平均池化得到句向量normalize: true把向量归一化到长度 1——这一步直接决定了后续可以用更便宜的内积运算替代余弦距离见第四步。第二步把嵌入存进带vector列的 Postgres 表先在数据库启用vector扩展扩展名即vector而不是pgvector然后声明带维度的向量列。仓库中真实的迁移脚本如下-- examples/ai/edge-functions/supabase/migrations/20240408072601_embeddings.sql create extension if not exists pg_net with schema extensions; create extension if not exists vector with schema extensions; create table embeddings ( id bigint primary key generated always as identity, content text not null, embedding vector (384) ); alter table embeddings enable row level security;vector(384)中的 384 必须与你所用嵌入模型的输出维度一致上例中的开源模型gte-small输出 384 维。Vector columns 文档 补充了一条经验总体而言维度更少的嵌入表现更好因此选型时可在精度与维度之间权衡。embedding只是普通列名可以随意命名迁移脚本同时开启了 RLS说明向量表与业务表一样受 Supabase 的行级安全策略保护。第三步创建 HNSW 或 IVFFlat 索引加速检索同一迁移脚本在表建好后立即创建了 HNSW 索引-- 20240408072601_embeddings.sql 最后一行 create index on embeddings using hnsw (embedding vector_ip_ops);索引类型和算子类必须与查询使用的距离算子匹配。pgvector 提供三个距离算子与算子类的对应关系摘自 vector-columns.mdx算子含义算子类-欧氏L2距离vector_l2_ops#负内积vector_ip_ops余弦距离vector_cosine_ops因此若查询走内积就应建vector_ip_ops的 HNSW 索引否则索引无法被该算子使用。第四步用距离算子查询相似度检索是最常见用法直接按距离排序即可-- 余弦距离示例来自 pgvector 扩展文档的查询写法 select * from embeddings order by embedding [...] limit 5;若要通过 Supabase 客户端如supabase-js调用由于客户端经由 PostgREST 访问 Postgres而 PostgREST 不支持 pgvector 的相似度算子需要把查询包在 Postgres 函数中再用rpc()调用。仓库中的 query_embeddings 函数 是完整范例-- examples/ai/edge-functions/supabase/migrations/20240410031515_vector-search.sql create or replace function query_embeddings(embedding vector(384), match_threshold float) returns setof embeddings language plpgsql as $$ begin return query select * from embeddings -- 内积符号相反因此对 match_threshold 取负 where embeddings.embedding # embedding -match_threshold -- 嵌入已归一化到长度 1余弦相似度与内积结果等价 -- 而内积计算更快所以这里选用 # order by embeddings.embedding # embedding; end; $$;这段源码印证了文档中归一化向量下内积最快的结论因为嵌入生成时就执行了normalize: true#与的排序结果一致选内积只是为了省一次范数计算。match_threshold参数则保证只返回相似度超过最低阈值的行避免返回主观上不相关的内容——阈值取值需要按业务自测确定。官方文档还给出了另一种等价的 RPC 写法vector-columns.mdx带match_count参数并在返回列中显式计算similaritycreate or replace function match_documents ( query_embedding extensions.vector(384), match_threshold float, match_count int ) returns table (id bigint, title text, body text, similarity float) language sql stable as $$ select documents.id, documents.title, documents.body, 1 - (documents.embedding query_embedding) as similarity from documents where 1 - (documents.embedding query_embedding) match_threshold order by (documents.embedding query_embedding) asc limit match_count; $$;客户端调用只需const { data: documents } await supabaseClient.rpc(match_documents, { query_embedding: embedding, // 查询文本生成的嵌入 match_threshold: 0.78, // 按数据特点调整 match_count: 10, // 返回条数 })两个要点均来自文档中的注意事项一、order by必须直接按距离函数排序如上例而不是按算出来的similarity列排序否则可能绕过索引导致性能劣化二、参与距离计算的嵌入必须来自同一个嵌入模型跨模型比较没有意义。第五步与标准 SQL 组合做混合查询向量列与普通列同表意味着可以任意叠加JOIN、WHERE、GROUP BY。仓库中的 search 函数 展示了完整的线上形态先为搜索词生成嵌入再调 RPC 取回 Top-N 并链式.select(content).limit(3)const { data: result, error } await ctx.supabaseAdmin .rpc(query_embeddings, { embedding: JSON.stringify(embedding), match_threshold: 0.8, }) .select(content) .limit(3)配合元数据过滤时在函数上多加一个参数和where子句即可完整示例见 语义搜索文档的Filtering vector search by metadata一节。另有一个实现细节值得注意ANN 索引在带过滤条件时可能返回少于LIMIT的行索引先按距离取候选、过滤后数量不足官方文档在 pgvector 扩展页 中给出了规避方案——使用 pgvector 的 iterative index scans 继续扫描索引直到凑足结果HNSW 的具体机制见下文。HNSW 索引原理、维度上限与调优HNSW 是产品文档标注为recommended的默认索引类型。HNSW 索引文档 将其拆解为两个概念**分层Hierarchical**借鉴跳表思想底层是连接所有节点的稠密图每往上一层按固定概率抽稀形成越来越稀疏的长距离连接。搜索从顶层开始找不到目标就下沉到下一层逐层收敛。可导航小世界Navigable Small World每个向量是图上的一个节点除连接近邻外还带少量长程连接使几乎任意节点都能在数跳内到达贪心搜索因此能以接近对数的复杂度导航图结构。维度上限。产品页给出的规格是Max dimensions: 2,000 (HNSW), 16,000 (flat)。官方文档的更精确口径是pgvector 0.7.0 及以上版本中HNSW 索引支持vector类型最多 2,000 维、halfvec最多 4,000 维、bit最多 64,000 维可用SELECT * FROM pg_extension WHERE extname vector;查看当前版本。超出 2,000 维的场景可用halfvec转型建索引例如 3,072 维的嵌入CREATE TABLE documents ( id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, content text, embedding vector(3072) ); CREATE INDEX ON documents USING hnsw ((embedding::halfvec(3072)) halfvec_cosine_ops);建索引时机。与 IVFFlat 不同HNSW 基于图结构建表后即可立即构建新数据插入时索引自动填充并保持结构最优不需要等数据量积累到位。过滤与 iterative index scans。给向量查询加where不会绕过 HNSW 索引Postgres 规划器会根据过滤选择性与表规模在索引扫描和顺序扫描之间做选择代价是过滤条件高选择性时索引先返回的 Top-k 被大量过滤掉最终行数可能少于LIMIT。从 pgvector 0.8.0 起规划器支持由hnsw.iterative_scanGUC 控制的迭代索引扫描默认off两种启用模式为strict_order跨轮次保持严格距离顺序与relaxed_order允许轻微重排以换取更高召回。扫描深度由hnsw.max_scan_tuples默认 20,000和hnsw.scan_mem_multiplier默认 1约束摘自 HNSW 索引文档。IVFFlat 索引lists 与 probes 的权衡IVFFlat 索引文档 说明其原理是倒排文件索引建索引时对向量做聚类倒排列表 / cell clusters查询时只与命中的邻近聚类比较而不是全表比较。建索引 SQL 需指定lists数量例如create index on items using ivfflat (column_name vector_cosine_ops) with (lists 100);核心权衡参数lists越大查询越快但召回率越差probes每次查询探测的邻近聚类数默认 1越大召回越好但越慢可按会话设置set ivfflat.probes 10;或按事务设置set local ivfflat.probes 10;。当 probes 等于 lists 时退化为精确搜索规划器将不再使用该索引建索引时机官方建议在表已有足够数据后再建使内部聚类基于真实数据分布数据分布显著变化时应考虑重建索引。这也是文档推荐默认使用 HNSW 的两个理由之一另一个是性能。Edge Functions 全链路从写入 Webhook 到语义搜索examples/ai/edge-functions/把前述五步串成了一个可在本地跑通的完整闭环README 提供本地启动与 curl 调用说明其数据流是业务表发生 INSERT/UPDATE 时Postgres Webhook 触发 generate-embedding 函数。函数先比较content与old_record.content内容未变则直接返回ok - no change避免重复推理有变化则调用gte-small模型生成嵌入用supabaseAdmin客户端写回embeddings表。客户端发起搜索时search 函数 对搜索词生成嵌入调用query_embeddingsRPCmatch_threshold: 0.8取回 Top-3 内容。两个函数均以apikey头携带密钥调用部署时verify_jwt false即绕过 JWT 校验、走服务侧密钥认证。本地验证命令摘自 search 函数源码注释# 1. supabase start # 2. supabase functions serve # 3. 发起搜索请求 curl -i --location --request POST http://127.0.0.1:54321/functions/v1/search \ --header apikey: SUPABASE_SECRET_KEY \ --header Content-Type: application/json \ --data {search:vehicles}技术规格与生产化要点对照产品文档的 Technical Details 逐项说明扩展pgvector开源 Postgres 扩展启用方式为create extension vector with schema extensions;见 pgvector 文档禁用为drop extension if exists vector;。最大维度HNSW 索引 2,000 维vector类型、flat 16,000补充上文所述halfvec4,000 维、bit64,000 维的扩展上限以及 2,000 维时的halfvec转型建索引方案。索引类型HNSW推荐默认与 IVFFlat选择依据见上面两节。扩缩容向量检索与你所在 Supabase 数据库共享同一套计算扩缩容Micro 到 16XL 的计算规格容量规划可参考 选择计算规格文档更大的工程化讨论见 engineering-for-scale。备份每日自动备份 PITRpoint-in-time recovery。Python 客户端vecs提供 collection 管理、upsert 与查询的高层 API适合以向量集合而非裸表方式组织的未结构化嵌入详见 vecs-python-client 文档结构化嵌入则建议走数据库迁移管理参见 headless-vector-search 示例 的数据库准备部分。模型与框架集成仓库examples/ai/目录收录了 Amazon Bedrock 图像生成/检索aws_bedrock_image_search、LlamaIndexllamaindex.ipynb、llamafile 边端推理等示例LangChain、Hugging Face 等集成指南见 AI 指南 的 Integrations 章节。生产检查清单上线前的部署考量含向量场景见 going-to-prod 文档查询变慢时优先考虑补 HNSW 索引对应排查指南见 troubleshooting/increase-vector-lookup-speeds-by-applying-an-hsnw-index-ohLHUM.mdx。小结Supabase Vector 的价值在于消除独立向量数据库的引入成本嵌入与事务数据同库同 schema索引、备份、扩缩容、行级安全全部复用 Postgres 既有能力三个距离算子、HNSW/IVFFlat 两类索引以及 RPC 封装模式覆盖了从几十条到生产规模的知识库检索需求。建议按迁移脚本建表建索引20240408072601_embeddings.sql→ RPC 函数封装查询20240410031515_vector-search.sql→ Edge Functions 生成与检索examples/ai/edge-functions的路径在当前仓库内复现完整链路再按需引入halfvec、iterative scans 或vecs客户端做进阶优化。【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考