Dots3 Note¶

1 简介¶

Dots3 Note 是采用 Dots3 Note MoE + MLA 架构的大语言模型，并带有 audio 与 vision 多模态编码器。text、image、audio 三种形态并不是互斥的，可以同时开启；在显存有限的情况下，建议按需开启所需形态。形态不能在同一进程中动态切换，切换时需要重启服务。

形态	输入	典型场景	模态配置
text-only	文本	长上下文对话、文本推理	`--language-model-only`
image	文本 + 图片（每请求 ≤ 7 张）	MMMU 等视觉任务	`--limit-mm-per-prompt '{"image":7,"video":0,"audio":0}'`
audio	文本 + 音频	MMAR 等音频任务	`--limit-mm-per-prompt '{"image":0,"video":0,"audio":1}'`

如果只验证文本能力，选择 text-only；验证 MMMU 等视觉任务时选择 image；验证 MMAR 等音频任务时选择 audio。启用某种形态后，后续的启动和功能验证命令必须使用同一形态。

本文档基于 vLLM-Ascend v0.22.1rc1（配套 vLLM 0.22.1）验证并编写。Dots3 Note 在此版本中完全支持，v0.22.1rc1 及后续版本均可稳定运行。

2 支持特性¶

Dots3 Note 在 vLLM-Ascend 上支持以下特性：

特性	支持	说明
模型架构	Dots3 Note MoE + MLA	MoE 混合专家 + 多头潜在注意力
多模态	audio + vision	音频 / 视觉编码器，按形态分别启用（见 §5.1）
MTP 投机解码	✅（text-only / audio）	MTP3 + draft eager；image 形态关闭（Model Runner V1 限制）
FusedMC2	✅	Fused `dispatch_ffn_combine` / `mega_moe` operators for MoE (`--additional-config`)
Prefix caching	✅	`--enable-prefix-caching`, reuses KV for similar prompts

本章描述的是验证范围，不代表所有硬件和软件版本组合均已覆盖。复现本文结果时，应优先使用第 3～4 章列出的验证环境和组件版本。

3 前置条件¶

开始安装前，请先在宿主机完成本章检查。只有硬件、驱动、固件和模型权重均就绪后，才进入第 4 章。

3.1 硬件介绍¶

本文验证环境如下：

项	规格
服务器	单机 Atlas A3 推理系列（Atlas 800I A3，板卡型号 `IT22HMDA_4_S`）
NPU	Atlas A3 系列产品（8 张卡，每张双 die（2 芯片）），共 16 芯片，对应 `/dev/davinci[0-15]`
显存	每芯片 64 GB 显存
芯片软件版本	SOC_VERSION = `ascend910_9391`（A3 系列）
主机形态	单机部署（非多节点）

在宿主机执行以下检查：

npu-smi info
ls -l /dev/davinci{0..15} /dev/davinci_manager /dev/devmm_svm /dev/hisi_hdc

通过标准：npu-smi info 能识别 8 张卡、共 16 个芯片，所有芯片的显存状态正常；同时，容器启动所需的设备文件均存在。若设备数量或设备文件与本文不同，需要同步调整第 4.2 节中的设备映射及后续并行参数，不能直接照用 TP16 配置。

3.2 驱动版本要求¶

本文验证的软件环境如下：

项	版本
NPU 驱动（npu-smi）	26.0.rc1
Firmware	9.0.0.0.205
CANN	9.0.0
torch-npu	2.10.0

驱动与固件由宿主机安装，并通过 /usr/local/Ascend/driver/version.info、/usr/local/Ascend/driver/lib64/ 等路径挂载进容器。先在宿主机运行：

npu-smi info
cat /usr/local/Ascend/driver/version.info

npu-smi info 输出中显示 8 张卡、共 16 个芯片且显存正常，即表示宿主机侧 NPU 就绪。进入容器后还需要再次执行 npu-smi info，确认设备和驱动挂载在容器内同样可见。

3.3 模型权重¶

确保模型权重已经下载完整，并明确它在容器内的可见路径。后续所有启动命令都复用以下变量：

MODEL_PATH=/path/to/dots3_note   # Model weight directory inside the container
SERVED_NAME=dots3_note       # Model name exposed by the service

test -d "$MODEL_PATH"

如果模型权重位于宿主机，需要在启动容器时将宿主机目录挂载到容器，并把 MODEL_PATH 设置为挂载后的容器内路径。SERVED_NAME 必须与第 6 章客户端请求中的模型名保持一致，否则请求会返回 404。

4 安装¶

本章只提供一种安装方式：直接使用官方预构建镜像。

4.1 组件介绍¶

组件	版本	说明
vLLM	0.22.1	Inference serving framework, provides OpenAI-compatible service (`vllm serve`)
vLLM-Ascend（vllm-ascend）	0.22.1rc1	社区维护的 Ascend NPU 硬件插件，通过 vLLM 硬件可插拔接口将 NPU 接入 vLLM，与 vLLM 版本对齐
torch-npu	2.10.0	PyTorch NPU operator library, paired with the torch version
CANN	9.0.0	昇腾软件栈（开发套件 + 算子包），容器内路径 `/usr/local/Ascend/cann-9.0.0`

本文推荐使用 all-in-one 镜像 quay.io/ascend/vllm-ascend:dots3-note-prev-a3-openeuler。该镜像内置 vLLM、vLLM-Ascend、torch-npu 和 CANN，无需自行安装。

4.2 镜像获取与构建¶

运行环境使用 vLLM-Ascend 官方 all-in-one 镜像，镜像中已包含 vLLM、vLLM-Ascend、torch-npu、CANN 和 NNAL。请根据硬件系列和 OS 选择镜像：

镜像	硬件	OS
`quay.io/ascend/vllm-ascend:dots3-note-prev`	Atlas A2	Ubuntu
`quay.io/ascend/vllm-ascend:dots3-note-prev-openeuler`	Atlas A2	openEuler
`quay.io/ascend/vllm-ascend:dots3-note-prev-a3`	Atlas A3	Ubuntu
`quay.io/ascend/vllm-ascend:dots3-note-prev-a3-openeuler`	Atlas A3	openEuler

直接使用官方预构建镜像（推荐）

以下命令均在宿主机执行：

export IMAGE=quay.io/ascend/vllm-ascend:dots3-note-prev-a3-openeuler
docker pull "$IMAGE"

启动前，先设置模型权重在宿主机上的实际路径：

export HOST_MODEL_PATH=/path/to/dots3_note
test -d "$HOST_MODEL_PATH"

Atlas A3 需要映射全部 16 个 davinci 设备并挂载驱动。下面的命令已展开全部设备，可直接复制；如宿主机目录不同，请先调整挂载源路径：

docker run -it --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --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/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -v "$HOST_MODEL_PATH":/models/dots3_note:ro \
    "$IMAGE" bash

容器默认工作目录为 /workspace，vLLM 与 vLLM-Ascend 已按开发模式（pip install -e）安装。进入容器后，设置后续命令共用的路径和服务名：

export MODEL_PATH=/models/dots3_note
export SERVED_NAME=dots3_note

如果后续需要读取本地图片、音频等媒体文件，还应在 docker run 时增加相应的只读目录挂载，并确保第 5、6 章使用的是容器内路径。

进入容器后，应先完成以下最小检查，再继续部署：

npu-smi info
python -c "import vllm, vllm_ascend, torch_npu; print(vllm.__version__)"
pip show vllm vllm-ascend torch-npu
test -d "$MODEL_PATH"

4.3 环境变量¶

在容器内、启动服务前设置以下环境变量。三种部署形态通用；变量说明来自 vLLM-Ascend 官方文档与常见实践：

export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export TASK_QUEUE_ENABLE=1
export CPU_AFFINITY_CONF=1
export HCCL_OP_EXPANSION_MODE=AIV

变量	说明
`ASCEND_RT_VISIBLE_DEVICES`	指定对进程可见的 NPU 设备编号（16 芯片全部可见）
`PYTORCH_NPU_ALLOC_CONF=expandable_segments:True`	启用虚拟内存特性，缓解推理过程中动态内存大小调整引起的碎片化（官方 OOM 排障建议）
`TASK_QUEUE_ENABLE=1`	启用 NPU 任务队列，异步下发算子
`CPU_AFFINITY_CONF=1`	启用 CPU 核绑定，减少跨 NUMA 访问
`HCCL_OP_EXPANSION_MODE=AIV`	集合通信算子展开到 AIV 核，提升多卡通信带宽（官方教程示例配置）

设置后先确认关键变量和预加载库：

echo "$ASCEND_RT_VISIBLE_DEVICES"

5 在线服务部署¶

本章一次启动一种服务形态。首次部署建议先启动 text-only 完成基础链路验证，再根据测试目标切换到 image 或 audio。

5.1 部署模式¶

三种部署形态对比如下：

形态	输入	典型场景	模态配置	上下文	KV 方式	MTP	每 worker 权重加载
text-only	文本	长上下文对话、文本推理	`--language-model-only`	32768	`--gpu-memory-utilization 0.92`	✅ MTP3	36.26 GB
image	文本 + 图片（≤ 7 张/请求）	MMMU 等视觉任务	`--limit-mm-per-prompt '{"image":7,"video":0,"audio":0}'`	32768	`--kv-cache-memory-bytes 2816M`	❌	~48.8 GB（+12.5 GB）
audio	文本 + 音频	MMAR 等音频任务	`--limit-mm-per-prompt '{"image":0,"video":0,"audio":1}'`	4096	`--kv-cache-memory-bytes 4G`	✅ MTP3	37.88 GB（+1.62 GB）

三种形态共用 16 芯片 TP16 + MoE 专家并行（EP16）。启动前确认：

test -d "$MODEL_PATH"
npu-smi info

切换形态时，先在服务终端按 Ctrl+C 正常停止进程，再检查是否仍有残留 Worker。只有正常停止未清理干净时，才依次使用以下命令：

pgrep -af 'VLLM::Worker|vllm serve'
pkill -TERM -f 'VLLM::Worker'

# Last resort when the process still cannot exit
pkill -9 -f VLLM::Worker

确认旧进程已经退出、8000 端口已释放后，再启动另一形态，避免残留进程占用 NPU 显存。

并发建议：纯文本 / 音频使用 --max-num-seqs 4；图像可使用 --max-num-seqs 16。图像形态的 2816MB KV 是 16 并发下 FusedMC2 计算峰值所允许的上限（每卡约 3.64 GiB）；将 KV 增大到 ≥3072MB 会导致 OOM。如果需要更大的 KV 容量，请将并发降低到 8。

5.2 text-only 在线部署¶

适用于纯文本对话、数学推理和长上下文场景。在容器内确认已执行第 4.3 节环境变量设置，然后启动：

vllm serve "$MODEL_PATH" \
    --served-model-name "$SERVED_NAME" \
    --tensor-parallel-size 16 \
    --enable-expert-parallel \
    --speculative-config \
      '{"method":"mtp","num_speculative_tokens":3,"enforce_eager":true}' \
    --additional-config \
      '{"enable_fused_mc2":1}' \
    --max-model-len 32768 \
    --gpu-memory-utilization 0.92 \
    --safetensors-load-strategy lazy \
    --enable-prefix-caching \
    --enable-chunked-prefill \
    --async-scheduling \
    --language-model-only \
    --max-num-batched-tokens 8192 \
    --max-num-seqs 4 \
    --default-chat-template-kwargs '{"enable_thinking":false}' \
    --generation-config vllm \
    --compilation-config \
      '{"mode":"VLLM_COMPILE","cudagraph_mode":"FULL_DECODE_ONLY","cudagraph_capture_sizes":[16],"max_cudagraph_capture_size":16}' \
    --port 8000

保持该终端运行。看到第 5.6 节列出的成功日志后，在另一个容器终端或宿主机终端执行健康检查，再进入第 6.1 节。

5.3 image 在线部署¶

视觉形态关闭 MTP（Model Runner V1 限制），并强制视觉预填充分块，避免峰值 OOM。MEDIA_DIR 必须是容器内路径，且包含第 6.2 节测试图片：

export MEDIA_DIR=/path/to/local-image-root   # Local image media root directory (whitelist)
test -d "$MEDIA_DIR"

在容器内启动：

vllm serve "$MODEL_PATH" \
    --served-model-name "$SERVED_NAME" \
    --tensor-parallel-size 16 \
    --enable-expert-parallel \
    --additional-config \
      '{"enable_fused_mc2":1}' \
    --max-model-len 32768 \
    --kv-cache-memory-bytes 2816M \
    --safetensors-load-strategy lazy \
    --enable-prefix-caching \
    --enable-chunked-prefill \
    --async-scheduling \
    --allowed-local-media-path "$MEDIA_DIR" \
    --limit-mm-per-prompt '{"image":7,"video":0,"audio":0}' \
    --mm-processor-cache-gb 0 \
    --mm-encoder-tp-mode data \
    --skip-mm-profiling \
    --max-num-batched-tokens 1024 \
    --max-num-seqs 16 \
    --generation-config vllm \
    --compilation-config \
      '{"mode":"VLLM_COMPILE","cudagraph_mode":"FULL_DECODE_ONLY","cudagraph_capture_sizes":[16]}' \
    --port 8000

保持该终端运行。通过第 5.6 节健康检查后，再进入第 6.2 节。

5.4 audio 在线部署¶

MEDIA_ROOT 必须是容器内路径，且覆盖服务需要读取的本地音频目录：

export MEDIA_ROOT=/path/to/local-audio-root   # Local audio media root directory (whitelist)
test -d "$MEDIA_ROOT"

在容器内启动：

vllm serve "$MODEL_PATH" \
    --served-model-name "$SERVED_NAME" \
    --tensor-parallel-size 16 \
    --enable-expert-parallel \
    --speculative-config \
      '{"method":"mtp","num_speculative_tokens":3,"enforce_eager":true}' \
    --additional-config \
      '{"enable_fused_mc2":1}' \
    --max-model-len 4096 \
    --kv-cache-memory-bytes 4G \
    --safetensors-load-strategy lazy \
    --enable-prefix-caching \
    --enable-chunked-prefill \
    --async-scheduling \
    --limit-mm-per-prompt '{"image":0,"video":0,"audio":1}' \
    --allowed-local-media-path "$MEDIA_ROOT" \
    --mm-encoder-tp-mode data \
    --max-num-batched-tokens 4096 \
    --max-num-seqs 4 \
    --default-chat-template-kwargs '{"enable_thinking":false}' \
    --generation-config vllm \
    --compilation-config \
      '{"mode":"VLLM_COMPILE","cudagraph_mode":"FULL_DECODE_ONLY","cudagraph_capture_sizes":[4,8,16],"max_cudagraph_capture_size":16}' \
    --port 8000

保持该终端运行。通过第 5.6 节健康检查后，再进入第 6.3 节。

5.5 启动参数说明¶

参数分类与描述参考 vLLM 官方 Engine Arguments 文档（vllm serve 的引擎参数）与 vLLM-Ascend 文档。以下表格覆盖三种形态用到的全部参数；排障时先核对本节，再修改启动命令。

5.5.1 通用参数（三种形态均使用）¶

参数	取值	说明
`--served-model-name`	`dots3_note`	API 中对外暴露的模型名，客户端请求必须使用该名称（默认 `default` 会 404）
`--tensor-parallel-size`	16	Tensor parallel group size; model weights are sharded across 16 chips
`--enable-expert-parallel`	开	MoE 层使用专家并行代替张量并行，各 rank 只加载本 EP 分片的专家权重
`--safetensors-load-strategy`	`lazy`	safetensors 权重加载策略：`lazy` 表示从文件内存映射、按需加载，降低启动峰值显存
`--enable-prefix-caching`	开	自动前缀缓存，相似 prompt 复用 KV cache，提升吞吐
`--enable-chunked-prefill`	开	预填充分块，避免单个长请求占满整个 batch，降低 TTFT 波动
`--async-scheduling`	开	异步调度，调度与推理解耦，提升吞吐
`--max-num-seqs`	text-only / audio 为 4；image 为 16	单批最大并发序列数；应与客户端并发及对应形态的显存预算匹配
`--generation-config`	`vllm`	生成配置来源：`vllm` 表示不加载模型自带 generation config，使用 vLLM 默认
`--compilation-config`	见 §5.5.4	编译/图捕获配置（`VLLM_COMPILE`、`FULL_DECODE_ONLY`、capture sizes）
`--additional-config`	参见§5.5.4	vLLM-Ascend附加配置（FusedMC2）
`--port`	8000	Service listening port

5.5.2 模态相关参数¶

参数	text-only	image	audio	说明
`--language-model-only`	✅	—	—	Load only the language model without loading multimodal encoders
`--limit-mm-per-prompt`	—	`{"image":7,...}`	`{"audio":1,...}`	每请求各模态输入数量上限；对应模态为 `0` 时，该 encoder 不加载（见 §5.1）。image 使用 7 是支持单请求最多 7 张图片；如果仅有单图场景，可收紧为 1
`--max-model-len`	32768	32768	4096	Model context length (prompt + output)
`--max-num-batched-tokens`	8192	1024	4096	Maximum tokens per batch; image uses 1024 to chunk large-image prefill, avoiding FusedMC2 peak OOM
`--allowed-local-media-path`	—	`MEDIA_DIR`	`MEDIA_ROOT`	Directory whitelist that allows the API to read local media files (security-sensitive; enable only in trusted environments)
`--mm-processor-cache-gb`	—	0	—	Multimodal processor cache size (GB)
`--mm-encoder-tp-mode`	—	`data`	`data`	Tensor parallel mode of the multimodal encoder (data = replicate the encoder on each rank)
`--skip-mm-profiling`	—	✅	—	Skip multimodal memory profiling
`--speculative-config`	MTP3	—	MTP3	Speculative decoding configuration (MTP3 + draft eager); not set for the image form (Model Runner V1 vision limitation)
`--default-chat-template-kwargs`	`enable_thinking:false`	—	`enable_thinking:false`	Default chat template arguments, disabling thinking output

5.5.3 KV cache 配置¶

形态	KV 方式	理由
text-only	`--gpu-memory-utilization 0.92`	自动 profiling，验证通过
image	`--kv-cache-memory-bytes 2816M`	FusedMC2 峰值每卡需要约 3.64 GiB；KV 过大（3328MB）会导致 OOM；配合 `--max-num-batched-tokens 1024` 对大图像 prefill 进行分块
audio	`--kv-cache-memory-bytes 4G`	单请求预算约为 1,131 tokens（文本 360 + 音频 259 + 输出 512）；1GB 仅提供 2,220 tokens，不足，而 4GB 可提供 8,956 tokens（2.19 倍）

为什么 image/audio 使用显式 --kv-cache-memory-bytes（实测）：自动 profiling 在 v0.22.1 下可以分配较大的 KV（audio 在 0.92 时得到 21,565 tokens，在 0.95 时得到 25,686 tokens），但实际 graph capture 阶段的峰值显存会超限并导致 worker 退出，日志表现为 Worker proc VllmWorker-* died unexpectedly。显式 KV 比自动 profiling 更保守，可为 graph capture 的约 3.76 GiB 峰值留出余量，因此是当前验证过的稳定方式。

如果坚持使用自动 profiling，可设置 VLLM_MEMORY_PROFILER_ESTIMATE_CUDAGRAPHS=0，关闭 ACL graph 内存估算后再尝试；该方式尚未在单模态下验证，不建议作为对外部署测试的默认配置。

5.5.4 编译与 vLLM-Ascend 附加配置¶

参数	取值	说明
`--compilation-config.mode`	`VLLM_COMPILE`	编译模式
`--compilation-config.cudagraph_mode`	`FULL_DECODE_ONLY`	ACL graph 仅捕获 decode 阶段，降低捕获峰值显存
`--compilation-config.cudagraph_capture_sizes`	text-only `[16]`；image `[16]`；audio `[4,8,16]`	图捕获 batch size；TP16 + 序列并行要求为 16 的倍数，audio 的 `[4,8]` 在启动时会被自动剔除
`--compilation-config.max_cudagraph_capture_size`	16（text-only / audio）	最大图捕获 batch size，`= max_num_seqs × (1 + num_speculative_tokens) = 4 × 4`
`--additional-config.enable_fused_mc2`	`1`	启用 FusedMC2（MoE `dispatch_ffn_combine` / `mega_moe` 融合算子）

5.6 服务验证¶

不要仅以进程存在作为启动成功的判断。先等待模型加载和 graph capture 完成；成功日志应包含：

GPU KV cache size: <tokens>
Maximum concurrency for ... tokens per request: ...
Graph capturing finished ...
Application startup complete.

然后在另一个终端执行健康检查：

curl -sf http://127.0.0.1:8000/v1/models

返回结果中应包含模型名 dots3_note 和对应形态的 max_model_len。同时确认服务终端没有 worker died、OOM 或持续重启日志。只有满足这两个条件，才视为服务就绪并进入第 6 章。

如果健康检查失败，按以下顺序排查：服务是否仍在加载、8000 端口是否监听、--served-model-name 是否正确，以及服务终端是否出现 NPU OOM 或 Worker 异常退出。

6 功能验证¶

功能验证的目标是用一条真实请求确认“客户端 → OpenAI 兼容接口 → 模型推理 → 响应返回”链路可用。请只执行与当前服务形态对应的小节。

6.1 text-only¶

在另一个终端执行：

curl http://127.0.0.1:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "dots3_note",
        "messages": [{"role": "user", "content": "What is the capital of France?"}],
        "temperature": 0,
        "max_tokens": 640
    }'

通过标准：HTTP 请求成功，响应中的 model 与服务名一致，choices[0].message.content 包含有效文本答案。

6.2 image¶

先确认测试图片位于第 5.3 节配置的 MEDIA_DIR 白名单内，并将下方路径替换为实际文件：

curl http://127.0.0.1:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "dots3_note",
        "messages": [{
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": "file:///path/to/image.png"}},
                {"type": "text", "text": "What is shown in this image?"}
            ]
        }],
        "temperature": 0,
        "max_tokens": 256
    }'

通过标准：HTTP 请求成功，响应包含与图片内容相关的有效文本，服务终端没有媒体路径拒绝、HTTP 400 或 OOM。

本地路径必须位于 --allowed-local-media-path 白名单内；base64 data URL 通过 HTTP 提交，不需要本地路径白名单。

6.3 audio¶

先确认 /path/to/audio.wav 存在。以下命令依赖支持 base64 -w0 的 GNU coreutils：

curl -s http://127.0.0.1:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d @<(printf '{
        "model":"dots3_note",
        "messages":[{
            "role":"user",
            "content":[
                {"type":"audio_url","audio_url":{"url":"data:audio/wav;base64,'; base64 -w0 /path/to/audio.wav; printf '"}},
                {"type":"text","text":"What does the speaker say?"}
            ]
        }],
        "temperature":0,
        "max_tokens":1024
    }')

通过标准：HTTP 请求成功，响应包含与音频内容相关的有效文本，服务终端没有音频解码、HTTP 400 或 OOM 错误。

7 精度评测（参考）¶

本章提供精度评测指导，仅供参考。本章覆盖 GSM8K 数据集，用于评测纯文本数学推理。本章中的评测命令仅供参考；第 3～5 章的部署与服务启动流程是运行本章命令的前提。

GSM8K用于评估纯文本数学推理能力。gsm8k数据集内置于evalscope中，会自动从ModelScope下载，并包含4-shot模板和\boxed{}答案提取。在评估之前，请确认第5.2节中的纯文本服务正在运行，且客户端请求中的模型名称必须为dots3_note（默认模型名称default会返回404）。

先在容器内安装 evalscope：

# Install inside the container (for domestic networks, use the Tsinghua mirror)
pip install evalscope -i https://pypi.tuna.tsinghua.edu.cn/simple

# Verify the installation
evalscope eval --help
python -c "import evalscope; print(evalscope.__version__)"

先运行冒烟测试，再运行全量评测：

# Smoke test (5 samples)
evalscope eval \
  --model dots3_note \
  --api-url http://127.0.0.1:8000/v1 \
  --api-key EMPTY \
  --eval-type openai_api \
  --datasets gsm8k \
  --generation-config '{"temperature": 0, "max_tokens": 2048}' \
  --eval-batch-size 4 \
  --limit 5

# Full evaluation (1319 samples, remove --limit)
evalscope eval \
  --model dots3_note \
  --api-url http://127.0.0.1:8000/v1 \
  --api-key EMPTY \
  --eval-type openai_api \
  --datasets gsm8k \
  --generation-config '{"temperature": 0, "max_tokens": 2048}' \
  --eval-batch-size 4

内置数据集需要访问 ModelScope。国内网络可在运行前设置 export MODELSCOPE_API_URL=https://modelscope.cn。

8 性能评测（参考）¶

本章提供性能评测指导，仅供参考。本章中的评测方法与命令仅供参考；第 3～5 章的部署与服务启动流程是运行本章命令的前提。

8.1 使用 AISBench¶

详细内容请参考使用 AISBench 进行性能评测。

8.2 使用 vLLM Benchmark¶

更多细节请参考 vllm benchmark。