vLLM Renderer APIs 详解：将推理引擎拆分为无 GPU 前端与 Token-in/Token-out 后端

vLLM Renderer APIs 详解将推理引擎拆分为无 GPU 前端与 Token-in/Token-out 后端【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllmRenderer API 是 vLLM 面向分离式disaggregated在线服务架构设计的一组扩展端点它将请求的预处理阶段prompt tokenization、多模态输入处理等从 GPU 推理引擎中解耦出来放到一个可以完全无 GPU 运行的独立渲染render服务器上执行。读完本文你将掌握vllm launch render渲染服务器的定位与启动方式、VLLM_ENABLE_SCALE_OUT_ENDPOINTS环境变量的精确语义、/v1/completions/render与/v1/chat/completions/render的调用方式以及如何与 derenderer、token-in/token-out 引擎串成一条完整的render → generate → derender生产链路。Renderer API 要解决的问题在常规的vllm serve部署中一个 HTTP 请求的处理是一条龙式的服务端先做 tokenization、多模态输入预处理将 prompt 拼装成引擎输入GPU 引擎产出 token id随后服务端再完成 detokenization、tool call 解析、reasoning 内容解析最终拼装成 OpenAI 兼容响应。这意味着即使只是做一个前端代理也需要拉起来一个完整的、占用 GPU 的推理引擎。vLLM 的 renderer API 正是为了把这条链路拆开而设计核心目的是disaggregate拆分render 阶段预处理并让 API server 变成纯粹的 token-in / token-out。其设计目标在 renderer.md 中明确为三条前端无 GPU 部署tokenization、多模态MM输入处理等预处理以及 detokenization、tool call 解析、reasoning 解析等后处理都可以在没有 GPU 的机器上运行tokenization 拆分支持诸如 llm-d、Dynamo 以及各类自定义前端等使用场景——它们需要复用 vLLM 的预处理逻辑但不想运行完整的推理引擎纯 token-in / token-out 引擎让推理引擎本身成为一个纯粹输入 token、输出 token的服务与请求预处理彻底解耦。换句话说renderer 把OpenAI 兼容的漂亮请求翻译成引擎认识的 token id 序列而它的镜像端点是 derenderer负责把引擎产出的 token id 再翻译回 OpenAI 兼容响应。整体流水线render → generate → derenderrenderer 并不是孤立存在的它处于一条三段的流水线的最前端。整条链路的形态在 derenderer.md 中给出render generate derender request ───────────────▶ token_ids ─────────▶ token_ids ──────────▶ response (chat / (GPU less) (token-in / (GPU less) (OpenAI completion) │ token-out engine) ▲ compatible) └─────────────── request prompt_tokens ──┘render预处理无 GPU接收 OpenAI 风格的 chat/completion 请求输出引擎可直接消费的GenerateRequest含token_ids等字段generatetoken-in/token-out 引擎vLLM 推理引擎只接收 token id、只返回 token id不感知 chat template、工具调用等上层语义derender后处理无 GPU将引擎返回的 token id 重新解析为 OpenAI 兼容响应并复用 vLLM 的工具与 reasoning 解析器保证与标准vllm serve的输出切分content/reasoning/tool_calls完全一致。值得注意的是derender 这一步不仅需要引擎产出的 token id还需要渲染阶段带过来的原始chat_request/completion_request以及prompt_tokens以便工具解析器和 reasoning 解析器拥有所需的上下文详见 derenderer.md 的 Request format 小节。如何在服务中暴露这些端点环境变量VLLM_ENABLE_SCALE_OUT_ENDPOINTS的语义Scale-out 系列端点包括/render、/derender与/inference/v1/generate默认在标准推理服务器上是关闭的。是否注册这些路由由环境变量VLLM_ENABLE_SCALE_OUT_ENDPOINTS决定其合法取值只有0和1其他值会在启动阶段被拒绝校验逻辑见 envs.py。该变量的语义分两种部署形态在标准vllm serve上显式开启此时必须显式设置为1VLLM_ENABLE_SCALE_OUT_ENDPOINTS1 vllm serve model在专用渲染服务器 / token-only 模式下天然开启专用的vllm launch render服务器以及vllm serve --tokens-only模式属于显式 opt-in 的专用模式。当VLLM_ENABLE_SCALE_OUT_ENDPOINTS未设置或设置为1时服务器总是会暴露/render与/derender端点如果显式设置为0则与这些专用模式的语义冲突启动时直接报错拒绝。上述校验逻辑实现在 factories.py 的register_scale_out_api_routers中它会根据启动模式判定dedicated_modevllm launch render或--tokens-only若处于专用模式而环境变量被显式置为0则抛出ValueError提示VLLM_ENABLE_SCALE_OUT_ENDPOINTS0conflicts with ...; unset it or set it to 1。普通模式下未开启时会打印提示日志并跳过路由注册。端点注册后renderer、derenderer 与可选的token-in/token-out 路由会一并挂载到同一个 FastAPI app 上路由实现分散在 vllm/entrypoints/scale_out 目录下的render/、derender/与token_in_token_out/三个子包中。两种启动形态对比部署形态命令暴露的 Scale-out 端点GPU 需求专用渲染服务器vllm launch render model/render、/derender变量未设或为 1无 GPU 前端专用 token-only 引擎VLLM_ENABLE_SCALE_OUT_ENDPOINTS1 vllm serve model --tokens-only/render、/derender、/inference/v1/generate、/abort_requests需要 GPU标准推理服务器VLLM_ENABLE_SCALE_OUT_ENDPOINTS1 vllm serve model上述全部端点不追加/abort_requests需要 GPU关于vllm launch render的更多命令行信息可查阅 docs/cli/README.md其中包括渲染组件的基础用法vllm launch render meta-llama/Llama-3.2-1B-Instruct以及用vllm launch render --helpall查看全部可用参数。/abort_requests端点只在--tokens-only模式下注册见 token_in_token_out/api_router.py用于中止在途请求。API 参考两个核心 Render 端点按 renderer.md 的 API Reference渲染服务器在无 GPU 前端上提供两个 OpenAI 兼容的 render 端点端点用途/v1/completions/renderRender completion 请求/v1/chat/completions/renderRender chat completion 请求路由定义与 OpenAI 兼容服务器的请求模型一一对应可在 render/api_router.py 中看到具体实现render_chat_completion接收标准的ChatCompletionRequestrender_completion接收CompletionRequest最终都委托给ServingRender其初始化所需的OnlineRenderer等对象由 factories.py 的init_render_state注入到 app state。此外从 render/api_router.py 的源码看渲染路由还额外注册了一个/v1/messages/render端点用于 Anthropic messages 格式请求的渲染。每个 render 请求的处理流程见 render/serving.py 的render_chat_request/render_completion_request检查请求是否支持例如 beam search 等与渲染端点不兼容的特性会被拒绝返回错误响应调用OnlineRenderer渲染 prompt输出 engine prompt 组件skip_mm_cacheTrue多模态特征不做缓存以适配无状态前端抽取token_ids若为空则返回错误No token_ids rendered组装返回的GenerateRequest其中包含token_ids以及assistant_tokens_mask等辅助字段若 mask 长度与token_ids不一致服务端会做补齐或截断见 render/serving.py 的防御性处理。动手实践走通一次完整分离式请求结合 derenderer.md 的端到端示例我们可以在本地同时拉起两个服务器走一遍render → generate → derender的完整闭环# 1) 无 GPU 渲染服务器提供 /render 与 /derender vllm launch render meta-llama/Llama-3.2-1B-Instruct --port 8100 # 2) token-in / token-out 推理引擎提供 /inference/v1/generate VLLM_ENABLE_SCALE_OUT_ENDPOINTS1 vllm serve \ meta-llama/Llama-3.2-1B-Instruct --tokens-only --port 8200import httpx MODEL meta-llama/Llama-3.2-1B-Instruct RENDER http://localhost:8100 # vllm launch render ... ENGINE http://localhost:8200 # token-in / token-out engine chat_request { model: MODEL, messages: [{role: user, content: What is 22?}], max_tokens: 32, } with httpx.Client(timeout60.0) as client: # 1. Render: request - token IDs无 GPU 前端 generate_request client.post( f{RENDER}/v1/chat/completions/render, jsonchat_request ).json() prompt_tokens len(generate_request[token_ids]) # 2. Generate: token IDs - token IDstoken-in / token-out 引擎 generate_response client.post( f{ENGINE}/inference/v1/generate, jsongenerate_request ).json() # 3. Derender: token IDs - ChatCompletionResponse无 GPU 前端 response client.post( f{RENDER}/v1/chat/completions/derender, json{ model: MODEL, generate_response: generate_response, prompt_tokens: prompt_tokens, chat_request: chat_request, }, ).json() print(response[choices][0][message][content])这个示例中有几个值得注意的工程细节第 1 步的输出就是第 2 步的输入render 返回的generate_request含token_ids及多模态元数据可以直接 POST 给/inference/v1/generate这正是引擎不感知上层请求语义的体现prompt_tokens需要自己记录渲染输出的token_ids长度即 prompt token 数derender 阶段需要把它回传供 token 用量统计使用chat_request是可选但关键的上下文只有把原始chat_request一并传给 derenderer工具解析器与 reasoning 解析器才能工作最终response[choices][0][message]中content/reasoning/tool_calls的切分才会与标准vllm serve完全一致省略chat_request则只做纯 detokenization。Renderer 与 Derenderer 的分工边界Renderer 与 derenderer 是一对互补端点均由无 GPU 渲染服务器vllm launch render承载业务上经常搭配使用。两者差异如下维度Renderer/renderDerenderer/derender所处阶段流水线最前端预处理流水线最末端后处理输入OpenAI 兼容 chat/completion 请求引擎的GenerateResponseprompt_tokens 原始chat_request输出引擎可消费的GenerateRequesttoken id完整的 OpenAI 兼容响应是否可用 GPU否设计目标即无 GPU 运行否设计目标即无 GPU 运行解析器行为使用 vLLM 的 tokenizer / MM 处理器复用 vLLM 的工具与 reasoning 解析器保证与vllm serve输出一致Derenderer 相关的两个端点分别是/v1/chat/completions/derender处理单个GenerateResponse得到ChatCompletionResponse与/v1/completions/derender处理一组GenerateResponse每个 prompt 一个得到一个CompletionResponse请求体协议定义在 token_in_token_out/protocol.py 中细节可参考 derenderer.md。需要特别说明的边界是derenderer 目前只支持非流式non-streaming。两个 derender 端点期望收到的是包含全部 token id 的完整GenerateResponse然后做一次性解析。流式 derender 需要单独设计端点当前尚未实现处于规划中该能力描述同样见 derenderer.md。不过从 derender/serving.py 源码看内部已经预留了derender_chat_stream_response/derender_completion_stream_response等流式处理方法与客户端携带状态设计说明这是有意识的前向兼容铺垫但实际的路由与协议尚未对外暴露。安全与资源边界由于分离式架构下 derender 请求往往跨服务携带完整的 prompt、生成结果与多模态数据负载可能远大于普通推理请求。从 derender/serving.py 的源码可以看到ServingDerender会通过_validate_derender_bounds在调用任何tokenizer.decode()或解析器之前对超大 payload 做资源边界校验并返回400拒绝即 derenderer 文档中Oversized payloads are rejected with a400before anytokenizer.decode()or parser runs的实现位置。在部署这类端点前还应结合 docs/serving/online_serving/README.md 的 Scale-Out APIs 一节与 docs/usage/security.md 了解整体边界scale-out 端点默认关闭即是一种安全默认值只有确实需要分离式架构时才显式开启。总结Renderer API 是 vLLM 分离式在线服务体系中的入口翻译层它与 derenderer出口翻译层、token-in/token-out 引擎/inference/v1/generate共同构成了一条无 GPU 前端 纯 token 引擎的生产级流水线。掌握VLLM_ENABLE_SCALE_OUT_ENDPOINTS的开关语义、vllm launch render与vllm serve --tokens-only的分工以及render → generate → derender三段式数据流是使用 vLLM 搭建自定义前端、llm-d / Dynamo 等外部调度器接入或构建分离式推理集群的第一步。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考