Xinference 集群监控告警规则实战指南：基于 Prometheus 与 Alertmanager 的健康巡检体系

Xinference 集群监控告警规则实战指南：基于 Prometheus 与 Alertmanager 的健康巡检体系

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference

本指南以 Xinference 仓库中的 Prometheus 告警规则（中文版） 为骨架，系统讲解 Xinference 集群健康监控的告警体系：从 GPU 显存、Worker 资源、模型请求质量，到 Token Router 数据面可用性的完整分层告警设计，并给出 Prometheus 加载与 Alertmanager 路由/抑制的完整配置方法。读完本文，你将掌握如何为 Xinference 集群快速搭建一套可落地、可扩展、语义严谨的生产级告警监控方案。

一、告警规则文件概览

Xinference 在仓库 monitor/alert 目录下提供了一组开箱即用的 Prometheus 告警规则，覆盖 GPU 显存、Worker 节点、模型请求质量、磁盘空间、Token Router 数据面等关键维度。全部规则文件使用相同的告警表达式和阈值，仅对summary与description注解做了本地化翻译：

每个规则文件都包含两个规则组（group）：

• xinference-alert-rule：面向集群基础设施与模型服务的基础告警组，包含 10 条规则；
• xinference-token-router-monitoring-v2：面向 Token Router 控制面与数据面的分层告警组，包含 10 条规则。

这些告警表达式所引用的指标，绝大多数由 Xinference Supervisor 侧的内置监控指标（位于 xinference/core/metrics.py）导出，指标名统一使用xinference:前缀；只有DiskSpaceLow依赖通用的node_filesystem_*节点指标。

二、基础告警规则逐条解析（xinference-alert-rule）

2.1 GPUMemoryHigh — GPU 显存使用率过高

• 级别: critical（严重）
• 条件: GPU 显存使用率 > 90%，持续 5 分钟
• 表达式:xinference:worker_gpu_memory_used_bytes / xinference:worker_gpu_memory_total_bytes > 0.9

该规则按 Worker 与 GPU 维度告警，触发后可在 description 中看到worker_address与gpu_index标签，精确定位是哪台 Worker 的哪块 GPU 显存告急。底层指标由 Supervisor 定时快照各 Worker 的资源上报生成（参见 xinference/core/metrics.py 中worker_gpu_memory_used_bytes/worker_gpu_memory_total_bytes的定义），并随_SUPERVISOR_ONLY_METRICS集合仅在 Supervisor 侧暴露。

2.2 ModelRequestErrorRateHigh — 模型请求错误率过高

• 级别: warning（警告）
• 条件: 模型请求错误率 > 5%，持续 3 分钟
• 表达式:sum without (stream) (rate(xinference:model_request_errors_total[5m])) / sum without (stream) (rate(xinference:model_request_total[5m])) > 0.05

表达式首先用rate(..., [5m])计算 5 分钟窗口内错误数与请求总数的增量速率，再用sum without (stream)按除stream外的所有标签聚合，从而把同一模型的流式与非流式请求合并统计，得到整体错误率。model_request_errors_total与model_request_total在 xinference/core/metrics.py 中均为 Counter 类型。

2.3 TTFTHigh — 首 Token 延迟过高

• 级别: warning（警告）
• 条件: 首 Token 延迟 > 10 秒，持续 3 分钟
• 表达式:rate(xinference:time_to_first_token_seconds_sum[5m]) / rate(xinference:time_to_first_token_seconds_count[5m]) > 10

该规则将 TTFT 直方图的_sum与_count在 5 分钟窗口内的增量速率相除，得到窗口内的平均首 Token 时延。time_to_first_token_seconds在源码中的分桶为(0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, inf)，意味着超过 30 秒的请求落入最后一个桶，配合该告警可以及时发现模型推理吞吐下降或排队严重的情况（仅对 LLM 有效）。

2.4 WorkerOffline — Worker 节点离线

• 级别: critical（严重）
• 条件: 在线 Worker 数量 < 1，持续 2 分钟
• 表达式:xinference:workers_total < 1

workers_total是 Supervisor 侧 Gauge 指标，由 Supervisor 从集群心跳数据中的worker_count字段刷新（参见 xinference/core/metrics.py 中workers_total.set({}, cluster_data.get("worker_count", 0))）。当集群内一个在线 Worker 都没有时触发 critical 告警，说明整个推理集群已无可用计算节点。

注意：当前WorkerOffline是不带worker_address标签的集群汇总告警，因此无法在 Alertmanager 中安全地表达“只抑制同一 Worker 的副本派生告警”。若需要逐节点告警与精确抑制，需先将其调整为逐节点指标。

2.5 DiskSpaceLow — 磁盘空间不足

• 级别: critical（严重）
• 条件: 磁盘可用空间 < 10%，持续 5 分钟
• 表达式:(node_filesystem_avail_bytes / node_filesystem_size_bytes) < 0.1

这是唯一一条依赖通用节点指标（而非xinference:前缀指标）的规则，必须确保在所有集群节点上部署 node_exporter，否则该规则将因缺少时间序列而无法生效。触发后可依据instance与mountpoint标签定位具体节点与挂载点。

2.6 RequestQueueBacklog — 请求并发接近上限

• 级别: warning（警告）
• 条件: 模型并发比率（活跃数 / 上限）> 90%，持续 3 分钟
• 表达式:xinference:model_serve_count / (xinference:model_request_limit > 0) > 0.9

表达式中的(xinference:model_request_limit > 0)是一个保护性写法：当model_request_limit为 0 时整个布尔表达式结果为 0，从而避免除零产生无穷大而误报。model_serve_count（当前正在服务的请求数）与model_request_limit（该模型的并发请求上限）在 xinference/core/metrics.py 中均为 Gauge，两者之比 > 0.9 说明该模型的并发水位已接近上限，存在请求排队甚至超时的风险。

2.7 ModelLoadSlow — 模型加载缓慢

• 级别: warning（警告）
• 条件: 模型加载耗时 > 5 分钟
• 表达式:xinference:model_last_load_duration_seconds > 300

该规则基于 Gauge 指标model_last_load_duration_seconds，记录模型最近一次加载的耗时（秒），for: 0m表示一旦超过 300 秒立即触发，无需持续观察。description 中通过humanizeDuration模板函数把秒数格式化为人类可读时长，并结合model_name标签指明具体模型。模型加载慢通常意味着磁盘 IO 瓶颈、模型体积过大或资源竞争，可作为调度决策的参考信号。

2.8 ReplicaUnexpectedTerminated — 副本异常终止

• 级别: critical（严重）
• 条件: 副本因 Worker 故障被标记为异常下线，持续 1 分钟
• 表达式:xinference:model_unexpected_termination == 1

model_unexpected_termination为 Gauge，值为 1 表示副本当前因 Worker 故障而处于下线状态，并在重新部署（redeploy）后清零（源码注释："Replica currently down due to worker failure (value=1). Cleared on redeploy."）。触发后可结合model_name与replica_index标签确定具体副本。这是副本管理（xinference/core/replica_config.py、xinference/core/pd_model.py 等）场景中最重要的故障信号之一。

2.9 WorkerMemoryHigh — Worker 内存使用率过高

• 级别: warning（警告）
• 条件: Worker 内存使用率 > 90%，持续 5 分钟
• 表达式:xinference:worker_memory_used_bytes / xinference:worker_memory_total_bytes > 0.9

与 GPUMemoryHigh 类似，该规则由 Supervisor 汇总各 Worker 的内存使用量与总量快照而成（worker_memory_used_bytes/worker_memory_total_bytes均来自 xinference/core/metrics.py 中的 Worker 资源 Gauge），可配合worker_address标签定位内存水位过高的节点，提前规避 OOM 风险。

2.10 RequestLatencyHigh — 请求延迟过高

• 级别: warning（警告）
• 条件: P95 请求延迟 > 60 秒，持续 3 分钟
• 表达式:histogram_quantile(0.95, rate(xinference:model_request_duration_seconds_bucket[5m])) > 60

该规则基于请求耗时直方图model_request_duration_seconds（分桶定义见 xinference/core/metrics.py），先用rate(..., [5m])计算各桶计数速率，再用histogram_quantile(0.95, ...)估算 5 分钟窗口内的 P95 延迟。它与 TTFTHigh 共同构成了"首 Token 时延 + 整体请求时延"的双重视角。

2.11 BannedIPsSpike — 封禁 IP 数量异常

• 级别: warning（警告）
• 条件: 封禁 IP 数 > 10，持续 2 分钟
• 表达式:xinference:banned_ips_total > 10

banned_ips_total是 Supervisor 侧安全审计类 Gauge 指标（位于 xinference/core/metrics.py，与banned_keys_total、API Key 审计指标同一分组），统计当前被封禁的 IP 数量。封禁数异常升高通常意味着存在暴力破解或滥用行为，可与 Xinference 的 审计与安全文档、认证体系文档 配合排查。

三、Token Router 监控 V2.1 分层告警（xinference-token-router-monitoring-v2）

xinference-token-router-monitoring-v2规则组是 Token Router 监控体系（Monitoring V2.1）的告警侧实现，针对 Agent 连接、Assignment 就绪、Runtime 可用性/可控性/配置版本、Tokenizer 资产绑定以及逻辑 Router 健康度进行分层告警。这些告警对应的指标全部由 Supervisor 监控进程统一导出，属于"控制面快照"指标（Runtime 侧自身的请求计数器仍留在各 Runtime 自己的/metrics端点），定义集中在 xinference/core/metrics.py 的 Token Router Monitoring V2.1 分区（约第 162 行起），并随_SUPERVISOR_ONLY_METRICS集合仅在 Supervisor 侧暴露。

3.1 告警清单与关键表达式

其中涉及的关键指标语义（均见 xinference/core/metrics.py）：

• token_router_agent_connectivity_status：Agent 连接状态（one-hot，按status标签区分 suspected/offline 等）；
• token_router_runtime_up：Runtime 是否在 Supervisor Registry 中在线；
• token_router_runtime_effective_ready：Runtime 是否"有效且可用于服务流量"（effective_ready），它是比up更强的可用性语义；
• token_router_runtime_controllable：Runtime 当前是否可通过其 Agent 被控制；
• token_router_runtime_config_synced：Runtime 配置与 Assignment 代数是否保持最新；
• token_router_assignment_desired_state/token_router_assignment_runtime_ready：Assignment 期望状态（one-hot）与关联 Runtime 的就绪状态；
• token_router_tokenizer_binding_state：Tokenizer 资产绑定的期望/观测状态（observed_state取failed或stale）；
• token_router_desired_replicas/token_router_effective_ready_replicas：逻辑 Router 的期望副本数与"有效就绪"副本数；
• token_router_status：逻辑 Router 整体状态（one-hot，取值包括degraded等）。

TokenRouterAssignmentNotReady的表达式还体现了关键的一层过滤：只有当 Assignment 的期望状态是 running时，若其关联 Runtime 未就绪才告警——这避免了把"本来就不打算运行"的 Assignment 误报为故障。TokenRouterRuntimeUncontrollable则只对"有效就绪但失去控制链路"的 Runtime 触发，属于控制面异常而非数据面故障。

3.2 分层告警的可用性语义

该规则组设计的核心是分层、不越级、不互相淹没：

• Agent 被怀疑或离线是警告级别，它反映的是控制面（Agent 与 Supervisor 之间）的健康状况，并不直接等于 Router 数据面不可用；
• 有效 Runtime 失去控制链路时触发TokenRouterRuntimeUncontrollable；
• 只有当期望副本数 > 0 且有效就绪 Runtime 为 0 时，才触发严重级别的TokenRouterUnavailable，它才是"Router 服务不可用"的最高层信号；
• 不应因为 Agent Offline 警告而抑制TokenRouterUnavailable——Runtime 有效性是更高层的服务可用性信号，Agent 离线只是其可能的诱因之一。

Supervisor 侧通过_sync_gauge_series等辅助函数将控制面状态快照同步为 one-hot 指标序列（测试用例 xinference/core/tests/test_monitoring_v2.py 验证了"有效就绪与可控性分别导出"以及"过期标签集合会被清理"的行为），确保告警表达式基于一致的、无陈旧序列的指标集计算。

四、在 Prometheus 中加载告警规则

在 Prometheus 配置文件中通过rule_files引入规则文件（以中文版为例）：

# prometheus.yml rule_files: - "/path/to/monitor/alert/rules-zh-CN.yml"

保存配置后，向 Prometheus 发送热重载请求使配置生效：

curl -X POST http://localhost:9090/-/reload

或者向 Prometheus 进程发送SIGHUP信号触发重载。生效后可在 Prometheus Web UI 的 "Alerts" 页面查看全部规则的状态、表达式与当前触发情况；也可以通过promtool check rules先对规则文件做静态校验（promtool check rules monitor/alert/rules-zh-CN.yml），再加载到生产环境。

五、Alertmanager 路由与抑制集成

5.1 按严重级别路由分发

配置 Alertmanager 按告警的severity标签进行路由，将 critical 与 warning 分发到不同通知渠道：

# alertmanager.yml route: group_by: ['alertname'] receiver: default routes: - match: severity: critical receiver: critical-channel - match: severity: warning receiver: warning-channel

group_by: ['alertname']将同一告警名的通知聚合为一条，避免风暴式刷屏；receiver需在receivers段中定义（如 webhook、邮件、钉钉/飞书等），并按需为 critical 通道配置更快的重复通知间隔与升级策略。

5.2 抑制规则：避免症状告警淹没根因告警

仓库提供了 alertmanager-inhibition.yml 作为集成片段：它不能作为 Prometheus 告警规则文件加载，而应将其中的inhibit_rules合并到生产alertmanager.yml的顶层inhibit_rules键下。示例仅包含两条严格限定范围的抑制规则：

inhibit_rules: # 用逻辑 Router 可用性信号，优先于同一 Router 的逐 Runtime / 逐 Assignment 症状 - source_matchers: - alertname="TokenRouterUnavailable" target_matchers: - alertname=~"TokenRouterRuntimeDown|TokenRouterAssignmentNotReady" equal: - router_uid # Agent 已离线时，只抑制同一 node 的低层连接性或容量派生告警； # Runtime 与 Router 服务可用性告警保持可见 - source_matchers: - alertname="TokenRouterAgentOffline" target_matchers: - alertname=~"TokenRouterAgentSuspected|TokenRouterAgentCapacityMismatch|TokenRouterAgentHeartbeatStale" equal: - node_id

两条规则的语义边界非常明确：

• TokenRouterUnavailable只抑制相同router_uid的TokenRouterRuntimeDown与TokenRouterAssignmentNotReady——当根因是"Router 整体不可用"时，其下属的逐 Runtime/逐 Assignment 症状就不再重复告警；
• TokenRouterAgentOffline只抑制相同node_id的 Agent 低层连接性或容量派生告警（AgentSuspected、AgentCapacityMismatch、AgentHeartbeatStale）——Agent 本身已离线，再报它"suspected"或"心跳过期"没有意义。

同时，Agent 离线时不会抑制TokenRouterUnavailable、Runtime 数据面告警或其他业务可用性告警：控制面故障不能掩盖数据面真相。当前WorkerOffline因为是无worker_address标签的集群汇总告警，暂时无法安全表达"只抑制同一 Worker 的副本派生告警"，需要先将 Worker 离线告警调整为逐节点指标后，再增加对应 inhibition。

六、从规则到指标：告警体系的源码印证

整套告警规则并非凭空设计的"拍脑袋阈值"，而是与 Xinference 监控实现一一对应：

1. 指标定义：所有xinference:前缀指标都在 xinference/core/metrics.py 中声明，包括 Counter（如model_request_errors_total、model_request_total）、Histogram（如time_to_first_token_seconds、model_request_duration_seconds）与 Gauge（如workers_total、banned_ips_total、Token Router 控制面一族），并明确哪些属于_SUPERVISOR_ONLY_METRICS（Supervisor 启动时从 Worker Registry 移除）。
2. 指标快照逻辑：Supervisor 定期将集群心跳数据（Worker 资源、Agent 连接状态、Assignment、Runtime、Tokenizer 资产绑定、逻辑 Router 汇总等）快照为 one-hot 指标，并用_sync_gauge_series同步/清理标签集合，防止陈旧标签序列干扰告警计算。
3. 测试佐证：xinference/core/tests/test_monitoring_v2.py 验证了 Token Router 监控 V2.1 的指标导出行为（有效就绪与可控性分离、陈旧序列清理）；监控资产的完整性测试（xinference/core/tests/test_monitoring_assets.py）与监控配置存储测试（xinference/core/tests/test_monitor_config_store.py）则保障了告警规则与监控配置在发布过程中的一致性。

此外，monitor/alert 目录中还有面向其余语言的规则文件（rules.yml、rules-ja.yml、rules-ko.yml）供多语言团队直接选用；仓库内另有与告警配套的 Grafana 监控大盘（见 monitor/dashboard，覆盖 GPU 资源、主机资源、LLM SLO、模型加载、Overview 等主题），可与本告警规则组合成"指标可视化 + 规则告警"的完整可观测性闭环。

七、部署建议与常见问题

• node_exporter 前置依赖：DiskSpaceLow依赖节点级node_filesystem_*指标，务必在所有集群节点部署 node_exporter 并纳入 Prometheus 抓取，否则该规则永远处于 NoData 状态。
• 指标抓取范围：xinference:前缀指标由 Supervisor 侧暴露（其中大部分属于 Supervisor-only），请确认 Prometheus 的抓取目标覆盖了 Supervisor 端点；Runtime 侧自身的请求计数器则在各 Runtime 的/metrics端点，若需更细粒度的逐 Runtime 视图，可将它们一并纳入抓取。
• 阈值调优：规则中的阈值（90%、5%、10 秒、10%、0.9、300 秒、60 秒等）为通用默认值，生产环境应根据实际模型规模、GPU 型号与 SLO 目标调整；例如大模型集群可能把 TTFTHigh 阈值放宽，而对延迟敏感的业务则应收紧RequestLatencyHigh。
• 抑制规则合并位置：alertmanager-inhibition.yml中的inhibit_rules必须合并到生产alertmanager.yml顶层，而不是加载进 Prometheusrule_files，否则配置无效。
• 多语言选择：中文团队直接使用 rules-zh-CN.yml，其他语言可选用对应的rules-ja.yml、rules-ko.yml或英文版rules.yml，表达式与阈值完全一致，切换语言不会改变告警行为。

按照上述步骤完成 Prometheus 规则加载与 Alertmanager 路由/抑制配置后，Xinference 集群即可获得从 GPU/内存/磁盘等基础设施水位，到模型请求错误率、TTFT、P95 延迟等服务质量，再到 Token Router 控制面与数据面可用性的完整告警覆盖。

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference