1. 概要说明

1.1 文档概述

本部署手册适用于 GPUStack 平台在海光 DCU 设备上的部署。

1.2 应用场景

GPUStack 是一个开源的高性能模型服务 MaaS平台，面向异构算力与规模化推理场景，支持以下应用场景：

·        异构算力统一管理与推理服务化

支持基于 NVIDIA、AMD 以及海光 DCU等多种AI加速设备构建统一推理资源池，支持单节点与多节点异构集群管理。

·        多类型AI 模型的部署与运行

在统一平台中部署和运行 LLM、VLM、Embedding、Reranker、Image、Audio、OCR等多类AI 模型，满足企业多模型并行服务需求。

·        高性能推理与长序列场景优化

面向长上下文、多轮对话和Agent推理场景，集成推测解码加速与 KV Cache 扩展能力，降低首Token延迟与生成延迟，提升整体吞吐性能。

·        推理引擎选型与参数调优

基于长期积累的性能测试数据与最佳实践，辅助完成推理引擎选型和关键参数配置，降低人工调优成本，实现开箱即用的高性能推理。

·        可插拔推理后端与统一 API 接入

支持 vLLM、SGLang、MindIE 等多种内置推理后端和自定义推理后端的灵活接入与切换，并通过通用 API 代理无缝支持各种API，简化应用集成。

·        OpenAI 兼容 API 与应用对接

提供 OpenAI 兼容的 API 接口和各种通用API代理接口，支持快速对接各类 AI 应用系统和 Agent 框架。

·        模型试验与参数调测

提供图形化界面用于模型参数调试、性能观察与效果对比，加速模型验证与上线。

·        统一认证、访问控制与服务治理

支持 API Key 管理、模型级访问控制、用户与角色管理，并提供速率限制、Token 配额和容错机制，保障服务稳定与安全。

·        可观测性与使用度量

提供 GPU 与节点资源监控、模型健康状态与请求性能可视化仪表板，以及模型调用与 Token 使用统计，为运维、容量规划和成本管理提供支撑。

详细用户文档：https://docs.gpustack.ai/latest/

1.3 环境信息

1.4 GPUStack版本

安装版本为GPUStack v2.0.2版本，具体请参阅版本发布说明。

2. GPUStack安装

2.1 前置准备

以下操作适用于麒麟V10操作系统，其它操作系统根据实际情况调整检查指令。

1.      检查服务器时间，设置时区：

date
timedatectl set-timezone Asia/Shanghai

2.      检查并关闭系统防火墙：

systemctl status firewalld
systemctl disable firewalld --now
systemctl status firewalld

3.      确认Selinux已关闭（Disabled）：

getenforce
 
# 关闭指令
setenforce 0

4.      确认Docker已安装并正常启动，如未安装需要优先安装Docker：

docker info

5.      确认DCU驱动已安装并正常加载，版本要求rock-6.3以上，未安装请参考光合社区资源和教程进行安装https://download.sourcefind.cn:65024/6/main：

lsmod |grep -E "hydcu|hycu"

6.      确认/opt/hyhal和/opt/dtk目录已存在，如果不存在，若未安装DTK请参考光合社区资源和教程进行安装https://download.sourcefind.cn:65024/1/main。若安装在其它路径，请创建相应安装路径的符号链接：

ln -s /path/to/hyhal /opt/hyhal
ln -s /path/to/dtk   /opt/dtk

2.2 安装GPUStack管理端

GPUStack Server（管理端）作为整个模型服务平台的管理控制台，通过容器方式运行，支持分离部署在独立CPU节点（x86_64或arm64），也可以部署在AI算力节点中。

本文档统一部署在海光DCU设备节点，需要提前通过Docker联网下载以下镜像，以下从GPUStack国内镜像源下载：

# GPUStack镜像
docker pull --platform=linux/amd64 swr.cn-south-1.myhuaweicloud.com/gpustack/gpustack:v2.0.2
# Prometheus监控指标采集
docker pull --platform=linux/amd64 swr.cn-south-1.myhuaweicloud.com/gpustack/prometheus:latest
# Grafana监控仪表板展示
docker pull --platform=linux/amd64 swr.cn-south-1.myhuaweicloud.com/gpustack/grafana:latest
 
# 模型运行所需的推理引擎Runner镜像和Runtime镜像
docker pull --platform=linux/amd64 swr.cn-south-1.myhuaweicloud.com/gpustack/runner:dtk25.04-vllm0.9.2
docker pull --platform=linux/amd64 swr.cn-south-1.myhuaweicloud.com/gpustack/runtime:pause

镜像下载完成后，修改镜像tag：

docker tag swr.cn-south-1.myhuaweicloud.com/gpustack/runner:dtk25.04-vllm0.9.2 gpustack/runner:dtk25.04-vllm0.9.2
docker tag swr.cn-south-1.myhuaweicloud.com/gpustack/runner:dtk25.04-vllm0.9.2 quay.io/gpustack/runner:dtk25.04-vllm0.9.2
docker tag swr.cn-south-1.myhuaweicloud.com/gpustack/runtime:pause gpustack/runtime:pause
docker tag swr.cn-south-1.myhuaweicloud.com/gpustack/runtime:pause quay.io/gpustack/runtime:pause

进入附件的gpustack-docker-compose目录，通过Docker Compose配置文件启动GPUStack管理端：

cd gpustack-docker-compose/
IMAGE_REGISTRY=swr.cn-south-1.myhuaweicloud.com \
IMAGE_NAMESPACE=gpustack \
GPUSTACK_TAG=v2.0.2 \
PROMETHEUS_TAG=latest \
GRAFANA_TAG=latest \
docker compose -f docker-compose.server.yaml up -d

docker-compose.server.yaml中的：

     volumes:
      - gpustack-data:/var/lib/gpustack

将使用Docker Volume作为GPUStack的数据存储，需要确保Docker数据目录有足够空间，或者挂载到其它存储空间充足的主机目录，例如：

    volumes:
      - /data/gpustack-data:/var/lib/gpustack

如果需要部署已经预下载好的模型权重，配置卷挂载将模型权重挂载到容器中（强烈建议后续添加Worker计算节点时也配置相同路径的卷挂载），例如：

    volumes:
      - /data/gpustack-data:/var/lib/gpustack
      - /data/models:/data/models

检查GPUStack相关容器启动状态：

docker ps | grep gpustack

检查GPUStack Server容器启动日志：

docker logs -f gpustack-server

本机访问GPUStack Server验证是否可以访问，默认http 80端口：

curl http://localhost

查看初始登录密码：

docker exec -it gpustack-server cat /var/lib/gpustack/initial_admin_password

浏览器访问GPUStack，访问地址为DCU设备主机IP+默认http 80端口，以admin用户与上述步骤查询到的初始密码登录，确认GPUStack UI可正常访问，并设置用户密码，进入GPUStack管理控制台。

2.3 添加Worker计算节点

添加本机（8卡DCU设备）节点作为GPUStack Worker计算节点，用于节点资源与状态信息上报、响应模型部署任务与管理模型实例生命周期。

在GPUStack管理控制台，导航到集群菜单-添加集群，选择Docker类型，填写集群名称，例如K100_AI，保存进入下一步：

添加节点，设备厂商类型选择海光，然后下一步：

执行检查环境命令，确认通过后，下一步，指定Worker节点的IP地址，如果需要部署已经预下载好的模型权重，填写模型权重的路径，配置卷挂载将模型权重挂载到容器中（强烈建议给GPUStack Server也配置相同路径的卷挂载）：

复制以上docker run命令，在本机（8卡DCU设备）节点执行，然后检查GPUStack Worker容器启动状态：

    docker ps | grep gpustack-worker

检查GPUStack Worker容器启动日志：

    docker logs -f gpustack-worker

浏览器访问GPUStack控制台，检查Worker正常加入，DCU设备正常识别：

节点添加完成且状态正常，DCU设备正常识别，即可用于部署AI模型，具体步骤参见下节。

3. 模型部署（示例）

3.1        内置推理后端

针对海光DCU环境，GPUStack内置vLLM（vLLM-DTK）支持，当前最新版本为0.9.2，可从光源仓库搜索是否有新版本可用：https://sourcefind.cn/#/image/dcu/vllm?activeName=overview

如果有新版本镜像可以直接作为vLLM自定义版本添加：

GPUStack也支持可插拔后端，若海光DCU环境支持使用其它推理后端来提供模型推理服务，可以通过自定义后端方式在GPUStack中进行统一部署管理，参见3.2章节的示例。

以下为部分主流模型的部署示例。

3.1.1   大语言模型

3.1.1.1    Qwen3-14B

模型源：ModelScope（联网下载，离线需要手动下载模型挂载到GPUStack Server与Worker容器中，通过本地路径部署）

模型仓库：Qwen/Qwen3-14B

推理后端：vLLM

后端版本：0.9.2

调度方式：自动（可选手动选卡）

部署配置：

     后端参数：

     --reasoning-parser=deepseek_r1

     --max-model-len=32768

模型访问信息（部署菜单 - 模型 - 操作 - API 接入信息）：

3.1.1.2    Qwen3-32B-AWQ

模型源：ModelScope（联网下载，离线需要手动下载模型挂载到GPUStack Server与Worker容器中，通过本地路径部署）

模型仓库：Qwen/Qwen3-32B-AWQ

推理后端：vLLM

后端版本：0.9.2

调度方式：自动（可选手动选卡）

部署配置：

     后端参数：

     --reasoning-parser=deepseek_r1

     --max-model-len=32768

模型访问信息（部署菜单 - 模型 - 操作 - API 接入信息）：

3.1.1.3    Qwen3-30B-A3B-Instruct-2507

模型源：ModelScope（联网下载，离线需要手动下载模型挂载到GPUStack Server与Worker容器中，通过本地路径部署）

模型仓库：Qwen/Qwen3-30B-A3B-Instruct-2507

推理后端：vLLM

后端版本：0.9.2

调度方式：自动（可选手动选卡）

部署配置：

     后端参数：

     --tool-call-parser=hermes

     --enable-auto-tool-choice

     --max-model-len=32768

模型访问信息（部署菜单 - 模型 - 操作 - API 接入信息）：

3.1.1.4    Qwen2.5-Coder-14B-Instruct

模型源：ModelScope（联网下载，离线需要手动下载模型挂载到GPUStack Server与Worker容器中，通过本地路径部署）

模型仓库：Qwen/Qwen2.5-Coder-14B-Instruct

推理后端：vLLM

后端版本：0.9.2

调度方式：自动（可选手动选卡）

部署配置：

     后端参数：

     --max-model-len=32768

模型访问信息（部署菜单 - 模型 - 操作 - API 接入信息）：

3.1.2   多模态模型

3.1.2.1    Qwen2.5-VL-7B

模型源：ModelScope（联网下载，离线需要手动下载模型挂载到GPUStack Server与Worker容器中，通过本地路径部署）

模型仓库：Qwen/Qwen2.5-VL-7B-Instruct

推理后端：vLLM

后端版本：0.9.2

调度方式：自动（可选手动选卡）

部署配置：

     后端参数：

     --max-model-len=32768

     --limit-mm-per-prompt={"image": 4}

模型访问信息（部署菜单 - 模型 - 操作 - API 接入信息）：

3.1.3   Embedding模型

3.1.3.1    bge-m3

模型源：ModelScope（联网下载，离线需要手动下载模型权重，挂载到GPUStack Server与Worker容器中，通过本地路径部署）

模型仓库：BAAI/bge-m3

推理后端：vLLM

后端版本：0.9.2

调度方式：自动（可选手动选卡）

部署配置：

环境变量：

VLLM_USE_V1=0

模型访问信息（部署菜单 - 模型 - 操作 - API 接入信息）：

3.1.4   Reranker模型

3.1.4.1    bge-reranker-v2-m3

模型源：ModelScope（联网下载，离线需要手动下载模型权重，挂载到GPUStack Server与Worker容器中，通过本地路径部署）

模型仓库：BAAI/bge-reranker-v2-m3

推理后端：vLLM

后端版本：0.9.2

调度方式：自动（可选手动选卡）

部署配置：

环境变量：

VLLM_USE_V1=0

模型访问信息（部署菜单 - 模型 - 操作 - API 接入信息）：

3.2        自定义推理后端

3.2.1   OCR模型

3.2.1.1    pdf-parser - Mineru

模型源：本地路径（镜像内置模型，使用/tmp目录占位）

模型路径：/tmp

推理后端：自定义

镜像名称：harbor.sourcefind.cn:5443/dap/pdf-parser:mineru-2.5.4-v2.1

执行命令：python /root/server.py

调度方式：手动

GPU选择器：卡0

部署配置：

环境变量：

PORT=9911

模型访问信息：主机IP+9911端口

注意：暂不支持试验场测试

3.2.1.2    PaddleOCR-VL-0.9B

模型源：ModelScope（联网下载，离线需要手动下载模型挂载到GPUStack Server与Worker容器中，通过本地路径部署）

模型仓库：PaddlePaddle/PaddleOCR-VL

模型名称：PaddleOCR-VL-0.9B

推理后端：自定义后端（推理后端导入以下YAML，并在部署模型时选择后端为paddlex-genai-custom）

backend_name: paddlex-genai-custom
version_configs:
  latest-dcu:
    image_name: >-
      ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-dcu
    run_command: ''
    custom_framework: dtk
default_version: latest-dcu
default_backend_param: []
default_run_command: >-
  paddlex_genai_server --model_name {{model_name}} --model_dir {{model_path}}
  --host 0.0.0.0 --port {{port}} --backend vllm
is_built_in: false
description: null
health_check_path: null
built_in_version_configs: {}
framework_index_map:
  dtk:
    - latest-dcu

调度方式：自动（可选手动选卡）

访问设置：公开

模型访问信息（部署菜单 - 模型 - 操作 - API 接入信息）：

模型调用示例：

 python -m pip install paddlepaddle==3.2.2 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install "paddleocr[all]"
pip uninstall -y langchain langchain-community langchain-core langchain-openai
pip install "langchain<0.3" "langchain-community<0.3"
 
 paddleocr doc_parser --input ocr.png --vl_rec_backend vllm-server --vl_rec_server_url http://192.168.50.81/v1
 

3.2.2   语音模型

3.2.2.1    audio-parser

模型源：本地路径（镜像内置模型，使用/tmp目录占位）

模型路径：/tmp

推理后端：自定义

镜像名称： harbor.sourcefind.cn:5443/dap/audio-parser:dtk25.04.1-v1.1

执行命令：python /root/server.py

调度方式：手动

GPU选择器：卡2

部署配置：

环境变量：

PORT=9912

模型访问信息：主机IP+9912端口

注意：暂不支持试验场测试

3.2.3   图像模型

3.2.3.1    Kolors

模型源：本地路径（在模型文件菜单，从ModelScope预先下载Kwai-Kolors/Kolors）

模型路径：      /var/lib/gpustack/cache/model_scope/Kwai-Kolors/Kolors

推理后端：自定义

镜像名称：harbor.sourcefind.cn:5443/dap/dap-common:v2

执行命令：python /root/entrypoint.py

调度方式：手动

GPU选择器：卡2

部署配置：

环境变量：

SERVICE_TYPE=image

IMG_PORT=9913

IMG_MODEL_PATH=/var/lib/gpustack/cache/model_scope/Kwai-Kolors/Kolors

模型访问信息：主机IP+9913端口

注意：暂不支持试验场测试

4.  常见问题

4.1 安装问题

4.1.1   添加Worker后，检测不到DCU设备

请按照添加节点中的提示信息进行检查测试，并注意以下内容：

海光设备注意事项

1. 如果主机 /opt/hyhal 或 /opt/dtk 目录不存在，请创建指向海光安装路径的符号链接：

ln -s /path/to/hyhal /opt/hyhal

ln -s /path/to/dtk   /opt/dtk

2. 如果未能检测到设备，请尝试移除 --env ROCM_SMI_LIB_PATH=/opt/hyhal/lib。

如果调整映射目录，确保相关参数设置正确。例如，下面示例为错误设置，/opt/dtk-25.04 目录映射到容器内的路径为 /opt/dtk , env ROCM_PATH指向应当为容器内路径。

错误示例：

sudo docker run -d --name gpustack-worker \
      --restart=unless-stopped \
      --privileged \
      --network=host \
      --volume /var/run/docker.sock:/var/run/docker.sock \
      --volume gpustack-data:/var/lib/gpustack \
      --volume /opt/hyhal:/opt/hyhal:ro \
      --volume /opt/dtk-25.04:/opt/dtk:ro \
      --env ROCM_PATH=/opt/dtk-25.04 \
      --env ROCM_SMI_LIB_PATH=/opt/hyhal/lib \
      quay.io/gpustack/gpustack:v2.0.2 \
      --server-url http://xxx.xxx.xxx.xxx \
      --token gpustack_8a4**************************************************************

正确设置：

sudo docker run -d --name gpustack-worker \
      --restart=unless-stopped \
      --privileged \
      --network=host \
      --volume /var/run/docker.sock:/var/run/docker.sock \
      --volume gpustack-data:/var/lib/gpustack \
      --volume /opt/hyhal:/opt/hyhal:ro \
      --volume /opt/dtk-25.04:/opt/dtk:ro \
      --env ROCM_PATH=/opt/dtk \
      --env ROCM_SMI_LIB_PATH=/opt/hyhal/lib \
      quay.io/gpustack/gpustack:v2.0.2 \
      --server-url http://xxx.xxx.xxx.xxx \
      --token gpustack_8a4**************************************************************

注意：大家在使用GPUStack平台在DCU设备上部署模型服务过程中，如果遇到问题或者想购买GPUStack技术支持，可以联系：胡梦龙，135-6164-9610