Embedding向量维度不一致的根因,是缓存键没有包含“向量空间版本”的信息。缓存键通常由模型名和文本哈希组成,但模型名只表达请求侧的API参数,不表达上游实际响应来自哪个模型版本。中转站叠加了上游映射后,同一个对外模型名可能对应多个上游批次和模型版本。判断这个问题的第一步,是核对你的缓存键里是否有三个信息:模型名、上游版本标识、向量维度。缺了任何一项,模型升级后都会出现缓存错配。
模型名为什么撑不起版本键
很多中转站写缓存键时直接取model参数拼上文本哈希。这在单上游、版本锁定的情况下可用,但两条常见改动会打破这个前提:一是上游更新模型但为兼容旧接口仍沿用原模型名;二是中转站路由配置把新旧模型版本映射到同一个对外模型名。两种情况下,缓存键不变,实际返回的向量维度却可能变化。要判断中转站是否处于风险中,先查模型映射配置,确认每个对外模型名是否唯一对应一个上游模型ID和一个明确的上游版本。如果存在一对多或者版本未知,模型名就不能当版本键。
版本键的最小结构与写入位置
版本键要在请求处理的前置阶段生成,并且让缓存读取、缓存写入、返回前校验三个阶段使用同一个键。一个最小结构可以这样写:
def build_cache_key(model_name, model_version, dim, text):
text_hash = hashlib.sha256(text.encode("utf-8")).hexdigest()
return f"emb:{model_name}:{model_version}:{dim}:{text_hash}"model_version的取值原则是:优先使用上游API响应中暴露的模型版本号;上游不暴露时,用中转站配置中的模型映射版本号或配置项的更新时间。dim则来自当前配置期望的向量维度,不要用历史缓存里的维度回填缓存键,那会掩盖配置过期。缓存miss后调用上游,拿到实际响应时应重新核对维度,一致才写缓存,不一致则按异常处理并返回错误或降级结果。
旧缓存、命中率与维度校验的边界
引入版本键之后,旧缓存不会自动消失。你可以选择让旧键自然过期,也可以主动清掉旧前缀下的键,例如用Redis的SCAN遍历旧模型旧版本前缀后逐个删除。先明确一点:把维度加进键值通常不会降低命中率——同一模型版本下维度是恒定的,只有版本过渡期会同时存在新旧两部分缓存,这是缓存系统应承担的代价。真正需要兜底的是缓存键没有带版本但版本已变的时段:此时缓存返回的数据不会自报错误,必须在返回给调用方之前校验实际向量的维度是否等于期望维度,不匹配就走降级路径。风险边界在于,如果只靠返回校验,错误数据仍占据存储;如果全量清洗旧缓存,会带来一次性穿透,要不要做、何时做,需要结合业务可容忍的延迟抖动来决定。
用日志和拨测验证版本键生效
验证版本键是否生效,不建议只看命中率指标,因为错误缓存也能抬高命中率。可验证的线索有三条。第一,在缓存键生成处输出debug日志,记录model_name、model_version、dim和text_hash的前几位;上游升级后,同一请求文本的缓存键应随之变化。第二,对返回前的向量维度做计数统计,出现偏离配置维度的情况时立即告警,这比等用户投诉更早暴露问题。第三,用固定文本做拨测,记录每次请求的维度值和缓存命中情况;上游升级后第一次请求通常落到新键下,表现为一次冷调用,后续请求再命中新键。如果上游API不暴露版本号,就需要在配置层维护模型名到模型版本号的映射表,并在每次上游升级时手动推进这个版本号。这个动作没有自动化捷径,应纳入发布流程。