2. 推理服务部署快速上手
本章以Qwen模型为例描述如何用mx-arena快速部署沐曦千问推理服务。
部署推理服务需要使用沐曦的推理镜像，建议在开发者社区的镜像中心选择正式发布的镜像。
备注
有些旧版本镜像不支持非交互式启动。如果必须使用且启动推理时报找不到vllm，可通过 --env 参数增加 PATH 参数解决： --env="PATH=/opt/conda/bin:/opt/conda/condabin:$PATH"。
2.1. mx-arena 安装
mx-arena 下载安装，请参考3.1 安装 mx-arena。
2.2. 单节点部署千问推理
mx-arena 的serve custom命令用于将千问模型部署在一个节点上。
2.2.1. 核心参数说明
2.2.1.1. –gpus
用于指定需要的GPU个数。
2.2.1.2. –data-dir
用于将宿主机存放模型的路径挂载到容器中，宿主机路径和容器路径用 : 隔开。
2.2.1.3. –image
用于指定要运行的镜像。
2.2.2. 命令示例
可参考下面的命令参数，将上节的核心参数替换为实际使用的参数，快速拉起自己的千问模型。
mx-arena serve custom \
--name=qwen3-32b \
--version=v1 \
--gpus=8 \
--env="MACA_DIRECT_DISPATCH=1" \
--env="MACA_D2D_COPY_MODE=1" \
--env="MACA_MEMCPY_MODE=1" \
--share-memory=100Gi \
--data-dir=/mxstorage:/mxstorage \
--replicas=1 \
--restful-port=8035 \
--readiness-probe-action="httpGet" \
--readiness-probe-action-option="path: /health" \
--readiness-probe-action-option="port: 8035" \
--readiness-probe-option="initialDelaySeconds: 30" \
--readiness-probe-option="periodSeconds: 30" \
--image=mxcr.io/ai-release/maca/vllm-metax:0.25.0-maca.ai3.8.2.107-torch2.10-py310-ubuntu22.04-amd64 \
"vllm serve /mxstorage/pde_ai/models/llm/Qwen/Qwen3-32B \
-tp 8 --port 8035 \
--gpu-memory-utilization 0.9 \
--no-enable-prefix-caching \
--reasoning-parser qwen3"
2.2.3. 状态查询
可以通过下面的命令查看千问模型是否启动成功，千问模型的启动时间取决于模型大小。若AVAILABLE的值为1，则表明模型已启动成功。
(base) sw@gpunode-10-13-81-29@cluster-cp-0:~$ mx-arena serve list
NAME TYPE VERSION DESIRED AVAILABLE ADDRESS PORTS
qwen3-32b Custom v1 1 1 10.30.87.127 RESTFUL:8035
2.2.4. 使用示例
先获取服务的clusterIP，端口和模型路径，然后通过curl组合这些信息来访问千问模型服务。
# 获取服务的clusterIP及端口，下图显示IP为10.30.87.127, 端口为8035
(base) sw@gpunode-10-13-81-29@cluster-cp-0:~$ mx-arena serve list
NAME TYPE VERSION DESIRED AVAILABLE ADDRESS PORTS
qwen3-32b Custom v1 1 1 10.30.87.127 RESTFUL:8035
# 通过上一步获取的clusterIP和端口获取模型路径
(base) sw@gpunode-10-13-81-29@cluster-cp-0:~$ curl http://10.30.87.127:8035/v1/models
{"object":"list","data":[{"id":"/mxstorage/pde_ai/models/llm/Qwen/Qwen3-32B","object":"model","created":1791774342,"owned_by":"vllm","root":"/mxstorage/pde_ai/models/llm/Qwen/Qwen3-32B","parent":null ...}]}]}
# 通过clusterIP, 端口和模型路径访问千问模型，千问模型支持哪些HTTP接口，可以通过查看主POD的日志获取API列表。
(base) sw@gpunode-10-13-81-29@cluster-cp-0:~$ curl http://10.30.87.127:8035/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "/mxstorage/pde_ai/models/llm/Qwen/Qwen3-32B", "messages": [{"role": "user", "content": "你是谁"}], "max_tokens": 100,
"temperature": 0.7, "top_p": 0.9, "seed": 10}'
{"id":"chatcmpl-b1a9773e1e9cc767","object":"chat.completion","created":1786017410,"model":"/mxstorage/pde_ai/models/llm/Qwen/Qwen3-32B","choices":[{"index":0,"message":{"role":"assistant","content":null,"refusal":null,"annotations":null,"audio":null,
"function_call":null,"tool_calls":[],"reasoning":"\n好的，用户问“你是谁”，我需要先明确回答身份。作为通义千问，我应该介绍自己的基本功能和特点。同时，保持友好和开放的态度，鼓励用户进一步提问。要注意用简洁明了的语言，避免使用过于专业的术语，让用户容易理解。另外，可以提到
我的多语言支持和广泛的知识库，展示我的能力和优势。最后，确保回答符合格式要求，不使用markdown，保持口语化，分步骤解释思考"},"logprobs":null,"finish_reason":"length","stop_reason":null,"token_ids":null}],"service_tier":null,"system_fingerprint":null,"usage":
2.2.5. 删除推理服务
serve delete指令用于删除指定的推理服务，示例如下：
(base) sw@gpunode-10-13-81-29@cluster-cp-0:~$ mx-arena serve delete qwen3-32b
INFO[0001] The serving job qwen3-32bqwen3-32b with version v1 has been deleted successfully
2.3. 两节点部署千问模型
通过 mx-arena serve distributed命令将千问模型跨节点部署，这里以两节点为例进行说明。
2.3.1. 安装lws
mx-arena serve distributed命令依赖lws来进行跨节点部署，在使用该命令之前需要先部署lws服务。
获取lws服务有两种方式，一种方式是直接到lws官网下载合适版本的lws安装包进行安装。另一种方式是直接使用mx-arena安装时放在$HOME/mx-charts/lws目录下的0.8.0版本的安装包和镜像。
如果使用mx-arena自带的版本，请先将镜像docker load到宿主机上，然后执行如下安装指令：
#如果加载镜像时使用的repository和helm里默认的不一致，请正确设置repository
helm install lws ./lws-chart-0.0.0.tgz \
--namespace lws-system \
--create-namespace \
--wait --timeout 300s
2.3.2. 核心参数说明
2.3.2.1. –nic-configmap
通过 mx-arena 的serve distributed命令进行千问模型跨节点部署时， 需通过此参将包含各个节点网卡信息的configmap名传递给 mx-arena。
创建configmap的过程分为两个步骤：
创建配置文件mx_network_map
# 配置的格式为hostname=SOCKET_IFRAME:MCCL_IB_HCA，如果没有IB网卡也可以不配置MCCL_IB_HCA
# 示例中表示k8s集群有2个worker节点，同时配置了SOCKET_IFRAME和IB网卡
(base) sw@gpunode-10-13-81-29:~$ cat mx_network_map
gpunode-10-13-81-29.sde.metax-tech.com ens5f0np0:mlx5_0,mlx5_1,mlx5_2
gpunode-10-13-81-25.sde.metax-tech.com ens16f0:mlx5_0,mlx5_1,mlx5_2
创建configmap
awk '{print "--from-literal=" $1 "=" substr($0, index($0,$2))}' mx_network_map | xargs kubectl create configmap mx-nic
完成上述两个步骤后，可以通过–nic-configmap=mx-nic将包含网卡配置信息的configmap传递给 mx-arena。
2.3.2.2. –enable-hostnetwork
用于指定pod是否共享宿主机的网络，用法为：–enable-hostnetwork=true。
2.3.2.3. –master-gpus/–worker-gpus
用于指定master节点/worker节点需要的GPU资源数。
2.3.2.4. –masters/–workers
用于指定master/worker节点数。
2.3.3. 命令示例
下面是一个2节点集群的部署示例。
mx-arena serve distributed \
--name=vllm-qianwen35 \
--version=v3 \
--restful-port=8010 \
--image=mxcr.io/ai-release/maca/vllm-metax:0.25.0-maca.ai3.8.2.107-torch2.10-py310-ubuntu22.04-amd64 \
--data-dir=/mxstorage:/mxstorage \
--env="MACA_DIRECT_DISPATCH=1" --env="MACA_SMALL_PAGESIZE_ENABLE=1" --env="MACA_VLLM_ENABLE_MCTCLASS_FUSED_MOE=1" --env=MACA_VLLM_ENABLE_MCTCLASS_PYTHON_API=1 \
--masters=1 \
--master-gpus=8 \
--master-command="vllm serve /mxstorage/pde_ai/models/llm/Qwen/Qwen3.5-397B-A17B-W8A8 \
-tp 16 --trust-remote-code --max_num_batched_tokens 16384 \
--port 8010 \
--tool-call-parser qwen3_coder \
--reasoning-parser qwen3 \
--enable-auto-tool-choice \
--gpu-memory-utilization 0.9 \
--master-addr \$(LWS_LEADER_ADDRESS) \
--nnodes \$LWS_GROUP_SIZE --node-rank \$LWS_WORKER_INDEX \
--no-enable-prefix-caching" \
--workers=1 \
--worker-gpus=8 \
--worker-command="vllm serve /mxstorage/pde_ai/models/llm/Qwen/Qwen3.5-397B-A17B-W8A8 \
-tp 16 --trust-remote-code --max_num_batched_tokens 16384 \
--port 8010 \
--tool-call-parser qwen3_coder \
--reasoning-parser qwen3 \
--enable-auto-tool-choice \
--gpu-memory-utilization 0.9 \
--master-addr \$(LWS_LEADER_ADDRESS) --headless \
--nnodes \$LWS_GROUP_SIZE --node-rank \$LWS_WORKER_INDEX \
--no-enable-prefix-caching" \
--share-memory=100Gi \
--readiness-probe-action="httpGet" \
--readiness-probe-action-option="path: /health" \
--readiness-probe-action-option="port: 8010" \
--readiness-probe-option="initialDelaySeconds: 30" \
--readiness-probe-option="periodSeconds: 30" \
--readiness-probe-option="failureThreshold: 30" \
--nic-configmap=mx-nic \
--enable-hostnetwork=true
2.3.4. 状态查询
通过下面的命令查看千问模型是否启动成功，千问模型启动时间取决于模型大小。若AVAILABLE的值为1，则表明模型已启动成功。
(base) sw@gpunode-10-13-81-29:~$ mx-arena serve list
NAME TYPE VERSION DESIRED AVAILABLE ADDRESS PORTS
vllm-qianwen35 Distributed v3 1 1 10.30.224.169 RESTFUL:8010
可以通过下面的命令查看服务详细信息。
(base) sw@gpunode-10-13-81-29:~$ mx-arena serve get vllm-qianwen35
Name: vllm-qianwen35
Namespace: default
Type: Distributed
Version: v3
Desired: 1
Available: 1
Age: 17m
Address: 10.30.224.169
Port: RESTFUL:8010
Instances:
NAME STATUS AGE READY RESTARTS NODE
---- ------ --- ----- -------- ----
vllm-qianwen35-v3-distributed-serving-0 Running 17m 1/1 0 gpunode-10-13-81-25.sde.metax-tech.com
vllm-qianwen35-v3-distributed-serving-0-1 Running 17m 1/1 0 gpunode-10-13-81-29.sde.metax-tech.com
2.3.5. 使用示例
先获取服务的clusterIP，端口和模型路径，然后通过curl组合这些信息来访问千问模型服务。
# 获取服务的clusterIP及端口, 下图显示IP为10.30.224.169, 端口8010
(base) sw@gpunode-10-13-81-29:~$ mx-arena serve list
NAME TYPE VERSION DESIRED AVAILABLE ADDRESS PORTS
vllm-qianwen35 Distributed v3 1 1 10.30.224.169 RESTFUL:8010
# 通过上一步获取的clusterIP和端口获取模型路径
(base) sw@gpunode-10-13-81-29:~$ curl http://10.30.224.169:8010/v1/models
{"object":"list","data":[{"id":"/mxstorage/pde_ai/models/llm/Qwen/Qwen3.5-397B-A17B-W8A8","object":"model","created":1791774342,"owned_by":"vllm","root":"/mxstorage/pde_ai/models/llm/Qwen/Qwen3.5-397B-A17B-W8A8","parent":null ...}]}]}
# 通过clusterIP，端口和模型路径访问千问模型，千问模型支持哪些HTTP接口，可以通过查看主POD的日志获取API列表
(base) sw@gpunode-10-13-81-29:~$ curl http://10.30.224.169:8010/v1/chat/completions -H "Content-Type: application/json" -d
'{"model": "/mxstorage/pde_ai/models/llm/Qwen/Qwen3.5-397B-A17B-W8A8", "messages": [{"role": "user", "content": "你是谁"}], "max_tokens": 100, "temperature": 0.7, "top_p": 0.9, "seed": 10}'
{"id":"chatcmpl-843a1eb0b088bc6e","object":"chat.completion","created":1787553066,"model":"/mxstorage/pde_ai/models/llm/Qwen/Qwen3.5-397B-A17B-W8A8","choices":[{"index":0,"message":{"role":
"assistant","content":null,"refusal":null,"annotations":null,"audio":null,"function_call":null,"tool_calls":[],"reasoning":"嗯，用户问“你是谁”，这是一个很基础的身份确认问题。我需要简洁清晰地介绍自己的核心身份和关键能力。
\n\n首先，要明确说明我是 Qwen3.5，是阿里巴巴最新推出的通义千问大语言模型。然后需要概括我的主要升级点，比如上下文窗口、多语言支持、逻辑推理、视觉分析、代码能力、智能体规划等。\n\n接着要突出我的特色优势，比如长窗口精准掌控、多语言覆
盖、代码全栈"},"logprobs":null,"finish_reason":"length","stop_reason":null,"token_ids":null}],"service_tier":null,"system_fingerprint":null,"usage":{"prompt_tokens":11,"total_tokens":111,"completion_tokens":100,
"prompt_tokens_details":null},"prompt_logprobs":null,"prompt_token_ids":null,"kv_transfer_params":null}(base)
2.3.6. 删除推理服务
通过下列指令删除刚才部署的推理服务。
(base) sw@gpunode-10-13-81-29@cluster-cp-0:~$ mx-arena serve delete vllm-qianwen35
INFO[0001] The serving job vllm-qianwen35 with version v3 has been deleted successfully