[Bug]: GCS cache always misses on read when gcs_path is set (object name not URL-encoded in GET)

快速结论：当使用 GCS 缓存后端且设置了 gcs_path 前缀时，缓存读取会始终返回 miss，因为 GET 请求中的对象名称缺少 URL 编码。优先检查是否配置了 gcs_path，以及缓存读取时的 HTTP 响应是否为 404。

问题场景

在使用 LiteLLM 并配置 GCS（Google Cloud Storage）作为缓存后端时，如果设置了 gcs_path 参数，缓存写入可以成功，但所有缓存读取操作都会返回 miss，导致每次请求都重新计算，无法命中缓存。

报错原文

# 缓存读取返回 None，无显式错误日志
# GET 请求返回 404，但 httpx 未抛出异常
# 实际行为：缓存 key 存在，但读取请求路径错误导致 404

原因分析

在 litellm/caching/gcs_cache.py 中，set_cache 和 get_cache 构建对象 URL 的方式不一致：

写入（set）使用查询参数方式：?name={object_name}，允许 object_name 中包含斜杠（/），可以正确创建对象。
读取（get）将 object_name 直接插入 URL 路径：.../o/{object_name}?alt=media，GCS JSON API 要求路径中的对象名称必须是 URL 编码的（例如 / 必须编码为 %2F）。

由于 object_name 由 gcs_path 前缀（如 "my_cache/"）和缓存 key 拼接而成，未经编码的斜杠导致 GCS 返回 404，而 httpx 不会因 4xx 抛出异常，所以 status_code == 200 检查失败，返回 None。不使用 gcs_path 时，路径中没有斜杠，读取可以正常工作。

环境排查

确认 LiteLLM 版本：该问题在 litellm 1.86.1 上可复现，且在 main 分支上仍然存在。
确认 cache_params 配置中是否设置了 gcs_path 参数。
确认 GCS bucket 是否存在并有正确的访问权限。

解决步骤

作为临时绕过方案：移除 gcs_path 配置，使用默认路径（不带前缀斜杠的缓存 key）。
永久修复方案（需代码修改）：修改 litellm/caching/gcs_cache.py 中的 get_cache 和 async_get_cache 方法，对 object_name 进行 URL 编码：

from urllib.parse import quote

# 在 get_cache 中：
url = f"https://storage.googleapis.com/storage/v1/b/{bucket_name}/o/{quote(object_name, safe='')}?alt=media"

# 在 async_get_cache 中同样修改

可选：同步修改 set_cache / async_set_cache 中的 ?name= 参数（当前可以工作，但保持对称性更佳）。
该修复已提交 PR，等待合并。可直接更新到包含此修复的版本，或手动修改后使用。

验证方法

应用修复后，使用如下配置发送两次相同的 /chat/completions 请求：

litellm_settings:
  cache: true
  cache_params:
    type: gcs
    gcs_bucket_name: my-bucket
    gcs_path: my_cache/

检查第二次请求是否命中缓存（响应时间应明显缩短，且不需要重新计算）。可以通过查看 GCS bucket 中是否存在 my_cache/<sha256hash> 对象来辅助确认。

参考来源

BerriAI/litellm #30377

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Bug]: GCS cache always misses on read when gcs_path is set (object name not URL-encoded in GET)