面向强化学习的 vLLM-Ascend¶
概述¶
vLLM 通常用作强化学习（RL）和后训练工作流中的 rollout 引擎。训练框架使用 vLLM-Ascend 生成样本，根据这些样本更新策略，然后将新权重同步回 rollout 引擎。有关与 RL 框架的集成，请参阅上游 vLLM 的 RLHF 指南。
RL 工作负载通常需要以下能力：
- 在共置训练器运行时释放 NPU 内存；
- 在不重启 rollout 引擎的情况下更新模型权重；
- 在权重更新期间暂停生成；
- 返回 token 对数概率，以及对于受支持的 MoE 工作流，返回专家路由决策；
- 接受和返回 token ID，而无需冗余的 tokenization；以及
- 在不同批次组成下产生可重现的结果。
本页介绍这些功能如何在 Ascend 上协同工作。有关完整的配置详细信息，请参阅链接的功能指南和示例。
启用 RL 模式¶
vLLM-Ascend 在 additional_config.rl_config 下提供了统一的 RL 配置。对于同 NPU 和跨 NPU 部署，将其 enabled 字段设置为 true：
主开关应用常见的 RL 默认设置：它禁用 FRACTAL_NZ，启用开发端点，并从 PYTORCH_NPU_ALLOC_CONF 中移除 expandable_segments。可选字段包括：
| 字段 | 何时启用 |
|---|---|
sleep_mode_extra_cleanup |
在同 NPU 部署中，在休眠期间释放 HCCL 进程组和 ACL 图工作空间 |
enable_training_consistency |
选择 FA3 注意力后端以实现训练-推理一致性 |
enable_batch_invariant |
启用批次不变内核和确定性通信设置 |
除非 enabled 为 true，否则所有可选字段默认为 false 并被忽略。有关字段定义、先决条件以及从旧设置迁移的信息，请参阅 附加配置。
选择部署模式¶
| 部署模式 | 内存管理 | 权重传输后端 |
|---|---|---|
| 训练器和 rollout 引擎共享 NPU | 启用休眠模式，以便 rollout 引擎可以释放 NPU 内存 | ipc |
| 训练器和 rollout 引擎使用不同的 NPU | 在更新期间暂停生成；通常不需要休眠模式 | hccl |
确切的生命周期取决于框架。特别是，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 专用的权重传输后端：
| 后端 | 使用场景 | 传输方式 |
|---|---|---|
ipc |
训练器和 rollout 引擎使用同一物理 NPU | NPU IPC 句柄 |
hccl |
训练器和 rollout 引擎使用不同的 NPU | HCCL 集合通信 |
使用以下命令启动启用 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 句柄。仅在受信任的环境中启用它。
控制流程如下：
- 初始化传输引擎；
- 暂停生成；
- 开始权重更新；
- 传输一组或多组权重；
- 完成权重更新；以及
- 恢复生成。
该仓库包含两个后端的可运行示例：
权重更新必须禁用 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
暂停模式包括：
| 模式 | 行为 |
|---|---|
abort |
立即中止进行中的请求；这是默认行为 |
wait |
等待进行中的请求完成后再暂停 |
keep |
冻结请求，使其在 /resume 后继续执行 |
clear_cache 已弃用，且在 mode=keep 模式下会被忽略。因此，被保留的请求可能包含使用旧权重生成的 token 和 KV 缓存条目，并在恢复后使用新权重继续执行。当 rollout 不得跨越权重版本时，请使用 abort 或 wait。
有关 API 生命周期的详细信息，请参阅上游 异步 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 请求。有关相应的引擎级选项，请参阅上游采样参数文档。
路由器重放 (R3)¶
对于受支持的 MoE 工作流，请使用路由专家捕获功能启动服务器：
对于非流式 completions 响应，choices[].routed_experts 是一个 base64 编码的 NumPy 数组，而非内联张量。解码后，其形状为 (num_tokens - 1, num_layers, num_experts_per_tok)。最终采样的 token 没有路由记录，因为它尚未通过模型。当捕获被禁用或请求在前向传播之前被中止时，该字段为 null。
仅在训练器消费并重放捕获的专家选择时启用此选项。有关解码和重放逻辑，请参阅上游路由专家示例。
确定性 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 出¶
实验性的仅 token 端点接受预分词提示，并返回生成的 token ID。使用 --tokens-only 启动常规的 serve 命令：
向 /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 旨在用于分离式服务，可能会发生变化；请关注上游 Tokens API RFC 以了解其状态。
用于智能体 RL 的工具调用¶
智能体 rollout 环境可以使用标准的 OpenAI 兼容工具调用 API。对于具有受支持解析器的模型：
环境在 /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 数据并行部署和外部路由器。有关受支持的负载均衡模式，请参阅上游数据并行部署。
Trace Replay¶
Trace replay forces the engine to emit a predetermined token sequence during
decoding while computing real logprobs from the model's unmodified logit
distribution. It is only supported by model runner V2. When using the normal
vllm serve command with the token-in/token-out endpoint, explicitly enable
model runner V2 and the scale-out endpoints:
VLLM_USE_V2_MODEL_RUNNER=1 \
VLLM_ENABLE_SCALE_OUT_ENDPOINTS=1 \
vllm serve Qwen/Qwen3-8B \
--enable-trace-replay
VLLM_USE_V2_MODEL_RUNNER=1 prevents the server from falling back to model
runner V1, which is incompatible with trace replay.
VLLM_ENABLE_SCALE_OUT_ENDPOINTS=1 registers the
/inference/v1/generate endpoint for a normal serving process.
向 /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": {
"trace_decode_token_ids": [15, 284, 1026, 374],
"logprobs": 1
}
}'
The output tokens will always be [15, 284, 1026, 374]. The logprobs reflect the model's true probability for each forced token under the current inference configuration.
配置清单¶
| 设置 | 使用时机 | 用途 |
|---|---|---|
rl_config.enabled=true |
所有 RL 部署 | 应用 RL 默认设置：禁用 NZ，启用开发端点，并移除 expandable_segments |
--enable-sleep-mode |
训练器和 rollout 引擎共享 NPU | 启用 CaMemAllocator 内存池 |
VLLM_WORKER_MULTIPROC_METHOD=spawn |
睡眠模式 | 使用受支持的 worker 启动方法 |
rl_config.sleep_mode_extra_cleanup=true |
可选，用于睡眠模式 | 释放 HCCL 和 ACL 图资源，但会降低唤醒速度 |
rl_config.enable_training_consistency=true |
训练-推理一致性 | 选择 FA3；需要 flash_attn_npu_v3 包 |
rl_config.enable_batch_invariant=true |
可复现的 rollout | 启用批量不变内核和确定性通信设置 |
--weight-transfer-config '{"backend": "hccl"}' |
跨 NPU 权重传输 | 注册 Ascend HCCL 传输引擎 |
--weight-transfer-config '{"backend": "ipc"}' |
同 NPU 权重传输 | 选择 Ascend NPU IPC 传输引擎 |
--enable-return-routed-experts |
MoE 路由器重放 | 返回编码后的专家路由决策 |
VLLM_USE_V2_MODEL_RUNNER=1 |
Trace replay | Select the required model runner V2 implementation |
VLLM_ENABLE_SCALE_OUT_ENDPOINTS=1 |
Token-in/token-out requests on a normal server | Register /inference/v1/generate |
--enable-trace-replay |
trace replay | Forces decoding to follow a predetermined token sequence |