embedding 归一化怎么配置或排查

配置embedding归一化或者排查相关异常问题，不用上来就改模型的底层计算逻辑，顺着调用链路从参数配置、输出向量校验、依赖环境适配三个方向逐步梳理，大部分常见问题都能快速定位。

embedding 归一化最稳妥的做法，是把它当成检索系统的向量契约：query 和 document 必须经过同样的池化与 L2 归一化，索引和查询还要使用相互匹配的相似度度量。只在某一侧打开开关，或者先归一化再池化，都会让分数看起来“能跑”，却失去可解释性。

先把归一化放在正确的边界上

我通常把 embedding 流程拆成三层：Transformer 产生 token 表示，Pooling 把变长序列压成一个向量，Normalize 再把整条向量缩放到单位长度。这个顺序很重要。归一化是对最终 sentence embedding 做 L2 处理，不是对每个 token 随手处理，也不是用它代替池化。

如果模型本身的 Sentence Transformers 配置已经带有 Normalize 模块，推理时不要重复猜测；直接检查模型结构或用固定样本测范数。文档中的 encode 参数默认 normalize_embeddings=False，所以需要显式决定是否打开。

两种配置方式，关键是只保留一份契约

使用 Sentence Transformers 时，最短路径是把开关同时用于入库和查询。下面的例子只演示配置，不代表已经在本机执行。

from sentence_transformers import SentenceTransformer

# 入库和查询必须共用同一个归一化约定，避免两边的分数不可比
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
documents = ["向量检索需要统一距离度量", "池化会把 token 表示压成句向量"]
query = ["怎么统一 embedding 的相似度计算"]

# 显式打开 L2 归一化；默认值是 False
doc_vec = model.encode(documents, normalize_embeddings=True)
query_vec = model.encode(query, normalize_embeddings=True)

# 单位向量的点积等价于余弦相似度，便于交给支持 dot 的索引
scores = query_vec @ doc_vec.T
print(scores.shape)

如果直接使用 Hugging Face Transformers，则先做 masked mean pooling，再归一化。attention_mask 不能省略，否则 padding token 会改变短文本的方向。

import torch
import torch.nn.functional as F

def mean_pool(last_hidden_state, attention_mask):
    # 只平均真实 token，避免 padding 拉偏句向量
    mask = attention_mask.unsqueeze(-1).expand(last_hidden_state.size()).float()
    summed = torch.sum(last_hidden_state * mask, dim=1)
    counts = torch.clamp(mask.sum(dim=1), min=1e-9)
    return summed / counts

with torch.no_grad():
    output = model(**encoded_input, return_dict=True)

# 先池化得到 sentence embedding，再按行做 L2 归一化
embedding = mean_pool(output.last_hidden_state, encoded_input["attention_mask"])
embedding = F.normalize(embedding, p=2, dim=1)

分数不对时，按三条证据排查

第一条证据是范数。对二维向量矩阵计算 embedding.norm(dim=1)，开启归一化后每一行应接近 1。若 query 接近 1、document 却明显大于 1，通常是入库和查询走了两套编码函数。

第二条证据是池化。若短文本的结果特别不稳定，检查是否把 padding 算进了平均值；若把 token 先归一化再求均值，得到的也不是“先池化再归一化”的同一个向量。固定两三条文本，对比两条实现的维度、范数和余弦分数，比盯着单次召回结果更快。

第三条证据是度量。Sentence Transformers 文档说明，归一化后的向量使用 dot product 时与 cosine 等价，而且可以避免重复归一化。反过来，如果索引使用 inner product、查询却未归一化，向量长度会参与排序，长文本可能凭模长占优。

常见问题

归一化后还要不要再算 cosine？

可以，但通常没有必要。两侧都是单位向量时，点积已经给出余弦相似度；重复做 cosine 只会增加一次处理。

只给 document 归一化可以吗？

除非你明确设计了特殊评分函数，否则不建议。标准语义检索应让 query、document、索引距离度量保持同一契约。

归一化后召回变差怎么办？

先确认模型卡或训练目标期待的度量，再检查池化和 prompt 是否一致。归一化会去掉向量长度信息，如果模型恰好把长度作为有效信号，就应通过固定评测集比较，而不是盲目保留开关。

把这件事落成一个小检查清单就够了：同一模型、同一池化、同一 prompt、两侧同样的归一化、索引与查询同样的度量。五项都能对上，embedding 的“归一化怎么配置或排查”通常就不再是玄学问题。