rocm_vllm_nightly/README.md

# ROCm vLLM 容器化推理项目

基于镜像 `rocm/vllm:rocm7.12.0_gfx120X-all_ubuntu24.04_py3.12_pytorch_2.9.1_vllm_0.16.0` 的 Python 推理服务，适配双 AMD R9700 32G GPU。

## 项目目标

- 提供可容器化部署的模型推理 API
- 使用 vLLM 在双 GPU 上进行张量并行推理
- 提供健康检查、鉴权和参数化配置能力
- 暴露 `8001` OpenAI 标准协议接口，兼容 OpenClaw 调用

## 目录结构

```text
.
├── app
│   ├── config.py
│   ├── engine.py
│   ├── main.py
│   ├── model_catalog.py
│   └── schemas.py
├── .dockerignore
├── .env.example
├── config.json
├── docker-compose.yml
├── Dockerfile
└── requirements.txt
```

## 接口说明

### 1) 健康检查

- 方法：`GET /health`
- 返回：服务状态与当前模型名

### 2) 文本生成

- 方法：`POST /v1/generate`
- Header：可选 `x-api-key`（配置 `API_KEY` 后必填）
- 请求体：

```json
{
  "prompt": "请介绍一下ROCm和vLLM的关系",
  "max_tokens": 256,
  "temperature": 0.7,
  "top_p": 0.95,
  "repetition_penalty": 1.0,
  "stop": ["</s>"]
}
```

## 配置项

可通过 `.env` 配置，建议先复制 `.env.example`：

- `MODEL_CONFIG_FILE`：模型配置文件路径，默认 `config.json`
- `MODEL_KEY`：要启动的模型键，留空时使用 `config.json` 中 `default_model`
- `MODEL_NAME`：兜底模型名（仅在不使用配置文件时生效）
- `OPENAI_HOST`：OpenAI 协议服务监听地址，默认 `0.0.0.0`
- `OPENAI_PORT`：OpenAI 协议服务监听端口，默认 `8001`
- `TENSOR_PARALLEL_SIZE`：张量并行数，双卡建议为 `2`
- `GPU_MEMORY_UTILIZATION`：单卡显存利用率，建议 `0.90~0.95`
- `MAX_MODEL_LEN`：模型最大上下文长度
- `MAX_NUM_SEQS`：并发序列数量
- `MAX_TOKENS`：单请求最大生成长度
- `DTYPE`：精度类型，默认 `bfloat16`
- `API_KEY`：可选接口访问密钥

## config.json 说明

`config.json` 采用以下结构：

- 顶层 `default_model`：默认模型名
- 顶层其他键：每个模型的配置档位
- 每个模型至少建议包含：`hf_model_id`、`ctx`、`max_num_seqs`、`max_tokens`、`gpu_util`、`valid_tp`

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

1. `.env` 中 `MODEL_KEY`
2. `config.json` 中 `default_model`

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

- `model_name` ← `hf_model_id`
- `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
cp .env.example .env
```

2. 修改 `.env` 中的 `MODEL_KEY`，选择要启动的模型。

3. 构建并启动容器：

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

4. 验证自定义推理服务：

```bash
curl http://localhost:8000/health
```

5. 验证 OpenAI 协议服务：

```bash
curl http://localhost:8001/v1/models
```

## 推理请求示例

```bash
curl -X POST "http://localhost:8000/v1/generate" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\":\"请用三句话介绍大模型推理优化\",\"max_tokens\":128,\"temperature\":0.7}"
```

## OpenAI 协议示例（8001）

```bash
curl -X POST "http://localhost:8001/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${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 使用 `.env` 中 `API_KEY` 对应值
- 模型名使用 `config.json` 中 `served_model_name`
- 若使用工具调用，`config.json` 中应配置 `tool_call_parser` 与 `enable_auto_tool_choice`

## 双 AMD R9700 调优建议

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