14. ModelZoo.LLM.SGLang

14.1. ModelZoo.LLM.SGLang介绍

ModelZoo.LLm.SGLang 依托 MacaRT 底层推理引擎，方便用户在沐曦通用 GPU 上快速部署、调试、验证大语言模型，提供主流大模型在沐曦通用 GPU 下的 SGLang 高性能推理部署方案，适配对话问答、内容创作、代码生成、翻译、摘要、长文本处理、多模态大模型交互等场景。ModelZoo.LLm.SGLang 具有如下特性：

丰富的模型覆盖，兼容主流开源大参数基座模型与微调版本，可直接复用已有工程或快速接入新增同架构大模型完成部署验证。
完备的运行环境，配套专属 Docker 镜像，内置适配沐曦硬件的 MacaRT、SGLang 运行时、编译工具链全套软件栈。
完整的推理链路，封装文本分词、上下文缓存、并行推理、token 生成、结果解码、输出格式化全流程模块。
灵活的性能精度评估，通过启动命令与配置参数，一键评测不同量化精度、并行策略下模型的吞吐、延迟、首包响应速度与输出效果。
标准化统一参数配置，依托规范配置文件统一管理模型权重加载、量化方案、上下文窗口、批处理大小、前后处理、并行调度等全部部署参数。
沐曦硬件深度适配，原生支持沐曦 GPU 张量并行、KV Cache 优化、算子加速，充分释放 MacaRT 推理算力。

14.2. 模型评测条件

ModelZoo.LLm.SGLang 上快速实现模型部署的依赖条件如下：

安装有沐曦通用 GPU 板卡，兼容单卡、多卡张量并行部署；支持多卡集群分布式推理场景。
模型目录必须包含完整配置文件 config.json、分词器文件 tokenizer 系列文件。量化模型附带沐曦量化参数配置以及带有标注信息的数据集。

14.3. 代码目录结构及说明

ModelZoo.LLm.SGLang的目录结构和说明如下：

├── code(存放测试代码和脚本)
         ├── src(核心推理调度源码)
                ├── __init__.py
                ├── benchmark.py
                ├── connection.py
                ├── master.py
                ├── output.py
                ├── slave.py
                └── task.py
         ├── utils(公共工具库)
                ├── __init__.py
                └── utils.py
         ├── bench_sglang.py
         ├── run_ceval_client.py
         ├── pd_scripts(启动脚本)
                ├── generate_config.py
                ├── launch_servers.sh
                ├── template_decoder.sh
                ├── template_docker.sh
                └── template_prefill.sh
         ├── dataset(评测数据集目录)
                └── ceval_val_cmcc.jsonl
         ├── models（模型配置集合）
                ├── ${MODEL_NAME}
                        ├── config.json(单模型专属部署配置文件)
         ├── machines.json(集群硬件资源配置文件)
         └── readme.md（模型评测说明，注意每个模型类别的此文件，可能有特殊说明）

14.4. 源码、模型和环境准备

14.4.1. 源码镜像获取

操作步骤

进入沐曦软件中心，点击页面上方的Docker页签。
选择沐曦通用 GPU 的型号。
在左侧的分类导航栏，点击AI，然后选中ModelZoo下的 Modelzoo.LLM.SGLlang。
在筛选出的镜像列表上方，按需设置架构、操作系统、Python版本和框架版本。

通过上述操作选择 ModelZoo.LLm.SGLang 源代码的镜像，点击docker pull命令复制，获取此 Docker 镜像的拉取命令，可通过此命令在沐曦软件中心服务器上拉取此镜像。

进入容器，可在/workspace/ModelZoo.LLM.Inference目录查看 ModelZoo.LLm.SGLang 源代码。容器镜像的使用，参见《沐曦通用GPU用户指南》中“容器相关场景支持”章节。

14.4.2. 模型获取

模型权重可以从魔搭社区获取，若不存在则默认使用官方发布的权重。在 ModelZoo.LLm.SGLang 的 code/models 目录下已经存放了部分模型的 config 文件，其他模型可参考已有的 config 进行构建。更多说明见后文“修改模型配置文件”部分。

14.4.3. 服务器信息配置

节点信息和通用环境变量配置，参见表 14.1。

表 14.1 machine_info的节点配置
参数名称	说明
ip	IP 地址。
ifname	网络接口名。填写与 IP 地址匹配的网卡名称。可以在 host 机器上使用命令 ifconfig，然后查看 IP 地址对应的网卡名称。
ib_hcas	主机通道适配器。在 host 机器上执行 ibstat 命令，筛选并汇总所有名称以 mlx5 开头、端口状态为 Active 的网卡信息。

公共环境变量配置，配置默认路径在sgl/models/machines.json,参数说明参见表 14.2。

表 14.2 模型评测命令行参数解析
参数名称	说明
MACA_SMALL_PAGESIZE_ENABLE	页面大小优化
TRITON_ENABLE_MACA_OPT_MOVE_DOT_OPERANDS_OUT_LOOP	Triton 编译器优化
TRITON_ENABLE_MACA_CHAIN_DOT_OPT	Triton 编译器的链式 Dot 操作优化
MACA_DIRECT_DISPATCH	开启 direct dispatch 功能
MCDBG_GRAPH_LAUNCH_QUEUE_POLICY	设置 graph 内部创建的 stream/queue 的优先级为 high
MCDBG_GRAPH_LAUNCH_QUEUE_POLICY	设置 graph 内部创建的 stream/queue 的优先级为 high
PYTORCH_ENABLE_PG_HIGH_PRIORITY_STREAM	PyTorch 的优先级流（Priority Stream）优化
MACA_QUEUE_SCHEDULE_POLICY	MACA 队列调度策略设置

这里可以配置多组环境变量，以组名区分，如default_envs、specific_scenario_envs。针对不同的任务，可以通过 task 和 benchmark 配置中的 environment 字段添加组名（如specific_scenario_envs）来直接使用对应的环境变量。

注意：default_envs是针对当前版本提供的默认服务启动参数的最优环境变量。如果变更服务启动参数，比如由 TP 切分改为 DP 切分，当前默认的环境变量可能不是最优，可以尝试使用specific_scenario_envs，DP多场景切分推荐使用该组环境变量。

14.4.4. 修改模型配置文件

进入模型目录(以DeepSeek-R1-W8A8为例)：

cd /workspace/ModelZoo.LLM.Inference/sgl/code/models/DeepSeek-R1-W8A8/config.json

所有内置的模型 config.json 文件包含的都是当前版本的最佳性能参数，您只需要修改模型路径和机器等信息即可。通过参数可以配置测试任务为性能测试任务、精度测试任务或两者兼有。具体参数，参见表 14.3。

"benchmark_cmds": {
   "random": {
      "command_base": "python3 -m sglang.bench_serving --backend sglang --dataset-name random --random-range-ratio 1.0 --dataset-path /models/ShareGPT_V3_unfiltered_cleaned_split.json",
      "input_output_len": ["3072/1024"],
      "max_concurrency": ["1", "16", "32", "64", "128"],
      "num_prompt_times": 5
   }
},

表 14.3 性能测试参数说明
参数名称	说明
type	测试类型，支持 perf，ceval，mmlu，默认为 perf
input_output_len	输入 token 长度/输出 token 长度
num_prompt	并发请求数，为列表
max_concurrency	最大并发数，为列表。如果不设置该参数，则并发数和 num_prompt 相等。该参数必须和 num_prompt_times 一起使用，且不需要配置 num_prompt 参数
num_prompt_times	发送的请求数是最大并发数的多少倍，如果是单个数字，则会以 max_concurrency 里面的所有并发数乘上这个倍数作为 num_prompts。如果是个列表，则会将这个列表与 max_concurrency 列表对应，只有存在对应关系的 max_concurrency 会乘上这个列表的值作为 num_prompts

14.5. 模型评测步骤

14.5.1. 启动容器镜像

从发布的软件包中获取 ModelZoo.LLm.SGLang 容器镜像并启动。此容器镜像包含 ModelZoo.LLm.SGLang 模型评测所需的运行时软件栈。容器镜像的使用，参见《沐曦通用GPU用户指南》中“容器相关场景支持”章节。容器镜像启动时需要挂载用户的模型目录和数据集目录。

14.5.2. 配置机器信息

进入主节点容器内部，modelzoo 目录在 /workspace/ModelZoo.LLM.Inference。

修改 /workspace/ModelZoo.LLM.Inference/models/machines.json 使用的节点信息。此处 DeepSeek-R1-W8A8 使用的双机，只需要添加两个节点的信息。

"machine_info": [
   {
      "ip": "192.168.0.1",
      "ifname": "*****",
      "ib_hcas": "*****"
   },
   {
      "ip": "192.168.0.2",
      "ifname": "*****",
      "ib_hcas": "*****"
   }
   ],

需要注意的是，此处配置的机器的数量需要与任务执行所需的机器的数量一致。否则，多余配置的机器也需要作为从节点启动。

14.5.3. 配置任务信息

以 DeepSeek-R1-W8A8 为例，测试的任务是性能测试，那么修改/workspace/ModelZoo.LLM.Inference/models/DeepSeek-R1-W8A8/config.json。配置里面默认带的是本版本最佳性能参数，需要用户手动改 model_path，mtp model_path，ShareGPT_V3_unfiltered_cleaned_split.json（如有使用）的路径为镜像内部可以访问的路径。

如果想测试其他参数组合，可以在 launch_server 里面添加，会自动组合生成测试结果，且 json 支持添加多个任务；需要注意的是，如果测试其他组合出现 out of memory，需自行调小 mem-frac 的配置，查看当前使用 mem-frac 的大小方法：如果参数中有设置就是设置的值，如果参数中没设置，就在服务启动日志中搜索 mem_fraction_static 即可。

14.5.4. 执行模型评测

进入容器后进入 code 目录

cd /workspace/ModelZoo.LLM.Inference/code
python3 -m src.master --output-path ../outputs/ --tasks-config ../models/DeepSeek-R1-W8A8/config.json --machine-config ../models/machines.json --port 20005 --local-ip 192.168.1.2  #主节点
python3 -m src.slave --local-ip 192.168.1.10 --port 20005  #从节点

对 machines.json 文件中除主节点以外的“所有”从节点执行（无论从节点在此任务中有没有使用到）。以上面配置机器信息为例，对 IP 地址为 192.168.0.2 的设备执行即可。port 可自定义但需要保持主从一致。其中必选参数:–local-ip。该参数代表当前节点的 IP 地址，与 machines.json 中配置的从节点 IP 地址保持一致。可选参数:–port。该参数代表从节点监听的端口时，必须和主节点一致，默认是20000；在主节点执行，port 可自定义（保持主从一致），可不配置，默认 20000。

参数说明:

machine-config: 本次测试需要的机器信息。
output-path: 结果输出的根目录，最好是外部挂载到容器的目录，防止容器删了结果丢失。
tasks-config: 指定测试的配置文件或者目录，可以指定多个配置。
image-tag: 镜像标签，用于结果区分，默认为空。
specify-test: 从测试的配置文件中筛选出特定的任务类型执行，支持 perf,mmlu,ceval，默认是全部执行，可选择多个。
port: socket 的端口号，默认 20000。
timeout: 测试的超时时间，单位是秒，默认 1200 秒。
local-ip: 当前节点的 IP 地址，与 machines.json 中配置的主节点 IP 地址保持一致。