[Bug]: Amazon Bedrock cache misses when adding a ‘role’: ‘system’ message

快速结论：当通过 LiteLLM 代理访问 Amazon Bedrock 上运行的 Claude Opus 4.8 模型时，如果在消息中间插入一条 role: "system" 消息，LiteLLM 会错误地将其提升到顶层的 system 字段中，导致整个请求的前缀变更，使 Prompt Cache 失效。优先排查 LiteLLM 版本是否包含 #32578 修复。

问题场景

用户在使用 LiteLLM 代理转发请求至 Amazon Bedrock 上的 Claude Opus 4.8 模型（模型 ID: eu.anthropic.claude-opus-4-8）时，发现 Claude Code 的缓存命中率远低于预期。经过深入排查，确认问题出现在 LiteLLM 将 OpenAI 兼容格式转换为 Bedrock /v1/messages 格式的过程中。

报错原文

Amazon Bedrock cache misses when adding a 'role': 'system' message

litellm seems to sort it to the front or add it to the "system":  messages which breaks the cache.

The Bedrock Invoke `/v1/messages` transform was hoisting mid-conversation `role: "system"` reminders into the top-level `system` field, which mutated the cached prefix and collapsed the prompt cache for the whole history

原因分析

LiteLLM 在将消息序列转换为 Bedrock 的 /v1/messages 请求时，会检测消息列表中的 role: "system" 消息并将其提升到请求顶层的 system 字段。这种转换逻辑原本是为了兼容旧版 Claude 模型（它们在消息中间不接受 role: "system"），但它在 Claude Opus 4.8 上产生了副作用：

被提升的 role: "system" 消息从原本的消息列表中被移除，改变了整个请求的 token 序列（前缀）
Claude Opus 4.8 原生支持 mid-conversation system（通过 anthropic-beta: mid-conversation-system-2026-04-07 头启用），因此这种提升行为是不必要的
前缀变化导致 cache_read_input_tokens 始终为 0（缓存未命中），即使后续请求的 role: "user" 开头部分完全相同

环境排查

确认 LiteLLM 版本：检查是否包含 PR #32578 的修复（该修复已合入 main 分支）
确认目标模型为 Claude Opus 4.8 或更新版本（需支持 mid-conversation-system beta 头）
确认 anthropic-beta 头中包含了 mid-conversation-system-2026-04-07（或后续版本）
确认请求中的 role: "system" 消息是位于消息列表中间（非首位）

解决步骤

升级 LiteLLM：将部署升级到包含 PR #32578 的构建版本。该修复停止了对 Opus 4.8 的 role: "system" 消息提升行为，保留了原始的 token 序列，使缓存前缀在多次请求间保持一致。
（可选）进一步升级：获取包含 PR #32831 的版本。该修复引入了 supports_mid_conversation_system 能力标志，使 LiteLLM 能够根据模型能力进行智能判断：
- Opus 4.8+：保留 role: "system" 在消息列表中，不提升 → 缓存保持
- 旧版 Claude（如 Claude 2/Instant）：依然提升到顶层 system 字段 → 避免 Bedrock 返回 400 错误
验证配置：如果无法立即升级，可优先尝试移除请求中间的 role: "system" 消息，将其合并到顶层的 system 字段中，作为临时规避方案（仅限 Opus 4.8 用户）。

验证方法

运行类似 Issue 中提供的测试脚本（发送两次相同前缀的请求，中间包含 role: "system" 消息），检查 response.usage.cache_read_input_tokens 字段：

修复前：第二次请求的 cache_read_input_tokens 仍为 0（缓存未命中）
修复后：第二次请求的 cache_read_input_tokens 应为非零值（表示缓存命中）

具体检查 prompt_tokens_details.cached_tokens 或 cache_read_input_tokens 字段值是否与第一次请求的 cache_creation_input_tokens 或 input_tokens 匹配。

参考来源

BerriAI/litellm #32730

AI 工具推荐

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

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

了解 GamsGo AI

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

[Bug]: Amazon Bedrock cache misses when adding a ‘role’: ‘system’ message