向量检索为什么召回为空：embedding 维度与归一化的排查链

向量检索返回空结果时，先别急着重建索引或更换向量数据库。更常见的情况是：入库向量和查询向量的 dimension 不一致，或者一边做了归一化、另一边没有，导致查询链路在真正进入相似度计算前就被拒绝。下面用一个最小 Go 实验，把这条排查链拆开。

先确认 dimension，再确认 normalize，最后才看相似度阈值；这三个检查顺序能区分“根本没算”与“算了但没过阈值”。

先复现：数据在库里，为什么结果仍然为空

假设文档入库时使用 1536 维 embedding，查询服务上线后换成了 768 维模型。向量库可能直接报维度错误，也可能由业务层把异常吞掉，最后只返回一个空数组。另一类问题更隐蔽：两边维度一致，但入库向量已归一化，查询向量保持原长度，固定阈值就不再代表同一件事。

为了避免把数据库、网络和模型服务混在一起，先在本地只验证三个节点：ValidateDimension 检查长度，Normalize 统一尺度，CosineSimilarity 计算最终分数。

package main

import (
    "errors"
    "fmt"
    "math"
)

func ValidateDimension(vector []float64, dimension int) error {
    if len(vector) != dimension {
        return fmt.Errorf("dimension mismatch: got=%d want=%d", len(vector), dimension)
    }
    return nil
}

func Normalize(vector []float64) ([]float64, error) {
    var sum float64
    for _, value := range vector {
        sum += value * value
    }
    if sum == 0 {
        return nil, errors.New("cannot normalize zero vector")
    }
    length := math.Sqrt(sum)
    normalized := make([]float64, len(vector))
    for i, value := range vector {
        normalized[i] = value / length
    }
    return normalized, nil
}

func CosineSimilarity(left, right []float64) (float64, error) {
    if len(left) != len(right) {
        return 0, errors.New("vectors have different dimensions")
    }
    var dot, leftSum, rightSum float64
    for i := range left {
        dot += left[i] * right[i]
        leftSum += left[i] * left[i]
        rightSum += right[i] * right[i]
    }
    if leftSum == 0 || rightSum == 0 {
        return 0, errors.New("zero vector has no cosine direction")
    }
    return dot / math.Sqrt(leftSum*rightSum), nil
}

把排查顺序固定成三次检查

第一步：记录入库向量和查询向量的维度

在写入和查询的边界分别记录 len(vector) 与配置中的 dimension。如果第一步已经失败，不要继续调整相似度阈值；阈值只对已经完成计算的分数有意义。下面的调用顺序刻意把维度错误留在最前面：

func search(query, stored []float64, dimension int, threshold float64) (float64, error) {
    if err := ValidateDimension(query, dimension); err != nil {
        return 0, err
    }
    if err := ValidateDimension(stored, dimension); err != nil {
        return 0, err
    }
    query, err := Normalize(query)
    if err != nil {
        return 0, err
    }
    stored, err = Normalize(stored)
    if err != nil {
        return 0, err
    }
    score, err := CosineSimilarity(query, stored)
    if err != nil {
        return 0, err
    }
    if score 

第二步：确认归一化发生在同一层

不要把“模型输出天然可比较”当成约定。最稳妥的做法是让入库和查询都显式调用 Normalize，并在日志里标记 normalized=true。如果向量库已经配置了内置归一化，应用层就不要再次猜测，而应通过一组固定向量做一次对照实验。

第三步：最后才调整阈值

当维度相同、零向量被拒绝、归一化策略一致后，再观察 CosineSimilarity 的分布。阈值应由验证集上的相关与不相关样本决定，不要因为“空结果”就无限降低阈值，否则噪声会混入上下文。

常见故障表现对应什么证据

• 返回 dimension mismatch：记录 got 和 want，先核对模型配置与索引创建参数。
• 返回 zero vector：检查文本是否为空、模型服务是否把异常结果转成全零数组。
• 分数正常但全部低于阈值：固定向量跑归一化前后对照，确认阈值是否建立在同一尺度。
• 应用日志为空且向量库无请求：检查业务层是否把上述错误直接转换成空列表。

扩展实验：用固定向量保护回归

把一组小而稳定的向量放进单元测试：相同方向的向量应得到接近 1 的分数，正交向量应接近 0，维度不同和全零向量必须返回错误。测试的价值不在于模拟某一家模型，而在于锁住你自己的预处理契约。

func TestSearchRejectsDimensionMismatch(t *testing.T) {
    _, err := search([]float64{1, 0}, []float64{1, 0, 0}, 3, 0.8)
    if err == nil {
        t.Fatal("expected dimension mismatch")
    }
}

把这条链带回线上

生产日志至少保留请求向量维度、索引维度、是否归一化、相似度阈值和错误分支，不要记录完整向量本身。告警按“维度错误”“零向量”“低分数”分开统计，排查时就能知道是模型契约断了，还是召回策略真的变了。

相关问题

向量维度相同就一定能直接比较吗？

不一定。维度只是形状条件，模型语义空间、归一化规则和距离度量也必须一致。

为什么不建议先把阈值降到很低？

因为维度或归一化错误会制造系统性偏差，降低阈值只能把无关内容带进上下文，无法修复输入契约。

总结

召回为空的排查顺序可以很朴素：先用 ValidateDimension 排除形状错误，再用 Normalize 统一尺度，最后用 CosineSimilarity 和验证集重新判断阈值。把三个节点分开，空结果就不再是一个没有证据的黑盒。