Supabase 向量检索配置：pgvector 表结构与 RPC 查询
Supabase 的向量检索依赖 PostgreSQL 的 pgvector 扩展。
你不需要额外安装数据库，只要在 Supabase 项目的 SQL Editor 中启用扩展、建好带 vector 列的表和索引，再通过 RPC 函数或直接 SQL 做相似度查询即可。
下面按从零配置的顺序展开，适用于 Supabase 免费版和付费版项目。
先确认扩展和表结构
登录 Supabase 控制台，进入目标项目，打开左侧 SQL Editor。
先执行以下语句启用 pgvector：
create extension if not exists vector;如果没有报错，说明扩展可用。
接着创建一张用于存储文档向量的表，例如 documents：
create table documents (
id bigint primary key generated always as identity,
content text not null,
embedding vector(1536)
);这里 vector(1536) 表示向量维度为 1536，必须与你实际使用的嵌入模型输出维度一致。
例如 OpenAI 的 text-embedding-3-small 默认输出 1536 维，更换模型时要同步修改列定义。
建立向量索引
数据量较小时可以不建索引直接查询，但数据超过几千行后建议创建 HNSW 索引来加速近似最近邻搜索：
create index on documents
using hnsw (embedding vector_cosine_ops);vector_cosine_ops 对应余弦距离。
如果你在查询时使用内积或欧氏距离，索引操作符类也要相应换成 vector_ip_ops 或 vector_l2_ops，否则查询可能用不上索引。
建完索引后，可以通过以下语句确认索引存在：
select indexname, indexdef
from pg_indexes
where tablename = 'documents';编写 RPC 检索函数
Supabase 推荐把检索逻辑封装成数据库函数，然后通过客户端 RPC 调用。
在 SQL Editor 中执行：
create or replace function match_documents (
query_embedding vector(1536),
match_threshold float default 0.7,
match_count int default 5
)
returns table (
id bigint,
content text,
similarity float
)
language sql stable
as $$
select
documents.id,
documents.content,
1 - (documents.embedding <=> query_embedding) as similarity
from documents
where 1 - (documents.embedding <=> query_embedding) > match_threshold
order by documents.embedding <=> query_embedding
limit match_count;
$$;函数参数 query_embedding 的维度必须和表列一致。<=> 是余弦距离操作符，1 - 距离 得到相似度，值越接近 1 表示越相似。
函数创建后，在 Supabase 客户端的 JavaScript 中这样调用：
const { data, error } = await supabase.rpc('match_documents', {
query_embedding: embedding,
match_threshold: 0.7,
match_count: 5
});注意：RPC 函数默认遵循表的行级安全策略（RLS）。
如果表启用了 RLS 且没有给当前用户配置 select 权限，函数会返回空结果或权限错误。
测试阶段可以先在表上关闭 RLS，或者为 anon / authenticated 角色创建允许读取的策略。
常见配置错误
- 向量维度不匹配：插入数据或调用函数时报
expected 1536 dimensions, not 768，说明嵌入模型输出维度与表定义不一致，需要统一修改列类型和函数参数。 - 索引未被使用：查询时使用
order by embedding <-> query_embedding但索引建的是vector_cosine_ops，操作符类不一致会导致全表扫描，建议查询和索引使用同一种距离度量。 - RPC 调用返回空数组：先检查表里是否有数据，再确认 RLS 策略是否允许当前角色读取，最后检查
match_threshold是否设得过高。
验证检索是否生效
在 SQL Editor 中直接插入两条测试向量并查询：
insert into documents (content, embedding)
values
('测试文档一', array_fill(0.1, array[1536])::vector),
('测试文档二', array_fill(0.2, array[1536])::vector);
select * from match_documents(
array_fill(0.1, array[1536])::vector,
0.5,
2
);预期返回两条记录，且第一条相似度更高。
如果查询结果为空，优先检查向量维度是否一致以及函数内阈值条件。
整个配置的核心在于三处对齐：表列维度、函数参数维度、实际嵌入模型输出维度。
索引操作符类与查询距离度量保持一致，再确认 RLS 权限，Supabase 向量检索就能正常跑通。
