向量检索召回条件里哪些字段是非必填？接口参数逐一说明

第一次调向量检索接口，很容易把召回条件整段照抄示例，结果不是报参数错就是结果不对。真正卡住人的往往不是必填字段，而是那一堆「看起来可填可不填」的参数。这篇把召回条件里的非必填字段逐个拆开：它管什么、不填时走什么默认逻辑、什么场景下必须显式给值，并给一份排查顺序，让你对着自己的调用日志逐项核对。

第一次调向量检索接口，很多人是把示例里的召回条件整段照抄，跑不通就到处加字段，结果不是报参数错，就是返回一堆不相关的结果。真正卡人的往往不是必填字段——那几项漏了接口直接骂你——而是那一堆看起来可填可不填的参数：它们决定返回多少条、要不要过滤、走不走重排。

这篇把召回条件里的非必填字段逐个拆开：它管什么、不填时服务端走什么默认逻辑、什么场景下必须显式给值。最后给一份排查顺序，照着对着自己的调用日志逐项核对就行。注意各家向量库的字段名不完全一样，具体写法差异去 /stacks/vector-dbs 对照。

先分清哪几个字段动的是「结果集」

topK / limit、相似度阈值、最小分数这几项，是召回条件里最容易被忽略、但影响最大的非必填字段。它们决定的不是「查得准不准」，而是「返回几条、低于多少分直接丢」。不填时通常走服务端默认条数，并且不做任何分数过滤，也就是有多少返回多少。

topK / limit

限定返回条数；不填走服务端默认，默认值通常偏小，容易让你以为模型召回差

相似度阈值 / 最小分数

低于这个分数直接丢弃；不填等于不做过滤，噪声全给你

距离度量相关参数

部分库可显式指定；不填按索引创建时的设置走

阈值设了反而结果变空，多半是把分数方向理解反了：余弦相似度越高越好，欧氏距离越小越好，两者判断方向正好相反。先确认你的库返回的是哪种口径，不确定就去 /embeddings 看该模型建议的度量方式。做去重或聚类时不要依赖默认条数——宁可在客户端截断，也别让服务端默认值替你决定拿到几条。

过滤类字段：能省，但别省成一次全量检索

按租户、时间、标签、权限做的标量过滤，全部属于非必填。不填就是全库召回，单租户、小数据量的脚本里这么干没问题。但多租户场景下省掉租户过滤，等于把别人的数据也捞进结果里，这已经不是性能问题而是数据越界。

• 预过滤：过滤条件和查询一起传，先缩小候选集再算相似度，结果条数少时优先用它；
• 后过滤：先向量召回再按条件筛，候选条数给小了会明显漏召，表现是「明明有数据却搜不到」；
• 字段名大小写、时间格式、数组包含的写法，各家库口径不同，拿一条你能确认命中过的样本回测最快；
• 单租户、索引里只有自己这批数据时，省掉过滤是合理的，前提是你确认过库里的数据范围。

重排、混合检索与权重：省掉它们你会得到什么

重排开关、重排候选数、关键词与向量的融合权重，同样是非必填。这些字段不填，通常就是「纯向量、不重排」的路径。对语义完整的长问句影响不大，但短查询、专有名词、型号编码这类输入，纯向量召回往往不如关键词命中，这也是很多人觉得「模型不行」的真实原因。

混合检索里那组权重决定关键词命中和语义命中各占多少。不知道填多少时别凭感觉调，同一批问题跑两版对比，看哪版把该命中的都捞回来了。重排候选数给太大既慢又贵，给太小重排等于走过场，先用小批量测出「召回够用」的最小值再放大。

字段排查顺序：从报错到结果不对怎么走

1. 第一步先看报错指向哪个字段。类型不符、参数多包了一层、必填缺失，这三种修法完全不同；具体字段名和嵌套结构到 /stacks/vector-dbs 对照你用的那家。
2. 第二步按「只留必填 → 逐个加回」二分定位。每次只加一个非必填字段，记下返回条数和耗时的变化，哪个字段一动结果就变，问题就在哪。
3. 第三步拿同一批查询做两版对照：一版省掉该字段，一版显式给值。确认差异确实是字段造成的，而不是索引还没建完、数据刚更新没进索引。
4. 第四步把每次调用的召回条数、命中分数区间、过滤条件写进日志。后面调阈值和候选数时，这份日志就是唯一依据。

如果索引刚建好或者数据刚写入，先别急着调字段——召回结果不稳定常常是索引没就绪，而不是参数写错。另一个常见误区是拿单条查询的成败下结论，召回质量要看一批查询的整体命中情况。涉及不同提供方的接口延迟和稳定性对比，到 /tools/speed-test 用当时的数字做参考。