Gemini explicit cache creation drops lifecycle usage; spend callbacks omit creation and storage accounting

快速结论：在 LiteLLM 使用 Vertex Gemini 显式缓存（explicit cache）时，如果出现 Gemini explicit cache creation drops lifecycle usage 和 spend callbacks omit creation and storage accounting，通常意味着缓存创建调用产生的创建用量、createTime/expireTime 元数据被丢弃，回调只上报推理费用。优先排查缓存生命周期是否缺少独立的创建计费事件。

适用环境：Issue 已确认：litellm==1.100.0、Python 3.11.14、httpx 0.28.1、pytest 9.1.1、pytest-asyncio 1.4.0；复现路径为 Vertex AI（vertex_ai/gemini-2.5-flash、vertex_ai/gemini-2.5-flash-lite）。未确认操作系统、CUDA、显卡或数据库环境。

最快修复方案：暂无确认的一步修复方案。Issue 中讨论的方向是新增独立的缓存生命周期计费事件（如 cache.created），按 provider resource name 去重，而不是把创建/存储费用附加到第一次成功的 completion 上。

注意事项：Issue 中的复现使用 mock，不能证明实际留存时长、provider 账单金额或存储取整方式。TTL 更新与提前删除仍需要单独的生命周期对账；仅修复成功 completion 的计费路径会漏掉“创建成功、生成失败”的场景。

问题场景

用户在 LiteLLM 中调用 Vertex AI Gemini 模型，并启用自动显式缓存。复现路径为 LIST → CREATE → GENERATE → LIST → GENERATE，即先创建 Google cachedContents 资源，随后复用该缓存进行生成。在该路径下，创建缓存的用量和生命周期元数据没有进入回调，spend callbacks 只报告推理费用。另一个场景是 LIST → CREATE → GENERATE (400)：缓存资源已经创建，但生成请求失败，此时只出现失败回调，成本为零，且没有任何创建/过期元数据。

报错原文

Gemini explicit cache creation drops lifecycle usage; spend callbacks omit creation and storage accounting

原因分析

可能原因：共享的 create-response 处理代码在处理 Vertex Gemini 显式缓存创建响应时，没有保留 provider 返回的创建用量（复现中为 10,000 creation tokens）以及 createTime/expireTime 时间戳，导致这些数据无法传递给计费回调。

可能原因：回调契约目前只围绕 completion 的成功/失败构建，缺少独立于生成结果的缓存生命周期事件。因此当创建成功但生成失败时，没有任何回调携带创建元数据；当同一缓存被多次读取时，也无法区分“一次创建”与“多次推理读取”。

社区评论中提出，缓存创建成本不应只挂在第一次成功的 completion 上，因为 TTL 可能独立过期或被更新，且创建成功后可能有多次复用或后续生成失败。

环境排查

确认 LiteLLM 版本是否为 1.100.0，该复现基于此版本。
确认 Python 版本是否为 3.11.14。
确认 httpx 是否为 0.28.1。
确认 pytest 是否为 9.1.1，pytest-asyncio 是否为 1.4.0。
确认调用路径是否为 Vertex AI，模型是否为 vertex_ai/gemini-2.5-flash 或 vertex_ai/gemini-2.5-flash-lite。
确认是否启用了显式缓存，并检查创建响应中是否包含 creation tokens 与 createTime/expireTime。
确认 completion 回调中是否只有推理费用，没有缓存创建或存储相关条目。

解决步骤

复现缓存创建路径，观察 LIST → CREATE → GENERATE → LIST → GENERATE 下回调的数量与内容。按 Issue 描述，当前只会出现两个推理回调，且不含 provider 的创建/过期元数据。
复现“创建成功、生成失败”路径：LIST → CREATE → GENERATE (400)。确认此时只有失败回调，成本为零，且没有创建/过期元数据。
检查回调 payload 中是否包含缓存资源标识（provider resource name）、创建用量和 createTime/expireTime。若没有，则属于该 Issue 描述的可观测性缺失。
可优先尝试：为缓存创建引入独立生命周期事件，按 provider resource name 作为 key，携带创建用量、创建与过期时间、模型和请求归属信息，使其不依赖 generation 成功与否。
可优先尝试：spend 消费端按 resource id 去重，将创建计费与存储对账从推理回调中分离；completion 回调仍可携带 cached-read tokens，但不再隐式承担一次性的创建/存储计费。
增加验收测试：mock LIST → CREATE → GENERATE(400)，断言即使 completion 事件为失败/零成本，仍然发出 cache-created 计费事件。

验证方法

确认修复后，在 LIST → CREATE → GENERATE → LIST → GENERATE 路径中，除了两次推理回调外，还应出现一次独立的缓存创建事件，且该事件包含创建用量和创建/过期时间戳。在 LIST → CREATE → GENERATE (400) 路径中，即使生成失败，也应出现缓存创建事件。检查多次缓存读取是否不会各自产生新的创建/存储计费，并确认创建事件可按 resource id 去重。