企业官网建设流程全解析

导读

本文基于 community-templates 仓库中的「LiteLLM by HTTP」Zabbix 模板（说明文档 与 模板导出 YAML），系统讲解如何通过纯 HTTP 方式监控 LiteLLM 代理服务器：包括 Prometheus/metrics/端点抓取、/health/liveliness与/health/readiness健康探测、以及基于litellm_deployment_state指标的按部署（model_id）自动发现。读完本文，你将掌握该模板的完整接入流程、全部宏变量与监控项/触发器设计原理，并能直接照做部署。

模板概览：采集架构与三个数据来源

「LiteLLM by HTTP」模板的目标是监控一个 LiteLLM 代理（proxy）服务器，全程只依赖 HTTP，不需要在 LiteLLM 主机上安装任何 Zabbix agent。其采集架构遵循 Zabbix 典型的「主采集项 + 依赖项」模式：

1. 主采集项（master item）：由 HTTP agent 定时抓取 LiteLLM 的 Prometheus 指标端点/metrics/，原始 Prometheus 文本经预处理PROMETHEUS_TO_JSON转换为 JSON；
2. 依赖项（dependent items）：通过 JSONPath 从主采集项转换后的 JSON 中抽取具体指标（计数器转速率、直方图求均值等）；
3. 健康探测：可用性取自无需鉴权的/health/liveliness与/health/readiness两个端点；
4. 部署级发现：对litellm_deployment_state指标执行低级别自动发现（LLD），按model_id生成每个 LLM 部署（deployment）的监控项与触发器原型。

在 template_litellm_by_http.yaml 中可看到模板所属分组为Templates/Applications，模板名与展示名均为LiteLLM by HTTP，并带有class: software、target: litellm标签。

环境要求与已验证版本

• Zabbix 版本：要求 7.4 及以上（模板导出格式为zabbix_export: version: '7.4'，用到了 7.4 新增的能力，如依赖项、LLD 宏路径lld_macro_paths、图表原型、SECRET 类型宏等）。
• 已验证组合：LiteLLM 代理开启 Prometheus callback；Zabbix 7.4.11。
• 前提条件：LiteLLM 侧的 Prometheus 导出器必须开启，否则/metrics根本不会注册，也就没有数据可抓。

按 Zabbix 官方手册「Templates out of the box」章节的要求配置好 Zabbix 后再导入模板（模板依赖 Zabbix 内置的 Prometheus 预处理与 HTTP agent 功能）。

部署前准备：LiteLLM 侧配置

1. 开启 Prometheus exporter

在 LiteLLM 代理的配置文件中加入：

litellm_settings: callbacks: ["prometheus"]

这是整个监控方案成立的前提——callbacks: ["prometheus"]会注册/metrics端点并输出litellm_*系列指标；不开启则/metrics不存在，模板的抓取与依赖项全部无数据可依。

2. 为抓取创建虚拟密钥（virtual key）

默认情况下/metrics需要 LiteLLM 密钥（key）鉴权。创建一个只允许访问/metrics路由的虚拟密钥：

curl -sS https://<litellm-host>/key/generate \ -H 'Authorization: Bearer <MASTER_KEY>' -H 'Content-Type: application/json' \ -d '{"key_alias":"zabbix-metrics","allowed_routes":["/metrics"]}'

这里有两个关键细节（README 中特别强调）：

• 必须使用精确路径/metrics：/metrics/*这类通配符不会匹配/metrics本身；
• 生成的密钥填入宏{$LITELLM.API.TOKEN}，请求时放在x-litellm-api-key请求头中（见 YAML 中主采集项的headers配置），从而把Authorization头空出来留给可能的入口网关 Basic 认证。

3. 备选：关闭 metrics 鉴权

如果环境允许，也可以直接设置：

litellm_settings: require_auth_for_metrics_endpoint: false

此时无需创建密钥，{$LITELLM.API.TOKEN}留空即可。

在 Zabbix 中接入模板

导入与主机配置

1. 导入模板（导入template_litellm_by_http.yaml）；
2. 为 LiteLLM 代理创建（或选用）一台主机，并添加一个interface，其 DNS/IP 指向 LiteLLM 主机——因为所有 HTTP agent 监控项的 URL 都使用{HOST.CONN}宏；
3. 将LiteLLM by HTTP模板链接到该主机；
4. 设置主机宏：最低限度配置{$LITELLM.API.TOKEN}；若与默认值不同，还需调整{$LITELLM.SCHEME}/{$LITELLM.PORT}/{$LITELLM.METRICS.PATH}。

主采集项的实际请求 URL 在 YAML 中定义为：

{$LITELLM.SCHEME}://{HOST.CONN}:{$LITELLM.PORT}{$LITELLM.METRICS.PATH}

即默认https://<host>:443/metrics/。

请求头与双重认证共存

• metrics 请求始终把密钥放在x-litellm-api-key头里，Authorization头保持空闲；
• 如果/metrics在入口网关处还套了一层 HTTP Basic 认证，两层可以共存：把主采集项的Authentication设置为Basic，并填写{$LITELLM.METRICS.USER}/{$LITELLM.METRICS.PASSWORD}；
• TLS 校验在 HTTP agent 监控项上是关闭的，因此内部 CA 与自签名证书可以开箱即用。

触发器的防风暴设计

模板的触发器被刻意做成链式依赖：LiteLLM: Service is not responding是根触发器，readiness、数据库、抓取、延迟、错误率以及各部署级触发器都依赖它（另有少量细分：例如Readiness status is not healthy还依赖Database is not connected；某个部署的partial outage依赖该部署的complete outage）。这样代理整体宕机时，你只会收到一条 High 告警，而不是一打告警刷屏。

宏变量一览

监控项详解

模板共定义 25 个主机级监控项，下面按功能分组完整列出（键名与 YAML 一致）。

主采集项与可用性探测

请求与错误指标

错误率计算项的公式（YAML 中params）：

100*last(//litellm.requests.failed.rate)/(last(//litellm.requests.rate)+(last(//litellm.requests.rate)=0))

注意分母上+(last(...)=0)的写法：当请求速率为 0 时分子为 1，从而避免除零错误——模板中所有比率类计算项都采用了这一零除保护技巧。

Token 吞吐与花费

延迟指标（直方图求均值）

这里展示了一种通用技法：Prometheus 直方图不直接给出均值，模板先分别把_sum与_count转成每秒速率，再相除得到“每请求平均延迟”，从而规避了计数器清零/重启带来的抖动。

缓存与平台指标

所有依赖项的 JSONPath 抽取都带error_handler: CUSTOM_VALUE且参数为0——即指标尚未出现数据时按0处理（见文末「已知限制」），保证监控项不会报 Not supported。

触发器与依赖链设计

模板内置 7 个主机级触发器，表达式可直接复制到 Zabbix 使用：

设计要点：

• 延迟告警拆成 Warn/Crit 两级，且 Warning 依赖 Critical——Critical 已触发时不再重复报 Warning；
• 错误率告警持续5 分钟才触发（min(...,5m)），避免瞬时抖动误报；
• 所有性能/可用性告警都挂在根触发器Service is not responding之下，代理整体不可用时收敛为单条 High 告警；
• 部分触发器带opdata（如 readiness/db 触发器输出Current state: {ITEM.LASTVALUE1}），告警消息中直接携带当前状态值。

基于 LLD 的部署级自动发现

发现规则

LLD 宏通过lld_macro_paths从指标 label 中提取：

发现规则的过滤条件（evaltype: AND）组合两个正则宏：模型名匹配{$LITELLM.LLD.MODEL.MATCHES}的保留，匹配{$LITELLM.LLD.MODEL.NOT_MATCHES}的丢弃（NOT_MATCHES_REGEX），可用来只监控关心的模型、排除测试/内部模型。

原型监控项（6 个）

触发器原型（4 个）

触发器原型名称与描述中会代入{#MODEL}/{#API_BASE}，例如告警标题Deployment {#MODEL} ({#API_BASE}) reports a complete outage，同时opdata携带api_base: {#API_BASE}，一眼定位是哪个上游部署出了问题。层级设计上 partial outage 依赖 complete outage，保证同一部署“部分故障”不会叠加在“完全故障”之上。

值映射

模板内置两张值映射表（YAML 中valuemaps定义），把原始数值翻译为可读状态：

LiteLLM service state（用于litellm.liveness）

LiteLLM deployment state（用于litellm.deployment.state[{#MODEL_ID}]）

仪表盘与图形

模板自带一张LiteLLM overview仪表盘（YAML 中dashboards定义），共 6 个 widget，全部引用模板级图形/图形原型，即使脱离仪表盘也可独立使用：

• LiteLLM: Output tokens per second：输出 Token 速率（绿色粗线 1A7C11）；
• LiteLLM: Requests and errors：总请求速率（渐变线 1A7C11）、代理失败请求（红 F63100）、LLM API 失败（棕 A54F10）三线对比；
• LiteLLM: Token throughput：总 Token（1A7C11）、输入 Token（蓝 2774A4）、输出 Token（红 F63100）三线；
• LiteLLM: Latency：端到端请求延迟（1A7C11）与上游 LLM API 延迟（2774A4）对比——可直观看出瓶颈在代理还是上游；
• LiteLLM: Cache operations：缓存命中（渐变线 1A7C11）与未命中（红 F63100）；
• LiteLLM: Deployment throughput [{#MODEL}]（图形原型）：成功（1A7C11）、失败（F63100）、总请求（2774A4）三线，随 LLD 自动按部署生成。

已知限制与使用注意

README 明确列出的几点，接入前务必知晓：

• 计数器带_total后缀：所有速率类指标都是对带_total的计数器做CHANGE_PER_SECOND（每秒变化率），不要误当成瞬时值；
• 尚无数据的计数器按 0 处理：所有 JSONPath 抽取均配置CUSTOM_VALUE（参数 0），指标尚未产出时监控项显示 0 而不是 Not supported；
• 部分 gauge 依赖特定功能才填充：
  • litellm_remaining_requests_metric/litellm_remaining_tokens_metric（剩余配额类）需要上游返回x-ratelimit-*响应头才有值；
  • litellm_total_users/litellm_teams_count需要启用基于数据库的用户/团队跟踪；
  • 在这些功能开启之前，对应监控项会一直显示 0，属正常现象而非故障。

小结

「LiteLLM by HTTP」是一个“零 Agent、纯 HTTP”的完整监控方案：一个 Prometheus 抓取主采集项 + JSONPath 依赖项完成指标解析，两个无鉴权健康端点负责可用性，一条 LLD 规则把litellm_deployment_state展开成每个 model_id 的部署级监控，最后以链式触发器依赖避免告警风暴。如果你正在维护一个 LiteLLM 代理网关，可以按本文步骤直接在 Zabbix 7.4+ 中导入 模板导出 YAML，配合 官方说明文档 快速落地。该模板作者为 @nikosch86。