模型部署教程模板¶

English | 中文

文档版本：v2.0
更新日期：2026-08-27

该模板旨在为模型部署文档撰写提供参考，使用者可遵循模板指引，系统性完成相关技术文档的构建工作。

标题规范：

• 正式版本：以模型名称命名，例如 DeepSeek-V3.2
• 实验性版本（0day/POC）：以模型名称命名并添加 (Experimental) 后缀，例如 Kimi-K3 (Experimental)

1 简介¶

资料写作要求：

• 用一段话同时涵盖模型的基本架构、核心特性、主要应用场景，以及本文档的目的与达成目标。
• 说明文档使用的vLLM-Ascend版本及模型的版本支持情况，若涉及0day或POC模型，须进行相关描述，说明模型的适配状态。

示例1：模型介绍

DeepSeek-V3.2 是一种稀疏注意力模型。其主要架构与 DeepSeek-V3.1 类似，但采用了稀疏注意力机制，旨在探索和验证在长上下文场景下训练和推理效率的优化方案。本文档将展示模型的主要验证步骤，包括支持的功能、功能配置、环境准备、单节点和多节点部署、准确性和性能评估。

示例2：版本信息与适配状态说明

• 正式版本：本文档基于vLLM-Ascend v0.13.0 版本进行验证和编写。当前模型（XXX）在该版本中已完整支持，v0.13.0 及更高版本均可稳定运行。如需使用最新特性（如PD分离、MTP等），建议使用最新的候选版本或正式版本。

• 实验性版本（0day/POC）：vLLM-Ascend 0.26.0rc 中的 Kimi K3 支持是一个初始实验性版本。它仅适用于按照本指南中的固定部署配置进行评估和验证。支持的场景、性能和配置接口可能在后续版本中发生变化；请勿将此指南视为生产支持承诺。

2 支持的特性¶

介绍该模型支持的特性，包括支持的硬件、量化方式、数据并行、长序列特性等。

资料写作要求：

• 采用表格形式，呈现模型和特性的支持情况。
• 或提供可跳转的交叉引用（推荐）。

示例1：特性支持列表

注意：此为简化示例，完整表格请参考完整特性矩阵。

示例2：引用

请参考模型支持列表，获取模型支持的特性。

请参考特性指南，获取功能配置信息。

3 前置准备¶

3.1 模型权重¶

资料写作要求：

• 说明部署所需的硬件资源和模型文件。
• 需同时提供 Hugging Face 和 ModelScope 两个来源的权重下载链接。
• 路径说明：提供下载链接后，须增加路径说明示例，明确提示用户记录实际存放路径，并说明该路径将在后续部署命令中使用。

示例：

路径说明： 请将模型权重下载至您指定的目录，并记录该路径。例如：/root/.cache/modelscope/hub/models/vllm-ascend/DeepSeek-V3.2-W8A8，后续部署命令中将使用 <YOUR_MODEL_PATH> 占位符，请替换为此处记录的路径。

3.2 验证多节点通信（可选）¶

示例：

若需部署多节点环境，请依据验证多节点通信环境指南进行通信验证。

4 安装¶

资料写作要求：

• 提供具体的安装步骤与命令（参数需解释含义、取值范围、单位等）。
• 版本号书写规范：优先使用占位符（值统一配置）；若使用固定值且该值与文档验证版本不一致，须加注释“请按实际版本替换”。
• 提供验证命令及预期状态：指导用户通过执行命令（如 docker ps）检查安装结果，说明成功时的状态码或输出特征，并提供完整的回显信息示例。
• 若模型仅支持单一硬件系列（如仅支持Atlas 300I DUO），须在安装章节开头明确说明；若支持多硬件系列（如 A3/A2 系列），须使用标签页语法将它们分开展示，并按新机型优先的顺序排列。关于 MkDocs 与 Sphinx 框架在标签页语法上的具体差异，请参阅 语法补充。

4.1 Docker镜像安装¶

示例：（关于 MkDocs + Material 标签语法（=== "label"）和 Sphinx + MyST-Parser 标签语法（::::{tab-item}），请参阅语法补充。

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0
docker run ...

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0
docker run ...

4.2 源码安装¶

示例： 略

5 在线服务化部署¶

资料写作要求（以下要求适用于第五章节的各子章节）：

• 在启动命令下方提供常见问题指引，如公共FAQ中已有描述可直接链接呈现。
• 模型路径规范：部署命令中，模型路径须使用变量占位符 <YOUR_MODEL_PATH>，并注释提示用户根据3.1章节记录的路径替换该占位符。
• 商发模型的配置脚本需要和版本出口某个场景下最优性能保持一致（禁止使用未经验证调优的通用启动脚本）。
• 若模型仅支持单一硬件系列（如仅支持Atlas 300I DUO），须在安装章节开头明确说明；若支持多硬件系列（如 A3/A2 系列），须使用标签页语法将它们分开展示，并按新机型优先的顺序排列。关于 MkDocs 与 Sphinx 框架在标签页语法上的具体差异，请参阅 语法补充。
• 提供成功启动时的输出样例

5.1 单机在线部署¶

资料写作要求：

• 说明单机部署的架构特点与适用场景
• 提供启动命令模板和关键参数说明

示例：

单机部署将Prefill与Decode在同一节点内完成，适用于XXX场景。

启动命令：

# 请将 <YOUR_MODEL_PATH> 替换为您在3.1节中记录的实际存放路径
vllm serve <YOUR_MODEL_PATH> \
  --port 8000 \
  --served-model-name DeepSeek-V3.2-W8A8

成功启动时输出为：

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.

常见问题提示：如遇xxx问题，请参考公共FAQ进行检查。

5.2 多机在线部署¶

资料写作要求：

• 说明多机部署的架构特点与适用场景。
• 提供各节点的启动流程、关键配置及部署验证说明。

示例： 略

5.3 多机PD分离部署¶

资料写作要求：

• 说明PD分离架构的原理与适用场景。
• 提供启动流程、关键配置及部署验证说明。

示例： 略

5.4 特殊部署形态（可选）¶

资料写作要求：

• 若模型存在非标准部署形态（如embedding模型的离线批处理、reranker模型的低延迟在线服务等），需在文档中明确体现对应部署方案。
• 可参考本章5.1、5.2、5.3节进行扩展。

6 功能验证¶

资料写作要求：

• 指导用户如何在服务启动后，通过发送推理请求验证模型功能是否正常、推理结果是否正确。
• 说明预期输出特征（如返回包含 choices 字段且内容合理），并提供完整的回显信息示例。

示例：

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

       curl http://<node0_ip>:<port>/v1/completions \
           -H "Content-Type: application/json" \
           -d '{
               "model": "deepseek_v3.2",
               "prompt": "The future of AI is",
               "max_tokens": 50,
               "temperature": 0
           }'

预期结果：略（按实际输出书写即可）。

7 精度评估¶

资料写作要求： 介绍评估模型输出质量（精度）的标准化方法及工具，以下提供两种精度评估方法作为示例；或直接链接现有文档进行呈现。

7.1 AISBench的使用¶

详情请参考Using AISBench。

7.2 Language Model Evaluation Harness的使用¶

以gsm8k数据集作为测试数据集为例，在线模式下运行DeepSeek-V3.2-W8A8的精度评估。

1. lm_eval安装请参考Using lm_eval。
2. 运行lm_eval执行精度评估。

lm_eval \
  --model local-completions \
  --model_args model=/root/.cache/Eco-Tech/DeepSeek-V3.2-w8a8-mtp-QuaRot,base_url=http://127.0.0.1:8000/v1/completions,tokenized_requests=False,trust_remote_code=True \
  --tasks gsm8k \
  --output_path ./

8 性能评估¶

资料写作要求： 要求同第七章节精度评估，需提供基本命令示例及完整的回显信息。 示例： 略

9 性能调优¶

9.1 推荐配置¶

资料写作要求：

提供模型在三个典型场景下的推荐配置（长序列、低时延、高吞吐），需明确说明配置的非全局最优性，并引导用户根据实际进行调优；以下示例中的详细配置表格，按实际情况选择相对应的列进行呈现。

示例：

说明：以下配置基于特定测试环境验证，仅作参考。实际最优配置取决于最大输入输出长度、前缀缓存命中率、精度要求、部署机器配比等因素，建议根据实际参考9.2章节进行调优。

详细配置

完整启动命令及参数含义请参考第5章部署示例。

9.2 调优思路¶

9.2.1 模型特有优化¶

资料写作要求：

针对模型特有优化，需总结其关键优化技术和调参经验（若第五章节关键参数介绍已明确说明，可省略）。

示例： 需显式开启的优化

9.2.2 通用调优参考¶

资料写作要求：

若不涉及特殊调优可直接给出特性叠加表和优化与调优链接供参考。

示例：

请参考优化与调优获得调优方法。 请参考特性矩阵获得详细特性说明。

10 FAQ¶

资料写作要求：

• 在章节开头添加说明：常见环境、安装、通用参数问题请参考公共FAQs；本章仅收录本模型特有疑难问题。
• 针对本模型特有疑难问题 ，提供以下要素：问题现象描述、原因分析、解决措施。