MAX serve 的 /metrics 端点如何配置 Prometheus 抓取推理延迟指标-酒店常州论坛

MAX serve 的 /metrics 端点如何配置 Prometheus 抓取推理延迟指标

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo

如果你的 MAX 推理服务已经跑起来，需要持续观察首 token 延迟（TTFT）、每 token 解码延迟等指标，就需要把 Prometheus 指向 MAX serve 暴露的/metrics端点。Modular 平台的 MAX 在运行max serve命令或使用 MAX 容器提供服务时，会自带一个返回 Prometheus 文本格式指标的/metrics端点，默认监听8001 端口。本文说明如何验证端点、把 Prometheus 抓取任务配置好，以及哪些指标对应推理延迟。

前提条件

已通过max serve启动模型服务，或通过 MAX 容器（如modular/max-nvidia-full:latest）部署。启动方式可参考 local-to-cloud 部署文档，例如：
```
max serve --model modularai/Llama-3.1-8B-Instruct-GGUF
```
服务端点可用时，/metrics端点随之可用，无需额外开启开关。

先验证端点是否工作

在能访问 MAX serve 的机器上，用curl请求端点：

curl http://localhost:8001/metrics

如果服务正常，会返回全部指标的 Prometheus 文本格式内容。也可以用过滤确认延迟指标存在：

curl -s http://localhost:8001/metrics | grep maxserve_time_to_first_token

返回中出现以maxserve_time_to_first_token开头的序列（如maxserve_time_to_first_token_milliseconds），说明端点和延迟指标都正常，可以进入 Prometheus 配置。

如果 8001 端口连不上，先检查服务是否以max serve方式启动，以及是否修改过指标端口（见下一节）。

指标端口调整（可选）

/metrics端点默认使用 8001 端口。需要改动时，通过环境变量MAX_SERVE_METRICS_ENDPOINT_PORT设置（整数端口号），配置优先级以环境变量文档为准：CLI 参数/代码直接初始化 > 环境变量 >.env文件。

一旦修改了该端口，Prometheus 的targets必须同步更新，否则抓取会失败。注意区分：MAX_SERVE_PORT（默认 8000）是推理 API 服务端口，MAX_SERVE_METRICS_ENDPOINT_PORT（默认 8001）才是指标端口，两者互不影响。

在 Prometheus 中添加抓取任务

在 Prometheus 配置中加入一个 job，把目标指向 MAX serve 的指标端口：

scrape_configs: - job_name: max-serve scrape_interval: 15s static_configs: - targets: ["localhost:8001"]

文档给出的是localhost:8001的直接示例。实际部署中，把targets换成 MAX serve 所在主机可被 Prometheus 访问的地址，端口与MAX_SERVE_METRICS_ENDPOINT_PORT保持一致（文档未展开其他部署拓扑下的具体写法）。

保存配置后按 Prometheus 常规流程重载配置，确认max-serve这个 job 出现在目标列表中且抓取成功。

抓取后关注哪些推理延迟指标

Metrics 参考把请求延迟类指标分为端到端与分阶段两类，均为 Histogram 类型，单位毫秒：

指标	含义
`maxserve_request_time_milliseconds`	处理一个请求的总时间（总推理时间）
`maxserve_time_to_first_token_milliseconds`	TTFT，从服务端收到请求算起，包含解析、校验、媒体解析、分词、排队和 prefill
`maxserve_time_per_output_token_milliseconds`	TPOT，平均每个生成 token 的解码延迟，按`decode_time / (num_generated_tokens - 1)`计算，每请求输出一次，不含首 token 与 prefill
`maxserve_input_processing_time_milliseconds`	输入处理时间（IPT）
`maxserve_output_processing_time_milliseconds`	输出生成时间（OGT）
`maxserve_itl_milliseconds`	token 间延迟（inter-token latency）

抓到的都是原始序列，Prometheus 中通常需要基于这些 Histogram 做分位数聚合（如histogram_quantile）才能得到 p99 延迟，这一步属于你自己的查询写法，文档未提供具体 PromQL。

与延迟相关的辅助指标还有：

maxserve_num_requests_awaiting_admission（UpDownCounter）：API 服务器已收到但尚未交给模型 worker 的请求数，持续偏高说明积压在 API 服务器而非调度器；
maxserve_batch_execution_time_milliseconds、maxserve_batch_creation_time_milliseconds：批执行与批构建耗时分布；
maxserve_response_queue_time_milliseconds：模型 worker 响应在输出队列中等待被流式层消费的耗时。

排查与限制

抓取失败：确认端口与MAX_SERVE_METRICS_ENDPOINT_PORT一致；localhost:8001仅在 Prometheus 与 MAX serve 同机时成立，跨机部署需改用对应主机地址。
指标缺失：数据并行指标（maxserve_dp_*）仅在data_parallel_degree > 1时记录；分离式推理指标（maxserve_di_*）仅在 disaggregated inference 部署中记录。如果你没有启用对应部署形态，看不到这些序列是正常的。
遥测与 /metrics 端点相互独立：MAX 默认收集匿名使用遥测，可用MAX_SERVE_DISABLE_TELEMETRY=1关闭；MAX_SERVE_OTLP_METRICS_ENDPOINT可把遥测发到自己的 OTLP 端点。这些配置影响的是 OpenTelemetry 遥测链路，不影响 Prometheus 对/metrics的抓取。
容器场景下，容器文档确认 MAX 暴露的是 Prometheus 兼容的/metrics端点，指标清单与遥测配置均以上面的 Metrics 参考为准。

参考

指标端点用法与完整指标清单：docs/max/serve/metrics.mdx
环境变量默认值与优先级：docs/max/environment-variables.mdx
容器部署的 Metrics 说明：docs/max/container.mdx

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析