vLLM 推理服务的 Speculative Decoding

简介

Speculative Decoding 允许 vLLM 服务器在每个解码步骤中提出多个令牌,并通过对目标模型执行一次前向传递来验证这些令牌,从而降低交互式工作负载的每令牌延迟,同时不会改变输出分布。

本页面重点介绍如何为运行在 Alauda AI Platform 上的 InferenceService 启用、配置、验证和回滚 Speculative Decoding。有关该上游技术本身以及 vLLM 支持的方法完整列表,请参阅 vLLM Speculative Decoding 文档。

WARNING

Speculative Decoding 涉及对运行时版本敏感的标志。确切的 --speculative-config JSON 键、受支持的 method 值,以及下文引用的指标名称,取决于运行时镜像中的 vLLM 版本。请将此处的所有代码片段视为起点,并根据你提供的 vLLM 版本进行确认。

决策前须知

当每个请求的解码循环占据端到端延迟的主要部分,且提出的令牌具有足够高的接受率,能够摊销提出令牌的开销时,Speculative Decoding 会带来帮助。

它通常适用于:

  • 具有相对可预测后续内容的交互式聊天 / 智能体循环。
  • 摘要、RAG 答案和代码补全等输出内容与提示词存在重叠的场景。

在以下情况下,它可能带来负面影响或没有明显效果:

  • 高温度采样,此时接受率会大幅下降。
  • 高 QPS / 批处理已饱和的服务,此时解码容量不再空闲。vLLM 团队在 2024 年针对 V0 引擎进行的基准测试报告显示,在高 QPS 下,同一数据集上的性能降低了 1.4×–1.8×。V1 引擎的调度方式有所不同,因此在你的运行时中影响幅度可能不同,但风险方向相同。
  • 目标模型非常小,此时验证步骤本身已经十分廉价。

在将 Speculative Decoding 设为默认配置之前,请先运行具有代表性的工作负载。请参阅验证并衡量影响。

在 Alauda AI Platform 上本指南验证的方法

以下两种方法是本指南涵盖的,并且已在 Alauda AI Platform 上完成端到端验证。vLLM upstream 还支持其他方法(例如,为随模型提供多令牌预测头的模型提供的 MTP、Medusa、MLP Speculator、Suffix、Draft Model),这些方法也可能通过相同的 --speculative-config 标志在 Alauda AI Platform 上使用。它们不在本页面的范围内,因此请参阅 upstream 文档,并在你自己的设置上完成验证,然后再推广到生产环境。

方法你需要提供权衡
N-gram仅目标模型无需额外权重,也无需训练。收益取决于提示词与输出之间的令牌重叠程度。
EAGLE-3目标模型以及匹配的 EAGLE-3 草稿头需要针对确切目标模型训练的草稿头。会额外占用少量 GPU 内存。

注意:

  • vLLM upstream 将 N-gram 描述为“适用于摘要和问答等提示词与答案之间存在显著重叠的用例”。
  • vLLM upstream 将 EAGLE-3 描述为“当前 Speculative Decoding 算法中的 SOTA”(该表述来自最新功能页面的快照;请根据每个版本重新确认)。

不存在适用于所有工作负载的单一最佳方法。以下是用于降低试错成本的保守起点。在推广到生产环境之前,始终根据你自己的流量进行验证。

如果你有……从以下方法开始
可用 EAGLE-3 头的通用聊天 / 指令模型EAGLE-3,初始使用 num_speculative_tokens: 3。
较高的提示词与输出重叠程度(RAG、摘要、代码补全),但没有 EAGLE-3 头N-gram,初始使用 num_speculative_tokens: 5。
以上情况均不满足暂缓启用 Speculative Decoding,直到满足上述条件之一。

内部验证快照 — N-gram

上述起点是指导建议,而非保证。下面的测量结果来自 Alauda AI Platform 内部实验室的一个具体数据点,旨在帮助你校准在类似单 GPU 服务设置下的预期。你自己的模型、GPU、运行时版本和流量会产生不同的结果——在推广到生产环境之前,务必进行基准测试。

  • 硬件:NVIDIA A30 24 GB × 1
  • 模型:Qwen3-8B(BF16,HuggingFace Qwen/Qwen3-8B)
  • 运行时:vLLM 0.19.1(V1 引擎)
  • 请求参数:temperature=0、seed=42、max_tokens=1024、enable_thinking=false,单个并发请求,丢弃 1 次预热运行 + 3 次计时运行(报告中位数)

基线命令(无 spec decode):

python3 -m vllm.entrypoints.openai.api_server \
  --port 8080 \
  --served-model-name t-ng \
  --model /mnt/models \
  --gpu-memory-utilization 0.8 \
  --max-model-len 4096 \
  --max-num-seqs 8 \
  --seed 42

N-gram 命令(仅 --speculative-config 不同):

python3 -m vllm.entrypoints.openai.api_server \
  --port 8080 \
  --served-model-name t-ng \
  --model /mnt/models \
  --gpu-memory-utilization 0.8 \
  --max-model-len 4096 \
  --max-num-seqs 8 \
  --seed 42 \
  --speculative-config '{"method":"ngram","num_speculative_tokens":5,"prompt_lookup_max":4,"prompt_lookup_min":2}'

工作负载:

  • 代码重构(高提示词与输出重叠):要求模型为一个 30 行的 Python 类添加文档字符串和类型注解,并返回完整的更新后类
  • 通用聊天(无提示词与输出重叠):要求模型用至少 800 个单词解释一个概念

结果:

工作负载基线 tok/sN-gram tok/s加速比墙钟时间变化
代码重构(高重叠)47.0245.920.98×+524 ms
通用聊天(无重叠)47.1339.940.85×+3914 ms

解读:

  • 在这个单 GPU 8B 设置上,N-gram 在代码重构工作负载上出现轻微回退,在聊天工作负载上则出现明显的约 15% 回退。提议器的 CPU 工作、每步对五个候选令牌的验证,以及 vLLM 在 N-gram 下禁用异步调度这几项开销加在一起,超过了已接受令牌带来的节省。
  • 高重叠代码工作负载的接受率较为理想(早期非正式探测中的平均接受长度约为 3),但接受率本身无法预测端到端加速比——必须将每步开销与目标模型实际的解码时间进行摊销。在单 GPU 上使用较小的目标模型时,解码本身已经很廉价,可供摊销的空间很小。
  • 聊天结果印证了关于无提示词与输出重叠工作负载的注意事项。

在更大的目标模型上(每个验证步骤成本更高)、使用多 GPU tensor parallelism,或在更高并发下,同一方法的表现可能大不相同。请将此快照视为提醒你进行测量,而不是对 N-gram 本身的定论。

内部验证快照 — EAGLE-3

上述起点是指导建议,而非保证。下面的测量结果来自 Alauda AI Platform 内部实验室的一个具体数据点,旨在帮助你校准在类似单 GPU EAGLE-3 设置下的预期。你自己的模型、GPU、运行时版本和流量会产生不同的结果——在推广到生产环境之前,务必进行基准测试。

  • 硬件:NVIDIA A30 24 GB × 1
  • 模型:Meta-Llama-3.1-8B-Instruct(BF16,HuggingFace meta-llama/Meta-Llama-3.1-8B-Instruct),以及 EAGLE-3 草稿 yuhuili/EAGLE3-LLaMA3.1-Instruct-8B
  • 运行时:vLLM 0.19.1(V1 引擎)
  • 请求参数:temperature=0、seed=42、max_tokens=1024,单个并发请求,丢弃 1 次预热运行 + 3 次计时运行(报告中位数)

基线命令(无 spec decode):

python3 -m vllm.entrypoints.openai.api_server \
  --port 8080 \
  --served-model-name eagle \
  --model /mnt/models/Meta-Llama-3.1-8B-Instruct \
  --dtype auto \
  --gpu-memory-utilization 0.8 \
  --max-model-len 4096 \
  --max-num-seqs 8 \
  --seed 42

EAGLE-3 命令(仅 --speculative-config 不同):

python3 -m vllm.entrypoints.openai.api_server \
  --port 8080 \
  --served-model-name eagle \
  --model /mnt/models/Meta-Llama-3.1-8B-Instruct \
  --dtype auto \
  --gpu-memory-utilization 0.8 \
  --max-model-len 4096 \
  --max-num-seqs 8 \
  --seed 42 \
  --speculative-config '{"method":"eagle3","model":"/mnt/models/EAGLE3-LLaMA3.1-Instruct-8B","num_speculative_tokens":3}'

工作负载:

  • 代码重构(高提示词与输出重叠):要求模型为一个 30 行的 Python 类添加文档字符串和类型注解,并返回完整的更新后类
  • 通用聊天(无提示词与输出重叠):要求模型用至少 800 个单词解释一个概念

结果:

工作负载基线 tok/sEAGLE-3 tok/s加速比墙钟时间变化(中位数)
代码重构(高重叠)47.8488.251.84×−6171 ms
通用聊天(无重叠)47.8747.450.99×+2416 ms

加速比是 tok/s 的比值(与完成长度无关)。墙钟时间变化直接比较墙钟时间的中位数;聊天运行生成的输出量不同(基线为 588 个令牌,EAGLE-3 为 709 个令牌),因此在该场景下,加速比是更可靠的指标。

Speculative Decoding 行为(EAGLE-3 侧,来自 SpecDecoding metrics 日志窗口):

工作负载平均接受长度平均草稿接受率按位置统计的接受率
代码重构(高重叠)≈ 2.54≈ 51%0.50 / 0.40 / 0.33
通用聊天(无重叠)≈ 1.19≈ 6%0.16 / 0.02 / 0.01

平均接受长度和接受率是在覆盖每次基准测试运行的 SpecDecoding metrics 日志窗口中按草稿加权计算的;按位置统计的值来自每次运行期间的持续负载窗口。

解读:

  • 在这个单 GPU 8B 设置上,EAGLE-3 在代码重构工作负载上实现了约 1.84× 的加速,在通用聊天工作负载上则基本持平(约 0.99×)。两次基线运行均稳定在约 47.8 tok/s,符合预期——基础解码速率是模型和硬件的属性,不取决于提示词内容。所有可观察到的差距都来自 EAGLE-3 侧。
  • 为什么代码重构有效,而聊天无效——接受数据直接说明了其中的机制。在代码重构场景中,草稿头每个解码步骤平均生成约 2.54 个令牌,接受率约为 51%,因此大多数步骤都会输出多个令牌;按位置统计的接受率下降缓慢(0.50 / 0.40 / 0.33),所以即使是第 3 个推测位置,也有三分之一的概率能够发挥作用。在聊天场景中,平均接受长度约为 1.19,接受率仅约 6%,并且按位置统计的接受率在第 2 个位置时就骤降(0.16 / 0.02 / 0.01)——几乎每一步都只输出经过验证的令牌,而草稿令牌会被丢弃。
  • 实际结果与理论结果。在提议器开销为零的情况下,平均接受长度是加速比的理论上限。代码重构实际达到 1.84×,而上限为 2.54×(约转化了 72%),也就是说,提议器 CPU 工作、对被拒绝提议的验证,以及异步调度成本消耗了约四分之一的潜在收益。聊天场景的理论上限为 1.19×,但这部分收益完全被开销消耗,最终出现轻微回退。这与注意事项一致:在单 GPU 上使用较小模型时,每步开销几乎没有空闲的解码容量可以掩盖。

在更大的目标模型上(每个验证步骤成本更高)、使用多 GPU tensor parallelism,或在更高并发下,同一方法的表现可能大不相同。请将此快照视为提醒你进行测量,而不是对 EAGLE-3 本身的定论。

前置条件

  • 已安装 KServe 的 Kubernetes 集群,以及一个可在其中创建 InferenceService 资源的命名空间。
  • 平台上已注册一个 vLLM 服务运行时,且其 vLLM 版本支持你计划使用的推测解码方法。要检查版本,请使用该运行时启动的 Pod,通过 exec 进入正在运行的 Pod:kubectl exec <pod> -- python3 -c "import vllm; print(vllm.__version__)"。
  • 目标模型可通过其存储源(模型仓库、PVC 或 OCI 镜像)供服务访问。
  • 对于 EAGLE-3:草稿头的架构、tokenizer 和基础版本必须与确切的目标模型匹配。不匹配的草稿头会悄然降低接受率,且可能不会表现为启动错误。
  • 对于 EAGLE-3:需要一种模型制品加载机制,能够将目标模型和草稿模型都加载到同一个 Pod 中。请参阅Alauda AI Platform 上的模型制品供应。

配置项

在 vLLM v1 中,只需一个参数即可启用推测解码:

--speculative-config '{"method": "<method>", "num_speculative_tokens": <k>, ...}'

常用键:

  • method:要使用的提议器。本指南中使用的值:ngram 和 eagle3。上游还提供其他值(例如 medusa,或特定于模型的 MTP 名称,例如 deepseek_mtp)——请在 vLLM 推测解码文档中确认适用于你所用方法的确切值。
  • num_speculative_tokens:每步提议的令牌数。值越高,加速效果可能越明显,但也会在提议被拒绝时浪费计算资源。
  • model:对于需要加载单独草稿制品的方法(例如 EAGLE-3),这是该制品在容器内的路径。
  • 特定于方法的键,例如 N-gram 的 prompt_lookup_max / prompt_lookup_min。这些名称在不同的 vLLM 版本间发生过变化——请根据所部署的版本进行核实。

所有其他 vLLM 参数(--model、--tensor-parallel-size、--gpu-memory-utilization 等)与非推测解码部署中的用法相同。

在 Alauda AI Platform 上提供模型制品

不同的方法需要在预测器 Pod 中使用不同的文件。

单制品模式(N-gram)

N-gram 只需要目标模型。与其他推理服务一样,直接使用 storageUri:

spec:
  predictor:
    model:
      storageUri: hf://<your-model-path>

模型会存放在 /mnt/models,并通过 --model 传递给 vLLM。

双制品模式(EAGLE-3 及类似方法)

EAGLE-3 需要将目标模型和匹配的草稿头都加载到同一个 Pod 中。有三种受支持的供应方式。请根据平台版本、网络访问情况和运维偏好进行选择。

选项 A — KServe storageUris(可用时优先)

storageUris 是 KServe 的一个字段,接受多个存储位置,并将每个位置挂载到声明的路径下。若你的平台所用的 KServe 版本支持该字段(KServe 0.16 及更高版本),这是最简洁的选择。

spec:
  predictor:
    model:
      storageUris:
        - uri: hf://<your-target-model-path>
          mountPath: /mnt/models/target
        - uri: hf://<your-draft-head-path>
          mountPath: /mnt/models/draft

然后将这两个路径传递给 vLLM:

--model /mnt/models/target \
--speculative-config '{"method":"eagle3","model":"/mnt/models/draft","num_speculative_tokens":3}'

需要注意的限制:

  • storageUri(单数)和 storageUris(复数)不能同时使用。
  • 所有 mountPath 值都必须是绝对路径,并且共享同一个父目录(例如 /mnt/models/target 和 /mnt/models/draft)。
  • 对于私有仓库,请将相应的凭据 Secret 附加到预测器 Pod 使用的服务账户。

如果你的平台所用的 KServe 版本尚未包含 storageUris,请使用选项 B 或选项 C。

选项 B — 使用一个 OCI Modelcar 容纳两种制品

将目标模型和草稿头打包到一个 OCI 镜像中,并分别放在可预测的子目录下(例如 /models/target 和 /models/draft),然后使用 storageUri: oci://... 部署。打包步骤请参阅使用 KServe Modelcar 存储模型。镜像中应包含的示例磁盘布局:

/models/
├── target/
│   └── ... target model files ...
└── draft/
    └── ... EAGLE-3 head files ...

然后在 vLLM 命令中引用相同的路径:

--model /mnt/models/target \
--speculative-config '{"method":"eagle3","model":"/mnt/models/draft","num_speculative_tokens":3}'

此选项非常适合离线或隔离网络的集群,因为两种制品会一并进行版本管理,并从你自己的镜像仓库拉取。

选项 C — 预先暂存到共享 PVC

按照已知的目录布局,将两种制品暂存到 PVC 上,挂载该 PVC,并在 vLLM 命令中引用本地路径。如果你已在共享文件系统上管理模型文件,这是最简单的选择。

在 A / B / C 之间进行选择

限制条件选择
联网集群,KServe ≥ 0.16,且希望使用声明式清单选项 A
离线或隔离网络,希望使用单个版本化制品选项 B
已有存放模型文件的共享 PVC选项 C

端到端示例

以下两个示例涵盖了 Alauda AI Platform 上可用的方法中列出的方法。请将 <your-namespace>、<your-vllm-runtime> 和存储 URI 替换为你环境中的值。

示例 1 — N-gram

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  annotations:
    aml-model-repo: Qwen2.5-7B-Instruct
    serving.kserve.io/deploymentMode: Standard
  labels:
    aml.cpaas.io/runtime-type: vllm
  name: qwen-ngram-spec
  namespace: <your-namespace>
spec:
  predictor:
    minReplicas: 1
    maxReplicas: 1
    model:
      command:
        - bash
        - -c
        - |
          set -ex

          MODEL_PATH="/mnt/models/${MODEL_NAME}"
          if [ ! -d "${MODEL_PATH}" ]; then
            MODEL_PATH="/mnt/models"
          fi

          python3 -m vllm.entrypoints.openai.api_server \
            --port 8080 \
            --served-model-name {{.Name}} {{.Namespace}}/{{.Name}} \
            --model "${MODEL_PATH}" \
            --dtype ${DTYPE} \
            --gpu-memory-utilization ${GPU_MEMORY_UTILIZATION} \
            --speculative-config '{"method":"ngram","num_speculative_tokens":5,"prompt_lookup_max":4,"prompt_lookup_min":2}' 
        - bash
      env:
        - name: DTYPE
          value: half
        - name: GPU_MEMORY_UTILIZATION
          value: '0.85'
        - name: MODEL_NAME
          value: '{{ index .Annotations "aml-model-repo" }}'
      modelFormat:
        name: transformers
      protocolVersion: v2
      resources:
        limits:
          cpu: '8'
          memory: 32Gi
          nvidia.com/gpu: '1'
        requests:
          cpu: '4'
          memory: 16Gi
      runtime: <your-vllm-runtime>
      storageUri: hf://<your-model-path>
    securityContext:
      seccompProfile:
        type: RuntimeDefault
  1. 替换为实际的模型名称;平台会使用此注解进行显示。
  2. prompt_lookup_* 键属于 n-gram proposer。它们的名称在不同 vLLM 版本之间有所变化,请根据运行时镜像中的版本进行确认。

示例 2 — 在共享 PVC 上使用 target + draft 的 EAGLE-3

此清单与上文 内部验证快照 — EAGLE-3 中使用的设置一致。target 模型和 EAGLE-3 draft head 均已预先暂存到单个 PVC 中的固定子目录下;storageUri: pvc://... 将该 PVC 挂载到 /mnt/models/,而 vLLM 命令直接引用这两个子目录。

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  annotations:
    aml-model-repo: Meta-Llama-3.1-8B-Instruct
    serving.kserve.io/deploymentMode: Standard
  labels:
    aml.cpaas.io/runtime-type: vllm
  name: llama-eagle3-spec
  namespace: <your-namespace>
spec:
  predictor:
    minReplicas: 1
    maxReplicas: 1
    model:
      command:
        - bash
        - -c
        - |
          set -ex

          python3 -m vllm.entrypoints.openai.api_server \
            --port 8080 \
            --served-model-name {{.Name}} {{.Namespace}}/{{.Name}} \
            --model /mnt/models/Meta-Llama-3.1-8B-Instruct \
            --dtype ${DTYPE} \
            --gpu-memory-utilization ${GPU_MEMORY_UTILIZATION} \
            --max-model-len 4096 \
            --max-num-seqs 8 \
            --seed 42 \
            --speculative-config '{"method":"eagle3","model":"/mnt/models/EAGLE3-LLaMA3.1-Instruct-8B","num_speculative_tokens":3}' 
        - bash
      env:
        - name: DTYPE
          value: auto
        - name: GPU_MEMORY_UTILIZATION
          value: '0.8'
      modelFormat:
        name: transformers
      protocolVersion: v2
      resources:
        limits:
          cpu: '8'
          memory: 48Gi
          nvidia.com/gpu: '1'
        requests:
          cpu: '4'
          memory: 24Gi
      runtime: <your-vllm-runtime>
      storageUri: pvc://<your-pvc-name>/
    securityContext:
      seccompProfile:
        type: RuntimeDefault
  1. vLLM 命令中的两个路径(--model 和 --speculative-config 中的 model 键)必须与 PVC 内部的目录名称完全一致。如果 PVC 中的制品使用了不同的目录名称,请同时调整这两个路径。
  2. EAGLE-3 head 会占用 --gpu-memory-utilization 预算之外的 GPU 内存。预留一定余量(此处为 0.8,而非 0.9)可降低同时加载两种制品时发生 OOM 的可能性。
  3. pvc://<your-pvc-name>/ 要求 PVC 预先暂存target 模型和 EAGLE-3 draft head;PVC 根目录挂载到 /mnt/models/,因此这两种制品必须分别位于 /mnt/models/<target-subdir>/ 和 /mnt/models/<draft-subdir>/。请参见下方的预期布局。如果你更倾向于使用声明式多 URI 挂载(KServe 0.16+),或将 target + draft 打包到单个 OCI 镜像中,请参见提供模型制品中的选项 A 或选项 B。

PVC 内的预期布局(在 Pod 中挂载到 /mnt/models/):

<PVC root>/
├── Meta-Llama-3.1-8B-Instruct/
│   └── ... target model files ...
└── EAGLE3-LLaMA3.1-Instruct-8B/
    └── ... EAGLE-3 draft head files ...

预测器 Pod 启动后,从 Pod 内部验证目录布局:

kubectl exec -n <your-namespace> <pod> -- ls /mnt/models/
# Expected: EAGLE3-LLaMA3.1-Instruct-8B/  Meta-Llama-3.1-8B-Instruct/

使用以下命令应用上述任一清单:

kubectl apply -f <manifest>.yaml -n <your-namespace>

验证并衡量效果

确认已配置推测解码只是一个步骤。确认它能否改善你的工作负载则是另一个步骤。

1. 确认配置已应用

kubectl get inferenceservice <name> -n <your-namespace> -o yaml

在预测器命令中查找 --speculative-config,并确认就绪状态:

kubectl get pods -n <your-namespace> -l serving.kserve.io/inferenceservice=<name>

2. 确认推测解码确实正在运行

启动时的首个信号是引擎配置日志行;它会打印引擎解析出的 speculative_config,因此你可以验证所选方法和 draft 路径是否已生效:

kubectl logs -n <your-namespace> -l serving.kserve.io/inferenceservice=<name> \
  | grep -m1 'Initializing a V1 LLM engine'
# Expected to contain: speculative_config=SpeculativeConfig(method='eagle3', model='...', num_spec_tokens=3)

对于实时计数器,vLLM 会在 /metrics 暴露 Prometheus 指标。具体指标名称取决于 vLLM 版本,因此请先尽可能广泛地搜索:

kubectl exec <pod> -n <your-namespace> -- curl -s localhost:8080/metrics | grep -iE 'spec_decode|draft|acceptance'

如果没有返回结果,说明 Pod 尚未处理任何请求(计数器会在首次生成完成后才发布),或者你的 vLLM 构建版本中的指标名称不同;此时请改为查看预测器日志。

vLLM 会打印逐窗口汇总行,这是最易读的实时概览。以下是在 vLLM 0.19.1 中使用 num_speculative_tokens=3 时该行的实际格式:

SpecDecoding metrics: Mean acceptance length: 2.68, Accepted throughput: 65.69 tokens/s,
Drafted throughput: 116.98 tokens/s, Accepted: 657 tokens, Drafted: 1170 tokens,
Per-position acceptance rate: 0.664, 0.559, 0.462, Avg Draft acceptance rate: 56.2%

解读方式:

  • 平均接受长度 — 每个解码步骤平均输出的 token 数。基线为 1。这是此工作负载可能达到的加速效果的实际上限。
  • 平均 Draft 接受率 — 提议的 token 中被接受的总体比例。这个数值可以回答“提议器大部分时候是在发挥作用,还是大部分时候都白费功夫?”。
  • 各位置接受率 — 位置 1..num_speculative_tokens 对应的各槽位接受率。你会看到恰好 num_speculative_tokens 个值 — 上面的示例有 3 个,因为该次运行使用了 num_speculative_tokens=3;使用 num_speculative_tokens=5 的 ngram 运行会打印 5 个值。健康的曲线会缓慢下降;如果曲线到第 2 个槽位时就骤降至接近零,则说明该工作负载不适合此提议器。

3. 衡量端到端效果

对同一个有代表性的工作负载运行两次:

  1. 移除 --speculative-config(基线)。
  2. 启用该项(其他设置完全相同,包括 --seed)。

每次运行记录以下三个数值:

  • 首 token 耗时(TTFT)。
  • 每 token 延迟(或固定输出长度下的端到端延迟)。
  • 在实际服务的 QPS 下的吞吐量(tokens/second)。

如果在目标 QPS 下这三项都有改善,则值得保留推测解码。常见的一种失败情况是在低 QPS 下有所改善,但在生产 QPS 下出现回退 — 请在实际运行负载的条件下进行测量。

4. 如何报告或比较数据

没有上下文的性能数据无法复现,也不值得信赖。每次发布比较结果时 — 无论是在内部、客户报告中,还是反馈给平台团队 — 都应包含以下五项。缺少其中任何一项的数据都应视为轶闻,而非证据。

**Hardware:** <GPU model and count, e.g. NVIDIA A30 24 GB × 1>
**Model:** <model identifier and dtype, e.g. Qwen3-8B (BF16)>
**Runtime:** <vLLM version and runtime image name, e.g. vLLM 0.19.1 inside aml-vllm-x.y.z>
**Request parameters:** <temperature, max_tokens, concurrency, sampling toggles, runs per prompt>

**Baseline command (no spec decode):**
```text
python3 -m vllm.entrypoints.openai.api_server \
  --port 8080 \
  --served-model-name <name> \
  --model /mnt/models \
  --gpu-memory-utilization 0.8 \
  --max-model-len 4096 \
  --max-num-seqs 8 \
  --seed 42

推测解码命令(仅 --speculative-config 不同):

python3 -m vllm.entrypoints.openai.api_server \
  --port 8080 \
  --served-model-name <name> \
  --model /mnt/models \
  --gpu-memory-utilization 0.8 \
  --max-model-len 4096 \
  --max-num-seqs 8 \
  --seed 42 \
  --speculative-config '{"method":"ngram","num_speculative_tokens":5,"prompt_lookup_max":4,"prompt_lookup_min":2}'

结果:

工作负载基线 TTFTSpec TTFT基线 tok/sSpec tok/s平均接受长度平均接受率加速比 (tok/s)
chat…………………
code…………………
rag…………………

比较时请遵循以下两条实用规则:

  • 两种配置使用相同的 --seed 和 temperature=0,并在计时前分别向每个服务发送 3 个不计入结果的预热请求 — 否则,采样和编译缓存造成的噪声会掩盖你测得的差异。
  • 对基线和推测解码使用相同的固定提示词列表,并保持相同顺序;每个提示词至少运行 5–10 次,并比较中位数而非平均值。

回滚

若要在不更改其他设置的情况下禁用推测解码,请从 predictor 命令中移除 --speculative-config 行,然后重新应用:

kubectl edit inferenceservice <name> -n <your-namespace>
# delete the --speculative-config line, save, exit

或者重新应用省略该标志的清单:

kubectl apply -f <manifest-without-spec-config>.yaml -n <your-namespace>

服务会在没有推测提议器的情况下滚动更新到新版本。对于 N-gram,无需更改模型制品。对于 EAGLE-3,draft head 仍会挂载,但不会被使用——如果要回收磁盘空间,请在下一次更改时移除 draft-head 制品(对于选项 A,删除匹配的 storageUris 条目;对于选项 B,在不包含 draft 目录的情况下重新构建 OCI 镜像;或者对于选项 C,从 PVC 中删除 draft 子目录)。

故障排除

症状可能原因检查项
Pod 启动失败,并显示提及 speculative 的 vLLM 参数错误或未知 JSON 键--speculative-config 键与运行时镜像中的 vLLM 版本不匹配kubectl exec <pod> -- python3 -c "import vllm; print(vllm.__version__)",并根据该版本调整标志
Pod 启动失败,并显示未知的 method 值method 中存在拼写错误,或使用了你的 vLLM 版本不支持的值(例如使用 eagle 而不是 eagle3)在上游推测解码文档中确认你的 vLLM 版本支持的 method 值
启用 EAGLE-3 后在模型加载期间发生 OOM未为 EAGLE-3 head 预留内存将 --gpu-memory-utilization 降低 0.05–0.10,或减少 GPU 上的其他工作负载
服务 Ready,但接受率接近零target 与 draft 之间的 tokenizer / 架构不匹配,或采样温度过高重新确认 draft head 与目标模型完全匹配;降低评估时的采样温度
生产 QPS 下 TTFT 或延迟回归提议开销不再能被空闲的解码容量隐藏在此服务上禁用该功能,或降低 num_speculative_tokens;请参阅回滚
API server 拒绝 storageUris平台上的 KServe 版本早于 storageUris改用选项 B(Modelcar)或选项 C(PVC)
服务在滚动更新期间持续处于 NotReady 状态,或 Knative 因进度截止时间超时而将版本标记为 NotReady带有 draft 制品的冷启动比不带制品时更慢——backbone 和 EAGLE head 的 torch.compile,加上引擎分析,可能使启动时间超过就绪截止时间。我们在 A30 + Llama-3.1-8B 上测得的 EAGLE-3 冷启动时间约为 ~5 分钟在 Standard 模式下,提高 predictor 就绪探针的超时时间,使其能够容纳 5 分钟的启动时间,例如使用 initialDelaySeconds: 60,并设置 periodSeconds: 10 和 failureThreshold: 30。在 Knative 模式下,将 serving.knative.dev/progress-deadline 注解设置为 1800s
在 spec decode 下使用 min_p 或 logit_bias 时,客户端观察到意外的采样行为启用推测解码后,vLLM 会静默忽略这两个参数(引擎初始化时会打印警告)从请求中删除该参数,或在客户端依赖该参数的服务上禁用推测解码

对于 Pod 级别的问题,请使用标准的推理服务故障排除命令:

kubectl describe inferenceservice <name> -n <your-namespace>
kubectl logs -n <your-namespace> -l serving.kserve.io/inferenceservice=<name>

注意事项和已知限制

  • 结果会因工作负载形态而大幅波动——回归和加速都确实存在。 上游 V0 基准测试报告称,在高 QPS 下速度减慢 1.4×–1.8×。我们自己的 A30 + Qwen3-8B N-gram 测试(请参阅 内部验证快照 — N-gram)发现,即使在高重叠代码工作负载下也略有回归。在相同硬件上,Llama-3.1-8B 的 EAGLE-3(请参阅 内部验证快照 — EAGLE-3)在代码重构场景中实现了 1.84× 加速,但在聊天场景中基本持平(~0.99×)——相同模型、相同方法、相同 Pod,在两种提示词形态之间,实际收益相差 2 倍。请始终根据生产流量特征进行验证。
  • N-gram 会禁用异步调度。 在近期的 vLLM 版本中,启用 ngram 方法会强制关闭异步调度(predictor 会记录 Async scheduling not supported with ngram-based speculative decoding and will be disabled)。如果你的服务依赖异步调度来提升吞吐量,请优先使用 EAGLE-3,或明确测量其中的权衡。
  • storageUris 的可用性。 此字段从 KServe 0.16 开始提供。较旧的平台版本必须使用 Modelcar 或 PVC 选项。
  • Draft head 不匹配不会显式报错。 与目标模型不完全匹配的 draft head 通常仍能正常启动并处理流量,但接受率会非常低。启用后请始终检查接受率。
  • 采样参数会影响接受率。 较高的温度会降低接受率;请使用能够反映生产环境使用情况的采样设置进行基准测试。
  • gpu-memory-utilization 预算。 Draft 制品(EAGLE-3 head、MLP speculator、draft model)不计入 --gpu-memory-utilization 预算;添加 draft 制品时请降低该值。
  • 镜像依赖。 运行时镜像必须包含所选方法所需的库。如果某种方法初始化失败,请重新构建或替换运行时镜像——请参阅扩展推理运行时。
  • min_p 和 logit_bias 会被静默忽略。 在推测解码模式下,vLLM 会在引擎初始化期间记录警告 min_p and logit_bias parameters won't work with speculative decoding.。传入任一采样参数的请求仍会收到 200 响应,但这些参数不会生效——如果你的流量依赖这些参数,请根据客户端假设进行验证。
  • 与其他功能的组合。 推测解码可与张量并行和连续批处理组合使用,但与自动扩缩容以及 EP / 高级并行的交互方式取决于 vLLM 版本。使用 draft 制品时冷启动开销明显更高:在我们的 A30 + Llama-3.1-8B + EAGLE-3 head 实验环境中,predictor 从容器就绪到 Application startup complete 用时 ~5 分钟(权重加载 ~45 秒,draft 权重 ~5 秒,torch.compile backbone ~48 秒,torch.compile EAGLE head ~17 秒,CUDA graph 捕获和预热 ~10 秒,此外还有约 2 分钟的引擎分析和 KV-cache 大小调整)。请据此设置就绪截止时间,而不要参考非推测解码基线:在 Standard 模式下,predictor 就绪探针必须能够容纳 5 分钟的启动时间;在 Knative 模式下,serving.knative.dev/progress-deadline 注解应设置为 1800s。请将任何从零开始扩缩容的 SLO 设置为相同的时长。
  • 输出等价性。 vLLM 声明推测解码不会改变输出分布。这是 vLLM 的属性,而不是 Alauda AI Platform 的保证——如果运行时镜像需要保证完全等价,请将其作为验收测试的一部分进行验证。

参考资料