Text Generation Inference（TGI）Prometheus 指标全解析：/metrics端点、指标语义与监控扩缩容实践
【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inference
Text Generation Inference（TGI）在启动后会自动暴露一个 Prometheus 格式的/metrics端点，用于收集服务运行期间的批处理、队列与请求级观测数据。本文以仓库内 Metrics 参考文档 为核心骨架，结合 router 服务端 与 v2/v3 后端 的实际埋点代码，逐一解读每个指标的语义、标签与单位，并给出基于 Prometheus + Grafana 的监控、告警与自动扩缩容落地方案。读完本文，你将能够准确理解 TGI 暴露的每一个tgi_*指标，知道它们从哪里产生、如何采集、如何解读，并据此搭建起可观测、可告警、可扩缩容的 TGI 生产监控体系。
一、指标总览：TGI 暴露了哪些度量
TGI 通过/metricsPrometheus 端点对外暴露多种指标。这些指标可用于：
- 监控 TGI 服务的性能表现；
- 支撑部署的自动扩缩容（autoscale）决策；
- 帮助定位系统瓶颈。
全部指标清单如下（单位列中的Count表示计数，Seconds表示秒）：
| Metric Name | Description | Type | Unit |
|---|---|---|---|
tgi_batch_current_max_tokens | Maximum tokens for the current batch | Gauge | Count |
tgi_batch_current_size | Current batch size | Gauge | Count |
tgi_batch_decode_duration | Time spent decoding a batch per method (prefill or decode) | Histogram | Seconds |
tgi_batch_filter_duration | Time spent filtering batches and sending generated tokens per method (prefill or decode) | Histogram | Seconds |
tgi_batch_forward_duration | Batch forward duration per method (prefill or decode) | Histogram | Seconds |
tgi_batch_inference_count | Inference calls per method (prefill or decode) | Counter | Count |
tgi_batch_inference_duration | Batch inference duration | Histogram | Seconds |
tgi_batch_inference_success | Number of successful inference calls per method (prefill or decode) | Counter | Count |
tgi_batch_next_size | Batch size of the next batch | Histogram | Count |
tgi_queue_size | Current queue size | Gauge | Count |
tgi_request_count | Total number of requests | Counter | Count |
tgi_request_duration | Total time spent processing the request (e2e latency) | Histogram | Seconds |
tgi_request_generated_tokens | Generated tokens per request | Histogram | Count |
tgi_request_inference_duration | Request inference duration | Histogram | Seconds |
tgi_request_input_length | Input token length per request | Histogram | Count |
tgi_request_max_new_tokens | Maximum new tokens per request | Histogram | Count |
tgi_request_mean_time_per_token_duration | Mean time per token per request (inter-token latency) | Histogram | Seconds |
tgi_request_queue_duration | Time spent in the queue per request | Histogram | Seconds |
tgi_request_skipped_tokens | Speculated tokens per request | Histogram | Count |
tgi_request_success | Number of successful requests | Counter | |
tgi_request_validation_duration | Time spent validating the request | Histogram | Seconds |
从指标命名上可以清晰看出三类主题：tgi_batch_*面向服务端批处理引擎，tgi_queue_*面向排队系统，tgi_request_*面向单个请求的端到端生命周期。下一节我们从源码出发，说明这些指标分别在何处产生、如何打点。
二、指标从哪里来：Router 与 Backend 的双层埋点
TGI 的指标埋点分布在两个层面，理解这一点对定位问题至关重要：
- Router 层（请求生命周期）：所有
tgi_request_*指标都在 router/src/server.rs 中打点，覆盖 HTTP 请求从进入、校验、排队、推理到返回的完整链路。 - Backend 层（批处理引擎）：所有
tgi_batch_*指标与队列指标在 backends/v3/src/backend.rs、backends/v2/src/backend.rs 与 backends/v3/src/queue.rs 等后端实现中打点。
在 Router 中，一次成功的请求结束时（以/generate为例），server.rs 会依次记录：
metrics::counter!("tgi_request_success").increment(1); metrics::histogram!("tgi_request_duration").record(total_time.as_secs_f64()); metrics::histogram!("tgi_request_validation_duration").record(validation_time.as_secs_f64()); metrics::histogram!("tgi_request_queue_duration").record(queue_time.as_secs_f64()); metrics::histogram!("tgi_request_inference_duration").record(inference_time.as_secs_f64()); metrics::histogram!("tgi_request_mean_time_per_token_duration").record(time_per_token.as_secs_f64()); metrics::histogram!("tgi_request_generated_tokens").record(response.generated_text.generated_tokens as f64);其中total_time、validation_time、queue_time、inference_time分别对应请求的总耗时、参数校验耗时、排队耗时与模型推理耗时；time_per_token即每个 token 的平均耗时（inter-token latency，ITL）。/generate_stream路径同样在流结束处打点（见 server.rs）。请求进入时还会累加tgi_request_count（见 server.rs），失败时则记录tgi_request_failure计数器（带err标签区分validation、incomplete等原因）。
在 Backend 层，批处理引擎按prefill（预填充）与decode（解码）两种方法分别打点。例如 backends/v3/src/backend.rs 中 prefill 阶段会记录：
metrics::counter!("tgi_batch_inference_count", "method" => "prefill").increment(1); metrics::histogram!("tgi_batch_forward_duration", "method" => "prefill").record(...); metrics::histogram!("tgi_batch_decode_duration", "method" => "prefill").record(...); metrics::histogram!("tgi_batch_filter_duration", "method" => "prefill").record(...); metrics::histogram!("tgi_batch_inference_duration", "method" => "prefill").record(...); metrics::counter!("tgi_batch_inference_success", "method" => "prefill").increment(1);decode 阶段使用相同的指标名、"method" => "decode"标签（见 backends/v3/src/backend.rs），v2 后端结构一致（见 backends/v2/src/backend.rs）。因此查询时可通过method标签分别观察 prefill 与 decode 两个阶段的性能。
为什么文档里写 “per method (prefill or decode)”？因为
tgi_batch_decode_duration、tgi_batch_filter_duration、tgi_batch_forward_duration、tgi_batch_inference_count、tgi_batch_inference_success这五个指标都携带method标签，其取值正是prefill或decode。从源码结构可以推断，这是为了精细区分“一次批处理中，预填充阶段与解码阶段各自的耗时与成功率”。
三、指标分组精读：语义、用途与告警建议
3.1 请求级指标（tgi_request_*）：端到端体验的镜子
| 指标 | 解读要点 |
|---|---|
tgi_request_count | 累计收到的请求总数（Counter）。请求一进入 Router 即累加，可与tgi_request_success对比计算成功率。 |
tgi_request_success | 成功完成的请求数（Counter）。注意该指标在 Router 描述注册中明确为 “Number of successful requests”（server.rs）。 |
tgi_request_duration | 请求端到端总耗时（e2e latency），即用户感知的完整延迟，含校验、排队与推理。 |
tgi_request_validation_duration | 参数校验阶段耗时，帮助判断是否因过重的校验逻辑拖慢请求。 |
tgi_request_queue_duration | 请求在队列中的等待时间。队列等待过长通常是吞吐瓶颈或扩缩容滞后的信号。 |
tgi_request_inference_duration | 实际模型推理阶段耗时，不含排队与校验。 |
tgi_request_mean_time_per_token_duration | 每个 token 的平均生成耗时（inter-token latency），是评估生成流畅度的关键指标，数值越小越好。 |
tgi_request_generated_tokens | 单请求生成的 token 数，可用于统计 token 吞吐量（tokens/s）。 |
tgi_request_input_length | 单请求输入 token 长度。 |
tgi_request_max_new_tokens | 单请求允许生成的最大新 token 数（即请求参数中的max_new_tokens）。 |
tgi_request_skipped_tokens | 投机解码（speculation）场景下被跳过的投机 token 数（文档描述为 “Speculated tokens per request”）。后端在投机验证时记录(n - 1)个被接受跳过的 token（见 backends/v3/src/backend.rs）。 |
监控建议：重点关注tgi_request_duration与tgi_request_mean_time_per_token_duration的 P50/P95/P99 分位数，以及tgi_request_queue_duration的上涨趋势；tgi_request_generated_tokens与tgi_request_input_length适合做用量统计与容量规划。
3.2 批处理级指标（tgi_batch_*）：引擎内部效率的探针
| 指标 | 解读要点 |
|---|---|
tgi_batch_current_size | 当前批次的请求数（Gauge）。批处理引擎在每轮迭代前更新，批处理结束后归零（见 backends/v3/src/backend.rs 与 backends/v3/src/backend.rs）。 |
tgi_batch_current_max_tokens | 当前批次的最大 token 数（Gauge），反映当前批次在 KV Cache 上的占用上限。 |
tgi_batch_next_size | 下一批次的大小（Histogram），用于观察调度器组织的批次规模分布，是判断批处理引擎“吃满”程度的重要依据（记录点在 backends/v3/src/queue.rs）。 |
tgi_batch_inference_count | 推理调用次数（Counter，带method标签）。 |
tgi_batch_inference_success/tgi_batch_inference_failure | 推理成功/失败次数（Counter，带method标签）。失败计数在推理异常分支累加（见 backends/v3/src/backend.rs 与 backends/v3/src/backend.rs）。 |
tgi_batch_forward_duration | 模型前向（forward）计算耗时（Histogram，带method标签）。 |
tgi_batch_decode_duration | 批处理中“解码”环节的总耗时（Histogram，带method标签），即对批内所有请求执行一次生成步骤的时间。 |
tgi_batch_filter_duration | 过滤批次并把已生成 token 发给客户端所花的时间（Histogram，带method标签），即每轮迭代的收尾开销。 |
tgi_batch_inference_duration | 一次完整批推理的总耗时（Histogram）。 |
监控建议：tgi_batch_current_size与tgi_batch_current_max_tokens可观察批处理饱和度；tgi_batch_next_size的分布能反映并发请求是否足以填满批次；tgi_batch_decode_duration与tgi_batch_forward_duration的差距可帮助判断瓶颈在计算还是在其他环节。
3.3 队列指标（tgi_queue_size）：负载水位计
tgi_queue_size（Gauge）表示当前排队中的请求数，是判断服务是否过载、是否该扩容的最直接信号。它在队列状态变更时更新：请求入队时increment，每轮调度后按队列实际条目数set（见 backends/v3/src/queue.rs 与 backends/v3/src/queue.rs）。该指标与tgi_request_queue_duration配合，可以完整刻画排队压力：队列长度上升且排队耗时上升，说明后端处理速度跟不上请求到达速度。
3.4 文档未列出但源码中存在的重要指标
除上表外，从源码中可以确认 TGI 还打点了以下指标（未出现在参考文档表中，但对生产排障很有价值）：
tgi_request_failure：请求失败计数器，带err标签，取值包括validation（校验失败）、incomplete（生成不完整）、dropped（请求被丢弃）、generation（生成阶段错误）等（见 router/src/server.rs 与 backends/v3/src/backend.rs）。tgi_batch_concat/tgi_batch_concat_duration：批次拼接次数与耗时，带reason标签（backpressure、chunking、wait_exceeded），反映动态批处理时批次合并的发生频率（见 backends/v3/src/backend.rs）。tgi_batch_total_tokens：在 Router 的指标注册代码中描述为 “Maximum amount of tokens in total”（见 server.rs），用于统计 token 总量的上限水位。
四、如何采集：/metrics端点与 Prometheus 配置
4.1 端点与端口
Router 在启动时注册了 Prometheus 指标抓取端点/metrics（server.rs），处理器直接渲染全局 recorder 的内容：
async fn metrics(prom_handle: Extension<PrometheusHandle>) -> String { prom_handle.render() }Prometheus 抓取端口由启动参数--prometheus-port控制，默认值为9000（见 launcher/src/main.rs 与 launcher 参考文档）。也就是说，TGI 的 HTTP 服务端口（默认3000）与指标端口（默认9000）相互独立，可以直接通过curl 0.0.0.0:9000/metrics验证指标是否正常输出。该参数同样支持环境变量PROMETHEUS_PORT覆盖，也支持-p短选项。
4.2 在 Prometheus 中配置抓取
在 Prometheus 的prometheus.yml中，将 TGI 实例加入scrape_configs即可：
scrape_configs: - job_name: "tgi" static_configs: - targets: ["<TGI_HOST>:9000"]完整的上手流程（含 Prometheus 安装、TGI 服务端验证、Grafana 数据源与仪表盘导入）可参考仓库内的 监控教程：该教程演示了通过 Grafana 仪表盘消费 Prometheus 数据，可观测的有效指标包括 TGI 实际使用的批次大小统计、prefill/decode 延迟、生成 token 数等。
4.3 开箱即用的 Grafana 仪表盘
仓库的 assets/tgi_grafana.json 提供了一份可直接导入 Grafana 的仪表盘模板，覆盖本节所述核心指标的常见可视化组合。导入方式：在 Grafana 中选择 “Import dashboard”，上传或粘贴该 JSON 文件内容，并选择已配置好的 Prometheus 数据源即可。
五、深入底层：直方图桶（Bucket）是如何定制的
TGI 的直方图桶并非使用 Prometheus 默认配置，而是在 server.rs 中按指标类型做了定制，这对正确解读分位数（如 P99）至关重要：
- 持续时间类指标（所有名称以
duration结尾的指标，通过Matcher::Suffix("duration")匹配）：采用 35 个桶的几何递增序列，从0.0001秒起步、每桶乘以1.5，桶边界最终延伸到约 9 秒量级。这种指数型桶布局保证从亚毫秒级到秒级都有足够的分辨率，适配 LLM 推理“token 级耗时小、整请求耗时大”的动态范围。 tgi_request_input_length：按max_input_tokens / 100等间距生成 100 个桶，覆盖 0 到最大输入长度。tgi_request_generated_tokens与tgi_request_max_new_tokens：按max_total_tokens / 100等间距生成 100 个桶。tgi_batch_next_size：从 1 到 1024 每个整数一个桶，精确刻画批次规模的分布。
了解桶边界后，在计算分位数时就不会因桶过粗或过细而产生误读。同时也可以看到，tgi_request_skipped_tokens的专用桶配置在当前源码中被注释掉（server.rs），从源码结构看该指标目前使用默认桶，这也解释了为何文档表格中它的描述没有进一步细化。
六、指标注册与描述：从describe_*看官方语义
Router 启动时会通过metrics::describe_*!系列宏为每个指标注册官方描述（server.rs），这些描述会被 Prometheus 以HELP注释输出。例如：
metrics::describe_counter!("tgi_request_success", "Number of successful requests"); metrics::describe_histogram!("tgi_request_mean_time_per_token_duration", metrics::Unit::Seconds, "Mean time per token per request"); metrics::describe_gauge!("tgi_batch_current_max_tokens", metrics::Unit::Count, "Maximum tokens for the current batch");抓取到的/metrics响应中会带有这些HELP文本，与本文第一节表格中的 Description 列一一对应。如果你在排查时对某个指标含义有疑问，直接查看抓取结果中的# HELP tgi_xxx注释即可，无需翻代码。
七、实战：用指标驱动监控告警与自动扩缩容
结合前三节的语义分析，可以形成一套实用的监控策略：
- 延迟告警：对
tgi_request_duration、tgi_request_mean_time_per_token_duration的 P99 设置阈值告警；若延迟上涨的同时tgi_queue_size同步上涨，可判定为后端过载导致排队，而非单次请求异常。 - 成功率告警：
1 - rate(tgi_request_success[5m]) / rate(tgi_request_count[5m])计算请求失败率；配合tgi_request_failure的err标签区分失败类型，快速定位是校验问题还是生成中断。 - 批处理效率观察：
tgi_batch_next_size与tgi_batch_current_max_tokens的比值可反映批次利用率；若批次长期偏小，说明并发不足以填满吞吐，可考虑提升并发或降低实例数。 - 自动扩缩容：
tgi_queue_size是最适合作为扩缩容依据的水位指标——队列持续堆积时扩容，队列长时间为空时缩容。官方文档明确说明这些指标可用于 autoscale 部署（见 Metrics 参考文档），生产环境可将其接入 Kubernetes HPA 或 KEDA 等基于 Prometheus 的扩缩容机制。
八、延伸阅读
- Metrics 参考文档（本文核心来源）
- 监控教程：Prometheus + Grafana 完整搭建
- Grafana 仪表盘模板
- Router 指标埋点与端点实现
- v3 后端批处理指标实现 / v2 后端批处理指标实现
- 队列指标实现
- Launcher 参数文档（
--prometheus-port）
【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inference
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
