> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/aphrodite-engine.md).

# Aphrodite 引擎

在 Clore.ai 上使用 Aphrodite Engine 在旧款和现代 GPU 上进行 LLM 推理

Aphrodite Engine 是一个基于 vLLM 构建的优化版 LLM 推理服务器，专为创意写作和角色扮演社区量身打造。它支持从 Pascal（GTX 1000 系列）开始的广泛 GPU，因此非常适合在较旧或预算有限的 CLORE.AI GPU 服务器上运行语言模型，而其他框架在这些环境下会失效。Aphrodite 还添加了 Kobold 兼容 API、Mirostat 采样，以及主流服务框架中没有的高级文本采样算法。

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

## 服务器要求

| 参数  | 最低                        | 推荐            |
| --- | ------------------------- | ------------- |
| 内存  | 16 GB                     | 32 GB+        |
| 显存  | 6 GB                      | 16 GB+        |
| 磁盘  | 40 GB                     | 150 GB+       |
| GPU | NVIDIA Pascal+（GTX 1060+） | RTX 3090，A100 |

{% hint style="info" %}
Aphrodite Engine 是少数支持 Pascal 代 GPU（GTX 10xx 系列）的 LLM 服务器之一。这使它非常适合 CLORE.AI 上配备旧款 GPU、租金较低的预算型服务器。
{% endhint %}

## 在 CLORE.AI 上快速部署

**Docker 镜像：** `alpindale/aphrodite-engine:latest`

**端口：** `22/tcp`, `2242/http`

**环境变量：**

| 变量                | 示例                                   | 描述                   |
| ----------------- | ------------------------------------ | -------------------- |
| `HF_TOKEN`        | `hf_xxx...`                          | 受限模型的 HuggingFace 令牌 |
| `APHRODITE_MODEL` | `mistralai/Mistral-7B-Instruct-v0.3` | 要加载的模型               |

## 逐步设置

### 1. 在 CLORE.AI 上租用 GPU 服务器

Aphrodite 的广泛 GPU 支持让你可以在 [CLORE.AI 市场](https://clore.ai/marketplace):

* **Pascal（GTX 1060–1080 Ti）**: 6–11 GB 显存——通过量化运行较小的 3B-7B 模型
* **Turing（RTX 2000 系列）**: 8–24 GB 显存——7B-13B 模型，性能更好
* **Ampere（RTX 3000/A100）**: 24–80 GB 显存——30B-70B 模型，满速运行
* **Ada（RTX 4000 系列）**: 16–24 GB 显存——最佳性能/成本比

### 2. 通过 SSH 连接

```bash
ssh -p <PORT> root@<SERVER_IP>
```

### 3. 拉取 Aphrodite Engine 镜像

```bash
docker pull alpindale/aphrodite-engine:latest
```

### 4. 启动 Aphrodite Engine

**使用 7B 模型的基础启动：**

```bash
docker run -d \\
  --name aphrodite \\
  --gpus all \\
  --ipc host \\
  -p 2242:2242 \\
  -v /root/models:/root/.cache/huggingface \\
  alpindale/aphrodite-engine:latest \\
  python3 -m aphrodite.endpoints.openai.api_server \\
    --model mistralai/Mistral-7B-Instruct-v0.3 \
    --host 0.0.0.0 \\
    --port 2242 \\
    --max-model-len 4096
```

**使用 HuggingFace 令牌（Llama 3）：**

```bash
docker run -d \\
  --name aphrodite \\
  --gpus all \\
  --ipc host \\
  -p 2242:2242 \\
  -v /root/models:/root/.cache/huggingface \\
  -e HF_TOKEN=hf_your_token_here \\
  alpindale/aphrodite-engine:latest \\
  python3 -m aphrodite.endpoints.openai.api_server \\
    --model meta-llama/Meta-Llama-3-8B-Instruct \\
    --host 0.0.0.0 \\
    --port 2242 \\
    --dtype bfloat16 \\
    --max-model-len 8192
```

**使用 GPTQ 量化（适用于显存有限的情况）：**

```bash
docker run -d \\
  --name aphrodite \\
  --gpus all \\
  --ipc host \\
  -p 2242:2242 \\
  -v /root/models:/root/.cache/huggingface \\
  alpindale/aphrodite-engine:latest \\
  python3 -m aphrodite.endpoints.openai.api_server \\
    --model TheBloke/Mistral-7B-Instruct-v0.2-GPTQ \\
    --host 0.0.0.0 \\
    --port 2242 \\
    --quantization gptq \\
    --max-model-len 4096
```

**使用 AWQ 量化：**

```bash
docker run -d \\
  --name aphrodite \\
  --gpus all \\
  --ipc host \\
  -p 2242:2242 \\
  -v /root/models:/root/.cache/huggingface \\
  alpindale/aphrodite-engine:latest \\
  python3 -m aphrodite.endpoints.openai.api_server \\
    --model casperhansen/mistral-7b-instruct-v0.2-awq \\
    --host 0.0.0.0 \\
    --port 2242 \\
    --quantization awq \
    --max-model-len 4096
```

**运行 GGUF 模型（Aphrodite 原生支持 GGUF）：**

```bash
# 首先下载 GGUF 文件
docker exec -it aphrodite bash -c "
pip install huggingface_hub
python3 -c \"from huggingface_hub import hf_hub_download; hf_hub_download(
    repo_id='TheBloke/Mistral-7B-Instruct-v0.2-GGUF',
    filename='mistral-7b-instruct-v0.2.Q4_K_M.gguf',
    local_dir='/root/models/mistral-gguf'
)\"
"

# 然后使用 GGUF 启动
docker run -d \\
  --name aphrodite \\
  --gpus all \\
  --ipc host \\
  -p 2242:2242 \\
  -v /root/models:/models \\
  alpindale/aphrodite-engine:latest \\
  python3 -m aphrodite.endpoints.openai.api_server \\
    --model /models/mistral-gguf/mistral-7b-instruct-v0.2.Q4_K_M.gguf \\
    --host 0.0.0.0 \\
    --port 2242 \\
    --tokenizer mistralai/Mistral-7B-Instruct-v0.2
```

### 5. 验证服务器

```bash
# 检查日志
docker logs -f aphrodite

# 健康检查
curl http://localhost:2242/health

# 列出已加载的模型
curl http://localhost:2242/v1/models
```

### 6. 通过 CLORE.AI HTTP 代理访问

CLORE.AI 订单面板提供了一个 `http_pub` 端口 2242 的 URL。请在你的客户端应用中使用它：

```
https://<order-id>-2242.clore.ai/v1
```

***

## 使用示例

### 示例 1：OpenAI 兼容聊天

```bash
curl http://localhost:2242/v1/chat/completions \\
  -X POST \\
  -H 'Content-Type: application/json' \\
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.3",
    "messages": [
      {"role": "system", "content": "你是一位专门从事奇幻小说的创意写作者。"},
      {"role": "user", "content": "开始写一个关于一条学会绘画的龙的短篇故事。"}
    ],
    "max_tokens": 500,
    "temperature": 0.9,
    "top_p": 0.95
  }'
```

### 示例 2：使用 Mirostat 的高级采样

Aphrodite 支持 Mirostat 采样，以生成更连贯的长文本：

```bash
curl http://localhost:2242/v1/completions \\
  -X POST \\
  -H 'Content-Type: application/json' \\
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.3",
    "prompt": "很久以前，在一座赛博朋克城市里，",
    "max_tokens": 400,
    "mirostat_mode": 2,
    "mirostat_tau": 5.0,
    "mirostat_eta": 0.1
  }'
```

### 示例 3：Kobold 兼容 API

Aphrodite 包含一个与 Kobold 兼容的端点，可供基于 KoboldAI 的前端使用：

```bash
# Kobold 生成端点
curl http://localhost:2242/api/v1/generate \\
  -X POST \\
  -H 'Content-Type: application/json' \\
  -d '{
    "prompt": "飞船进入了超空间，",
    "max_length": 200,
    "temperature": 0.8,
    "top_p": 0.92,
    "rep_pen": 1.15
  }'
```

### 示例 4：带自定义采样器的 Python 客户端

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:2242/v1",
    api_key="none",
)

# 使用定制采样器进行创意写作
response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.3",
    messages=[
        {
            "role": "user",
            "content": "写一首关于星辰之间寂静的诗。",
        }
    ],
    max_tokens=300,
    temperature=1.1,
    top_p=0.95,
    frequency_penalty=0.3,
    presence_penalty=0.2,
)

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

### 示例 5：批量补全

```python
import requests

BASE_URL = "http://localhost:2242"

prompts = [
    "古老的巫师打开了他的书卷并",
    "在霓虹灯照亮的小巷里，侦探注意到",
    "地球上最后一个 AI 对机器人说：",
]

for prompt in prompts:
    response = requests.post(
        f"{BASE_URL}/v1/completions",
        json={
            "model": "mistralai/Mistral-7B-Instruct-v0.3",
            "prompt": prompt,
            "max_tokens": 150,
            "temperature": 0.85,
            "top_k": 50,
            "top_p": 0.95,
            "repetition_penalty": 1.1,
        },
    )
    result = response.json()
    print(f"提示词：{prompt}")
    print(f"续写：{result['choices'][0]['text']}\n")
```

***

## 配置

### 关键启动参数

| 参数                         | 默认值         | 描述                                 |
| -------------------------- | ----------- | ---------------------------------- |
| `--model`                  | 必需          | 模型 ID 或本地路径                        |
| `--host`                   | `127.0.0.1` | 绑定地址                               |
| `--port`                   | `2242`      | 服务器端口                              |
| `--dtype`                  | `自动`        | `float16`, `bfloat16`, `float32`   |
| `--quantization`           | 无           | `awq`, `gptq`, `squeezellm`, `fp8` |
| `--max-model-len`          | 模型最大值       | 覆盖最大上下文长度                          |
| `--gpu-memory-utilization` | `0.90`      | GPU 内存占用比例                         |
| `--tensor-parallel-size`   | `1`         | 张量并行的 GPU 数量                       |
| `--max-num-seqs`           | `256`       | 最大并发序列数                            |
| `--trust-remote-code`      | false       | 允许自定义模型代码                          |
| `--api-keys`               | 无           | 用于身份验证的以逗号分隔的 API 密钥               |
| `--served-model-name`      | 模型名称        | 用于 API 响应的自定义名称                    |

### 添加 API 密钥认证

```bash
python3 -m aphrodite.endpoints.openai.api_server \\
  --model mistralai/Mistral-7B-Instruct-v0.3 \
  --host 0.0.0.0 \\
  --port 2242 \\
  --api-keys "mysecretkey1,mysecretkey2"
```

然后使用 `Authorization: Bearer mysecretkey1` 在请求中。

### 加载本地模型

```bash
# 挂载你的模型目录并引用它
docker run -d \\
  --name aphrodite \\
  --gpus all \\
  --ipc host \\
  -p 2242:2242 \\
  -v /path/to/your/model:/model \\
  alpindale/aphrodite-engine:latest \\
  python3 -m aphrodite.endpoints.openai.api_server \\
    --model /model \\
    --host 0.0.0.0 \\
    --port 2242
```

***

## 性能提示

### 1. 为你的 GPU 选择合适的量化方案

| GPU 显存 | 7B 模型       | 13B 模型      | 30B 模型  |
| ------ | ----------- | ----------- | ------- |
| 6 GB   | GPTQ/AWQ Q4 | ❌           | ❌       |
| 8 GB   | GPTQ Q4     | GPTQ Q4（紧张） | ❌       |
| 12 GB  | Float16     | GPTQ Q4     | ❌       |
| 16 GB  | Float16     | Float16     | GPTQ Q4 |
| 24 GB  | Float16     | Float16     | GPTQ Q4 |
| 48 GB  | Float16     | Float16     | Float16 |

### 2. 调整 GPU 内存利用率

```bash
--gpu-memory-utilization 0.93  # 尽量挤出更多 KV 缓存
```

先从较低值开始，如果没有 OOM 错误再逐步提高。

### 3. 在 Ampere+ GPU 上使用 bfloat16

```bash
--dtype bfloat16
```

比 float16 更好的数值稳定性，速度相同。

### 4. 针对角色扮演/创意写作进行优化

这些采样器非常适合叙事文本：

```json
{
  "temperature": 0.85,
  "top_p": 0.92,
  "top_k": 40,
  "repetition_penalty": 1.12,
  "mirostat_mode": 2,
  "mirostat_tau": 5.0
}
```

### 5. Pascal GPU 提示（GTX 10xx）

对于 Pascal GPU，避免使用 Flash Attention（不受支持）：

```bash
--dtype float16  # 如果出现 NaN 错误则使用 float32
--max-model-len 2048  # 缩短上下文以节省内存
```

***

## 故障排查

### 问题：“CUDA capability sm\_6x not supported”

Pascal GPU 需要特殊处理。使用：

```bash
--dtype float16
```

如果仍然失败，请检查镜像版本是否支持 Pascal：

```bash
docker pull alpindale/aphrodite-engine:v0.5.4  # 尝试特定版本
```

### 问题：“小显卡上内存不足”

```bash
--gpu-memory-utilization 0.85
--max-model-len 2048
--quantization gptq  # 或 awq
```

### 问题：token 生成缓慢

* 检查 GPU 是否 वास्तव वास्तव正在被使用： `nvidia-smi` 在容器内
* 启用更大的批量大小： `--max-num-seqs 64`
* 使用 AWQ 替代 GPTQ（推理更快）

### 问题：未找到模型 / 404 错误

始终检查你的模型名称是否完全匹配：

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

在请求中使用响应里的准确模型名称。

### 问题：输出重复

添加重复惩罚：

```json
{
  "repetition_penalty": 1.15,
  "frequency_penalty": 0.3
}
```

### 问题：Docker 容器静默退出

```bash
docker logs aphrodite 2>&1 | tail -100
# 常见原因：显存不足、模型路径无效
```

***

## 链接

* [GitHub](https://github.com/PygmalionAI/aphrodite-engine)
* [文档](https://aphrodite.pygmalion.chat)
* [Docker Hub](https://hub.docker.com/r/alpindale/aphrodite-engine)
* [支持的模型](https://github.com/PygmalionAI/aphrodite-engine?tab=readme-ov-file#supported-models)
* [CLORE.AI 市场](https://clore.ai/marketplace)

***

## Clore.ai GPU 推荐

| 使用场景         | 推荐 GPU           | Clore.ai 预计成本     |
| ------------ | ---------------- | ----------------- |
| 开发/测试        | RTX 3090（24GB）   | $0.07–0.21/gpu/hr |
| 生产环境（7B–13B） | RTX 4090（24GB）   | $0.14–0.42/gpu/hr |
| 大模型（70B+）    | A100 80GB / H100 | 约 $1.04/每 GPU/小时  |

> 💡 本指南中的所有示例都可以部署在 [Clore.ai](https://clore.ai/marketplace) GPU 服务器上。浏览可用 GPU 并按小时租用——无需承诺，拥有完整 root 访问权限。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/aphrodite-engine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.