rocm_vllm_nightly/README.md

# ROCm vLLM 容器化推理项目

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

## 项目目标

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

## 目录结构

```text
.
├── 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. 预拉取基础镜像（与官方文档一致）：

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

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

3. 构建并启动容器：

```bash
docker compose up -d --build
```

4. 验证 OpenAI 协议服务：

```bash
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）

```bash
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` 的强制升级，使用镜像内置依赖重建。
- 报错 `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`。