Qwen3-Coder-30B-A3B

1 引言

Qwen3-Coder-30B-A3B 是 Qwen3 Coder 系列中的混合专家（MoE）模型，与 Qwen3-30B-A3B 共享相同的架构，总参数量为 30.5B，每个 Token 激活 3.3B 参数。该模型基于 Qwen3 基础架构构建，在智能体编码、高达 1M Token 的扩展上下文支持以及多功能函数调用能力方面实现了显著优化。

本文档将演示在 vLLM-Ascend 环境中对 Qwen3-Coder-30B-A3B 的主要验证步骤，包括支持的特性、环境准备、单节点部署以及精度和性能评估。

Qwen3-Coder-30B-A3B 模型首次在 v0.10.0rc1 中得到支持。本文档基于 vLLM-Ascend v0.22.1rc 进行验证和编写。所有 v0.22.1rc 及更高版本 均可稳定运行。为使用最新特性，建议使用最新的候选发布版或正式版。

2 支持的特性

模型支持矩阵请参考支持特性列表。

特性配置信息请参考特性指南。

3 前提条件

3.1 模型权重

以下模型变体可用。建议将模型权重下载到所有节点均可访问的共享目录中。

模型	硬件要求	下载
Qwen3-Coder-30B-A3B-Instruct (BF16)	Atlas 800I A3 (64G, 1~2 卡) Atlas 800I A2 (64G, 2~4 卡)	下载
Qwen3-Coder-30B-A3B-Instruct-W8A8	Atlas 800I A3 (64G, 1~2 卡) Atlas 800I A2 (64G, 2~4 卡)	下载
Eagle3 草稿模型	不适用	下载

这些是推荐的卡数，可根据实际情况进行调整。

如果 W8A8 量化权重无法直接下载，您可以通过使用 msmodelslim 量化 BF16 模型来获取。详情请参考量化指南。本文档中的所有模型路径应调整为您的实际本地路径。

Note

Qwen3-Coder-30B-A3B-W8A8 采用混合量化策略（按模型结构排序）：

• 嵌入层：BF16（无量化）
• Q/K 归一化 (q_norm, k_norm)：BF16（权重和偏置）
• 注意力投影 (q/k/v/o_proj)：静态 W8A8，使用预计算的逐张量缩放因子；偏置保持 BF16
• MoE 路由门控 (mlp.gate)：BF16
• MoE 专家投影 (gate/up/down_proj)：动态 W8A8，输入缩放因子在推理过程中即时计算

4 安装

4.1 Docker 镜像安装

您可以使用 Qwen3 MoE 模型的官方一体化 Docker 镜像。

A3 seriesA2 series

Docker 运行：

export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-a3

docker run \
    --name vllm-ascend-env \
    --ipc host \
    --net host \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci2 \
    --device /dev/davinci3 \
    --device /dev/davinci4 \
    --device /dev/davinci5 \
    --device /dev/davinci6 \
    --device /dev/davinci7 \
    --device /dev/davinci8 \
    --device /dev/davinci9 \
    --device /dev/davinci10 \
    --device /dev/davinci11 \
    --device /dev/davinci12 \
    --device /dev/davinci13 \
    --device /dev/davinci14 \
    --device /dev/davinci15 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /usr/local/sbin:/usr/local/sbin \
    -it -d $IMAGE bash

Note

A3 有 8 个 NPU，采用双 die 设计（共 16 个芯片：/dev/davinci[0-15]）。 如果您在共享机器上，请仅映射您需要的芯片（例如，NPU 0-3 映射 /dev/davinci[0-7]）。

Docker 运行：

export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1

docker run \
    --name vllm-ascend-env \
    --ipc host \
    --net host \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci2 \
    --device /dev/davinci3 \
    --device /dev/davinci4 \
    --device /dev/davinci5 \
    --device /dev/davinci6 \
    --device /dev/davinci7 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /usr/local/sbin:/usr/local/sbin \
    -it -d $IMAGE bash

Tip

The mounts above are the minimum required for NPU driver access. Add additional -v mounts (e.g., model weight paths, datasets) as needed for your environment.

默认工作目录是 /workspace。vLLM 和 vLLM-Ascend 作为 Python 包安装在 site-packages 中。

安装验证：

启动容器后，运行以下命令验证安装：

docker ps | grep vllm-ascend-env

预期结果：容器被列出，状态为 Up。您还可以在容器内验证 vllm-ascend 版本：

pip show vllm-ascend

预期结果：显示版本信息，与拉取的镜像版本匹配。

4.2 源码安装

如果您不想使用 Docker 镜像，可以从源码构建。首先从源码安装 vLLM：

1. 克隆并安装 vLLM：

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

1. 克隆并安装 vLLM-Ascend 仓库：

git clone https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
pip install -e .

安装验证：

pip show vllm vllm-ascend

预期结果：显示两个包的版本信息，确认安装成功。

Note

如果部署多节点环境，请在每个节点上设置环境。

更多详情，请参考安装指南。

5 在线服务部署

5.1 单节点在线部署

单节点部署在同一节点内完成 Prefill 和 Decode，适用于开发、测试以及中小规模推理场景。对于 Qwen3-Coder-30B-A3B MoE 模型，需要使用专家并行（EP）将专家分布到多个 NPU 上。

以下命令为示例配置。请根据您的实际场景调整参数。

Atlas 800I A2/A3：

export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
export HCCL_OP_EXPANSION_MODE="AIV"  # not needed on A2
export HCCL_BUFFSIZE=1024
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve your_model_path \
    --served-model-name qwen3-coder \
    --trust-remote-code \
    --max-num-seqs 100 \
    --max-model-len 40960 \
    --max-num-batched-tokens 16384 \
    --tensor-parallel-size 4 \
    --enable-expert-parallel \
    --quantization ascend \
    --distributed_executor_backend "mp" \
    --no-enable-prefix-caching \
    --async-scheduling \
    --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
    --additional-config '{"enable_flashcomm1": true, "weight_nz_mode": 2}' \
    --gpu-memory-utilization 0.95 \
    --port 8000 \
    --speculative-config '{"method": "eagle3", "model": "your_eagle3_model_path", "draft_tensor_parallel_size": 1, "num_speculative_tokens": 3}'

Note

• ASCEND_RT_VISIBLE_DEVICES：必须设置为分配给您的环境的NPU芯片ID（例如，4个芯片设为0,1,2,3）。
• --port：调整以避免与同一机器上运行的其他服务冲突。
• --no-enable-prefix-caching：默认禁用，因为该模型在Ascend NPU上的前缀缓存效果尚未完全评估。您可以尝试启用它以评估工作负载的缓存命中率。
• --quantization ascend：W8A8量化模型必需。使用BF16权重时请移除该参数。

Tip

参数详情请参考：

• vLLM CLI文档 — 标准服务参数（--host、--port、--max-model-len等）
• 环境变量 — Ascend特定环境变量（HCCL_*等）
• 附加配置 — --additional-config格式和选项

服务验证：

服务启动后，通过发送提示词验证其是否正常运行。使用示例请参考第6节。

6 功能验证

服务启动后，可通过发送提示词调用模型。

聊天补全API：

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "qwen3-coder",
        "messages": [
            {"role": "user", "content": "Give me a short introduction to large language models."}
        ],
        "temperature": 0.6,
        "top_p": 0.95,
        "top_k": 20,
        "max_completion_tokens": 4096
    }'

Note

根据您的部署情况调整以下字段：

• URL (http://localhost:8000)：将localhost和8000替换为您的服务器IP和--port命令中的vllm serve值。
• model：必须与--served-model-name命令中的vllm serve值一致（例如qwen3-coder）。

预期结果：HTTP 200，返回包含choices字段及生成文本的JSON响应。

7 精度评估

使用AISBench

安装、数据集下载和配置等设置详情，请参考使用AISBench。

以下是以GSM8K数据集为例的精度评估配置文件示例：

# Example configuration: benchmarks/ais_bench/benchmark/configs/models/vllm_api/vllm_api_general_chat.py
from ais_bench.benchmark.models import VLLMCustomAPIChat

models = [
    dict(
        attr="service",
        type=VLLMCustomAPIChat,
        abbr='vllm-api-general-chat',
        path="your_model_path",
        model="qwen3-coder",
        request_rate=0,
        retry=2,
        host_ip="localhost",
        host_port=8000,
        max_out_len=32768,
        batch_size=32,
        trust_remote_code=True,
        generation_kwargs=dict(
            temperature=0.6,
            top_k=20,
            top_p=0.95,
        ),
    )
]

以gsm8k数据集为例运行精度评估：

ais_bench --models vllm_api_general_chat --datasets gsm8k_gen_4_shot_cot_str --mode all --dump-eval-details --debug

下表列出了每个评估数据集的--datasets参数：

数据集	--datasets 参数
GSM8K	gsm8k_gen_4_shot_cot_str
GPQA-Diamond	gpqa_gen_0_shot_cot_chat_prompt
AIME 2024	aime2024_gen_0_shot_str
LiveCodeBench	livecodebench_0_shot_chat_v4_v5_v6

--models参数值对应配置文件名称（例如vllm_api_general_chat对应vllm_api_general_chat.py）。请根据您的场景调整max_out_len、batch_size和数据集任务。

数据集准备请参考AISBench数据集指南。

Note

vLLM-Ascend还支持以下评估工具：

• lm_eval
• OpenCompass
• EvalScope

精度结果（Atlas 800I A3，vLLM-Ascend v0.22.1rc，W8A8）：

数据集	指标	分数
GSM8K	准确率（4-shot CoT）	90.14%
GPQA-Diamond	准确率（0-shot CoT）	53.54%
LiveCodeBench	pass@1（0-shot）	38.60%
AIME 2024	准确率（0-shot）	33.33%

8 性能评估

使用AISBench

设置详情请参考使用AISBench进行性能评估。

首先，配置流式性能测试模型（ais_bench/benchmark/configs/models/vllm_api/vllm_api_stream_chat.py）：

from ais_bench.benchmark.models import VLLMCustomAPIChat
from ais_bench.benchmark.utils.postprocess.model_postprocessors import extract_non_reasoning_content

models = [
    dict(
        attr="service",
        type=VLLMCustomAPIChat,
        abbr='vllm-api-stream-chat',
        path="your_model_path",
        model="qwen3-coder",
        stream=True,
        request_rate=0,
        retry=2,
        host_ip="localhost",
        host_port=8000,
        max_out_len=1500,
        batch_size=32,
        trust_remote_code=True,
        generation_kwargs=dict(
            temperature=0.01,
            ignore_eos=True,
        ),
        pred_postprocessor=dict(type=extract_non_reasoning_content),
    )
]

与精度配置的主要区别：stream=True、ignore_eos=True（确保输出达到max_out_len以实现一致的TPOT测量），以及batch_size控制并发数。

然后，配置合成数据集分布（ais_bench/datasets/synthetic/synthetic_config.py）。根据实际场景调整配置。注意，随机合成数据不适用于启用前缀缓存的基准测试场景，因为随机输入会产生零缓存命中率。

synthetic_config = {
    "Type": "string",
    "RequestCount": 200,
    "StringConfig": {
        "Input": {
            "Method": "uniform",
            "Params": {"MinValue": 3500, "MaxValue": 3500}
        },
        "Output": {
            "Method": "uniform",
            "Params": {"MinValue": 1500, "MaxValue": 1500}
        }
    }
}

然后运行性能评估：

ais_bench --models vllm_api_stream_chat --datasets synthetic_gen --mode perf --debug

--models值应与模型配置文件中的abbr一致。使用--num-prompts限制测试请求数量。

使用vLLM基准测试

更多详情请参考vLLM基准测试。

以serve子命令为例。--random-output-len参数控制每个请求的输出token数；根据目标场景调整（例如，短输出设为2048，长输出设为32768）。

vllm bench serve \
    --model your_model_path \
    --served-model-name qwen3-coder \
    --port 8000 \
    --dataset-name random \
    --random-input 200 \
    --random-output-len 2048 \
    --num-prompts 200 \
    --request-rate 1 \
    --save-result \
    --result-dir ./

9 性能调优

9.1 推荐配置

注意：以下配置已在特定测试环境中验证，仅供参考。最佳配置取决于最大输入/输出长度、前缀缓存命中率、精度要求和部署机器比例等因素。建议参考第9.2节根据实际情况进行调整。

表1：场景概览

场景	部署模式	*总NPU数	权重版本	关键考量
高吞吐量	单节点（TP1）	1 (A3) 2 (A2)	W8A8	单卡部署最大化并发请求处理能力
低延迟	单节点（TP4）	2 (A3) 4 (A2)	W8A8	多卡TP通过专家并行降低每token延迟
长上下文	单节点（TP4）	2 (A3) 4 (A2)	W8A8	减少并发序列以容纳更长的max-model-len

*Total NPUs表示所有节点使用的NPU总数。在Atlas 800I A3上，每个NPU包含两个die（芯片），因此TP4需要4个芯片=2个NPU。

表2：详细节点配置

场景	NPU数	TP	max-model-len	max-num-seqs	FUSED_MC2	EP	hf-overrides
High Throughput	1 (A3)	1	37364	100	Off	Off	-
Low Latency	2 (A3)	4	37364	100	Off	On	-
Long Context	2 (A3)	4	131072	14	Off	On	-

有关详细参数说明，请参考第5节中的部署示例。

低延迟配置：

export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_BUFFSIZE=1024
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve your_model_path \
    --served-model-name qwen3-coder \
    --trust-remote-code \
    --max-num-seqs 100 \
    --max-model-len 37364 \
    --max-num-batched-tokens 16384 \
    --tensor-parallel-size 4 \
    --enable-expert-parallel \
    --distributed_executor_backend "mp" \
    --no-enable-prefix-caching \
    --async-scheduling \
    --quantization ascend \
    --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
    --additional-config '{"enable_flashcomm1": true, "weight_nz_mode": 2}' \
    --gpu-memory-utilization 0.95 \
    --port 8000 \
    --speculative-config '{"method": "eagle3","model": "your_eagle3_model_path", "num_speculative_tokens": 3}'

Tip

此配置的AISBench设置示例：

• request_rate: 0
• batch_size: 32
• 输入/输出长度：2048/2048 或 3500/1500

高吞吐配置：

export ASCEND_RT_VISIBLE_DEVICES=0
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_BUFFSIZE=1024
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve your_model_path \
    --served-model-name qwen3-coder \
    --trust-remote-code \
    --max-num-seqs 100 \
    --max-model-len 37364 \
    --max-num-batched-tokens 16384 \
    --tensor-parallel-size 1 \
    --distributed_executor_backend "mp" \
    --no-enable-prefix-caching \
    --async-scheduling \
    --quantization ascend \
    --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
    --additional-config '{"weight_nz_mode": 2}' \
    --gpu-memory-utilization 0.95 \
    --port 8000 \
    --speculative-config '{"method": "eagle3","model": "your_eagle3_model_path", "num_speculative_tokens": 3}'

Tip

此配置的AISBench设置示例：

• request_rate: 0
• batch_size: 32
• 输入/输出长度：2048/2048 或 3500/1500

长上下文配置：

export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_BUFFSIZE=1024
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve your_model_path \
    --served-model-name qwen3-coder \
    --trust-remote-code \
    --max-num-seqs 14 \
    --max-model-len 131072 \
    --max-num-batched-tokens 16384 \
    --tensor-parallel-size 4 \
    --enable-expert-parallel \
    --distributed_executor_backend "mp" \
    --no-enable-prefix-caching \
    --async-scheduling \
    --quantization ascend \
    --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
    --additional-config '{"enable_flashcomm1": true, "weight_nz_mode": 2}' \
    --gpu-memory-utilization 0.95 \
    --port 8000 \
    --speculative-config '{"method": "eagle3","model": "your_eagle3_model_path", "num_speculative_tokens": 3}'

Tip

此配置的AISBench设置示例：

• request_rate: 0
• batch_size: 32
• 输入/输出长度：65536/1024 或 131072/1024

9.2 调优指南

请参考公共性能调优文档了解调优方法。 请参考功能指南了解详细的功能描述。

10 常见问题

关于常见环境、安装和通用参数问题，请参考公共FAQ。本章仅涵盖模型特定问题。

问：如何启用长上下文（超过256K）？

Qwen3-Coder-30B-A3B原生支持256K token的上下文长度。对于超过256K的上下文，需要使用YaRN rope缩放扩展到1M。通过--hf-overrides启用YaRN：

--hf-overrides '{"rope_parameters": {"rope_type":"yarn","factor":4,"original_max_position_embeddings":262144}}'

对于在原生256K范围内的上下文，无需额外配置。只需将--max-model-len设置为您所需的长度即可。

问：Qwen3-Coder与Qwen3-30B-A3B有何不同？

Qwen3-Coder-30B-A3B与基础版Qwen3-30B-A3B共享相同的MoE架构（30.5B/3.3B），但专门针对编码任务进行了微调，针对智能体编码、函数调用进行了优化，并支持高达1M token的扩展上下文。