Mid-conversation system-role hoist invalidates the entire prompt-cache prefix (AnthropicMessagesConfig)

快速结论：该报错源于 LiteLLM 将对话中途的 system 消息提升（hoist）到顶层 system 字段，导致 Anthropic 提示缓存前缀失效。优先建议检查 LiteLLM 版本，并确认是否已应用将 system 消息原地转换为 user 角色的修复方案。

适用环境：LiteLLM `main` 分支 @ `6a919aec6a`（Issue 报告时版本）；Vertex AI 上的 Claude 部署（未标记 `supports_mid_conversation_system` 的旧代模型）；AnthropicMessagesConfig 请求路径。

最快修复方案：Issue 确认的方案（已合并至后续 RC）：编辑 `_normalize_system_role_messages` 的 `else` 分支，对不支持的模型将 system 消息原地转换为 `user` 角色，并添加 `_CONVERTED_SYSTEM_NOTE` 前缀，而非提升到 `system` 字段。暂无已验证的一步式配置开关方案。

注意事项：转换为 `user` 角色会丢失 Claude 的“系统指令优先于冲突用户指令”语义；该方案已作为默认行为，但模型可能无法完全加权文本提示。此修复仅影响未标记 `supports_mid_conversation_system` 的模型，标记分支不受影响。

问题场景

在使用 LiteLLM 通过 Vertex AI、Azure Foundry 或 Bedrock Invoke 等 partner endpoint 调用旧代 Claude 模型时，若对话中途出现 `role: “system”` 消息（例如 Claude Agent SDK 的 `mid-conversation-system-2026-04-07` 提醒），会触发该问题。LiteLLM 的 `AnthropicMessagesConfig._normalize_system_role_messages` 会将所有 system 消息提升至顶层，虽避免 400 错误，但破坏了提示缓存。

报错原文

Mid-conversation system-role hoist invalidates the entire prompt-cache prefix (AnthropicMessagesConfig)

原因分析

可能原因：Anthropic 提示缓存按 `tools` → `system` → `messages` 顺序哈希请求前缀，`system` 字段位于较早位置。LiteLLM 将中途 system 消息提升到 `system` 字段后，任何增添都会使缓存前缀字节不匹配，导致整段对话缓存失效。已有实测数据（Vertex AI 流量）：修复前提醒轮次 `cache_creation_input_tokens` 高达 1746，修复后降至 60。

环境排查

确认 LiteLLM 版本：如使用 `main` 分支，需更新至包含修复的版本（Issue 提及 1.88.0-rc.1）；若为旧版本，请检查是否含 #33807 引入的 `_normalize_system_role_messages` 逻辑。
确认模型是否支持 `supports_mid_conversation_system`：不支持时才会走旧的提升路径。
确认部署的 partner endpoint（Vertex、Azure Foundry、Bedrock Invoke），以便复现缓存失效场景。

解决步骤

升级 LiteLLM 至包含修复的 RC 版本（例如 1.88.0-rc.1），或拉取最新 `main` 分支代码。
定位 `litellm/llms/anthropic/experimental_pass_through/messages/transformation.py` 中 `_normalize_system_role_messages` 函数。
在 `else` 分支（无 `supports_mid_conversation_system`）中，对每条 system 消息调用新的 `_convert_system_role_message_to_user_in_place` 方法，原地修改 `role` 为 `”user”` 并添加说明前缀，不移动位置。
保留原有 `hoisted = []`、`remaining = messages` 逻辑，确保无提升发生。
验证带 `supports_mid_conversation_system` 的标记分支未受改动影响。

验证方法

在触发中途 system 提醒的对话中，对比修复前后的 `cache_read_input_tokens` 和 `cache_creation_input_tokens` 指标：修复后提醒轮次应看到 `cache_read_input_tokens` 大幅提升（接近历史完整前缀），`cache_creation_input_tokens` 显著下降，同时请求仍返回 HTTP 200，无 400 错误。