别再让用户用关键词猜:给 vibe 项目加一个语义搜索
用户问“清爽开胃的夏日凉菜”,关键词搜不到,语义搜索能找到凉拌黄瓜。本文用 OpenAI 官方文档与 pgvector README,手把手搭一条向量检索链路:切块、选模型、建表、查询、索引、过滤与混合搜索,附成本账与验收办法。

先把这篇的边界说清楚。站里已经有好几篇讲搜索的指南,但讲的都不是这篇的东西。《搜索框实战》讲的是输入框那一层:防抖、联想、无结果怎么办。《搜索排序指南》讲的是排好的结果怎么定先后。《关键词搜索》那几篇讲的是按字面匹配找东西。这篇讲的是另一条路:按意思找东西——用户说“清爽开胃的夏日凉菜”,你返回凉拌黄瓜和酸辣海带丝,而不是因为菜谱里没有“夏日”两个字就返回空结果。另外,站里有一篇《微调还是 RAG》的决策指南,讲的是选哪条路;这篇是动手指南,讲选了向量检索这条路之后,具体怎么一步步搭起来。关键词搜索和向量搜索不是二选一,后面有一节专门讲怎么把两者合起来用。
下面用到的“吃什么”是一个虚构的练手项目:一个人用 AI 帮着写的菜谱网站,上面有 800 篇菜谱,能按菜名搜、也能按食材搜。本文所有以它为例的操作、命令、数字和查询结果,都是为了讲清楚做法编出来的,不是真实记录。所有关于向量模型和 pgvector 的规则、默认值和 SQL 写法,都来自 OpenAI 的官方文档和 pgvector 的官方 README,来源见文末。切块大小、相似度阈值、验收用的测试集这些,属于工程上的通行做法,正文里会说明这是建议值,不是哪份文档的规定,照着调就行。
关键词搜不到“好吃的”
先看一个具体的毛病。你的菜谱网站已经能按关键词搜了,用户输入“凉拌黄瓜”,能搜到;输入“黄瓜”,也能搜到。但用户真正想问的往往不是菜名,而是意思:“夏天吃点清爽开胃的”“孩子不吃辣,有什么下饭菜”“冰箱里只剩鸡蛋和番茄,能做什么”。关键词搜这些问题,要么返回空,要么返回一堆沾边但不对的东西——因为“清爽”“开胃”“下饭”这些词,菜谱正文里未必出现过。
向量搜索换了一个思路:不比字面,比意思。把每篇菜谱变成一串数字(向量),意思越接近的菜谱,向量之间的距离就越近。用户的问题也变成一串向量,然后在数据库里找距离最近的那几篇。这样“清爽开胃的夏日凉菜”就能找到凉拌黄瓜,哪怕那篇菜谱里一个“夏日”都没写。这就是语义搜索:搜的是意思,不是字。
向量是什么:先搞懂,再动手
向量就是一串浮点数。OpenAI 的官方文档说得很直白:嵌入(embedding)是文本的数字表示,可以用它来衡量两段文本之间的关联程度;两段文本的向量之间距离越小,关联程度越高;距离越大,关联程度越低。同一份文档还列了嵌入的常见用途:搜索(按与查询字符串的相关性给结果排序)、聚类、推荐、异常检测、多样性衡量、分类。我们的菜谱网站只用到第一项:搜索。
理解这件事不需要数学。想象一张巨大的地图,每个意思都是地图上的一个点:“凉拌黄瓜”和“酸辣海带丝”离得近,因为它们都是凉菜、都开胃;“红烧肉”离它们远,因为它重油重辣。向量就是每个点在地图上的坐标,搜东西就是在地图上找离你的问题最近的那几个点。坐标有多少维,取决于你用的模型——下面一节就讲这个。
选模型:默认用 small,知道什么时候换 large
OpenAI 现在主推的是第三代嵌入模型,一共两个,加上一个老型号。官方文档里的对照表是这样的:
text-embedding-3-small,默认 1536 维,每美元约 62500 页(按每页约 800 token 算),MTEB 评测 62.3%,单次输入最多 8192 token。text-embedding-3-large,默认 3072 维,每美元约 9615 页,MTEB 评测 64.6%,单次输入最多也是 8192 token。老型号 text-embedding-ada-002,默认 1536 维,每美元约 12500 页,MTEB 评测 61.0%,单次输入最多 8192 token。
结论很直接:新项目默认用 small。它最便宜,效果比老型号还好。large 只在一种情况下值得换:你试过 small,发现排在前面的结果总有那么几个不对,想用更好的模型再提一提准确率。ada-002 别在新项目上用了,它是被替代的老型号。
还有一个很实用的参数:dimensions。两个第三代模型都支持把它调小,而且调小之后损失比你想象的小。官方文档明确写了:把 large 的向量从 3072 维缩到 256 维,在 MTEB 评测上仍然超过没缩过的 ada-002(1536 维)。这是因为这两个模型训练的时候就考虑到了这一点,前面的维度带的信息最多。所以如果你以后发现向量存得太多、查得太慢,先试试把维度调小,而不是急着换更贵的存储方案。注意一个细节:如果你是自己动手截断向量(而不是用 dimensions 参数),截完要重新归一化,官方文档给了现成的代码;直接用参数的话,模型会替你处理好。
花多少钱,先算一笔小账。按官方表的口径,small 每美元约 62500 页,每页约 800 token。“吃什么”的 800 篇菜谱切成 2400 个文本块,每块约 300 token,一共约 72 万 token,折合约 900 页,成本约 900 除以 62500,也就是约 1.4 美分。第一次全量向量化花一美分多,之后每次只给新菜谱或改过的菜谱算向量,几乎不花钱。向量搜索的账,贵的地方从来不在生成向量,而在你把它做复杂之后。
切块:一个块只讲一件事
向量模型一次最多吃 8192 token,但这不等于你应该把整篇菜谱一股脑塞进去。搜出来的是块,不是篇:一篇 2000 字的菜谱里同时讲了做法、讲了选材、讲了摆盘,用户搜“怎么挑嫩黄瓜”,你返回整篇菜谱没用,返回“挑黄瓜那一段”才有用。所以要先把内容切成块,一个块只讲一件事。
给“吃什么”定的切法是这样的:一篇菜谱按“标题加简介”“食材清单”“做法步骤”“小贴士”切成 3 块左右,800 篇菜谱切出 2400 块。每块控制在 200 到 500 token 之间,太短了意思不完整,太长了几种意思混在一起,搜出来也不准。相邻的块之间留一点重叠,比如把上一块的最后一句话带进下一块的开头,这样意思在切口处不会断掉。重叠多少没有标准答案,留 10% 到 20% 是个常见的起点,跑起来之后再按实测结果调。
每块除了正文,还要带上三样东西:它属于哪篇菜谱、它是第几块、它是用哪个模型、多少维算出来的。前面两样是给查询结果用的:搜出来的是块,展示的时候要能跳回原来的菜谱;第三样是给以后换模型留的后路:向量是按模型算出来的,换了模型,旧的向量就作废了,全部要重算。把模型名字和维度存在表里,换模型的时候一眼就能看出来哪些要重算。
把整条链路串起来看,就是下面这张图的五个数字:800 篇菜谱切成 2400 个块,每个块算成一个 1536 维的向量存进 Postgres;用户问一句,问题也算成向量,取距离最近的 10 个块,界面上展示前 5 个。链路上的每一步都有对应的章节:切块是这一节,算向量和建表是下面两节,查询和索引是再往后的两节。先记住这五个数字,后面每一节都是在讲其中一步怎么做。

建表:向量就存在 Postgres 里
向量不用另起一个数据库。pgvector 是 Postgres 的一个开源扩展,装上它,你原来的 Postgres 就能存向量、能按距离查。官方 README 的原话是:把向量和你的其他数据存在一起,还能享受 Postgres 的事务、即时恢复、JOIN 这些现成功能。已经有 Postgres 的项目,这是最顺的一条路。
搭起来分四步。第一步,打开扩展,一个数据库里做一次就行:
CREATE EXTENSION vector;
第二步,建一张表。向量列的类型是 vector(1536),1536 这个数必须和你用的模型对上:small 默认就是 1536 维,large 是 3072 维,维数对不上,插数据的时候就会报错。除了向量列,表里还要有菜谱编号、块编号、块正文、模型名字这些字段:
CREATE TABLE recipe_chunks (
id bigserial PRIMARY KEY,
recipe_id bigint NOT NULL,
chunk_no int NOT NULL,
content text NOT NULL,
model text NOT NULL,
embedding vector(1536) NOT NULL
);
第三步,把向量写进去。调 OpenAI 的接口给每个块算向量,一批多传几个块,别一个一个调;算出来的向量按块存进表里。数据量大的时候用 COPY 批量导,比一条一条插快得多。第四步,索引先别建,等初始数据导完了再建,官方 README 明确建议索引后建,建得更快;生产环境建索引要用 CREATE INDEX CONCURRENTLY,避免锁表挡住写入。
查询:把问题也变成向量
查的时候分两步:先把用户的问题用同一个模型算成向量,再到表里找距离最近的几行。模型必须用同一个——用 small 存的向量,只能用 small 算查询向量,混用模型查出来的结果是错的。pgvector 提供了一组距离运算符:<-> 是 L2 距离(欧氏距离),<#> 是内积的负数,<=> 是余弦距离,<+> 是 L1 距离。文本向量一般用余弦距离,余弦相似度等于 1 减余弦距离,越接近 1 越相似:
SELECT recipe_id, chunk_no, content,
1 - (embedding <=> '[0.12,-0.03,...]'::vector) AS similarity
FROM recipe_chunks
ORDER BY embedding <=> '[0.12,-0.03,...]'::vector
LIMIT 10;
这条 SQL 里有个细节:查询向量要写成 '[0.12,-0.03,...]'::vector 这种形式,实际用的时候是程序把算出来的向量拼进参数里传进去,不是手写。返回 10 条,界面上只展示前 5 条,留 5 条做备用。还有一个细节来自官方 README 的性能一节:OpenAI 的向量本身就是归一化过的(长度为 1),这时候用内积查最快;内积运算符返回的是负数,取实际值的时候要乘以负一。
要不要给相似度设一道门槛?建议设,但别拍脑袋定。先跑起来,看一周的真实查询:排第一的结果相似度一般是多少,明显答非所问的结果相似度一般是多少,两者中间那个数就是你的门槛。门槛以下的不要直接展示,改成回一句“没找到特别对口的,你要不要换个说法”——比硬塞一个不对的结果好得多。
索引:数据少的时候不用建,数据多了再建
pgvector 默认做的是精确最近邻搜索:不建索引,把每一行都比一遍,结果百分百准。数据量小的时候这完全够用,800 篇菜谱、2400 个块,精确搜索眨眼就完。数据量大了,逐行比就慢了,这时候再建近似索引:用近似换速度,召回率会打一点折。
两种索引,选 HNSW 就行。它建的是一个多层图,查询速度和召回率的平衡比 IVFFlat 好,建得慢一点、占内存多一点,但不用像 IVFFlat 那样先有数据才能建——空表上就能建,数据可以慢慢加。给余弦距离建 HNSW 索引的写法是这样的:
CREATE INDEX ON recipe_chunks USING hnsw (embedding vector_cosine_ops);
注意运算符类要和查询里用的距离对上:查余弦距离就用 vector_cosine_ops,查 L2 距离就用 vector_l2_ops,查内积就用 vector_ip_ops。一个距离函数建一个索引,混着用是查不快的。HNSW 有三个数可以调,都是官方 README 里的默认值:建图时每层最多连 16 个邻居(m 默认 16),建图时的候选集大小默认 64(ef_construction),查的时候候选集大小默认 40(hnsw.ef_search)。想召回率高一点,把 hnsw.ef_search 调大,比如调到 100,代价是查得慢一点:
SET hnsw.ef_search = 100;
IVFFlat 是另一种选择:它把向量分成很多组,查询的时候只查离查询向量最近的那几组。建得快、占内存少,但召回率和速度的平衡不如 HNSW,而且建索引之前表里得先有数据。它的三个经验数也在官方 README 里:组数从“行数除以 1000”起步(100 万行以内),超过 100 万行用行数的平方根;查询时查的组数从组数的平方根起步。刚开始做语义搜索,HNSW 是更省心的默认选择;等你对召回率和延迟都有了实测数据,再考虑要不要换。
过滤:先筛掉,再比距离
真实的查询很少是“全库比距离”,多半还带着条件:只要川菜、只要 30 分钟内能做好的、不含花生。pgvector 里过滤有个容易踩的坑:用近似索引的时候,过滤是在扫完索引之后才做的。官方 README 给了一个很具体的例子:如果某个条件只匹配 10% 的行,HNSW 默认的 ef_search 是 40,平均下来只会命中 4 行——你要 10 条,它只给你 4 条。解决办法是开迭代索引扫描(0.8.0 版本开始支持),让它自动多扫一些索引,直到找够为止:
SET hnsw.iterative_scan = strict_order;
strict_order 保证结果严格按距离排,relaxed_order 允许顺序稍微乱一点,但召回率更好。除了这个开关,还有两招:一是给过滤用的列单独建索引(比如给菜系建一个普通索引),匹配比例低的条件用精确索引效果最好;二是如果某个过滤值特别常用,比如“只要素菜”,可以给它建一个只含这些行的部分索引。数据量再大、租户再多,就要考虑按租户分区或者分表——官方 README 的多租户一节明确建议,多个租户共用一个近似索引会互相影响召回率和速度,隔离要用分区或者分表。
混合搜索:关键词和向量各管一摊
向量搜索擅长“意思对”,关键词搜索擅长“名字准”。用户搜“宫保鸡丁”,关键词直接命中菜名,又快又准;用户搜“辣口下饭的鸡肉菜”,向量更靠谱。所以别在两者之间二选一,合起来用。pgvector 的 README 专门有一节讲混合搜索:和 Postgres 的全文检索一起用,两个结果合起来排,合并的办法可以用倒数排名融合(RRF),也可以用交叉编码器重排。
刚开始做,合并不用搞复杂。先各查各的:关键词查一遍,向量查一遍,两边结果去重后按一个简单的规则合并——比如菜名精确命中的排前面,向量相似度高的跟在后面。跑起来之后再看数据:如果向量结果经常把关键词结果挤掉,就调权重;如果用户搜菜名还总搜不到,就把关键词那边的权重调高。混合搜索的精髓不在公式,在你有真实查询数据之后再调。
更新与换模型:向量是会过期的
向量不是一劳永逸的。菜谱改了,块就得重算;块重算了,旧向量就得换掉。做法很简单:内容表和向量表用同一套主键,内容一改,就把对应的块删掉重切、重算、重插。别只改正文不改向量,不然搜出来的还是旧内容的意思。
换模型是更大的事。向量是按模型算出来的,换了模型,旧的向量全部作废,一张表要全量重算。这就是为什么建表那节让你把模型名字和维度存在表里:换模型之前,先看一眼表里存的是什么,再决定重算的范围。重算的时候别直接覆盖原表:先在新表里算好,验证没问题了再切换过去,万一新模型效果不如旧的,还能退回来。
还有一个容易忽略的点:向量列的维度是建表时定死的。small 是 1536 维,large 是 3072 维,从 small 换到 large,不只是重算向量,还要改表结构。提前想好这一步,换模型的时候就不会手忙脚乱。
验收:20 条真实问题,比什么指标都管用
搜得准不准,别凭感觉。准备 20 条真实用户会问的问题——从你自己的搜索框日志里找,或者找几个朋友现问现记。跑一遍,看前 5 条里有没有对口的答案,记下来。每改一次切块、换一次模型、调一次参数,就把这 20 条再跑一遍。数字变好了,改动就是对的;数字变差了,就退回去。
还有一个验收办法来自官方 README 的监控一节:拿近似搜索的结果和精确搜索的结果比一比。关掉索引扫描(SET LOCAL enable_indexscan = off),跑一次精确搜索,再开索引跑一次近似搜索,两边的结果重合度就是你的召回率。召回率低了,先调 hnsw.ef_search,再考虑换索引类型。
五个反模式
反模式一:整篇菜谱只算一个向量。一篇里讲了四五件事,一个向量只能代表一个平均意思,搜什么都不准。按意思切块,一个块一件事。
反模式二:查询和存向量用不同的模型。small 存的向量,用 large 算查询向量,查出来的结果是错的。存和查,模型必须同一个。
反模式三:维度对不上还硬插。表是 vector(1536),large 算出来是 3072 维,插不进去。建表之前先对一下模型和维度。
反模式四:数据量很小就急着建索引。几千个块,精确搜索又快又准,建索引反而多一层维护。先跑起来,慢了再建。
反模式五:只看相似度,不看答案。相似度 0.9 的块也可能答非所问,相似度 0.7 的块也可能是正解。验收要用真实问题,别只盯着数字。
检查表:一天就能跑通的最小版本
第一步:装扩展、建表,维度按 small 的 1536 来。别纠结选哪个模型,先用 small 跑起来。
第二步:切 100 篇菜谱,算向量,导进去。先别全量,100 篇够你验证整条链路。
第三步:写查询接口,问题算向量、按余弦距离取前 10、展示前 5。跑通 20 条真实问题,记下前 5 条的命中情况。
第四步:数据量上去了、查询变慢了,再建 HNSW 索引;有过滤条件了,再开迭代扫描;关键词和向量都想要了,再做混合搜索。
语义搜索听起来像大工程,拆开来就是四步:切块、算向量、存起来、按距离查。先让 100 篇菜谱跑通,再谈 800 篇、再谈 8 万篇。很多项目死在第一步想得太多:模型选了一个月,索引调了一周,一行查询都没写过。先跑起来,再调优。等你自己的搜索框里有了真实查询,再回头调切块、调维度、调索引,那时候的每一调都有数据撑着,不再是凭感觉。
评论 (0)
原始来源
相关文章
2026 年 11 月 19 日,PostgreSQL 19 正式发布,比往年晚了两个月——AI 上报的漏洞潮打乱了时间表。新版本带来 REPACK (CONCURRENTLY)、pg_plan_advice 与 WAIT FOR LSN:表可以边跑边整理,执行计划可以钉住,备库会等你写完再读。
localStorage 只能存字符串、没有索引。IndexedDB 是浏览器里真正的数据库:能存结构化数据、容量大得多、能建索引、能用事务。本文按 MDN 的《Using IndexedDB》《IDBDatabase》《IDBObjectStore》三篇官方文档讲清楚:五步套路、开库、升级、主键、索引、事务、add 与 put、get、游标、范围与多标签页升级。
函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。