109 lines
3.7 KiB
Markdown
109 lines
3.7 KiB
Markdown
# 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`）
|
||
- `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`
|
||
|
||
启动时会按以下优先级选模型：
|
||
|
||
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. 修改 `config.json` 中的 `models.selected` 与服务参数。
|
||
|
||
2. 构建并启动容器：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
3. 验证 OpenAI 协议服务：
|
||
|
||
```bash
|
||
curl http://localhost:<services.openai.port>/v1/models
|
||
```
|
||
|
||
## 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\":\"Qwen3.5-35B-A3B-GPTQ-Int4\",\"messages\":[{\"role\":\"user\",\"content\":\"你好，介绍一下你自己\"}],\"temperature\":0.7}"
|
||
```
|
||
|
||
## OpenClaw 调用说明
|
||
|
||
- Base URL 使用 `http://<服务器IP>:8001/v1`
|
||
- API Key 使用 `config.json` 中 `api_key`
|
||
- 模型名使用 `config.json` 中 `models.profiles.<模型名>.served_model_name`
|
||
- 若使用工具调用，`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 type ... Transformers does not recognize this architecture` 时，说明当前模型与镜像内依赖不兼容，建议更换模型或升级镜像版本。
|
||
- 若模型目录存在但仍加载失败，检查挂载路径是否为 `/opt/model:/opt/model:ro`，并确认容器内可见模型文件。
|
||
- 如果看到 `No services to build`，说明未触发重建；需要先执行 `docker compose build --no-cache` 再 `up`。
|