# Mistral.rs

**用 Rust 编写的超快大型语言模型推理** — 生产就绪服务器，支持 GGUF、GGML、SafeTensors 和兼容 OpenAI 的 API。

> 🦀 **采用 Rust 构建** 以获得最大性能 | 支持 GGUF 和视觉模型 | Apache-2.0 许可证

***

## 什么是 Mistral.rs？

Mistral.rs 是一个完全用 Rust 编写的高性能大型语言模型推理引擎， **Rust**。最初专注于 Mistral 模型，现在支持现代大型语言模型的整个生态。Rust 基础提供：

* **零成本抽象** — 推理期间没有垃圾回收暂停
* **内存安全** — 没有空指针异常或内存泄漏
* **确定性性能** — 一致的延迟，没有 JVM/Python 开销
* **编译时优化** — 在构建时优化的 SIMD、多线程和 GPU 内核

### 主要功能

* **GGUF 支持** — 运行任何量化模型（Q4\_K\_M、Q8\_0 等）
* **ISQ（就地量化）** — 在加载时即时进行量化
* **PagedAttention** — 高效的 KV 缓存与连续批处理
* **视觉语言模型** — 支持 LLaVA、Phi-3 Vision、Idefics
* **推测式解码** — 使用草稿模型更快的推理
* **X-LoRA** — 可扩展的微调适配器支持
* **兼容 OpenAI 的 REST API** — 即插即用替代方案

### 支持的模型系列

| 系列              | 格式               | 引擎        |
| --------------- | ---------------- | --------- |
| Llama 2/3       | GGUF、SafeTensors | Rust CUDA |
| Mistral/Mixtral | GGUF、SafeTensors | Rust CUDA |
| Phi-2/3         | GGUF、SafeTensors | Rust CUDA |
| Gemma           | GGUF、SafeTensors | Rust CUDA |
| Qwen 2          | GGUF、SafeTensors | Rust CUDA |
| Starcoder 2     | GGUF             | Rust CUDA |
| LLaVA 1.5/1.6   | SafeTensors      | 视觉        |
| Phi-3 Vision    | SafeTensors      | 视觉        |

***

## 在 Clore.ai 上快速开始

### 步骤 1：查找 GPU 服务器

在 [clore.ai](https://clore.ai) 市场：

* **最低要求：** 8GB 显存（用于 7B Q4 模型）
* **推荐：** 较大模型需 RTX 3090/4090（24GB）
* 需要 CUDA 11.8+

### 第 2 步：部署 Mistral.rs Docker

```
Docker 镜像：ghcr.io/ericlbuehler/mistral.rs:cuda
```

**端口映射：**

| 容器端口   | 用途           |
| ------ | ------------ |
| `22`   | SSH 访问       |
| `8080` | REST API 服务器 |

**可用的镜像变体：**

```bash
# CUDA（大多数 Clore.ai 服务器）
ghcr.io/ericlbuehler/mistral.rs:cuda

# 仅 CPU
ghcr.io/ericlbuehler/mistral.rs:cpu

# Metal（Apple Silicon - 非 Clore.ai 使用）
ghcr.io/ericlbuehler/mistral.rs:metal
```

### 第 3 步：连接并验证

```bash
ssh root@<clore-node-ip> -p <ssh-port>

# 检查 mistral.rs 可执行文件
mistralrs-server --help
```

***

## 运行服务器

### 使用 GGUF 模型快速开始

```bash
# 直接从 HuggingFace 提供 GGUF 模型服务
mistralrs-server \
  --port 8080 \
  --log info \
  gguf \
  -m TheBloke/Llama-2-7B-Chat-GGUF \
  -f llama-2-7b-chat.Q4_K_M.gguf
```

### 提供 Mistral 7B（SafeTensors）

```bash
mistralrs-server \
  --port 8080 \
  plain \
  -m mistralai/Mistral-7B-Instruct-v0.3 \
  --isq Q4K
```

### 使用就地量化（ISQ）提供服务

ISQ 在加载时对模型进行量化 — 无需预先量化的模型：

```bash
# 加载 Llama 3 8B 并即时量化为 Q4K
mistralrs-server \
  --port 8080 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K

# 可用的 ISQ 选项：
# Q4_0、Q4_1、Q5_0、Q5_1、Q8_0
# Q2K、Q3K、Q4K、Q5K、Q6K、Q8K
# HQQ4、HQQ8（半二次量化）
```

### 视觉语言模型

```bash
mistralrs-server \
  --port 8080 \
  vision-plain \
  -m llava-hf/llava-1.5-7b-hf \
  --isq Q4K
```

### 投机性解码

```bash
# 使用小型草稿模型来加速生成
mistralrs-server \
  --port 8080 \
  speculative \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K \
  -d meta-llama/Meta-Llama-3-1B-Instruct \
  --draft-isq Q4K \
  -n 5  # 投机令牌数
```

{% hint style="success" %}
**推测式解码** 可以提供 **2–3 倍的加速** 适用于大多数对话工作负载，其中小型草稿模型可以准确预测下一个令牌。
{% endhint %}

***

## API 使用

### 兼容 OpenAI 的端点

| 端点                       | 方法   | 描述           |
| ------------------------ | ---- | ------------ |
| `/v1/chat/completions`   | POST | 聊天补全         |
| `/v1/completions`        | POST | 文本补全         |
| `/v1/models`             | GET  | 列出模型         |
| `/v1/images/generations` | POST | 图像生成（视觉语言模型） |
| `/v1/re_isq`             | POST | 重新对已加载模型进行量化 |
| `/health`                | GET  | 健康检查         |

### Python 示例

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://<clore-node-ip>:<api-port>/v1",
    api_key="none"  # 默认不需要认证
)

# 聊天补全
response = client.chat.completions.create(
    model="llama-3-8b",  # 模型名称可灵活替换
    messages=[
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "写一个反转链表的 Python 函数"}
    ],
    temperature=0.1,  # 低温度用于代码生成
    max_tokens=1024
)
print(response.choices[0].message.content)
```

### 流式响应

```python
with client.chat.completions.create(
    model="llama-3-8b",
    messages=[{"role": "user", "content": "给我讲一个关于机器人的故事。"}],
    stream=True,
    max_tokens=512
) as stream:
    for chunk in stream:
        delta = chunk.choices[0].delta
        if hasattr(delta, 'content') and delta.content:
            print(delta.content, end="", flush=True)
print()
```

### 视觉/图像输入

```python
BASE_URL = "http://localhost:9090"  # 或您的 CLORE.AI http_pub URL
from pathlib import Path

# 加载图像
image_data = base64.b64encode(Path("photo.jpg").read_bytes()).decode()

response = client.chat.completions.create(
    model="llava-1.5-7b",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    }
                },
                {
                    "type": "text",
                    "text": "你在这张图像中看到了什么？"
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)
```

### cURL 示例

```bash
# 基本聊天
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-7b",
    "messages": [{"role": "user", "content": "什么是 Rust？"}],
    "temperature": 0.7,
    "max_tokens": 256
  }'

# 列出模型
curl http://localhost:8080/v1/models

# 健康检查
curl http://localhost:8080/health
```

***

## 配置选项

### 服务器标志

```bash
mistralrs-server \
  --port 8080 \                    # API 端口（默认：1234）
  --host 0.0.0.0 \                 # 绑定地址
  --log info \                     # 日志级别：off/error/warn/info/debug/trace
  --token-source env:HF_TOKEN \    # HuggingFace 令牌来源
  --max-seqs 16 \                  # 最大并发序列数
  --no-paged-attn \                # 禁用 PagedAttention（用于调试）
  --prefix-cache-n 16 \            # 前缀缓存条目数
  plain \                          # 模型类型子命令
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### ISQ 量化参考

| ISQ 选项 | 位数 | 速度    | 显存（7B）  |
| ------ | -- | ----- | ------- |
| `Q2K`  | 2  | ★★☆☆☆ | \~2.5GB |
| `Q3K`  | 3  | ★★★☆☆ | \~3.5GB |
| `Q4_0` | 4  | ★★★★☆ | \~4.5GB |
| `Q4K`  | 4  | ★★★★☆ | \~4.5GB |
| `Q5K`  | 5  | ★★★★★ | \~5.5GB |
| `Q6K`  | 6  | ★★★★★ | \~6.5GB |
| `Q8_0` | 8  | ★★★★★ | ≈8GB    |
| `HQQ4` | 4  | ★★★★☆ | \~4.5GB |
| `HQQ8` | 8  | ★★★★★ | ≈8GB    |

{% hint style="info" %}
**HQQ（半二次量化）** 在相同位级别上，通常比 GGUF 的 Q4 达到更好的质量，尤其是在跟随指令的任务上。
{% endhint %}

***

## 高级功能

### X-LoRA（多个 LoRA 适配器的混合）

动态地为每个令牌运行多个微调适配器并选择：

```bash
mistralrs-server \
  --port 8080 \
  x-lora-plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K \
  -x ./xlora-config.json
```

### 运行时重新量化

```bash
# 无需重启即可更改量化
curl http://localhost:8080/v1/re_isq \
  -H "Content-Type: application/json" \
  -d '{"isq_type": "Q8_0"}'
```

### 请求日志

```bash
# 启用请求日志到文件
mistralrs-server \
  --port 8080 \
  --log info \
  --request-logging-file ./requests.jsonl \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

***

## 性能调优

### 优化吞吐量

```bash
# 增加 max-seqs 以处理并发请求
mistralrs-server \
  --port 8080 \
  --max-seqs 32 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### 优化低延迟

```bash
# 降低 max-seqs，禁用前缀缓存共享
mistralrs-server \
  --port 8080 \
  --max-seqs 4 \
  --prefix-cache-n 0 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### 监控性能

```bash
# 在推理期间监视 GPU 使用情况
watch -n 1 nvidia-smi

# 使用 nvtop 进行性能分析
apt-get install nvtop && nvtop
```

***

## Docker Compose

```yaml
version: '3.8'
services:
  mistral-rs:
    image: ghcr.io/ericlbuehler/mistral.rs:cuda
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - HF_TOKEN=${HUGGING_FACE_HUB_TOKEN}
    ports:
      - "8080:8080"
    volumes:
      - hf-cache:/root/.cache/huggingface
    command: >
      mistralrs-server
      --port 8080
      --host 0.0.0.0
      --log info
      --max-seqs 16
      --token-source env:HF_TOKEN
      plain
      -m meta-llama/Meta-Llama-3-8B-Instruct
      --isq Q4K
    restart: unless-stopped

volumes:
  hf-cache:
```

***

## 从源码构建

如果 Docker 镜像与您的 CUDA 版本不匹配：

```bash
# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 克隆并构建
git clone https://github.com/EricLBuehler/mistral.rs.git
cd mistral.rs

# 使用 CUDA 支持进行构建
cargo build --release --features cuda

# 可执行文件位置
./target/release/mistralrs-server --help
```

{% hint style="warning" %}
**构建时间：** Rust 编译速度较慢。完整构建预计需 10–20 分钟。使用 `sccache` 以加速增量构建： `cargo install sccache && RUSTC_WRAPPER=sccache cargo build --release --features cuda`
{% endhint %}

***

## 故障排除

### 未找到 CUDA 库

```bash
# 检查 CUDA 库
ldconfig -p | grep libcuda
ls /usr/local/cuda/lib64/

# 设置库路径
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
```

### 模型下载失败

```bash
# 设置 HuggingFace 令牌
export HF_TOKEN=your_token_here

# 或使用 --token-source 标志
mistralrs-server \
  --token-source env:HF_TOKEN \
  ...

# 或先手动下载
huggingface-cli download meta-llama/Meta-Llama-3-8B-Instruct --local-dir ./llama3-8b
mistralrs-server ... plain -m ./llama3-8b --isq Q4K
```

### 端口 8080 被占用

```bash
# 查找并终止进程
fuser -k 8080/tcp

# 使用不同端口
mistralrs-server --port 9090 ...
```

### 量化期间内存不足

```bash
# ISQ 在 GPU 上进行量化 — 先减少其他 GPU 使用
# 或切换到 GGUF（预量化，加载时峰值内存更低）
mistralrs-server \
  gguf \
  -m TheBloke/Llama-2-7B-Chat-GGUF \
  -f llama-2-7b-chat.Q4_K_M.gguf
```

{% hint style="danger" %}
**ISQ 与 GGUF：** ISQ 在加载时使用 GPU 内存进行量化（会出现临时峰值）。如果显存紧张，请使用来自 TheBloke 或类似来源的预量化 GGUF 文件 — 它们在加载期间使用更低的峰值内存。
{% endhint %}

***

## Clore.ai 的 GPU 建议

Mistral.rs 是一个原生 Rust 引擎 — 它的低开销意味着相比基于 Python 的服务器，你能以更低的 GPU 成本获得更高的吞吐量。

| GPU               | 显存（VRAM） | Clore.ai 价格 | 推荐使用                   | 吞吐量（Mistral 7B Q4） |
| ----------------- | -------- | ----------- | ---------------------- | ------------------ |
| RTX 3090          | 24 GB    | \~$0.12/小时  | 最佳预算选项 — 7B Q4/Q8、视觉模型 | \~120 令牌/秒         |
| RTX 4090          | 24 GB    | \~$0.70/小时  | 高吞吐量 7B–34B，投机性解码      | \~200 令牌/秒         |
| A100 40GB         | 40 GB    | \~$1.20/小时  | 生产级 34B–70B Q4 服务      | \~160 令牌/秒         |
| 💡 本指南中的所有示例均可部署在 | 80 GB    | \~$2.00/小时  | 全精度 70B，多模型            | \~185 令牌/秒         |

**为什么 RTX 3090 在此表现出色：** Mistral.rs 的 Rust CUDA 内核避免了 Python GIL 开销和会影响 Python 服务器的垃圾回收暂停。在相同硬件上运行 Mistral 7B Q4\_K\_M 的 RTX 3090 提供了 ~~120 令牌/秒 — 在相同硬件上与 vLLM 可比，但成本只是其一小部分（~~$0.12/小时 vs 云提供商收费 $1–2/小时）。

**投机性解码：** 将大型模型（34B）与小型草稿模型（3B）配对，可在不损失质量的情况下实现 2–3× 加速。RTX 4090 非常适合这种模式。

***

## 资源

* 🐙 **GitHub：** [github.com/EricLBuehler/mistral.rs](https://github.com/EricLBuehler/mistral.rs)
* 📦 **容器镜像库：** [ghcr.io/ericlbuehler/mistral.rs](https://ghcr.io/ericlbuehler/mistral.rs)
* 📚 **文档：** [ericlbuehler.github.io/mistral.rs](https://ericlbuehler.github.io/mistral.rs/mistralrs/)
* 💬 **Discord：** [discord.gg/SZrecqK8qw](https://discord.gg/SZrecqK8qw)
* 🤗 **GGUF 模型：** [huggingface.co/TheBloke](https://huggingface.co/TheBloke)


---

# Agent Instructions: 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:

```
GET https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/mistral-rs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.