# vLLM

用于在 CLORE.AI GPU 上对生产工作负载进行高吞吐量大语言模型推理的服务器。

{% hint style="success" %}
所有示例都可以在通过以下方式租用的 GPU 服务器上运行： [CLORE.AI 市场](https://clore.ai/marketplace).
{% endhint %}

{% hint style="info" %}
**当前版本：v0.7.x** — 本指南涵盖 vLLM v0.7.3+。新功能包括对 DeepSeek-R1 的支持、具有自动工具选择的结构化输出、支持多 LoRA 服务以及改进的内存效率。
{% endhint %}

## 服务器要求

| 参数   | 最低       | 推荐     |
| ---- | -------- | ------ |
| 内存   | **16GB** | 32GB+  |
| 显存   | 16GB（7B） | 24GB+  |
| 网络   | 500Mbps  | 1Gbps+ |
| 启动时间 | 5-15 分钟  | -      |

{% hint style="danger" %}
**重要：** vLLM 需要大量的内存（RAM）和显存（VRAM）。内存少于 16GB 的服务器即使运行 7B 模型也会失败。
{% endhint %}

{% hint style="warning" %}
**启动时间：** 第一次启动会从 HuggingFace 下载模型（根据模型大小和网络速度需 5–15 分钟）。在此期间出现 HTTP 502 是正常的。
{% endhint %}

## 为什么选择 vLLM？

* **最快的吞吐量** - PagedAttention 实现 24 倍更高的吞吐量
* **可用于生产** - 开箱即用兼容 OpenAI API
* **连续批处理** - 高效的多用户服务
* **流式传输** - 实时令牌生成
* **多 GPU** - 针对大型模型的张量并行
* **多 LoRA** - 同时服务多个微调适配器（v0.7+）
* **结构化输出** - JSON 模式强制与工具调用（v0.7+）

## 在 CLORE.AI 上快速部署

**Docker 镜像：**

```
vllm/vllm-openai:v0.7.3
```

**端口：**

```
22/tcp
8000/http
```

**命令：**

```bash
vllm serve mistralai/Mistral-7B-Instruct-v0.2 --host 0.0.0.0 --port 8000
```

### 验证是否正常运行

部署后，在以下位置查找您的 `http_pub` URL： **我的订单**:

```bash
# 检查健康状态（首次运行可能需 5–15 分钟）
curl https://your-http-pub.clorecloud.net/health

# 列出模型（仅在模型加载后有效）
curl https://your-http-pub.clorecloud.net/v1/models
```

{% hint style="warning" %}
如果出现 HTTP 502 超过 15 分钟，请检查：

1. 服务器是否有 16GB+ RAM
2. 服务器是否有足够的显存以容纳模型
3. 针对受限模型是否设置了 HuggingFace 令牌
   {% endhint %}

## 访问您的服务

当部署在 CLORE.AI 上时，通过以下方式访问 vLLM： `http_pub` URL：

```bash
# 聊天补全
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.2",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

{% hint style="info" %}
全部 `localhost:8000` 下面的示例在通过 SSH 连接时可用。若需外部访问，请替换为你的 `https://your-http-pub.clorecloud.net/` URL。
{% endhint %}

## 安装

### 使用 Docker（推荐）

```bash
docker run -d --gpus all \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.7.3 \
    --model mistralai/Mistral-7B-Instruct-v0.2 \
    --host 0.0.0.0
```

### 使用 pip

```bash
pip install vllm==0.7.3

# 运行服务器
python -m vllm.entrypoints.openai.api_server \
    --model mistralai/Mistral-7B-Instruct-v0.2
```

## 支持的模型

| A100                          | 参数量      | 所需显存            | 所需内存（RAM） |
| ----------------------------- | -------- | --------------- | --------- |
| Mistral 7B                    | 7B       | 14GB            | 16GB+     |
| Llama 3.1 8B                  | 8B       | 16GB            | 16GB+     |
| Llama 3.1 70B                 | 70B      | 140GB（或 2×80GB） | 64GB+     |
| Mixtral 8x7B                  | 47B      | 90GB            | 32GB+     |
| Qwen2.5 7B                    | 7B       | 14GB            | 16GB+     |
| Qwen2.5 72B                   | 72B      | 145GB           | 64GB+     |
| DeepSeek-V3                   | 236B MoE | 多 GPU           | 128GB+    |
| DeepSeek-R1-Distill-Qwen-7B   | 7B       | 14GB            | 16GB+     |
| DeepSeek-R1-Distill-Qwen-32B  | 32B      | 64GB            | 32GB+     |
| DeepSeek-R1-Distill-Llama-70B | 70B      | 140GB           | 64GB+     |
| Phi-4                         | 14B      | 28GB            | 32GB+     |
| Gemma 2 9B                    | 9B       | 18GB            | 16GB+     |
| CodeLlama 34B                 | 34B      | 68GB            | 32GB+     |

## 服务器选项

### 基础服务器

```bash
vllm serve mistralai/Mistral-7B-Instruct-v0.2 \
    --host 0.0.0.0 \
    --port 8000
```

### 生产服务器

```bash
vllm serve mistralai/Mistral-7B-Instruct-v0.2 \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 1 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.9 \
    --max-num-seqs 256 \
    --enable-prefix-caching
```

### 使用量化（降低显存）

```bash
# AWQ 量化模型（使用更少显存）
vllm serve TheBloke/Mistral-7B-Instruct-v0.2-AWQ \
    --host 0.0.0.0 \
    --quantization awq
```

### 结构化输出与工具调用（v0.7+）

启用自动工具选择和结构化 JSON 输出：

```bash
vllm serve mistralai/Mistral-7B-Instruct-v0.2 \
    --host 0.0.0.0 \
    --enable-auto-tool-choice \
    --tool-call-parser mistral
```

在 Python 中使用：

```python
from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取某城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    messages=[{"role": "user", "content": "巴黎的天气如何？"}],
    tools=tools,
    tool_choice="auto"
)

# 解析工具调用
tool_call = response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
print(f"Tool: {tool_call.function.name}, Args: {args}")
```

通过响应格式获得结构化 JSON 输出：

```python
response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    messages=[{"role": "user", "content": "提取：John Smith，30 岁，软件工程师"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "occupation": {"type": "string"}
                },
                "required": ["name", "age", "occupation"]
            }
        }
    }
)
print(response.choices[0].message.content)
```

### 多 LoRA 服务（v0.7+）

同时为基础模型提供多个 LoRA 适配器服务：

```bash
vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --enable-lora \
    --lora-modules \
        sql-adapter=path/to/sql-lora \
        code-adapter=path/to/code-lora \
        chat-adapter=path/to/chat-lora \
    --max-lora-rank 64
```

通过模型名称查询特定 LoRA 适配器：

```python
# 使用 SQL 适配器
response = client.chat.completions.create(
    model="sql-adapter",
    messages=[{"role": "user", "content": "写一个 SQL 查询以查找前 10 名客户"}]
)

# 使用代码适配器
response = client.chat.completions.create(
    model="code-adapter",
    messages=[{"role": "user", "content": "写一个用于对列表排序的 Python 函数"}]
)
```

## DeepSeek-R1 支持（v0.7+）

vLLM v0.7+ 原生支持 DeepSeek-R1 蒸馏模型。这些推理模型会生成 `<think>` 在其推理过程中的标签。

### DeepSeek-R1-Distill-Qwen-7B（单 GPU）

```bash
vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-7B \
    --host 0.0.0.0 \
    --port 8000 \
    --max-model-len 16384
```

### DeepSeek-R1-Distill-Qwen-32B（双 GPU）

```bash
vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-32B \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 2 \
    --max-model-len 32768 \
    --gpu-memory-utilization 0.90
```

### DeepSeek-R1-Distill-Llama-70B（四 GPU）

```bash
vllm serve deepseek-ai/DeepSeek-R1-Distill-Llama-70B \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 4 \
    --max-model-len 32768
```

### 查询 DeepSeek-R1

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-R1-Distill-Qwen-32B",
    messages=[
        {
            "role": "user",
            "content": "求解：如果一列火车在 1.5 小时内行驶 120 公里，其速度为多少 m/s？"
        }
    ],
    max_tokens=2048,
    temperature=0.6
)

content = response.choices[0].message.content
# 响应包含 <think>...</think> 推理块，随后是答案
print(content)
```

解析 think 标签：

```python
import re

def parse_deepseek_r1_response(content: str) -> dict:
    """从 DeepSeek-R1 响应中提取思考与答案。"""
    think_match = re.search(r'<think>(.*?)</think>', content, re.DOTALL)
    thinking = think_match.group(1).strip() if think_match else ""
    answer = re.sub(r'<think>.*?</think>', '', content, flags=re.DOTALL).strip()
    return {"thinking": thinking, "answer": answer}

result = parse_deepseek_r1_response(content)
print("Thinking:", result["thinking"][:200], "...")
print("Answer:", result["answer"])
```

## API 使用

### 聊天补全（兼容 OpenAI）

```python
from openai import OpenAI

# 若需外部访问，请使用你的 http_pub URL：
client = OpenAI(
    base_url="https://your-http-pub.clorecloud.net/v1",
    api_key="not-needed"
)

# 或通过 SSH 隧道：
# client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    messages=[
        {"role": "user", "content": "解释量子计算"}
    ],
    max_tokens=500,
    temperature=0.7
)

print(response.choices[0].message.content)
```

### 流式传输

```python
stream = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    messages=[{"role": "user", "content": "写一首诗"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### cURL

```bash
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.2",
    "messages": [{"role": "user", "content": "你好！"}],
    "max_tokens": 100
  }'
```

### 文本补全

```bash
curl https://your-http-pub.clorecloud.net/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.2",
    "prompt": "法国的首都是",
    "max_tokens": 50
  }'
```

## 完整 API 参考

vLLM 提供兼容 OpenAI 的端点以及额外的实用端点。

### 标准端点

| 端点                     | 方法   | 4s          |
| ---------------------- | ---- | ----------- |
| `/v1/models`           | GET  | 列出可用模型      |
| `/v1/chat/completions` | POST | 聊天补全        |
| `/v1/completions`      | POST | 文本补全        |
| `/health`              | GET  | 健康检查（可能返回空） |

### 附加端点

| 端点            | 方法   | 4s            |
| ------------- | ---- | ------------- |
| `/tokenize`   | POST | 对文本进行分词       |
| `/detokenize` | POST | 将令牌转换为文本      |
| `/version`    | GET  | 获取 vLLM 版本    |
| `/docs`       | GET  | Swagger UI 文档 |
| `/metrics`    | GET  | Prometheus 指标 |

#### 对文本分词

在发送请求前用于计数令牌非常有用：

```bash
curl https://your-http-pub.clorecloud.net/tokenize \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.2",
    "prompt": "Hello world"
  }'
```

响应：

```json
{"count": 2, "max_model_len": 32768, "tokens": [9707, 1879]}
```

#### 反分词（Detokenize）

将令牌 ID 转回文本：

```bash
curl https://your-http-pub.clorecloud.net/detokenize \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.2",
    "tokens": [9707, 1879]
  }'
```

响应：

```json
{"prompt": "Hello world"}
```

#### 获取版本

```bash
curl https://your-http-pub.clorecloud.net/version
```

响应：

```json
{"version": "0.7.3"}
```

#### Swagger 文档

在浏览器中打开以获取交互式 API 文档：

```
https://your-http-pub.clorecloud.net/docs
```

#### Prometheus 指标

用于监控：

```bash
curl https://your-http-pub.clorecloud.net/metrics
```

{% hint style="info" %}
**推理模型：** DeepSeek-R1 等类似模型在回答中包含 `<think>` 显示模型在给出最终答案前推理过程的标签。
{% endhint %}

## 基准测试

### 吞吐量（每用户每秒令牌数）

| A100              | 速度  | 512x512 | 按日费率   | 4 小时会话 |
| ----------------- | --- | ------- | ------ | ------ |
| Mistral 7B        | 100 | 170     | 210    | 230    |
| Llama 3.1 8B      | 95  | 150     | 200    | 220    |
| Llama 3.1 8B（AWQ） | 130 | 190     | 260    | 280    |
| Mixtral 8x7B      | -   | 45      | 70     | 85     |
| Llama 3.1 70B     | -   | -       | 25（2x） | 45（2x） |
| DeepSeek-R1 7B    | 90  | 145     | 190    | 210    |
| DeepSeek-R1 32B   | -   | -       | 40     | 70（2x） |

*基准测试更新于 2026 年 1 月。*

### 上下文长度与显存

| A100     | 4K 上下文 | 8K 上下文 | 16K 上下文 | 32K 上下文 |
| -------- | ------ | ------ | ------- | ------- |
| 8B FP16  | 18GB   | 22GB   | 30GB    | 46GB    |
| 8B AWQ   | 8GB    | 10GB   | 14GB    | 22GB    |
| 70B FP16 | 145GB  | 160GB  | 190GB   | 250GB   |
| 70B AWQ  | 42GB   | 50GB   | 66GB    | 98GB    |

## Hugging Face 认证

针对受限模型（如 Llama 等）：

```bash
# 在命令中设置令牌
vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --env HUGGING_FACE_HUB_TOKEN=hf_xxxxx
```

或者将其设置为环境变量：

```bash
export HUGGING_FACE_HUB_TOKEN=hf_xxxxx
```

## GPU 要求

| A100 | 最小显存  | 最小内存     | 推荐              |
| ---- | ----- | -------- | --------------- |
| 7-8B | 16GB  | **16GB** | 24GB 显存，32GB 内存 |
| 13B  | 26GB  | 32GB     | 40GB 显存         |
| 34B  | 70GB  | 32GB     | 80GB 显存         |
| 70B  | 140GB | 64GB     | 2×80GB          |

## 下载所有所需的检查点

典型 CLORE.AI 市场价格：

| GPU     | 显存   | 价格/天       | 最适合       |
| ------- | ---- | ---------- | --------- |
| 速度      | 24GB | $0.30–1.00 | 7-8B 模型   |
| 512x512 | 24GB | $0.50–2.00 | 7-13B，快速  |
| 2s      | 40GB | $1.50–3.00 | 13-34B 模型 |
| 2s      | 80GB | $2.00–4.00 | 34-70B 模型 |

*价格以美元/天计。费率因提供商而异——请查看* [*CLORE.AI 市场*](https://clore.ai/marketplace) *A100 40GB*

## # 使用固定种子以获得一致结果

### 长时间出现 HTTP 502

1. **检查内存（RAM）：** 服务器必须有 16GB+ RAM
2. **检查显存（VRAM）：** 必须能容纳模型
3. **模型下载：** 首次运行会从 HuggingFace 下载（5–15 分钟）
4. **HF 令牌：** 受限模型需要认证

### 内存不足

```bash
# 减少内存使用
--gpu-memory-utilization 0.8
--max-model-len 4096
--max-num-seqs 64

# 或使用量化
--quantization awq
```

### 模型下载失败

```bash
# 检查 HF 令牌
echo $HUGGING_FACE_HUB_TOKEN

# 预先下载模型
huggingface-cli download mistralai/Mistral-7B-Instruct-v0.2
```

## vLLM 与其他方案比较

| 特性     | vLLM     | llama.cpp | Ollama |
| ------ | -------- | --------- | ------ |
| 吞吐量    | 最佳       | 良好        | 良好     |
| 显存使用   | 高        | 低         | 中等     |
| 易用性    | 中等       | 中等        | 简单     |
| 启动时间   | 5-15 分钟  | 1-2 分钟    | 30 秒   |
| 多 GPU  | 原生       | 有限        | 有限     |
| 工具调用   | 是（v0.7+） | 有限        | 有限     |
| 多 LoRA | 是（v0.7+） | 否         | 否      |

**在以下情况下使用 vLLM：**

* 优先考虑高吞吐量
* 为多用户提供服务
* 有足够的显存和内存
* 生产部署
* 需要工具调用 / 结构化输出

**在以下情况下使用 Ollama：**

* 需要快速设置
* 单用户
* 可用资源较少

## 使用以下方式支付

* [Ollama](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) - 启动更快的更简单替代方案
* [DeepSeek-R1](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/deepseek-r1) - 推理模型指南
* [DeepSeek-V3](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/deepseek-v3) - 最佳通用模型
* [Qwen2.5](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/qwen25) - 多语言模型
* [Llama.cpp](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/llamacpp-server) - 更低显存选项