Embedding 余弦相似度异常时如何检查向量归一化

余弦相似度突然变低、出现负数，或者同一对文本在离线脚本和向量库里得到不同分数时，先不要直接改阈值。最先要确认的是两条向量的维度、L2 范数和有限性；再在同一批数据上同时算原始点积、归一化后的点积和余弦值。三者的差异，通常比单看一个相似度分数更容易定位问题。

官方资料入口：https://developers.openai.com/api/reference/overview

排查顺序可以固定为：先看输入摘要，再看范数，再对照三种分数，最后检查向量库的距离配置。

先看范数：异常不一定来自余弦公式

余弦相似度的定义是 dot(a, b) / (norm(a) * norm(b))。因此，向量长度不是余弦公式的附属信息，而是排查入口。若某条向量的范数为 0，计算会遇到除零；如果出现 NaN 或 Inf，任何排序结果都不应继续使用。

先给每条向量做四项记录：长度、L2 范数、最大绝对值、是否全部为有限数。不要只打印前几个元素，因为截断或拼接错位可能发生在后半段。

import math

def vector_summary(vector):
    # 先把输入统一成浮点数，避免整数和字符串混入后难以定位
    values = [float(value) for value in vector]
    norm = math.sqrt(sum(value * value for value in values))
    return {
        "dimension": len(values),
        "l2_norm": norm,
        "max_abs": max((abs(value) for value in values), default=0.0),
        "finite": all(math.isfinite(value) for value in values),
    }

summary = vector_summary(query_embedding)
print(summary)

# 零向量不能参与余弦计算，非有限值也应在这里拦截
if not summary["finite"] or summary["l2_norm"] == 0:
    raise ValueError("embedding 不是有限的非零向量")

用同一批数据同时算点积和余弦

如果两条向量都已经是单位向量，点积与余弦相似度相等；如果原始向量长度不同，点积还会受到尺度影响。下面的配方故意保留三种结果，便于判断是“方向变了”，还是“长度变了”。

import math

def l2_norm(vector):
    # L2 范数用于把向量缩放到单位长度
    return math.sqrt(sum(value * value for value in vector))

def normalize(vector):
    norm = l2_norm(vector)
    if norm == 0:
        raise ValueError("零向量没有可用的方向")
    return [value / norm for value in vector]

def dot(left, right):
    # 维度不一致时立即失败，避免 zip 静默丢掉尾部元素
    if len(left) != len(right):
        raise ValueError("向量维度不一致")
    return sum(a * b for a, b in zip(left, right))

def cosine(left, right):
    # 公式中的两个范数必须来自同一对输入向量
    return dot(left, right) / (l2_norm(left) * l2_norm(right))

raw_dot = dot(query_embedding, document_embedding)
normalized_dot = dot(normalize(query_embedding), normalize(document_embedding))
cosine_score = cosine(query_embedding, document_embedding)
print(raw_dot, normalized_dot, cosine_score)

观察结果时抓住两个关系：normalized_dot 与 cosine_score 应该接近；如果它们差很多，优先查公式、浮点转换或输入顺序。如果两者接近，但 raw_dot 明显偏离，说明尺度影响了点积，不能拿点积阈值替代余弦阈值。

把问题定位到输入、归一化和向量库

脚本算对了，线上仍然异常，通常是链路中间改变了数据。可以按下面的检查表逐层抽样；每层只记录维度、范数、前后几个摘要值和请求批次，不要把完整向量写入普通日志。

特别注意“归一化两次”和“只归一化查询向量”这两类误解。对标准余弦公式来说，输入是否已经单位化并不改变最终角度；但如果向量库配置的是内积或欧氏距离，归一化会改变排序语义，必须与索引配置一起确认。

生产阈值怎么定

阈值不要从别人的示例分数直接搬过来。固定模型、切块策略和距离度量后，准备一小组已知相关的正例、容易混淆的难负例，以及空文本、零向量和长度异常样本。先保存每组的范数和分数，再根据误召回与漏召回的代价选择阈值。

如果模型或向量库发生变化，先重跑这组基准样本。阈值漂移不一定代表归一化坏了，也可能是模型空间、文本清洗或索引距离发生了变化。

常见问题

余弦相似度出现负数，是不是归一化失败？

不一定。负数表示夹角大于 90 度，可能是内容确实不相似。先确认范数非零且结果在合理范围内，再判断语料和模型是否适合当前任务。

向量已经是单位长度，还要再归一化吗？

可以在边界处做一次轻量检查，但不要把重复归一化当成修复手段。若范数已经接近 1，应该继续查输入、索引距离和排序方向。

为什么本地余弦和向量库分数不一样？

先确认向量库返回的是相似度还是距离，再核对是否使用同一批向量、同一维度和同一精度。只有这些条件一致，分数才适合逐项比较。