[SAP provider] cache_control is stripped from messages — Anthropic prompt caching unusable

快速结论：当通过 LiteLLM 的 sap/ Provider（SAP AI Core Orchestration）路由 Anthropic 模型时，消息内容块上的 cache_control 标记会在请求转换阶段被静默丢弃，导致 Anthropic prompt caching 永远无法生效，响应中的 cache_read / cache_creation 始终为 0。优先排查 SAP 消息模型是否正确保留了 cache_control 字段。

适用环境：LiteLLM 1.89.3；使用 sap/ Provider 路由 Anthropic 模型（SAP AI Core Orchestration）。Issue 未提供操作系统、Python、CUDA、显卡等环境信息。

最快修复方案：暂无确认的一步修复方案。截至 Issue 关闭时，已有两个开放 PR（#34810、#34948）尝试修复，均未在正文中确认为最终合并方案。

注意事项：两个 PR 各有权衡。#34810 保留了 fold_message_cache_control 步骤，能处理消息级 cache_control（content 为纯字符串时的常见路径），但存在边界情况 bug；#34948 结构更干净，但会回归最常见的缓存启用方式（注入点路径变成 no-op）。此外 SAPUserMessage 是唯一未运行内容校验器的角色，需要补齐与其他角色一致的 validator。

问题场景

用户在 LiteLLM 中通过 sap/ Provider（SAP AI Core Orchestration）路由 Anthropic 模型，并在消息内容块上放置 cache_control 标记以启用 Anthropic prompt caching。请求经过 LiteLLM 转换后，标记被丢弃，缓存无法激活。该问题影响所有通过此 Provider 路由 Anthropic 模型、依赖 prompt caching 控制 token 成本的 agentic 工作负载——每次对话都会以全价重新发送完整的静态 system prompt 和 tool schemas。

报错原文

[SAP provider] cache_control is stripped from messages — Anthropic prompt caching unusable

# Minimal repro output:
{"role": "system", "content": "…"}   # cache_control gone

# ValidationError:
a `user` message with a mixed list + a message-level `cache_control` raises `ValidationError`.

原因分析

SAP 的聊天消息模型（SAPMessage、SAPUserMessage、TextContent）未定义 cache_control 字段，内容在校验阶段被扁平化为纯字符串，因此标记在请求构建之前就被丢弃。相比之下，LiteLLM 原生的 anthropic Provider 支持消息和工具上的 cache_control。

评论进一步指出，SAPUserMessage 是唯一未运行其他角色所执行的内容校验器的消息角色，导致 user 路径出现三类问题：list 内容不再被扁平化为字符串（线格式变更）、混合 list 加消息级 cache_control 触发 ValidationError、cache_control: null 泄漏到 payload 中。此外，如果去掉 fold_message_cache_control 步骤，LiteLLM 自身的 cache_control_injection_points hook 在 content 为纯字符串（常见情况）时设置的消息级标记将无法折叠到内容块上，标记会被静默丢弃。

环境排查

确认 LiteLLM 版本（Issue 中为 1.89.3）
确认使用的是 sap/ Provider 而非原生 anthropic Provider
检查 SAPMessage 的 model_dump(by_alias=True) 输出中是否保留 cache_control
检查 SAPUserMessage 是否运行了与其他角色一致的内容校验器
查看响应中 cache_read / cache_creation 字段是否为 0

解决步骤

运行最小复现脚本，确认 cache_control 是否在 model_dump 后消失：

from litellm.llms.sap.chat.models import SAPMessage
m = SAPMessage(role="system", content=[
    {"type": "text", "text": "…large static prompt…",
     "cache_control": {"type": "ephemeral"}}
])
print(m.model_dump(by_alias=True))

如果输出中不含 cache_control，说明命中了本 Issue 描述的问题。
关注 PR #34810 和 #34948 的合并进展。评审建议：无论哪个 PR 落地，都应给 SAPUserMessage 添加与其他角色相同的内容校验器，以关闭 user 路径的三个边界问题。
如果选择 fold_message_cache_control 相关的修复方向，需确保消息级 cache_control 在 content 为纯字符串时仍能被折叠到内容块上，否则通过 cache_control_injection_points 启用缓存的常见路径会失效。
修复后在真实 SAP AI Core tenant 上验证 cache_control 是否端到端被 Orchestration 接受。

验证方法

在真实 SAP AI Core tenant 上发送两次相同请求：第一次应出现 cache write，第二次应出现 cache read。检查响应中的 cache_read / cache_creation 字段是否不再为 0。评论已确认 SAP AI Core Orchestration 本身端到端支持 cache_control，因此只要客户端 shaping 正确，缓存即可生效。