Mistral Inference：Mistral 官方最小推理库与命令行对话工具链｜部署与使用全指南

项目仓库： https://github.com/mistralai/mistral-inference

开源协议：Apache 2.0（库代码）；模型权重按各模型许可（部分为 Mistral AI 自定义非生产 / 研究许可） · 交付形态：PyPI 包 mistral-inference + CLI（mistral-demo / mistral-chat） · 支持模型：Mistral 7B v0.3、Mixtral 8x7B / 8x22B、Codestral 22B、Mathstral 7B、Codestral-Mamba 7B、Mistral Nemo 12B、Mistral Large 2、Pixtral、Mistral Small 3.1 24B · 官方文档：docs.mistral.ai

官方维护状态说明（务必先读）：仓库 README 顶部明确标注 "Archived — no longer maintained"，Mistral AI 表示未来可能推出新库或重大更新，但当前仓库已不再积极维护。本文命令与模型清单均取自归档时的 README；新模型与生产部署请以 docs.mistral.ai 与 Mistral AI 官方 API 最新说明为准。

1 项目简介

mistral-inference 是 Mistral AI 官方发布的最小推理代码库，用于在本地或自有 GPU 上加载 Mistral 系列开源权重并跑通命令行对话与 Python 调用。它以 PyPI 包形式分发，附带 mistral-demo（一次性推理）与 mistral-chat（交互式对话）两个 CLI；同时提供基于 vLLM 的 Docker 部署目录 deploy/，用于构建服务化镜像。

非官方 / 第三方边界声明：Mistral AI 同时运营商业 API（La Plateforme）与云厂商分发渠道；本指南仅覆盖开源仓库 mistral-inference 与可下载权重。Codestral 22B、Mistral Large 2 等模型采用自定义非生产 / 研究许可（MNPL / MRL），商用前须自行确认许可范围。

1.1 核心信息一览

1.2 适用场景

• 希望在单卡或多卡 GPU 上本地加载 Mistral 7B / Nemo 12B 等开源权重，跑通命令行对话与函数调用。
• 需要在 Python 中直接调用 mistral_inference.transformer.Transformer 做自定义推理管线，包括文本对话、多模态（Pixtral / Mistral Small 3.1）、函数调用与 FIM 代码补全。
• 希望基于仓库 deploy/ 目录构建 vLLM 服务镜像，将 Mistral 模型封装为 OpenAI 兼容 API。
• 研究人员需要对照官方参考实现做 logits 等价性测试（pytest tests）。

1.3 能力边界（官方口径）

• 仓库自述为 "minimal code to run Mistral models"，不提供 Web UI、用户管理或生产级鉴权；服务化请走 deploy/ 目录的 vLLM 镜像或官方 API。
• 安装依赖 xformers，而 xformers 本身需要在有 GPU 的环境下安装，因此纯 CPU 机器无法直接使用本库。
• 部分模型（Codestral 22B、Mistral Large 2）采用 MNPL / MRL 自定义许可，禁止生产商用；其余模型采用 Apache 2.0 或 Mistral 开放许可。
• 仓库已归档，不再接受新功能与缺陷修复；遇到问题请参考历史 Issues 或迁移到官方 API / vLLM 生态。

2 功能特性

2.1 双 CLI：demo 与 chat

• mistral-demo <模型目录>：一次性推理，适合快速验证模型加载是否正确。
• mistral-chat <模型目录> --instruct：交互式多轮对话，支持 --max_tokens、--temperature 等参数。
• 大模型（8x7B、8x22B）通过 torchrun --nproc-per-node N 启动多卡。

2.2 丰富模型覆盖

仓库 README 列出的可下载模型包括：Mistral 7B v0.3（Base / Instruct）、Mixtral 8x7B Instruct、Mixtral 8x22B（Base / Instruct v0.3）、Codestral 22B、Mathstral 7B、Codestral-Mamba 7B、Mistral Nemo（Base / Instruct 2407）、Mistral Large 2；并通过 Hugging Face Hub 对接 Pixtral 12B / Large、Mistral Small 3.1 24B 等更新模型。

2.3 Python 高阶能力

• 指令跟随：ChatCompletionRequest + UserMessage 组织对话。
• 多模态：通过 ImageURLChunk + TextChunk 传入图片 URL，配合 Pixtral / Mistral Small 3.1 视觉模型。
• 函数调用：通过 Tool + Function 声明工具 schema，模型返回结构化调用。
• FIM 代码补全：FIMRequest(prefix, suffix) 做代码中段填充，用于 Codestral 系列。

2.4 vLLM 服务化镜像

deploy/ 目录提供 Dockerfile，基于 vLLM 构建推理服务镜像；镜像内使用 transformers 加载权重，运行说明见官方 quickstart。

3 官方界面预览

本仓库为命令行与 Python 库，不提供图形界面；官方 README 仅含 Colab 徽章，无截图素材。下文以 mistral-chat 终端交互为准。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• 操作系统：Linux（推荐 Ubuntu 20.04/22.04）；macOS 可做开发测试但生产建议 Linux。
• Python：3.10 或更高（随 PyTorch / xformers 生态）。
• GPU 与 CUDA：必须有 NVIDIA GPU 且已安装 CUDA；xformers 在安装阶段需要 GPU 编译。
• wget / tar：用于下载并解压模型 tar 包。
• Git / Poetry：从源码安装时需要；PyPI 安装不需要 Poetry。

5.2 硬件建议（按模型规模粗估）

Codestral-Mamba 7B 还需额外安装 mamba-ssm 与 causal-conv1d。

5.3 端口说明

6 方式一：pip 安装与命令行快速开始

6.1 安装

# 在有 GPU 的环境中创建 conda 环境（示例）
conda create -n mistral python=3.10 -y
conda activate mistral

# 安装 PyTorch（按本机 CUDA 版本选择 wheel，此处略）
pip install torch

# 安装 mistral-inference（会自动带上 mistral-common、xformers 等）
pip install mistral-inference

6.2 下载并解压模型（以 Mistral Nemo 12B Instruct 为例）

export MISTRAL_MODEL=$HOME/mistral_models
mkdir -p $MISTRAL_MODEL

export 12B_DIR=$MISTRAL_MODEL/12B_Nemo
wget https://models.mistralcdn.com/mistral-nemo-2407/mistral-nemo-instruct-2407.tar
mkdir -p $12B_DIR
tar -xf mistral-nemo-instruct-2407.tar -C $12B_DIR

其他模型直链（均来自 README 表格）：

6.3 跑一次 demo 与 chat

# 单卡 demo（Nemo 12B）
mistral-demo $12B_DIR

# 交互式对话
mistral-chat $12B_DIR --instruct --max_tokens 1024 --temperature 0.35

# 多卡模型示例（Mixtral 8x7B）
export M8x7B_DIR=$MISTRAL_MODEL/8x7b_instruct
wget https://models.mistralcdn.com/mixtral-8x7b-v0-1/Mixtral-8x7B-v0.1-Instruct.tar
mkdir -p $M8x7B_DIR && tar -xf Mixtral-8x7B-v0.1-Instruct.tar -C $M8x7B_DIR

torchrun --nproc-per-node 2 --no-python mistral-demo $M8x7B_DIR
torchrun --nproc-per-node 2 --no-python mistral-chat $M8x7B_DIR --instruct

7 方式二：Docker / Compose 部署（vLLM 服务化）

仓库 deploy/ 目录提供 Dockerfile，基于 vLLM 构建服务镜像。

7.1 构建镜像

git clone https://github.com/mistralai/mistral-inference.git
cd mistral-inference

# MAX_JOBS=8 控制编译并行度，按机器核数调整
docker build deploy --build-arg MAX_JOBS=8

7.2 运行镜像

运行参数与挂载权重路径详见官方 quickstart；镜像内使用 transformers 加载权重并对外暴露 OpenAI 兼容接口。生产部署请额外配置 GPU 运行时（--gpus all）、权重目录挂载与反向代理。

8 方式三：源码安装与 Python 调用

8.1 源码安装

cd $HOME
git clone https://github.com/mistralai/mistral-inference
cd $HOME/mistral-inference && poetry install .

8.2 Python 指令跟随示例

from mistral_inference.transformer import Transformer
from mistral_inference.generate import generate
from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
from mistral_common.protocol.instruct.messages import UserMessage
from mistral_common.protocol.instruct.request import ChatCompletionRequest

tokenizer = MistralTokenizer.from_file("./mistral-nemo-instruct-v0.1/tekken.json")
model = Transformer.from_folder("./mistral-nemo-instruct-v0.1")

prompt = "How expensive would it be to ask a window cleaner to clean all windows in Paris?"
completion_request = ChatCompletionRequest(messages=[UserMessage(content=prompt)])
tokens = tokenizer.encode_chat_completion(completion_request).tokens

out_tokens, _ = generate(
    [tokens], model, max_tokens=1024, temperature=0.35,
    eos_id=tokenizer.instruct_tokenizer.tokenizer.eos_id,
)
result = tokenizer.instruct_tokenizer.tokenizer.decode(out_tokens[0])
print(result)

8.3 多模态（Pixtral / Mistral Small 3.1）

from huggingface_hub import snapshot_download
from mistral_common.protocol.instruct.messages import ImageURLChunk, TextChunk
# ... 其余导入同上

model_path = Path.home().joinpath("mistral_models") / "mistral-small-3.1-instruct"
snapshot_download(
    repo_id="mistralai/Mistral-Small-3.1-24B-Instruct-2503",
    allow_patterns=["params.json", "consolidated.safetensors", "tekken.json"],
    local_dir=model_path,
)
tokenizer = MistralTokenizer.from_file(model_path / "tekken.json")
model = Transformer.from_folder(model_path)

user_content = [
    ImageURLChunk(image_url="https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/yosemite.png"),
    TextChunk(text="这张图是哪个公园？给出识别线索。"),
]
tokens, images = tokenizer.instruct_tokenizer.encode_user_content(user_content, False)
out_tokens, _ = generate([tokens], model, images=[images], max_tokens=256, temperature=0.15,
                        eos_id=tokenizer.instruct_tokenizer.tokenizer.eos_id)
print(tokenizer.decode(out_tokens[0]))

9 配置项说明

9.1 CLI 参数

9.2 Python 关键类

9.3 环境变量

10 常用运维命令

# 查看已下载模型
ls -lh $HOME/mistral_models/

# 查看 GPU 占用
nvidia-smi

# 终止 mistral-chat 会话
# Ctrl+D 退出；卡住时 pkill -f mistral-chat

# 运行 logits 等价性测试（源码仓库内）
python -m pytest tests

# 查看 pip 包版本
pip show mistral-inference mistral-common

# 更新 mistral-common 以支持 FIM 等新特性
pip install --upgrade mistral-common

11 常见故障排查

• xformers 安装失败：本库必须在有 GPU 的环境安装；纯 CPU 机器请改用官方 API 或 vLLM 镜像。
• 模型 tar 解压后目录结构不对：确认 tar -xf <file>.tar -C <目标目录>，并确保目标目录存在；Transformer.from_folder 需要能直接看到 consolidated.safetensors、params.json、tekken.json。
• 多卡启动报 CUDA 错误：--nproc-per-node 不能超过实际可见 GPU 数；用 nvidia-smi 确认，必要时设置 CUDA_VISIBLE_DEVICES。
• Codestral-Mamba 7B 报错：需额外 pip install packaging mamba-ssm causal-conv1d transformers。
• FIM 补全报错：mistral-common 版本过低，执行 pip install --upgrade mistral-common（要求 ≥1.2.0）。
• Docker 构建慢：--build-arg MAX_JOBS=N 按 CPU 核数调大；首次构建需拉取 vLLM 基础镜像。
• 模型许可问题：Codestral 22B、Mistral Large 2 采用 MNPL / MRL 许可，禁止生产商用；商用请改用 Apache 2.0 模型或官方 API。

12 风险与合规说明

• 模型许可差异：Mistral 系列模型并非全部 Apache 2.0；Codestral 22B、Mistral Large 2 等采用自定义非生产 / 研究许可，商用前必须阅读对应 LICENSE。
• 仓库已归档：本仓库不再维护，生产环境请评估迁移到官方 API、vLLM 或更新的官方推理库。
• 数据隐私：本地推理不上传数据，但通过 Hugging Face 下载权重会与 HF 服务交互；公网部署 vLLM 服务须自行做好鉴权与速率限制。
• 内容风险：官方提供 guardrailing 指南，建议叠加输入输出过滤。
• 本文非官方文档：命令与参数均取自归档 README；如官方文档更新，以 docs.mistral.ai 最新说明为准。