面向 RL 的 vLLM-Ascend¶

概述¶

vLLM 通常用作强化学习（RL）和后训练工作流中的 rollout 引擎。训练框架使用 vLLM-Ascend 生成样本，根据这些样本更新策略，然后将新权重同步回 rollout 引擎。有关与 RL 框架的集成，请参阅上游 vLLM 的 RLHF 指南。

RL 工作负载通常需要以下能力：

• 在同置训练器运行时释放 NPU 内存；
• 无需重启 rollout 引擎即可更新模型权重；
• 在权重更新期间暂停生成；
• 返回 token 对数概率，以及（对于受支持的 MoE 工作流）专家路由决策；
• 接受和返回 token ID，而无需冗余分词；以及
• 在不同批次组成下产生可复现的结果。

本页介绍这些功能如何在 Ascend 上协同工作。请参阅所链接的功能指南和示例以获取完整的配置细节。

启用 RL 模式¶

vLLM-Ascend 在 additional_config.rl_config 下提供统一的 RL 配置。对于同 NPU 和跨 NPU 部署，请将其 enabled 字段设置为 true：

vllm serve Qwen/Qwen3-0.6B \
    --additional-config '{"rl_config": {"enabled": true}}'

总开关会应用常见的 RL 默认设置：禁用 FRACTAL_NZ，启用开发端点，并从 PYTORCH_NPU_ALLOC_CONF 中移除 expandable_segments。可选字段如下：

所有可选字段默认为 false，除非 enabled 为 true，否则将被忽略。有关字段定义、先决条件以及从旧版设置的迁移，请参阅 附加配置。

选择部署模式¶

确切的生命周期取决于框架。特别是，级别 2 休眠会丢弃权重。在加载或传输新权重之前唤醒 weights 分配，然后在更新完成后再唤醒 kv_cache。有关两阶段唤醒序列，请参阅 休眠模式。

引擎生命周期¶

休眠模式¶

休眠模式允许同置的 rollout 引擎在不退出的情况下释放 NPU 内存。级别 1 将模型权重卸载到 CPU 并丢弃 KV 缓存。级别 2 同时丢弃模型权重和 KV 缓存，适用于在推理恢复前加载新权重的情况。

要进行在线控制，请启用开发端点并使用以下命令以启用休眠模式的方式启动服务器：

VLLM_WORKER_MULTIPROC_METHOD=spawn \
vllm serve Qwen/Qwen3-0.6B \
    --enable-sleep-mode \
    --additional-config '{"rl_config": {"enabled": true}}'

休眠级别是一个查询参数；JSON 请求体会被忽略：

# Release memory.
curl -X POST "http://127.0.0.1:8000/sleep?level=1"
curl http://127.0.0.1:8000/is_sleeping

# Restore all tagged allocations.
curl -X POST http://127.0.0.1:8000/wake_up

对于级别 2 休眠，请按照 休眠模式 中记录的顺序唤醒标签：

curl -X POST "http://127.0.0.1:8000/sleep?level=2"
curl -X POST "http://127.0.0.1:8000/wake_up?tags=weights"
# Load or transfer the new weights here.
curl -X POST "http://127.0.0.1:8000/wake_up?tags=kv_cache"

要同时释放 HCCL 进程组和 ACL 图工作空间，请启用额外清理：

VLLM_WORKER_MULTIPROC_METHOD=spawn \
vllm serve Qwen/Qwen3-0.6B \
    --enable-sleep-mode \
    --additional-config '{"rl_config": {"enabled": true, "sleep_mode_extra_cleanup": true}}'

额外清理会减少休眠期间的 NPU 内存使用，但 HCCL 组必须在唤醒期间恢复，ACL 图也必须重新捕获。RL 模式会从 PYTORCH_NPU_ALLOC_CONF 中移除 expandable_segments，因为它与休眠模式内存池不兼容。原先的顶级选项 enable_sleep_mode_extra_cleanup 已被移除。

权重传输¶

vLLM-Ascend 提供了两个 Ascend 专用的权重传输后端：

使用以下命令启动启用 HCCL 的服务器：

vllm serve Qwen/Qwen3-0.6B \
    --weight-transfer-config '{"backend": "hccl"}' \
    --additional-config '{"rl_config": {"enabled": true}}'

对于同 NPU 传输，请使用 ipc 后端。在 Ascend 上，vLLM-Ascend 会将此面向用户的后端名称映射到 NPUIPCWeightTransferEngine：

VLLM_ALLOW_INSECURE_SERIALIZATION=1 \
vllm serve Qwen/Qwen3-0.6B \
    --weight-transfer-config '{"backend": "ipc"}' \
    --additional-config '{"rl_config": {"enabled": true}}'

HTTP NPU IPC 示例需要 VLLM_ALLOW_INSECURE_SERIALIZATION=1，因为它会序列化 IPC 句柄。仅在受信任的环境中启用它。

控制流程如下：

1. 初始化传输引擎；
2. 暂停生成；
3. 开始权重更新；
4. 传输一组或多组权重；
5. 完成权重更新；以及
6. 恢复生成。

该仓库包含两个后端的可运行示例：

• rlhf_http_hccl.py
• rlhf_http_npu_ipc.py
• rlhf_async_new_apis.py

更新权重时必须禁用 FRACTAL_NZ。RL 模式强制设置 weight_nz_mode=0；权重传输启动路径会校验生效的 Ascend 配置。

暂停与恢复生成¶

当 rl_config.enabled=true 时，服务器会暴露 /pause 和 /resume 端点。这些是开发用端点，不得暴露给不受信任的网络。暂停参数通过查询参数传递：

# Drain in-flight requests and clear caches before the update.
curl -X POST \
    "http://127.0.0.1:8000/pause?mode=wait&clear_cache=true"

# Transfer weights here.

curl -X POST http://127.0.0.1:8000/resume

暂停模式如下：

clear_cache 已弃用，并且在 mode=keep 时会被忽略。因此，被保留的请求可能包含使用旧权重生成的 token 和 KV-cache 条目，并在恢复后继续使用新权重。当 rollout 不得跨越权重版本时，请使用 abort 或 wait。

有关 API 生命周期，请参阅上游 Async RL 指南。

引擎返回的训练数据¶

Token 对数概率¶

在 completions 请求中设置 logprobs，并在需要时设置 prompt_logprobs：

curl http://127.0.0.1:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-0.6B",
        "prompt": "Your prompt here",
        "max_tokens": 32,
        "temperature": 1.0,
        "logprobs": 1,
        "prompt_logprobs": 1
    }'

prompt_logprobs 不适用于流式 completions 请求。有关对应的引擎级选项，请参阅上游采样参数文档。

Router Replay (R3)¶

对于受支持的 MoE 工作流，请启用 routed-expert 捕获来启动服务器：

vllm serve Qwen/Qwen3-30B-A3B --enable-return-routed-experts

对于非流式 completion 响应，choices[].routed_experts 是一个 base64 编码的 NumPy 数组，而不是内联张量。解码后，其形状为 (num_tokens - 1, num_layers, num_experts_per_tok)。最终采样得到的 token 没有路由记录，因为它尚未经过模型。当捕获被禁用或请求在前向传播之前被中止时，该字段为 null。

仅当训练器消费并重放捕获的专家选择时才启用此选项。有关解码和重放逻辑，请参阅上游 routed experts 示例。

确定性 Rollout¶

批次不变性可减少由批次形状或请求顺序变化引起的输出差异。在 Atlas A2 和 A3 上，使用 COMPILE_CUSTOM_KERNELS=1 构建 vLLM-Ascend，然后通过统一的 RL 配置启用批次不变性：

vllm serve Qwen/Qwen3-8B \
    --additional-config '{"rl_config": {"enabled": true, "enable_batch_invariant": true}}' \
    --compilation-config '{"cudagraph_mode": "PIECEWISE"}'

RL 模式会禁用 FRACTAL_NZ。当启用批次不变性时，worker 初始化还会设置 HCCL_DETERMINISTIC=strict 和 LCCL_DETERMINISTIC=1。有关支持的硬件、模型和限制，请参阅批次不变性。

Token 输入，Token 输出¶

实验性的 tokens-only 端点接受已预分词的 prompt，并返回生成的 token ID。使用 --tokens-only 启动常规 serve 命令：

vllm serve Qwen/Qwen3-0.6B --tokens-only

将请求发送到 /inference/v1/generate：

curl http://127.0.0.1:8000/inference/v1/generate \
    -H "Content-Type: application/json" \
    -d '{
        "request_id": "rollout-001",
        "token_ids": [151644, 8948, 198],
        "sampling_params": {
            "temperature": 1.0,
            "max_tokens": 32,
            "logprobs": 1
        }
    }'

非流式响应的结构如下：

{
  "request_id": "rollout-001",
  "model": "Qwen/Qwen3-0.6B",
  "choices": [
    {
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop",
      "token_ids": [123, 456],
      "routed_experts": null
    }
  ],
  "prompt_logprobs": null,
  "usage": null
}

logprob 和 usage 的具体值取决于采样参数和服务器配置。该 API 面向分离式（disaggregated）服务场景，可能会发生变化；请关注上游 Tokens API RFC 以了解其状态。

用于 Agentic RL 的工具调用¶

Agentic rollout 环境可以使用标准的 OpenAI 兼容工具调用 API。对于具有受支持解析器的模型：

vllm serve Qwen/Qwen3-8B \
    --enable-auto-tool-choice \
    --tool-call-parser hermes

环境在 /v1/chat/completions 中提供 tools，执行返回的工具调用，将工具结果追加到对话中，并提交下一轮。有关请求示例以及受支持的解析器/模型组合，请参阅上游工具调用。

数据并行请求路由¶

vLLM 的 OpenAI 服务层会识别 X-data-parallel-rank 请求头，并将其整数值传递给调度器。支持 DP 的外部路由器可以使用此请求头来指定目标 rank：

curl http://127.0.0.1:8000/v1/completions \
    -H "Content-Type: application/json" \
    -H "X-data-parallel-rank: 2" \
    -d '{
        "model": "Qwen/Qwen3-0.6B",
        "prompt": "Your prompt here",
        "max_tokens": 32
    }'

vLLM-Ascend 不提供 vllm serve router 命令或 --dp-routing-config 选项。请分别配置 vLLM 数据并行部署和外部路由器。有关受支持的负载均衡模式，请参阅上游数据并行部署。

配置检查清单¶

有关 Ascend 特定选项的定义，请参阅 附加配置 和 环境变量。