Embedding 向量入库前，怎样检查维度、非有限数与零范数

向量是一个数组还不够。维度错一位、含 NaN 或全为零，都可能让后续索引与相似度计算失效。客户端应在入库前按索引合同检查，并把每条拒绝理由留给原始业务 ID，不能等数据库报错再丢掉整批。

合同先固定期望维度

本文演示索引要求三维数字数组，使用普通数值列表，不接受编码字符串。实际维度必须来自选定模型与请求配置，不能照抄本例。官方 Embedding 参考定义了响应结构与相关参数，本文只对已经拿到的合成数组做本地数值检查，没有调用模型。

检查顺序是列表类型、长度、元素类型、有限性和范数。布尔值单独拒绝，避免 true 在 Python 中作为整数混入；字符串数字不自动转换。缺维不能补零，超维不能截断，否则向量含义会被改写，而且后续再也看不出原始输入出了问题。

非有限与零向量各有原因

NaN 和正负无穷通过 math.isfinite 检查拒绝。范数使用 math.hypot 计算，避免简单平方求和在较大数值下溢出；结果仍须有限且大于零。余弦相似度需要非零分母，所以一个维度完全正确的零向量也不适用。

附件正常项为三、四、零，范数应为五；坏样本分别是少一维、含布尔、含非有限值和全零。每类都有独立错误码。非有限示例以合法 JSON 中的巨大指数表示，解析后产生的异常值仍会被检查。检查器没有把样本中的坏数写成标准 JSON 允许的普通常量。

不擅自修复坏向量

失败反例是发现 NaN 就替换零，再继续归一化。这个操作会改变方向，得到的向量看起来合法却不再是原来的模型结果。另一个反例是在零向量上除以一个极小常数，虽然避免除零，却不能赋予向量真实语义。异常应隔离并回查来源，而不是加工成一个能入库的形状。

若索引合同要求单位范数，应明确容差并另验，不要把“非零”当成“已经归一化”。本文没有设通用归一误差阈值，因为不同编码与计算流程需要自己的数值政策。数值合法也不说明模型版本兼容，更不说明检索质量好。

生产报告应把映射正确、数值有效和语义效果分开。通过本例只代表向量满足三维有限非零合同，不涉及真实数据库写入、检索召回或性能测试。保留原始数组的受控证据及请求元数据，能在后续迁移时追踪哪一步改变了向量，而不是只剩一个无法解释的入库失败数量。

配套文件与依据

本文的合成输入和参考结果可下载独立样本 a034.json，离线检查器 a034.py与样本放在同一目录后运行。检查器不调用模型接口。 使用 Python 3.12 或兼容版本，将上述文件下载到同一目录，执行 python a034.py。

一手资料1；一手资料2。资料核对日期：2026-10-24。