[Bug]: Scale-out `/render` endpoints and `/inference/v1/generate` ignore the `X-Vllm-Priority` header

快速结论：在 vLLM scale-out 分离部署中，若你在 /render 端点或 /inference/v1/generate 上通过请求头 X-Vllm-Priority 传递优先级，该请求头会被静默忽略，服务端不会报错。优先级顺序错乱时，优先确认实际上是在请求体 priority 字段还是请求头中设置的，并检查该路由的代码路径是否读取了请求头。

适用环境：Issue 在 vLLM 提交 d46cb724ddaeb1146da9c9b882bf7679e049890b 上实测确认；使用 vLLM 的 scale-out 服务模式（vllm launch render 加 vllm serve –enable-scale-out），调度策略为 –scheduling-policy priority，模型为 Qwen/Qwen3-0.6B。render 服务在 CPU 上运行，engine 使用单张 GPU。Issue 未提供具体 Python、CUDA、PyTorch 版本，这里不做补充。

最快修复方案：暂无确认的一步修复方案（Issue 中只给出了修复方向，没有合并的补丁）。针对 /inference/v1/generate 路由，可优先尝试把 generate 处理函数中的 priority=request.priority 改为 priority=self._get_priority(request, raw_request)，前提是该函数已经持有 raw_request（Issue 中定位在 serving.py:422 附近）。

注意事项：上述一行修改只是 Issue 讨论中提出的建议，尚未验证为已合入方案。/render 系列端点属于设计层面的问题：ServingRender 继承的是 BaseServing，无法直接使用 _get_priority；并且 /v1/responses/render 的处理函数当前根本不接收 raw_request，需要先修改函数签名。修改前请确认 scale-out router 在转发时到底是在请求体中还是请求头中设置优先级，这会决定 /render 是否需要改动。

问题场景

用户在 vLLM scale-out 分离部署下运行两个服务：一个 render 服务（CPU，端口 18101）负责 /v1/chat/completions/render、/v1/completions/render、/v1/responses/render；一个推理引擎（GPU，端口 18219）通过 –enable-scale-out 开启 /inference/v1/generate，并设置 –scheduling-policy priority、–max-num-seqs 1。用户期望通过请求头 X-Vllm-Priority 控制请求优先级，就像耦合部署下的 /v1/completions 那样（文档说明该请求头会覆盖请求体中的值）。实际测试时，/render 端点返回的 GenerateRequest 中 priority 只取请求体的值，完全不看请求头；/inference/v1/generate 调度时也只使用请求体的 priority。测试脚本用 /render 分别以“无优先级、只带请求头 -10、只带请求体 -10”三种方式请求，并观察并发排队请求（A 阻塞、B 优先级 0、C 优先级 -10）的完成顺序，发现 C 只有在请求体优先级生效时才会先于 B 完成。

报错原文

[Bug]: Scale-out `/render` endpoints and `/inference/v1/generate` ignore the `X-Vllm-Priority` header

/v1/chat/completions/render, /v1/completions/render and /v1/responses/render return a `GenerateRequest` with the body `priority` and ignore `X-Vllm-Priority`, and /inference/v1/generate schedules at the body priority. A router that sets priority by header gets priority 0 on render and the body priority on generate, with no error.

原因分析

Issue 讨论把问题拆成两类，二者并不是同一个缺陷：

/inference/v1/generate：读取函数已继承，但调用时没有使用。ServingTokens 继承 GenerateBaseServing，_get_priority、_get_data_parallel_rank、_get_session_id_from_headers 这几个方法都已存在于 self 上。generate 处理函数在相邻的几行中调用了后两个方法，也拿到了 raw_request，但 priority 仍直接使用 request.priority，这是可能的原因中改动最小的一处。
四个 /render 路由：读取函数不可达，且其中一个路由连请求对象都拿不到。ServingRender 继承 BaseServing，而不是 GenerateBaseServing，_get_priority 不在其方法解析顺序（MRO）中，所以多处代码直接使用请求体的 priority。三个处理函数虽然收到了 raw_request，但只用于 _base_request_id；/v1/responses/render 的处理函数 render_responses_request 只接收 request 一个参数，必须修改函数签名才能读取任何请求头。
文档约定不覆盖 /render。openai_compatible_server.md 中关于 X-Vllm-Priority 的说明针对 Completions、Chat Completions、Responses 这些耦合 API 路由，这些路由目前确实调用了 _get_priority；而 /render 路由的文档在 renderer.md 中，没有提到优先级。因此 Issue 讨论认为 /render 的问题更适合理解为“render 端点是否应该接受这个请求头”，而不是单纯的“请求头被忽略”。

环境排查

确认使用的 vLLM 提交版本：Issue 的实测基线为 d46cb724ddaeb1146da9c9b882bf7679e049890b。
确认服务启动参数：engine 侧必须启用 –enable-scale-out；必须设置 –scheduling-policy priority，否则调度器为 FCFS，优先级本身就不起作用。
确认请求方式：请求头 X-Vllm-Priority 与请求体 priority 字段分别测试，区分两者不同的取值结果。
确认路由：/render 返回的 GenerateRequest 与 /inference/v1/generate 的实际调度路径是两个不同代码路径，需要分别验证。
Issue 未提供 Python、CUDA、PyTorch、依赖版本信息，这些环境项无证据可核对。

解决步骤

先用最小复现确认现象：render 服务与 engine 使用同一份代码检出，分别发起只带请求头、只带请求体、两者都不带的 /render 请求，对比返回 GenerateRequest 的 priority 值。
再用排队顺序验证调度：在 engine 上启动一个长请求 A 占住唯一的序列槽，随后入队 B（优先级 0）和 C（优先级 -10，分别通过请求头和请求体设置），观察 C 是否先于 B 完成。
对 /inference/v1/generate，可优先尝试在 generate 处理函数中把 priority=request.priority 改为 priority=self._get_priority(request, raw_request)，并确认此处 raw_request 可用。
对 /render 路由，先确认 scale-out router 在转发时如何设置优先级：如果 router 在转发调用上设置请求头，则需要让 ServingRender 具备读取该请求头的能力（基类调整），并修改 render_responses_request 的签名以接收 raw_request；如果 router 通过请求体传递，则按 Issue 讨论可考虑在文档中明确优先级只随请求体传递。
若希望长期修复，等待上游合并对应 PR 后再升级，不要在生产环境直接手动修改源码。

验证方法

重复 Issue 中的两组测试：对三个 /render 端点分别以只带请求头、只带请求体的方式请求，确认返回对象中的 priority 与预期一致（如 -10 能覆盖默认值）；再运行排队测试，确认优先级更低的 C（-10）在通过请求头设置时也能先于 B（0）完成。对 /inference/v1/generate，构造同样 A/B/C 排队场景，确认带 X-Vllm-Priority 的请求按优先级调度。