[Bug]: guardrail_information is null on successful requests with headroom-compression guardrail (default_on=true)

[Bug]: guardrail_information is null on successful requests with headroom-compression guardrail (default_on=true)

快速结论：当 LiteLLM 配置了 headroom-compression guardrail 并设置 default_on: true 时，成功请求的 guardrail_information 字段在 LiteLLM_SpendLogs.metadata 中为 null（仅失败请求会记录），导致无法按官方文档指引验证 guardrail 执行情况。同时 headroom 两个未文档化的默认值会导致 prompt-cache-heavy 场景（如 Claude Code 启用 Anthropic prompt caching 时）无法产生压缩。

问题场景

用户运行 LiteLLM Proxy，配置了 headroom-compression guardrail（设置 default_on: true），通过 /v1/messages 端点发送请求（例如使用 Claude Code 工具）。问题在路由层触发，与 LLM 响应本身无关——即使使用 mock provider 也能复现。

报错原文

guardrail_information is null on successful requests and only populated on failed requests

以及伴随的未压缩现象：

router.route_counts: {user_msg: 18, system_msg: 8}
requests_compressed: 0

原因分析

可能原因：LiteLLM 的后端日志记录逻辑仅在被 guardrail 拒绝（失败）的请求上填充 guardrail_information 字段，而成功通过的请求未写入该信息。此外，headroom 的两个默认行为在生产环境文档中缺失：

• HEADROOM_COMPRESS_USER_MESSAGES=0（headroom 默认值）—— 未在 LiteLLM headroom 文档中说明
• cache_control_protected —— headroom 会跳过带有 Anthropic prompt cache 标记的 messages，导致与 Anthropic prompt caching 产生未文档化的交互，在 prompt-cache-heavy 负载下压缩率为零

环境排查

• LiteLLM 版本：v1.92.0-dev.1（或更早版本）
• headroom 版本：0.27.0（通过 headroom-ai[proxy]==0.27.0 安装）
• Python 版本：3.12（headroom Docker 镜像使用）
• PostgreSQL 16（用于存储 SpendLogs）
• 后端语言/模型：Anthropic Claude（claude-sonnet-4-5）或任意 mock provider

解决步骤

1. 确认 headroom 默认压缩行为：检查 headroom 的环境变量 HEADROOM_COMPRESS_USER_MESSAGES 是否为 0（默认值）。如果是，需显式设置为 1 以启用对用户消息的压缩。
2. 检查 prompt caching 影响：如果工作负载使用了 Anthropic prompt caching（如 Claude Code），headroom 的 cache_control_protected 默认会跳过这些 messages。确认 headroom 版本及 cache_control_protected 相关配置是否可调整。
3. 等待 LiteLLM 修复发布：根据 Issue 讨论，此 Bug 已在 internal_staging 分支修复，等待正式发布。升级到包含此修复的 LiteLLM 版本（≥ 即将发布的版本）。
4. 可优先尝试：在修复发布前，可通过检查 headroom 日志和 /v1/compress 端点的调用来手动验证 guardrail 是否被执行。如果看到 router.route_counts: {user_msg: ..., system_msg: ...} 且 requests_compressed: 0，则表明压缩被 headroom 默认设置阻止了。

验证方法

修复后，发送一个成功的 /v1/messages 请求，然后查询 LiteLLM_SpendLogs.metadata 中对应的 guardrail_information 字段：

• 失败场景：guardrail_information 应为 null（旧行为）
• 修复后：guardrail_information 应包含 headroom 压缩的详细信息（如 requests_compressed 计数等）

同时验证 headroom 压缩是否生效：在启用 HEADROOM_COMPRESS_USER_MESSAGES=1 且没有 Anthropic prompt caching 的情况下，requests_compressed 应 > 0。

参考来源

BerriAI/litellm #32008（相关 Issue：#31969 —— “Headroom guardrail compress nothing”，症状一致）

AI 工具推荐

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

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

了解 GamsGo AI

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