操作指南
为推理模板声明引擎指标
本文目录
适用场景:你写了一个推理模板(尤其是 engine: callable 的自研或第三方引擎),部署后部署抽屉、实例页和服务监控页的推理面板没有数据,或者想让引擎自己的 TTFT、KV 使用率、投机接受率进入平台面板。
完成后,模板的指标映射通过校验,并能在一次实际推理后从平台面板或指标浏览器看到对应数据。
前置条件:引擎提供 Prometheus 文本或 JSON 指标端点,节点上的 agent 能通过实例端口访问它;你能登录该节点观察原始响应,并能导入或编辑推理模板(见推理目录 model.yaml 语法参考)。
先判断要不要声明
先对照下表,判断是否需要修改模板。agent 每 10 秒从运行中实例的端点采集指标,并按映射转换为平台指标。没有声明 api.metrics 时:
| 模板引擎 | 默认行为 | 需要声明吗 |
|---|---|---|
vllm / sglang | 用平台内置的 vLLM / SGLang 映射 | 不需要;要追加或改几条时写 map 即可 |
callable,引擎导出 vllm: 或 sglang: 开头的指标(vLLM / SGLang 的改版、包了一层 SGLang 的适配器) | 抓 /metrics,按抓到的前缀自动套用 vLLM 或 SGLang 的映射 | 一般不需要 |
callable,引擎用自己的名字(如 TensorFold 的 tensorfold:) | 抓 /metrics,但没有任何名字能对上,不出引擎指标 | 需要 |
引擎的指标端点返回 JSON(如 Strata 0.1.38 的 /metrics) | 按 Prometheus 文本解析不出任何一行 | 需要声明 format: json,见下文 |
| 引擎没有任何指标端点 | 抓取失败被跳过 | 声明也没用;延迟、token 等由网关统计 |
callable 模板没有声明 api.metrics 时,导入(以及 POST /api/v1/inference-templates/evaluate 预检)会返回警告 CATALOG_CALLABLE_METRICS_UNDECLARED,界面在导入或保存后列出它;警告不阻止导入,引擎确实没有指标端点或用的就是 vLLM / SGLang 的指标名时可以忽略(见导入前检查与警告)。
1. 看引擎的原始指标
在实例所在的节点上直接请求实例端口(端口见实例详情;agent 抓取用的就是这个地址):
curl --silent --show-error --include http://127.0.0.1:<实例端口>/metrics如果引擎的端点不在 /metrics,先替换为它的实际路径。确认 HTTP 状态为成功,再查看响应头和正文;不要先过滤 # 行,后面需要用 # TYPE 判断指标类型。
runveil 节点也一样在宿主机上请求;容器里有 curl 时也可以 gpuworks-agent runveil exec <容器名前缀> curl --silent --show-error --include http://127.0.0.1:<实例端口>/metrics(见 CLI 参考)。
看一下响应的 Content-Type:application/json 的是 JSON 端点,按下文 JSON 端点 写映射。Prometheus 文本的,对着输出确认三件事:族名(tensorfold:requests_running)、类型(# TYPE 行;直方图会有 _bucket / _sum / _count 三组行)、标签(同一族是否按 tier、state 等标签分成多行)。
2. 写映射
在 spec 的 api 下加 metrics,键是引擎指标,值是平台指标的短名:
api:
operations:
- type: openai.chat
metrics:
endpoint: /metrics # 可选,默认 /metrics
map:
'tensorfold:requests_running': requests_running
'tensorfold:time_to_first_token_seconds': ttft_seconds
'engine:kv_used_percent': {to: gpu_cache_usage_percent, scale: 0.01}规则:
- 目标写短名(
ttft_seconds),不写存储名gpuworks_infer_ttft_seconds;短名必须在词表里。 - 直方图用族名映射:写
tensorfold:time_to_first_token_seconds,不写..._bucket;agent 会把_bucket、_sum、_count一起转过去。直方图不能带标签选择器,不能换算;也不要再单独映射同一族的_count等行。 - 按标签挑一行:键可以带选择器,例如
'vllm:kv_offload_tiering_chunk_hits_total{tier="1:fs"}': kv_disk_hits_total,只取标签匹配的行;选择器内的标签值必须加双引号。 - 其他标签不保留:存下来的序列只带平台标签(实例、部署、引擎、节点)。计数器族有多行(例如按
model_name分开)时相加;gauge 族有多行时只取第一行,所以按状态等标签分行的 gauge 要用选择器挑出你要的那一行。 - 换算:长写法
{to: <短名>, scale: <系数>},对计数器和 gauge 生效,例如 0~100 的百分比转 0~1 的比例写scale: 0.01、以千 token 计的计数转成 token 写scale: 1000。 - 继承:
inherit: vllm或inherit: sglang先套用该引擎的整套内置映射,再应用map;同一个键以map为准(模板优先)。vllm/sglang引擎的模板不写inherit也会继承自身的映射。 - 写了
map或inherit之后,callable 的自动识别就不再进行。
只报 KV 池容量和空闲量、不报使用率的引擎,映射到 kv_capacity_tokens 和 kv_free_tokens 即可,KV 使用率由平台派生(见词表的派生指标)。
3. 导入并修正校验错误
导入 YAML、上传目录包或在模板编辑器里保存时,api.metrics 和其余字段一起校验,有错整份拒绝。模板编辑器里输入目标名时有补全。
| 错误码 | 原因 |
|---|---|
CATALOG_METRICS_ENDPOINT_INVALID | endpoint 不是以 / 开头的路径 |
CATALOG_METRICS_INHERIT_UNKNOWN | inherit 不是 vllm 或 sglang |
CATALOG_METRICS_SOURCE_INVALID | 键不是合法的指标族名,或选择器写法不对(值要加双引号) |
CATALOG_METRICS_UNKNOWN_METRIC | 目标短名不在词表里(拼错,或写成了 gpuworks_infer_ 开头的存储名) |
CATALOG_METRICS_HISTOGRAM_SELECTOR | 直方图目标的键带了标签选择器 |
CATALOG_METRICS_HISTOGRAM_SCALE | 直方图目标写了换算 |
CATALOG_METRICS_NEGATIVE_SCALE | 换算系数为负 |
CATALOG_METRICS_SHADOWED_HISTOGRAM | 映射了某个已映射直方图族的 _bucket / _sum / _count 行 |
CATALOG_METRICS_DUPLICATE_SOURCE | 同一个键(去掉首尾空白后)写了两次 |
CATALOG_METRICS_FORMAT_INVALID | format 不是 prometheus 或 json |
CATALOG_METRICS_JSON_INHERIT | format: json 时写了 inherit |
CATALOG_METRICS_JSON_PATH_INVALID | format: json 时键不是用点连接的键路径 |
CATALOG_METRICS_JSON_HISTOGRAM | format: json 时映射到了直方图(JSON 端点只能填计数器和 gauge) |
CATALOG_METRICS_JSON_COMPARE_COUNTER | format: json 时把比较式(路径!=词)映射到了计数器 |
4. 确认生效
- 保存模板后,用引用该档位的部署发起一次实际推理,确保要观察的指标产生样本。
- 等待下一轮采集,在部署抽屉或服务监控页查看推理面板;也可在指标浏览器查询自己映射的指标,例如
gpuworks_infer_requests_running{deployment="<部署 ID>"}。短请求可能在两次采集之间结束,运行中请求数仍为 0;可同时查看已映射的 token 或完成请求计数是否增长。 - 没有样本时,按文末排障表对照原始端点、路径和映射名;不要仅以模板保存成功判断采集生效。
新部署直接使用当前映射。已运行的部署不用重启或重新部署:保存模板后映射会推给引用该档位的实例, agent 收到后在下一轮采集使用;离线节点重连后才收到。server 升级带来的内置模板映射变化同样如此。
旧版本 agent 只认简单映射:带换算的条目、派生的 KV 使用率和 callable 的自动识别要等节点 agent 升级后才生效。
示例
以下片段都放在模板的 api 下;保留已有的 api.operations 等配置,不要把 metrics 放到模板顶层。
TensorFold(内置 GLM-5.3-Flash TensorFold 模板,名字取自 TensorFold 0.6.0 的真实 /metrics):
metrics:
map:
'tensorfold:requests_running': requests_running
'tensorfold:requests_waiting': requests_waiting
'tensorfold_health:requests_total': requests_success_total
'tensorfold:prompt_tokens_total': prompt_tokens_total
'tensorfold_health:completion_tokens_total': generation_tokens_total
'tensorfold_health:cached_tokens_total': prompt_tokens_cache_hit_total
'tensorfold:mtp_drafted_total': spec_draft_tokens_total
'tensorfold:mtp_accepted_total': spec_accepted_tokens_total
'tensorfold:time_to_first_token_seconds': ttft_seconds
'tensorfold:request_latency_seconds': e2e_seconds
'tensorfold_health:pool_tokens': kv_capacity_tokens
'tensorfold_health:pool_free_tokens': kv_free_tokens包了一层 SGLang、但改了指标前缀的适配器:继承 SGLang 的映射,再把改名的几条补上。
metrics:
inherit: sglang
map:
'adapter:num_running_reqs': requests_running
'adapter:num_queue_reqs': requests_waiting指标端点不在 /metrics、KV 使用率按百分比报告的自研引擎:
metrics:
endpoint: /stats/prometheus
map:
'myengine:active_requests': requests_running
'myengine:pending_requests': requests_waiting
'myengine:output_tokens_total': generation_tokens_total
'myengine:kv_used_percent': {to: gpu_cache_usage_percent, scale: 0.01}JSON 端点
有的引擎把统计放在一个 JSON 文档里返回,而不是 Prometheus 文本,例如 Strata 0.1.38 的 /metrics:
{"live": {"state": "generating", "queued": 0, "prompt_tokens": 50, "generated": 1971},
"totals": {"requests": 13, "prompt_tokens": 2548, "output_tokens": 3356, "drafts_offered": 2645, "drafts_accepted": 1578}}在模板的 api.metrics 下声明 format: json,map 的键写成用点连接的键路径。以下仍是放在 api 下的片段:
metrics:
format: json
map:
'live.state!=idle': requests_running
'live.queued': requests_waiting
'totals.requests': requests_success_total
'totals.prompt_tokens': prompt_tokens_total
'live.prompt_tokens': prompt_tokens_total
'totals.output_tokens': generation_tokens_total
'live.generated': generation_tokens_total
'totals.drafts_offered': spec_draft_tokens_total
'totals.drafts_accepted': spec_accepted_tokens_total- 路径上的值是数字才采集,布尔值记 1/0;
null、缺失的路径不出该指标。 - 字符串要写成比较:
路径==词或路径!=词,成立记 1、不成立记 0(live.state!=idle就是"正在处理的请求数")。比较只能映射到 gauge;被比较的值不是字符串时不出该指标。 - 只能映射计数器和 gauge:JSON 文档里没有直方图,TTFT、端到端延迟这类直方图指标由网关统计。
- 不能写
inherit,也不会套用引擎内置映射。长写法{to, scale}照常可用;两个路径映射到同一个指标时相加。 - 注意计数的口径。Strata 的
totals只在请求结束时累加,单映射它,生成吞吐会在长回复期间不动、结束时一次性冒出来。live描述正在处理的那个请求,结束时它已生成的量正好并入totals,所以把totals.output_tokens和live.generated映射到同一个计数器相加,吞吐就随生成过程连续增长。 - 这种相加的计数器在请求被取消时会回落(
live清空了,totals没加)。平台会把计数器的下降当成引擎重启,把整段读数算成一次增长,所以 agent 对 JSON 端点的计数器做了保持:回落后仍不低于上次读数一半的,保持上次读数,直到计数器重新超过它;跌到一半以下的才当成引擎重启放行。
排障
| 现象 | 检查 |
|---|---|
| 面板一直没有引擎数据 | 第 1 步的 curl 是否有输出;endpoint 是否与引擎实际路径一致;键是否与原始输出逐字相同(含前缀与冒号) |
| 只有部分指标有数据 | 没数据的那几条在原始输出里是否存在;带标签的族是否需要选择器 |
| 数值差了一个固定倍数(如 100 倍) | 引擎单位与词表不同,补上 scale |
| gauge 数值不对 | 同一族有多行,只取了第一行;用选择器挑出要的那一行 |
| 吞吐图平时为 0、请求结束时出尖峰 | 映射的计数只在请求结束时累计(看 # HELP 是否写着 finished requests);改映射包含在途请求的计数,例如 TensorFold 用 tensorfold_health:completion_tokens_total 而不是 tensorfold:generation_tokens_total |
这篇文档有帮助吗?