ROCm vLLM 容器化推理项目

基于镜像 docker.1ms.run/vllm/vllm-openai-rocm:latest 的 Python + vLLM 推理服务，适配双 AMD R9700 32G GPU。

项目目标

• 提供可容器化部署的模型推理 API
• 使用 vLLM + ROCm 在 AMD GPU 上执行推理
• 暴露 8001 OpenAI 标准协议接口，兼容 OpenClaw 调用

目录结构

.
├── app
│   ├── config.py
│   ├── model_catalog.py
│   ├── start_openai.py
│   └── schemas.py
├── .dockerignore
├── config.json
├── docker-compose.yml
├── Dockerfile
└── requirements.txt

配置项

项目只读取一个配置文件：config.json。

• services.openai.host / services.openai.port：OpenAI 协议服务监听地址与端口（默认 0.0.0.0:8001）
• public_model_name：对外固定模型名，切换底层模型时可保持调用方参数不变
• default_enable_thinking：服务端默认思考开关，默认 false（即调用方不传时也关闭）
• reasoning_enabled：是否启用推理解析器参数注入，默认 false
• api_key：OpenAI 接口访问密钥
• tensor_parallel_size：张量并行数，双卡建议 2
• dtype：推理精度，默认 bfloat16
• model_root：本地模型根目录，建议 /opt/model
• offline_mode：保留字段，当前实现固定只走离线本地模型
• models.selected：当前生效模型，留空时回退到 models.default

config.json 说明

config.json 采用以下结构：

• models.default：默认模型名
• models.selected：当前生效模型名
• models.profiles：模型配置集合
• 每个模型必须包含：local_path，并建议补充 ctx、max_num_seqs、max_tokens、dtype、quantization、reasoning_parser

启动时会按以下优先级选模型：

1. config.json 中 models.selected
2. config.json 中 models.default

模型被选中后，会自动覆盖运行参数，包括：

• model_name ← local_path（相对路径会自动拼接 model_root）
• max_model_len ← ctx
• max_num_seqs ← max_num_seqs
• max_tokens ← max_tokens
• gpu_memory_utilization ← gpu_util
• trust_remote_code ← trust_remote
• enforce_eager ← enforce_eager

部署步骤

1. 预拉取基础镜像（与官方文档一致）：

docker pull docker.1ms.run/vllm/vllm-openai-rocm:latest

2. 修改 config.json 中的 models.selected 与服务参数。

3. 构建并启动容器：

docker compose up -d --build

4. 验证 OpenAI 协议服务：

curl http://localhost:<services.openai.port>/v1/models

当前 docker-compose.yml 已按官方运行参数适配：

• --group-add=video → group_add: [video]
• --ipc=host → ipc: host
• --cap-add=SYS_PTRACE → cap_add: [SYS_PTRACE]
• --security-opt seccomp=unconfined → security_opt: [seccomp=unconfined]
• --device /dev/kfd 与 --device /dev/dri → devices
• -e HF_HOME=/app/models 在本项目等效为 HF_HOME=/opt/model

OpenAI 协议示例（8001）

curl -X POST "http://localhost:8001/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <config.json中的api_key>" \
  -d "{\"model\":\"Qwen_local_model\",\"messages\":[{\"role\":\"user\",\"content\":\"你好，介绍一下你自己\"}],\"temperature\":0.7,\"chat_template_kwargs\":{\"enable_thinking\":false}}"

OpenClaw 调用说明

• Base URL 使用 http://<服务器IP>:8001/v1
• API Key 使用 config.json 中 api_key
• 模型名固定使用 config.json 中 public_model_name（默认 Qwen_local_model）
• 思考模式按请求控制：chat_template_kwargs.enable_thinking=false/true
• 若调用方未传 chat_template_kwargs.enable_thinking，服务端使用 default_enable_thinking 兜底
• 仅当模型需要推理解析器时，再将 config.json 中 reasoning_enabled 设为 true
• 若使用工具调用，config.json 中应配置 tool_call_parser 与 enable_auto_tool_choice
• 服务强制离线模式，不会回退到 Hugging Face 远程下载
• 所有路径按 Ubuntu 规范填写，本地模型建议使用 /opt/model/<模型目录>

双 AMD R9700 调优建议

• 首选 TENSOR_PARALLEL_SIZE=2
• 首次部署建议设置 GPU_MEMORY_UTILIZATION=0.90，稳定后再调高
• 若模型较大且吞吐压力高，可逐步调低 MAX_MODEL_LEN 或 MAX_NUM_SEQS
• 确保宿主机已正确安装 ROCm 驱动并暴露 /dev/kfd 与 /dev/dri

常见故障排查

• 报错 Model architectures ['Qwen3_5MoeForConditionalGeneration'] are not supported for now 或 The Transformers implementation ... is not compatible with vLLM 时，说明当前 vLLM 栈与该模型架构不兼容，需切换到兼容模型或改用其他推理后端。
• 报错 StrictDataclassClassValidationError 且包含 validate_rope / unsupported operand type(s) for -=: 'set' and 'list' 时，移除 Dockerfile 中对 transformers --upgrade --pre 的强制升级，使用镜像内置依赖重建。
• 报错 moe_wna16 quantization is currently not supported in rocm 时，将该模型的 quantization 改回 gptq。
• 报错 model config (gptq) does not match quantization argument (gptq_marlin) 时，将该模型配置改为 dtype=float16 且 quantization=gptq。
• 报错 RPC call to sample_tokens timed out 或出现 GPU core dump 时，先下调模型配置为更稳参数：ctx=32768、max_num_seqs=4、max_tokens=2048、gpu_util=0.90，并开启 enforce_eager=true。
• 若模型目录存在但仍加载失败，检查挂载路径是否为 /opt/model:/opt/model:ro，并确认容器内可见模型文件。
• 如果看到 No services to build，说明未触发重建；需要先执行 docker compose build --no-cache 再 up。