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 市场：

• 最低要求： 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 服务器

可用的镜像变体：

# 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 步：连接并验证

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

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

---

运行服务器

使用 GGUF 模型快速开始

# 直接从 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）

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

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

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

# 加载 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（半二次量化）

视觉语言模型

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

投机性解码

# 使用小型草稿模型来加速生成
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  # 投机令牌数

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

---

API 使用

兼容 OpenAI 的端点

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

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)

流式响应

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()

视觉/图像输入

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 示例

# 基本聊天
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

---

配置选项

服务器标志

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

HQQ（半二次量化） 在相同位级别上，通常比 GGUF 的 Q4 达到更好的质量，尤其是在跟随指令的任务上。

---

高级功能

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

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

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

运行时重新量化

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

请求日志

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

---

性能调优

优化吞吐量

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

优化低延迟

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

监控性能

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

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

---

Docker Compose

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 版本不匹配：

# 安装 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

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

---

故障排除

未找到 CUDA 库

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

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

模型下载失败

# 设置 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 被占用

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

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

量化期间内存不足

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

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

---

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

• 📦 容器镜像库： ghcr.io/ericlbuehler/mistral.rs

• 📚 文档： ericlbuehler.github.io/mistral.rs

• 💬 Discord： discord.gg/SZrecqK8qw

• 🤗 GGUF 模型： huggingface.co/TheBloke