# https://github.com/mistralai/mistral-common 项目说明书
生成时间：2026-05-17 00:44:16 UTC
## 目录
- [项目介绍与安装](#p1)
- [项目架构总览](#p2)
- [分词器系统详解](#p3)
- [多模态处理（图像与音频）](#p4)
- [指令与填充中间（FIM）协议](#p5)
- [请求验证与标准化](#p6)
- [语音与转录协议](#p7)
- [Grammar Factory 与 LLM Guidance](#p8)
- [实验性功能（工具调用、思考解析、FastAPI 服务）](#p9)
- [数据文件与模型版本管理](#p10)
## 项目介绍与安装
### 相关页面
相关主题：[数据文件与模型版本管理](#p10), [项目架构总览](#p2)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)
- [AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)
- [pyproject.toml](https://github.com/mistralai/mistral-common/blob/main/pyproject.toml)
- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)
- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)
- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
# 项目介绍与安装
## 1. 项目概述
mistral-common 是 Mistral AI 开源的工具库集合，旨在帮助开发者更好地使用 Mistral AI 模型。该项目包含了令牌化器（tokenizers）、验证（validation）、规范化（normalization）等核心功能，可与 Mistral AI 的各种模型配合使用。
资料来源：[README.md:1]()
### 1.1 核心功能
| 功能模块 | 描述 |
|---------|------|
| **令牌化（Tokenization）** | 提供 Tekken 令牌化器，用于对请求进行编码 |
| **协议处理（Protocol）** | 支持 Instruct、FIM（Fill-In-The-Middle）和 Transcription 协议 |
| **验证与规范化** | 对聊天补全请求进行验证和规范化处理 |
| **多模态支持** | 支持图像和音频处理（可选依赖） |
| **Grammar 引导** | 使用 llguidance 创建工具调用、JSON schema 和推理的 Lark 语法 |
资料来源：[AGENTS.md:2]()
### 1.2 技术栈
| 技术项 | 要求 |
|-------|------|
| 编程语言 | Python 3.10 至 3.14 |
| 包管理器 | uv |
| 测试框架 | pytest |
| 代码格式化 | Ruff |
| 类型检查 | mypy |
| 持续集成 | GitHub Actions |
资料来源：[AGENTS.md:1]()
## 2. 项目架构
### 2.1 整体架构图
```mermaid
graph TD
subgraph "用户请求层"
A[ChatCompletionRequest] --> B[验证器 Validator]
B --> C[规范化器 Normalizer]
C --> D[InstructRequest]
end
subgraph "令牌化层"
D --> E[MistralTokenizer]
E --> F[Tekken Tokenizer]
end
subgraph "输出层"
F --> G[Tokenized 对象]
end
subgraph "可选模块"
H[Image Encoder] -.-> E
I[Audio Encoder] -.-> E
end
```
### 2.2 目录结构
```
mistral-common/
├── src/
│ └── mistral_common/
│ ├── protocol/ # 协议处理
│ │ ├── instruct/ # Instruct 协议
│ │ │ ├── request.py # ChatCompletionRequest 定义
│ │ │ ├── normalize.py # 请求规范化器
│ │ │ ├── validator.py # 请求验证器
│ │ │ ├── messages.py # 消息定义
│ │ │ └── tool_calls.py # 工具调用
│ │ ├── fim/ # FIM 协议
│ │ └── transcription/ # 转录协议
│ ├── tokens/ # 令牌化
│ │ └── tokenizers/ # 令牌化器实现
│ │ ├── tekken.py # Tekken 令牌化器
│ │ ├── mistral.py # Mistral 令牌化器
│ │ ├── instruct.py # Instruct 令牌化器
│ │ ├── image.py # 图像处理
│ │ └── audio.py # 音频处理
│ ├── guidance/ # Grammar 引导
│ └── experimental/ # 实验性功能
├── tests/ # 测试套件
├── docs/ # 文档
└── pyproject.toml # 项目配置
```
资料来源：[AGENTS.md:1-2]()
## 3. 安装指南
### 3.1 基础安装
使用 pip 进行基础安装：
```bash
pip install mistral-common
```
资料来源：[README.md:2]()
### 3.2 可选依赖安装
mistral-common 包含多个可选依赖模块，可以根据需要选择性安装：
| 依赖项 | 功能 | 安装命令 |
|-------|------|---------|
| `image` | 图像处理支持 | `pip install "mistral-common[image]"` |
| `audio` | 音频处理支持 | `pip install "mistral-common[audio]"` |
| `hf-hub` | 从 Hugging Face Hub 下载令牌化器 | `pip install "mistral-common[hf-hub]"` |
| `sentencepiece` | SentencePiece 令牌化器支持（已弃用） | `pip install "mistral-common[sentencepiece]"` |
| `server` | 服务器模式运行令牌化器 | `pip install "mistral-common[server]"` |
资料来源：[README.md:2-5]()
### 3.3 安装所有依赖
一次性安装所有可选依赖：
```bash
pip install "mistral-common[image,audio,hf-hub,sentencepiece,server]"
```
资料来源：[README.md:7]()
## 4. 快速入门
### 4.1 基本使用示例
```python
from mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage
from mistral_common.protocol.instruct.request import ChatCompletionRequest
from mistral_common.protocol.instruct.normalize import InstructRequestNormalizer
# 创建聊天补全请求
request = ChatCompletionRequest(
messages=[
UserMessage(content="你好！"),
AssistantMessage(content="你好！有什么可以帮助你的吗？"),
],
)
# 使用规范化器处理请求
normalizer = InstructRequestNormalizer.normalizer()
instruct_request = normalizer.from_chat_completion_request(request)
```
资料来源：[src/mistral_common/protocol/instruct/request.py:20-30]()
### 4.2 带工具调用的请求
```python
from mistral_common.protocol.instruct.tool_calls import Tool, ToolTypes, Function
# 定义工具
tool = Tool(
function=Function(
name="get_weather",
description="获取指定位置的天气信息",
parameters={
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA",
},
},
"required": ["location"],
},
),
)
# 创建带工具的请求
request = ChatCompletionRequest(
messages=[UserMessage(content="北京今天天气怎么样？")],
tools=[tool],
tool_choice="auto",
)
```
资料来源：[src/mistral_common/protocol/instruct/request.py:30-45]()
### 4.3 请求验证
```python
from mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode
from mistral_common.protocol.instruct.messages import UserMessage
# 创建验证器（测试模式）
validator = MistralRequestValidator(mode=ValidationMode.test)
# 创建请求
request = ChatCompletionRequest(
model="mistral-large-latest",
messages=[UserMessage(content="Hello!")],
)
# 验证请求
validated_request = validator.validate_request(request)
```
资料来源：[src/mistral_common/protocol/instruct/validator.py:20-40]()
## 5. 开发环境配置
### 5.1 环境设置
使用 uv 进行开发环境配置：
```bash
# 克隆仓库
git clone https://github.com/mistralai/mistral-common.git
cd mistral-common
# 创建虚拟环境
uv venv
source .venv/bin/activate
# 同步所有依赖和开发依赖
uv sync --frozen --all-extras --group dev
# 安装预提交钩子
uv run pre-commit install
```
资料来源：[README.md:40-50]()
### 5.2 代码质量检查
项目使用以下工具进行代码质量控制：
| 工具 | 用途 | 命令 |
|-----|------|------|
| Ruff | 代码格式化和检查 | `uv run ruff check .` |
| mypy | 类型检查 | `uv run mypy src/` |
| pytest | 测试运行 | `uv run pytest tests/` |
| pre-commit | 自动化检查 | `uv run pre-commit run --all-files` |
### 5.3 开发工作流
```mermaid
graph LR
A[修改代码] --> B[编写测试]
B --> C[运行预提交检查]
C --> D{Ruff 格式化}
D --> E{类型检查}
E --> F{运行测试}
F --> G[提交代码]
```
资料来源：[AGENTS.md:25-35]()
## 6. 核心组件详解
### 6.1 ChatCompletionRequest
`ChatCompletionRequest` 是用户查询的入口点，定义在 `src/mistral_common/protocol/instruct/request.py` 中。
| 属性 | 类型 | 描述 |
|-----|------|------|
| `model` | `str \| None` | 模型名称 |
| `messages` | `list[ChatMessageType]` | 消息列表 |
| `response_format` | `ResponseFormat` | 响应格式 |
| `tools` | `list[Tool] \| None` | 可用工具列表 |
| `tool_choice` | `ToolChoice` | 工具选择策略 |
| `truncate_for_context_length` | `bool` | 是否截断以适应上下文长度 |
| `continue_final_message` | `bool` | 是否继续最终消息 |
| `reasoning_effort` | `ReasoningEffort \| None` | 推理努力程度 |
资料来源：[src/mistral_common/protocol/instruct/request.py:20-35]()
### 6.2 令牌化器版本
mistral-common 支持多个令牌化器版本：
| 版本 | 图像支持 | 音频支持 | 说明 |
|-----|---------|---------|------|
| v1 | ❌ | ❌ | 基础版本 |
| v2 | ❌ | ❌ | 改进版本 |
| v3 | ✅ | ❌ | 支持图像处理 |
| v7 | ✅ | ✅ | 支持图像和音频 |
| v11 | ✅ | ✅ | 进一步改进 |
| v13 | ✅ | ✅ | 最新版本 |
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()
### 6.3 特殊令牌
Tekken 令牌化器定义了一系列特殊令牌：
| 令牌名称 | 用途 |
|---------|------|
| `bos` | 句子开始 |
| `eos` | 句子结束 |
| `unk` | 未知词元 |
| `eop` | 段落结束 |
| `eod` | 文档结束 |
| `begin_tool_results` | 工具结果开始 |
| `end_tool_results` | 工具结果结束 |
| `begin_tool_content` | 工具内容开始 |
| `img` | 图像标记 |
| `pad` | 填充令牌 |
资料来源：[src/mistral_common/tokens/tokenizers/tekken.py:1-30]()
## 7. 高级功能
### 7.1 多模态处理
#### 7.1.1 图像处理
使用图像令牌化器需要安装 `image` 依赖：
```bash
pip install "mistral-common[image]"
```
图像处理流程：
```mermaid
graph TD
A[图像文件] --> B[ImageEncoder]
B --> C[编码的图像数据]
C --> D[Tokenized 对象]
```
#### 7.1.2 音频处理
使用音频令牌化器需要安装 `audio` 依赖：
```bash
pip install "mistral-common[audio]"
```
### 7.2 服务器模式
提供 FastAPI 服务器模式运行令牌化器：
```bash
pip install "mistral-common[server]"
```
启动服务器：
```bash
python -m mistral_common.experimental.app.main serve \
--tokenizer-path /path/to/tokenizer \
--validation-mode test \
--host 127.0.0.1 \
--port 8000
```
资料来源：[src/mistral_common/experimental/app/main.py:1-50]()
### 7.3 Grammar 引导
使用 llguidance 创建语法引导的输出：
```python
from mistral_common.guidance.grammar_factory import GrammarFactory
# 创建语法工厂
grammar_factory = GrammarFactory()
# 生成工具调用的语法
grammar = grammar_factory.create_tool_call_grammar(tools=[tool])
```
资料来源：[AGENTS.md:12-15]()
## 8. 贡献指南
### 8.1 代码风格规范
| 规范 | 要求 |
|-----|------|
| 命名规范 | 函数/变量使用 snake_case，类使用 PascalCase |
| 类型提示 | 必须使用 Python 类型提示 |
| 文档字符串 | 必须使用 Google 风格文档字符串 |
| 导入规范 | 使用绝对导入，禁止通配符导入 |
资料来源：[AGENTS.md:18-30]()
### 8.2 提交规范
- 使用祈使语气
- 以动词开头
- 保持简洁明了
### 8.3 向后兼容性
新增功能时必须确保不破坏现有功能。
资料来源：[AGENTS.md:35-40]()
## 9. 许可协议
mistral-common 库采用 Apache 2.0 许可证。
> **重要提示**：您不得以侵犯、侵犯或以其他方式违反任何第三方权利（包括知识产权）的方式使用本库或我们的模型。
资料来源：[README.md:55-60]()
## 10. 相关资源
| 资源 | 链接 |
|-----|------|
| 官方文档 | https://mistralai.github.io/mistral-common/ |
| PyPI 主页 | https://pypi.org/project/mistral-common/ |
| GitHub Issues | https://github.com/mistralai/mistral-common/issues |
| 模型下载 | Hugging Face Hub |
---
## 项目架构总览
### 相关页面
相关主题：[项目介绍与安装](#p1), [分词器系统详解](#p3), [请求验证与标准化](#p6)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)
- [AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)
- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)
- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/misturalai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)
- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)
# 项目架构总览
## 概述
mistral-common 是 Mistral AI 官方开源的预处理库，专为 Mistral 大语言模型（LLM）设计。该库提供了一套完整的工具集，用于将用户请求编码为模型可处理的 token 序列，同时支持图像、音频等多模态数据的处理 资料来源：[README.md:1]()。
### 技术栈
| 类别 | 技术选型 |
|------|---------|
| 语言版本 | Python 3.10 - 3.14 |
| 包管理器 | uv |
| 测试框架 | pytest |
| 代码格式 | Ruff |
| 类型检查 | mypy |
| 持续集成 | GitHub Actions |
| 协议许可 | Apache 2.0 |
资料来源：[AGENTS.md:1-10]()
---
## 核心架构设计
mistral-common 采用分层架构设计，主要包含以下核心模块：
```mermaid
graph TB
subgraph "表现层 (Protocol)"
P1[Instruct Protocol]
P2[FIM Protocol]
P3[Transcription Protocol]
end
subgraph "处理层 (Tokens)"
T1[Instruct Tokenizer]
T2[Mistral Tokenizer]
T3[Tekken Tokenizer]
end
subgraph "指导层 (Guidance)"
G1[Grammar Factory]
G2[Token Guidance]
end
subgraph "实验层 (Experimental)"
E1[Tool Calls Parser]
E2[Think Parser]
end
P1 --> T1
P2 --> T1
P3 --> T1
T1 --> T2
T2 --> T3
G1 --> G2
```
---
## 模块详解
### 1. 协议层 (Protocol)
协议层是用户请求的入口点，负责定义和验证不同类型的请求格式 资料来源：[AGENTS.md:38-57]()。
#### 1.1 Instruct Protocol
Instruct Protocol 处理对话补全请求，是最常用的协议类型。
| 组件文件 | 功能描述 |
|---------|---------|
| `request.py` | 定义 `ChatCompletionRequest`，用户查询的入口点 |
| `messages.py` | 定义指导消息类型（UserMessage、AssistantMessage 等） |
| `validator.py` | 验证请求结构和内容 |
| `normalize.py` | 将请求转换为内部 instruct 格式 |
| `tool_calls.py` | 工具调用逻辑处理 |
| `converters.py` | 与 OpenAI 格式的转换辅助工具 |
| `chunk.py` | 消息内容分块处理 |
资料来源：[AGENTS.md:40-48]()
#### 1.2 FIM Protocol
Fill-in-the-Middle 协议用于代码补全等中间填空任务：
```python
# 入口文件: src/mistral_common/protocol/fim/request.py
class FIMRequest(BaseCompletionRequest)
```
#### 1.3 Transcription Protocol
音频转录协议处理音频文件的转录请求：
```python
# 入口文件: src/mistral_common/protocol/transcription/request.py
class TranscriptionRequest(BaseCompletionRequest)
```
---
### 2. 令牌化层 (Tokens)
令牌化层是核心处理引擎，负责将规范化后的请求编码为 token 序列 资料来源：[AGENTS.md:50-68]()。
#### 2.1 架构层级
```mermaid
graph LR
A[用户请求] --> B[Validator 验证]
B --> C[Normalizer 规范化]
C --> D[MistralTokenizer]
D --> E[InstructTokenizer]
E --> F[TekkenTokenizer]
F --> G[Token IDs]
```
#### 2.2 Tokenizer 类体系
| Tokenizer 类型 | 文件位置 | 功能说明 |
|---------------|---------|---------|
| `Tokenizer` | `base.py` | 抽象基类，定义通用接口 |
| `TekkenTokenizer` | `tekken.py` | Tekken 分词器，所有最新模型使用 |
| `InstructTokenizerV1-V11` | `instruct.py` | Instruct 令牌化器版本实现 |
| `MistralTokenizer` | `mistral.py` | 主令牌化器，编排验证和规范化流程 |
| `AudioTokenizer` | `audio.py` | 音频数据处理 |
资料来源：[AGENTS.md:50-66]()
#### 2.3 Tokenizer 版本支持
mistral-common 支持从 v1 到 v13 的多种 tokenizer 版本：
| 版本 | 图像支持 | 音频支持 | 特殊说明 |
|------|---------|---------|---------|
| v1 | ❌ | ❌ | 基础版本 |
| v2 | ❌ | ❌ | 增强验证 |
| v3 | ✅ | ❌ | 引入图像编码器 |
| v7 | ✅ | ✅ | 引入音频编码器 |
| v11 | ✅ | ✅ | 性能优化 |
| v13 | ✅ | ✅ | 最新版本 |
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-60]()
---
### 3. 验证与规范化流程
#### 3.1 验证模式
`MistralRequestValidator` 支持三种验证模式：
| 模式 | 用途 |
|------|------|
| `test` | 默认模式，用于标准测试 |
| `serving` | 服务模式，要求提供模型名称 |
| `finetuning` | 微调模式 |
```python
class ValidationMode(str, Enum):
serving = "serving"
finetuning = "finetuning"
test = "test"
```
资料来源：[src/mistral_common/protocol/instruct/validator.py:1-20]()
#### 3.2 规范化器
`InstructRequestNormalizer` 负责将 `ChatCompletionRequest` 转换为内部 instruct 格式：
```python
class InstructRequestNormalizer:
def from_chat_completion_request(self, request: ChatCompletionRequest) -> InstructRequest
```
资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-40]()
---
### 4. 指导层 (Guidance)
Guidance 模块使用 llguidance 库创建 Lark 语法，用于约束模型输出格式 资料来源：[AGENTS.md:70-77]()。
| 组件 | 功能 |
|------|------|
| `grammar_factory.py` | 从 Jinja 模板构建和渲染 Lark 语法 |
| `tokenizer.py` | 适配 Tekken 分词器用于 llguidance |
| `data/` | 包含 base、thinking 等模式的语法模板文件 |
---
### 5. 实验性功能 (Experimental)
experimental 模块包含尚未稳定的功能：
| 组件 | 功能 |
|------|------|
| `tools.py` | 工具调用解析器 |
| `think.py` | 思考模式解析器 |
| `utils.py` | 通用工具函数 |
| `app/` | FastAPI 应用，包含路由器和入口点 |
资料来源：[AGENTS.md:79-88]()
---
### 6. 根级工具模块
| 模块文件 | 功能描述 |
|---------|---------|
| `audio.py` | 音频处理工具，包含 Audio 类和梅尔刻度转换 |
| `image.py` | 图像下载和序列化处理 |
| `base.py` | Pydantic 模型基础配置 |
| `exceptions.py` | 自定义异常类 |
| `imports.py` | 导入工具和依赖检查 |
资料来源：[AGENTS.md:28-37]()
---
## 数据流架构
```mermaid
flowchart TD
A[ChatCompletionRequest] --> B[MistralRequestValidator]
B --> C{验证通过?}
C -->|否| D[抛出异常]
C -->|是| E[InstructRequestNormalizer]
E --> F[InstructRequest]
F --> G[MistralTokenizer]
G --> H[InstructTokenizer]
H --> I[TekkenTokenizer]
I --> J[Tokenized 对象]
K[Tokenized.tokens] --> L[模型输入]
M[Tokenized.images] --> N[多模态处理]
O[Tokenized.audios] --> P[音频处理]
```
---
## 项目目录结构
```
mistral-common/
├── src/
│ └── mistral_common/
│ ├── protocol/ # 协议层
│ │ ├── instruct/ # 对话补全协议
│ │ ├── fim/ # 填空协议
│ │ ├── transcription/ # 转录协议
│ │ ├── base.py # 基础请求类
│ │ └── utils.py # 工具函数
│ ├── tokens/ # 令牌化层
│ │ ├── tokenizers/ # 分词器实现
│ │ └── instruct/ # (已废弃)
│ ├── guidance/ # 指导层
│ ├── experimental/ # 实验性功能
│ ├── audio.py # 音频处理
│ ├── image.py # 图像处理
│ ├── base.py # 基础配置
│ └── exceptions.py # 异常定义
├── tests/ # 测试套件
├── docs/ # 文档
├── .github/workflows/ # CI/CD 工作流
├── pyproject.toml # 项目配置
└── README.md # 项目说明
```
资料来源：[AGENTS.md:12-26]()
---
## 依赖管理
mistral-common 采用可选依赖设计，各功能模块可独立安装：
```sh
# 图像处理
pip install "mistral-common[image]"
# 音频处理
pip install "mistral-common[audio]"
# HuggingFace Hub 支持
pip install "mistral-common[hf-hub]"
# SentencePiece 支持 (已废弃)
pip install "mistral-common[sentencepiece]"
# 服务器模式
pip install "mistral-common[server]"
# 安装全部依赖
pip install "mistral-common[image,audio,hf-hub,sentencepiece,server]"
```
资料来源：[README.md:1-20]()
---
## 核心类关系图
```mermaid
classDiagram
class BaseCompletionRequest {
<>
}
class ChatCompletionRequest {
+messages: list[ChatMessageType]
+tools: list[Tool]
+response_format: ResponseFormat
+to_openai(): dict
}
class InstructRequest {
+messages
+system_prompt
+available_tools
}
class Tokenized {
+tokens: list[int]
+text: str
+prefix_ids: list[int]
+images: list[np.ndarray]
+audios: list[Audio]
}
class MistralRequestValidator {
+validate_request()
+validate_messages()
+_validate_tools()
}
class InstructRequestNormalizer {
+from_chat_completion_request()
}
class Tokenizer {
<>
+vocab()
+id_to_piece()
}
BaseCompletionRequest <|-- ChatCompletionRequest
ChatCompletionRequest --> MistralRequestValidator
ChatCompletionRequest --> InstructRequestNormalizer
InstructRequestNormalizer ..> InstructRequest
MistralTokenizer --> Tokenized
MistralTokenizer --> InstructRequestNormalizer
MistralTokenizer --|> Tokenizer
```
---
## 开发指南
### 代码规范
| 规范类型 | 具体要求 |
|---------|---------|
| 命名 | 函数/变量使用 snake_case，类使用 PascalCase |
| 类型提示 | 必须使用，优先采用 Python 3.10+ 语法 |
| 文档字符串 | 采用 Google 风格，包含 Args/Returns |
| 错误处理 | 使用 `mistral_common.exceptions` 中的自定义异常 |
资料来源：[AGENTS.md:95-110]()
### 开发工作流
1. **环境配置**：使用 uv 同步开发环境
2. **代码编写**：遵循代码规范，编写测试用例
3. **代码检查**：运行 Ruff、mypy、pytest
4. **提交**：安装 pre-commit hooks 后提交
```bash
uv sync --frozen --all-extras --group dev --python 3.12
source .venv/bin/activate
uv run pre-commit install
```
资料来源：[AGENTS.md:112-126]()
---
## 总结
mistral-common 作为 Mistral AI 模型的官方预处理库，通过分层架构实现了请求验证、规范化和令牌化的完整流程。库的设计强调模块化、可扩展性和类型安全，支持从简单的文本对话到复杂的多模态输入场景。开发者可通过清晰定义的接口扩展新功能，同时保持与现有系统的高度兼容性。
---
## 分词器系统详解
### 相关页面
相关主题：[多模态处理（图像与音频）](#p4), [指令与填充中间（FIM）协议](#p5), [项目架构总览](#p2)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)
- [src/mistral_common/tokens/tokenizers/sentencepiece.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/sentencepiece.py)
- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)
- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
- [src/mistral_common/tokens/tokenizers/instruct.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/instruct.py)
# 分词器系统详解
## 概述
mistral-common 的分词器系统是连接文本请求与大语言模型的核心组件，负责将用户输入的文本转换为模型可处理的 token 序列，以及将模型的输出 token 序列还原为可读文本。该系统支持多种 tokenizer 版本，从早期的 SentencePiece 实现到最新的 Tekken 分词器，为 Mistral 各代模型提供统一的文本处理能力。
分词器系统的主要职责包括：
- **编码（Encode）**：将原始文本转换为 token ID 序列
- **解码（Decode）**：将 token ID 序列转换回可读文本
- **特殊标记处理**：管理模型使用的特殊标记（如 ``、``、`[INST]` 等）
- **多模态支持**：处理图像和音频内容（部分版本）
- **请求验证**：在编码前验证请求格式的正确性
资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)
## 架构设计
### 分词器类型层次
分词器系统采用分层架构设计，从底层的字符级别编码到高层的请求处理，形成清晰的职责划分：
```mermaid
graph TD
A[MistralTokenizer
高层入口] --> B[InstructTokenizer
指令编码器]
B --> C[TekkenTokenizer
核心分词器]
C --> D[Base Model
底层编码模型]
E[SentencePieceTokenizer
已废弃] -.-> D
```
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
### 核心组件关系
| 组件 | 文件位置 | 职责 | 状态 |
|------|---------|------|------|
| `MistralTokenizer` | mistral.py | 高层工厂类，负责版本选择和组件组装 | 活跃 |
| `InstructTokenizer` | instruct.py | 将请求编码为 token 序列 | 活跃 |
| `TekkenTokenizer` | tekken.py | 核心分词实现，支持 v11+ | 活跃 |
| `SentencePieceTokenizer` | sentencepiece.py | 旧版分词实现 | 已废弃 |
## Tekken 分词器
Tekken 是 Mistral 最新模型使用的分词器实现，相比 SentencePiece 具有更好的性能和更丰富的功能支持。
### 特殊标记定义
Tekken 分词器定义了一套完整的特殊标记系统，用于标识文本结构、工具调用、图像等不同内容类型：
| 标记名称 | 标记字符串 | 用途 | 优先级 |
|---------|-----------|------|--------|
| unk | `` | 未知词元 | 1 |
| bos | `` | 序列起始 | 2 |
| eos | `` | 序列结束 | 3 |
| begin_inst | `[INST]` | 指令开始 | 4 |
| end_inst | `[/INST]` | 指令结束 | 5 |
| begin_tools | `[AVAILABLE_TOOLS]` | 工具列表开始 | 6 |
| end_tools | `[/AVAILABLE_TOOLS]` | 工具列表结束 | 7 |
| begin_tool_results | `[TOOL_RESULTS]` | 工具结果开始 | 8 |
| end_tool_results | `[/TOOL_RESULTS]` | 工具结果结束 | 9 |
| tool_calls | `[TOOL_CALLS]` | 工具调用标记 | 10 |
| img | `[IMG]` | 图像标记 | 11 |
| pad | `` | 填充标记 | 12 |
| img_break | `[IMG_BREAK]` | 图像截断标记 | 13 |
| img_end | `[IMG_END]` | 图像结束标记 | 14 |
| prefix | `[PREFIX]` | FIM 前缀标记 | 15 |
| middle | `[MIDDLE]` | FIM 中间标记 | 16 |
| suffix | `[SUFFIX]` | FIM 后缀标记 | 17 |
| begin_system | `[SYSTEM_PROMPT]` | 系统提示开始 | 18 |
| end_system | `[/SYSTEM_PROMPT]` | 系统提示结束 | 19 |
| begin_tool_content | `[TOOL_CONTENT]` | 工具内容开始 | 20 |
| begin_think | `[THINK]` | 思考开始 | 21 |
| end_think | `[/THINK]` | 思考结束 | 22 |
资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)
### 特殊标记策略
`SpecialTokenPolicy` 枚举控制分词器在解码时如何处理特殊标记：
```python
class SpecialTokenPolicy(str, Enum):
"""What to do with special tokens when encoding/decoding."""
IGNORE = "ignore" # 解码时跳过特殊标记
KEEP = "keep" # 解码时保留特殊标记
RAISE = "raise" # 遇到特殊标记时抛出异常
```
使用示例：
```python
from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
from mistral_common.tokens.tokenizers.tekken import SpecialTokenPolicy
tokenizer = MistralTokenizer.v3(is_tekken=True)
tekken = tokenizer.instruct_tokenizer.tokenizer
tekken.special_token_policy = SpecialTokenPolicy.IGNORE
```
资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)
### 核心 API
TekkenTokenizer 提供以下核心接口：
| 方法/属性 | 返回类型 | 说明 |
|----------|---------|------|
| `n_words` | `int` | 词表大小 |
| `special_ids` | `set[int]` | 特殊标记的 ID 集合 |
| `num_special_tokens` | `int` | 特殊标记数量 |
| `vocab()` | `list[str]` | 返回所有词表 token |
| `id_to_piece(token_id)` | `str` | 将 token ID 转换为字符串 |
| `encode(text)` | `Tokenized` | 编码文本 |
| `decode(tokens)` | `str` | 解码 token 序列 |
| `is_byte(token_id)` | `bool` | 检查是否为字节 token |
| `is_special(token)` | `bool` | 检查是否为特殊标记 |
| `get_special_token(s)` | `int` | 获取特殊标记的 ID |
资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)
## Tokenized 数据结构
`Tokenized` 是分词结果的核心数据结构，用于在系统各组件间传递编码后的数据：
```python
class Tokenized:
"""Represents a tokenized request or response."""
model_config = ConfigDict(arbitrary_types_allowed=True)
tokens: list[int] # Token ID 列表
text: str | None = None # 原始文本（解码时使用）
prefix_ids: list[int] | None = None # FIM 前缀 ID
images: list[np.ndarray] = Field(default_factory=list) # 关联图像
audios: list[Audio] = Field(default_factory=list) # 关联音频
```
资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)
## 分词器版本演进
mistral-common 支持多个 tokenizer 版本，以适配不同代际的 Mistral 模型：
| 版本 | 图像支持 | 音频支持 | 推荐用途 |
|------|---------|---------|---------|
| v1 | ❌ | ❌ | 早期模型兼容 |
| v2 | ❌ | ❌ | 早期模型兼容 |
| v3 | ✅ | ❌ | 图像支持模型 |
| v7 | ✅ | ❌ | 高级推理模型 |
| v11 | ✅ | ✅ | 最新模型（推荐） |
| v13 | ✅ | ✅ | 最新模型（最新） |
版本创建逻辑：
```python
if tokenizer.version == TokenizerVersion.v1:
return MistralTokenizer(InstructTokenizerV1(tokenizer), ...)
elif tokenizer.version == TokenizerVersion.v11:
return MistralTokenizer(
InstructTokenizerV11(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),
...
)
```
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
## MistralTokenizer 工厂类
`MistralTokenizer` 是系统的高层入口，提供版本感知的分词器创建能力：
### 创建方法
| 静态方法 | 说明 | 适用版本 |
|---------|------|---------|
| `v1()` | 创建 v1 分词器 | v1 |
| `v2()` | 创建 v2 分词器 | v2 |
| `v3()` | 创建 v3 分词器 | v3 |
| `v7()` | 创建 v7 分词器 | v7 |
| `v11()` | 创建 v11 分词器 | v11 |
| `v13()` | 创建 v13 分词器 | v13 |
| `from_path(path)` | 从路径加载分词器 | 所有版本 |
### 核心属性
| 属性 | 类型 | 说明 |
|-----|------|------|
| `instruct_tokenizer` | `InstructTokenizer` | 指令编码器实例 |
| `validator` | `MistralRequestValidator` | 请求验证器 |
| `request_normalizer` | `InstructRequestNormalizer` | 请求标准化器 |
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
## 解码流程
解码过程处理 token 序列到文本的转换，需要正确处理特殊标记：
```mermaid
graph LR
A[Token ID 序列] --> B{特殊标记策略?}
B -->|KEEP| C[保留特殊标记字符串]
B -->|IGNORE| D[跳过特殊标记]
B -->|RAISE| E[抛出异常]
C --> F[普通 token 解码]
D --> F
F --> G[拼接结果]
C --> G
```
解码实现核心逻辑：
```python
def decode(self, tokens: list[int], ...) -> str:
decoded = []
for t in tokens:
if t in self._all_special_tokens:
if special_token_policy == SpecialTokenPolicy.RAISE:
raise ValueError("...")
elif special_token_policy == SpecialTokenPolicy.KEEP:
decoded.append(self._all_special_tokens[t]["token_str"])
elif special_token_policy == SpecialTokenPolicy.IGNORE:
continue
else:
decoded.append(self._model.decode([t - self.num_special_tokens]))
return "".join(decoded)
```
资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)
## 与 Guidance 系统集成
GrammarFactory 使用分词器生成语法约束，用于控制模型输出的格式。该集成需要 Tekken tokenizer 版本 >= v11：
```python
class GrammarFactory:
def __init__(self, tokenizer):
assert_llguidance_installed()
assert_jinja2_installed()
self._tokenizer = tokenizer.instruct_tokenizer.tokenizer
if not self.is_supported(tokenizer):
raise ValueError(
f"Guidance requires a Tekken tokenizer with version >= v11, "
f"got {type(self._tokenizer).__name__} {self._tokenizer.version.value}"
)
self._llg_tokenizer = from_mistral_tokenizer(tokenizer)
self._special_token_map = self._build_special_token_map()
```
资料来源：[src/mistral_common/guidance/grammar_factory.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/grammar_factory.py)
## 使用示例
### 基础编码解码
```python
from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
# 加载分词器
tokenizer = MistralTokenizer.v3()
# 编码文本
tokenized = tokenizer.instruct_tokenizer.encode("Hello, how are you?")
print(f"Token IDs: {tokenized.tokens}")
print(f"Token count: {len(tokenized.tokens)}")
# 解码文本
decoded = tokenizer.instruct_tokenizer.decode(tokenized.tokens)
print(f"Decoded: {decoded}")
```
### 处理多模态内容（v11+）
```python
from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
from mistral_common.image import Image
tokenizer = MistralTokenizer.v11()
# 处理包含图像的请求
image = Image.from_url("https://example.com/image.jpg")
tokenized = tokenizer.instruct_tokenizer.encode(
"Describe this image",
images=[image]
)
```
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
## 弃用说明
### SentencePieceTokenizer
`SentencePieceTokenizer` 已弃用，仅保留用于向后兼容。推荐使用 Tekken 分词器：
| 特性 | SentencePiece | Tekken |
|------|--------------|--------|
| 性能 | 较低 | 高 |
| 特殊标记支持 | 有限 | 完整 |
| 多模态支持 | ❌ | ✅ |
| Guidance 集成 | ❌ | ✅ |
| 状态 | 已废弃 | 活跃 |
资料来源：[src/mistral_common/tokens/tokenizers/sentencepiece.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/sentencepiece.py)
## 总结
mistral-common 的分词器系统提供了从底层编码到高层请求处理的完整能力栈。核心要点：
1. **Tekken 是推荐的实现**：相比废弃的 SentencePiece，提供更好的性能和更完整的功能
2. **版本分层设计**：通过 `MistralTokenizer` 工厂类统一管理不同版本的分词器
3. **特殊标记策略**：通过 `SpecialTokenPolicy` 灵活控制特殊标记的解码行为
4. **多模态扩展**：v3+ 版本支持图像处理，v11+ 版本支持音频处理
5. **与 Guidance 集成**：v11+ 版本可与 GrammarFactory 配合进行结构化输出控制
---
## 多模态处理（图像与音频）
### 相关页面
相关主题：[分词器系统详解](#p3), [指令与填充中间（FIM）协议](#p5)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mistral_common/tokens/tokenizers/image.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/image.py)
- [src/mistral_common/tokens/tokenizers/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/audio.py)
- [src/mistral_common/image.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/image.py)
- [src/mistral_common/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/audio.py)
- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)
- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
# 多模态处理（图像与音频）
## 概述
mistral-common 库提供了完整的多模态处理能力，支持在文本对话中嵌入图像和音频内容。该模块是预处理管道的核心组成部分，负责将用户提供的多模态数据（图像、音频）转换为模型可处理的 token 序列。
多模态处理的核心设计目标是：
- **图像支持**：从 v3 版本 tokenizer 开始引入，支持图像下载、预处理和 token 化
- **音频支持**：从 v7 版本 tokenizer 开始引入，支持音频编码和解码
- **无缝集成**：与现有的 ChatCompletionRequest 协议完全兼容
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()
## 架构设计
### 多模态处理流程
```mermaid
graph TD
A[ChatCompletionRequest] --> B[请求验证 Validator]
B --> C[请求标准化 Normalizer]
C --> D{多模态类型判断}
D -->|仅文本| E[InstructTokenizer - 纯文本编码]
D -->|含图像| F[ImageEncoder + InstructTokenizerV3/V7/V11/V13/V15]
D -->|含音频| G[AudioEncoder + InstructTokenizerV7/V11/V13/V15]
D -->|图像+音频| H[ImageEncoder + AudioEncoder + 组合Tokenizer]
E --> I[Tokenized 对象]
F --> I
G --> I
H --> I
I --> J[模型输入]
```
### 核心组件关系
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| Tokenized | `tokens/tokenizers/base.py` | 多模态 token 化结果的数据结构 |
| ImageEncoder | `tokens/tokenizers/image.py` | 图像编码器接口 |
| AudioEncoder | `tokens/tokenizers/audio.py` | 音频编码器接口 |
| MistralTokenizer | `tokens/tokenizers/mistral.py` | 综合 tokenizer，支持图像和音频 |
| Image 工具类 | `image.py` | 图像下载和序列化工具 |
| Audio 工具类 | `audio.py` | 音频处理和 mel-scale 转换 |
## Tokenized 数据结构
多模态处理的结果通过 `Tokenized` 类表示，该类继承自 Pydantic BaseModel，支持灵活的多模态数据存储：
```python
class Tokenized(MistralBase):
"""Represents the tokenized output of a tokenizer.
Attributes:
tokens: The token ids.
text: The text representation of the tokens.
prefix_ids: The prefix ids for FIM.
images: The loaded images associated with the tokens.
audios: The audio objects associated with the tokens.
"""
model_config = ConfigDict(arbitrary_types_allowed=True)
tokens: list[int]
text: str | None = None
prefix_ids: list[int] | None = None
images: list[np.ndarray] = Field(default_factory=list)
audios: list[Audio] = Field(default_factory=list)
```
**字段说明**：
| 字段 | 类型 | 说明 |
|------|------|------|
| `tokens` | `list[int]` | token ID 序列，模型的核心输入 |
| `text` | `str \| None` | token 对应的文本表示 |
| `prefix_ids` | `list[int] \| None` | FIM（Fill-In-The-Middle）任务的 prefix token |
| `images` | `list[np.ndarray]` | 预处理后的图像 NumPy 数组列表 |
| `audios` | `list[Audio]` | 处理后的音频对象列表 |
资料来源：[src/mistral_common/tokens/tokenizers/base.py:50-65]()
## 图像处理
### 安装依赖
图像处理需要安装 `image` 额外依赖：
```sh
pip install "mistral-common[image]"
```
### ImageEncoder 接口
`ImageEncoder` 是一个抽象基类，定义了图像编码的标准接口：
```python
class ImageEncoder(ABC):
@abstractmethod
def encode_images(self, images: list[np.ndarray]) -> list[ImageOutput]:
"""Encode a list of images into model input format."""
@property
@abstractmethod
def image_token_id(self) -> int:
"""The token id for image tokens."""
```
### 图像处理工具类
`mistral_common.image` 模块提供了图像处理的核心工具函数：
```python
class Image(MistralBase):
"""Image representation with download and serialization support."""
url: str | None = None
base64: str | None = None
content: bytes | None = None
```
主要功能：
- **图像下载**：支持从 URL 下载图像内容
- **Base64 编码/解码**：支持 base64 格式的图像数据
- **预处理**：将图像转换为 NumPy 数组格式
- **序列化**：支持图像数据的序列化和反序列化
资料来源：[src/mistral_common/image.py:1-100]()
### 特殊 Token
图像相关的特殊 Token 定义在 `SpecialTokens` 类中：
| Token | 标识 | 用途 |
|-------|------|------|
| `img` | `[IMG]` | 图像开始标记 |
| `img_break` | `[IMG_BREAK]` | 多图像分隔标记 |
| `img_end` | `[IMG_END]` | 图像结束标记 |
资料来源：[src/mistral_common/tokens/tokenizers/base.py:100-110]()
## 音频处理
### 安装依赖
音频处理需要安装 `audio` 额外依赖：
```sh
pip install "mistral-common[audio]"
```
### AudioEncoder 接口
`AudioEncoder` 是音频编码器的抽象基类：
```python
class AudioEncoder(ABC):
@abstractmethod
def encode_audio(self, audio: Audio) -> AudioOutput:
"""Encode a single audio object into model input format."""
```
### Audio 数据类
`Audio` 类是音频数据的核心表示：
```python
class Audio(MistralBase):
"""Audio representation with mel-scale conversion support."""
# 音频采样数据
samples: np.ndarray
# 采样率
sample_rate: int
# 编码格式
format: str | None = None
```
主要功能：
- **音频采样表示**：以 NumPy 数组形式存储音频采样数据
- **采样率管理**：记录和验证音频采样率
- **Mel-scale 转换**：支持梅尔频谱转换用于模型处理
- **格式支持**：支持多种音频编码格式
资料来源：[src/mistral_common/audio.py:1-100]()
### 音频相关特殊 Token
| Token | 标识 | 用途 |
|-------|------|------|
| `audio` | `[AUDIO]` | 音频 token 标记 |
| `begin_audio` | `[BEGIN_AUDIO]` | 音频内容开始 |
| `transcribe` | `[TRANSCRIBE]` | 转录指令 |
| `text_to_audio` | `[NEXT_AUDIO_TEXT]` | 文本转语音输出标记 |
| `audio_to_text` | `[REPEAT_AUDIO_TEXT]` | 语音转文本标记 |
资料来源：[src/mistral_common/tokens/tokenizers/base.py:110-120]()
## Tokenizer 版本与多模态支持
不同版本的 tokenizer 支持不同的多模态功能：
| Tokenizer 版本 | 图像支持 | 音频支持 | 特点 |
|----------------|----------|----------|------|
| v1 | ❌ | ❌ | 纯文本 tokenizer |
| v2 | ❌ | ❌ | 纯文本 tokenizer |
| v3 | ✅ | ❌ | 引入图像支持 |
| v7 | ✅ | ✅ | 引入音频支持 |
| v11 | ✅ | ✅ | 增强的多模态支持 |
| v13 | ✅ | ✅ | 最新稳定版本 |
| v15 | ✅ | ✅ | 最新版本 |
**版本断言检查**：
```python
def create_tokenizer(tokenizer_filename, image_encoder=None, audio_encoder=None):
if tokenizer.version == TokenizerVersion.v3:
assert image_encoder is not None, "Tokenizer version v3 requires image_encoder"
assert audio_encoder is None, "Tokenizer version v3 does not support audio"
elif tokenizer.version == TokenizerVersion.v7:
# v7+ 支持音频编码器
...
```
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:30-80]()
## ChatCompletionRequest 中的多模态支持
`ChatCompletionRequest` 是多模态请求的入口点，通过 `messages` 字段携带多模态内容：
```python
class ChatCompletionRequest(MistralBase):
"""Chat completion request with multimodal support."""
model: str | None = None
messages: list[ChatMessageType] # 可包含图像/音频消息
response_format: ResponseFormat = Field(default_factory=ResponseFormat)
tools: list[Tool] | None = None
tool_choice: ToolChoice = ToolChoiceEnum.auto
truncate_for_context_length: bool = False
continue_final_message: bool = False
reasoning_effort: ReasoningEffort | None = None # 推理控制参数
```
**消息类型层次结构**：
- `UserMessage`：用户消息，可包含文本、图像、音频
- `AssistantMessage`：助手回复消息
- `SystemMessage`：系统提示消息
- `ToolMessage`：工具调用结果消息
## 完整编码流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant Validator as MistralRequestValidator
participant Normalizer as InstructRequestNormalizer
participant Tokenizer as MistralTokenizer
participant Encoder as Image/Audio Encoder
participant Model as 底座模型
Client->>Validator: ChatCompletionRequest (含多模态)
Validator->>Validator: 验证消息结构
Validator->>Validator: 验证工具定义
Validator->>Normalizer: 验证通过的请求
Normalizer->>Normalizer: 标准化消息格式
Normalizer->>Tokenizer: InstructRequest
alt 包含图像
Tokenizer->>Encoder: 调用 ImageEncoder
Encoder-->>Tokenizer: ImageOutput
end
alt 包含音频
Tokenizer->>Encoder: 调用 AudioEncoder
Encoder-->>Tokenizer: AudioOutput
end
Tokenizer->>Tokenizer: 生成 token 序列
Tokenizer-->>Client: Tokenized 对象
Client->>Model: tokens + images + audios
```
## 使用示例
### 基本图像编码
```python
from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
from mistral_common.image import Image
import numpy as np
# 初始化 tokenizer
tokenizer = MistralTokenizer.from_filename("path/to/tokenizer")
# 准备图像数据
image_array = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
# 创建 Tokenized 结果
tokenized = tokenizer.encode_images([image_array])
```
### 音频编码
```python
from mistral_common.audio import Audio
from mistral_common.tokens.tokenizers.audio import AudioEncoder
import numpy as np
# 创建音频对象
audio = Audio(
samples=np.random.randn(16000), # 1秒音频，16kHz采样率
sample_rate=16000
)
# 通过 tokenizer 编码
tokenized = tokenizer.encode(audio)
```
### 完整对话请求
```python
from mistral_common.protocol.instruct.request import ChatCompletionRequest
from mistral_common.protocol.instruct.messages import UserMessage
from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
# 创建带图像的用户消息
request = ChatCompletionRequest(
messages=[
UserMessage(
content="这张图片中有什么?",
images=[image_data] # 图像数据
)
],
model="mistral-large-latest"
)
# 编码请求
tokenizer = MistralTokenizer.from_filename("path/to/tokenizer")
tokenized = tokenizer.encode_chat_completion(request)
```
## 最佳实践
1. **版本选择**：生产环境建议使用 v13 或 v15 版本，以获得完整的多模态支持
2. **图像预处理**：在传入 tokenizer 前，确保图像尺寸符合模型要求
3. **音频采样率**：验证音频采样率与模型预期一致（通常为 16kHz 或 24kHz）
4. **上下文截断**：设置 `truncate_for_context_length=True` 以处理超长输入
5. **错误处理**：使用 `InvalidRequestException` 捕获验证错误
## 相关文档
- [工具调用（Tool Calls）](./tool_calls.md)
- [指导语法（Grammar）](./grammar.md)
- [请求协议（Request Protocol）](./request_protocol.md)
- [API 参考文档](https://mistralai.github.io/mistral-common/)
---
## 指令与填充中间（FIM）协议
### 相关页面
相关主题：[请求验证与标准化](#p6), [语音与转录协议](#p7), [分词器系统详解](#p3)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)
- [src/mistral_common/protocol/fim/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/fim/request.py)
- [src/mistral_common/protocol/instruct/messages.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/messages.py)
- [src/mistral_common/protocol/instruct/chunk.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/chunk.py)
- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)
- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)
- [src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)
- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
# 指令与填充中间（FIM）协议
## 概述
mistral-common 库支持两种主要的协议类型，用于处理不同场景下的请求：
| 协议类型 | 用途 | 请求类 | 主要特性 |
|---------|------|--------|---------|
| **Instruct 协议** | 对话式指令任务 | `ChatCompletionRequest` | 支持多轮对话、工具调用、响应格式控制 |
| **FIM 协议** | 填充中间代码补全 | `FIMRequest` | 支持 prompt/suffix 模式进行代码补全 |
Instruct 协议是用户查询 Instruct 请求的入口点，而 FIM（Fill-in-the-Middle）协议专门用于代码补全场景，模型需要在给定的前缀（prompt）和后缀（suffix）之间生成内容。资料来源：[src/mistral_common/protocol/fim/request.py:1-15]()
---
## FIM 协议
### 概述
FIM（Fill-in-the-Middle）协议是一种用于代码补全的特殊协议。与传统的前缀补全不同，FIM 允许模型在两个已知部分（prefix 和 suffix）之间生成内容，这非常适合以下场景：
- 在函数签名和函数结尾之间补全函数体
- 在类的开头和结尾之间补全类成员
- 在代码块的开始和结束标记之间补全内容
### 数据模型
```python
class FIMRequest(BaseCompletionRequest):
"""填充中间请求模型"""
prompt: str # 前缀内容
suffix: str | None = None # 后缀内容（可选）
```
**字段说明：**
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `prompt` | `str` | 是 | 要补全内容的前缀部分 |
| `suffix` | `str \| None` | 否 | 要补全内容的后缀部分。如果提供，模型将在 prompt 和 suffix 之间生成文本 |
### 使用示例
```python
from mistral_common.protocol.fim.request import FIMRequest
# 基础用法
request = FIMRequest(prompt='def calculate_sum(a, b):\n """Calculate sum of two numbers"""\n return')
# 带后缀的用法
request = FIMRequest(
prompt='class MyClass:\n def __init__',
suffix='\n\n# Usage\nobj = MyClass(10)'
)
```
资料来源：[src/mistral_common/protocol/fim/request.py:1-17]()
---
## Instruct 协议
### 概述
Instruct 协议是处理对话式指令任务的核心协议。用户通过 `ChatCompletionRequest` 类发起请求，该请求经过验证、标准化后转换为内部指令格式，再由 tokenizer 编码为 token 序列。
### 架构流程
```mermaid
graph TD
A[用户请求] --> B[ChatCompletionRequest]
B --> C[MistralRequestValidator 验证]
C --> D[InstructRequestNormalizer 标准化]
D --> E[InstructRequest]
E --> F[InstructTokenizer 编码]
F --> G[Tokenized 输出]
H[消息列表] --> B
I[工具定义] --> B
J[响应格式] --> B
```
### ChatCompletionRequest 数据模型
```python
class ChatCompletionRequest(BaseCompletionRequest[UserMessageType, AssistantMessageType, ToolMessageType, SystemMessageType]):
"""Instruct 协议请求模型"""
model: str | None = None # 模型名称
messages: list[ChatMessageType] # 消息列表
response_format: ResponseFormat = Field(...) # 响应格式
tools: list[Tool] | None = None # 工具定义列表
tool_choice: ToolChoice = ToolChoiceEnum.auto # 工具选择策略
truncate_for_context_length: bool = False # 是否截断超长内容
continue_final_message: bool = False # 继续生成最终消息
reasoning_effort: ReasoningEffort | None = None # 推理努力程度
```
**核心字段说明：**
| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `model` | `str \| None` | `None` | 模型标识符，用于服务模式验证 |
| `messages` | `list[ChatMessageType]` | 必填 | 对话消息列表，包含用户、助手、系统消息 |
| `response_format` | `ResponseFormat` | `text` | 期望的响应格式 |
| `tools` | `list[Tool] \| None` | `None` | 可用工具定义列表 |
| `tool_choice` | `ToolChoice` | `auto` | 工具选择策略（auto/none/required/指定工具） |
| `truncate_for_context_length` | `bool` | `False` | 上下文超长时是否自动截断 |
| `continue_final_message` | `bool` | `False` | 是否继续生成未完成的最终消息 |
| `reasoning_effort` | `ReasoningEffort \| None` | `None` | 控制模型的推理努力程度 |
资料来源：[src/mistral_common/protocol/instruct/request.py:1-100]()
---
## 消息类型系统
### 消息类型分类
```mermaid
graph TD
A[ChatMessageType] --> B[UserMessage]
A --> C[AssistantMessage]
A --> D[SystemMessage]
A --> E[ToolMessage]
B --> F[文本内容]
B --> G[多媒体内容]
C --> H[文本内容]
C --> I[工具调用]
D --> J[系统提示]
```
### 消息基类与子类型
| 消息类型 | 角色标识 | 说明 |
|---------|---------|------|
| `UserMessage` | `user` | 用户消息，支持文本和多媒体内容 |
| `AssistantMessage` | `assistant` | 助手消息，可包含文本和工具调用结果 |
| `SystemMessage` | `system` | 系统级指令和上下文设置 |
| `ToolMessage` | `tool` | 工具执行结果返回消息 |
### 消息内容结构
消息内容支持多种格式的块（Chunk）：
```python
# 文本块
TextChunk(content="Hello, how can I help you?")
# 图片块
ImageChunk(image=image_data)
# 音频块
AudioChunk(audio=audio_data)
```
资料来源：[src/mistral_common/protocol/instruct/chunk.py:1-30]()
---
## 验证与标准化
### 请求验证流程
```mermaid
graph TD
A[ChatCompletionRequest] --> B{ValidationMode}
B -->|serving| C[检查 model 字段]
B -->|test/finetuning| D[跳过 model 检查]
C --> E[validate_messages]
D --> E
E --> F[validate_tools]
F --> G[validate_model_settings]
G --> H[返回验证后的请求]
```
### 验证模式
| 模式 | 说明 | model 字段要求 |
|-----|------|---------------|
| `ValidationMode.serving` | 生产服务模式 | 必须提供 |
| `ValidationMode.test` | 测试模式 | 可选 |
| `ValidationMode.finetuning` | 微调模式 | 可选 |
### 消息列表验证规则
1. **结构验证**：检查消息列表的起止位置是否符合预期
2. **内容验证**：检查每条消息的内容格式和字段完整性
3. **角色序列验证**：确保消息角色按合法顺序排列
4. **继续消息验证**：当 `continue_final_message=True` 时，验证最终消息格式
资料来源：[src/mistral_common/protocol/instruct/validator.py:1-80]()
### 标准化处理器
标准化器将 `ChatCompletionRequest` 转换为内部 `InstructRequest` 格式：
```python
class InstructRequestNormalizer:
"""请求标准化器基类"""
def from_chat_completion_request(self, request: ChatCompletionRequest) -> InstructRequest:
"""将聊天补全请求转换为指令请求"""
system_prompt = self._aggregate_system_prompts(request.messages)
messages = self._aggregate_messages(request.messages)
settings = self.build_settings(request)
return self._instruct_request_class(
messages=messages,
system_prompt=system_prompt,
available_tools=request.tools,
continue_final_message=request.continue_final_message,
settings=settings,
)
```
### 版本化标准化器
| 标准化器 | 版本 | 特性 |
|---------|------|------|
| `InstructRequestNormalizerV1` | v1 | 基础版本 |
| `InstructRequestNormalizerV2` | v2 | 支持更多配置 |
| `InstructRequestNormalizerV7` | v7 | 系统提示在开头，允许工具调用与内容共存 |
资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-60]()
---
## 工具调用系统
### 工具定义结构
```python
class Tool(MistralBase):
"""工具定义"""
type: ToolTypes = ToolTypes.function
function: Function
class Function:
"""函数定义"""
name: str # 函数名（正则: ^[a-zA-Z0-9_-]{1,64}$）
description: str | None = None # 函数描述
parameters: dict # JSON Schema 参数定义
```
### 工具选择策略
| 策略 | 说明 |
|-----|------|
| `ToolChoiceEnum.auto` | 模型自动决定是否调用工具 |
| `ToolChoiceEnum.none` | 禁止调用工具 |
| `ToolChoiceEnum.required` | 必须调用至少一个工具 |
| `NamedToolChoice` | 指定调用特定工具 |
### 工具参数 JSON Schema 验证
工具参数必须符合 JSON Schema Draft-7 规范：
```python
# 有效工具示例
tool = Tool(
function=Function(
name="get_current_weather",
description="获取指定位置的当前天气",
parameters={
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["location"]
}
)
)
```
资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:1-100]()
---
## Tokenizer 与编码
### Tokenizer 版本支持
| Tokenizer 版本 | 特性 | 图像支持 | 音频支持 |
|---------------|------|---------|---------|
| `TokenizerVersion.v1` | 基础 | ❌ | ❌ |
| `TokenizerVersion.v2` | 扩展 | ❌ | ❌ |
| `TokenizerVersion.v3` | 图像支持 | ✅ | ❌ |
| `TokenizerVersion.v7` | 图像+音频 | ✅ | ✅ |
| `TokenizerVersion.v11` | 高级 | ✅ | ✅ |
| `TokenizerVersion.v13` | 最新 | ✅ | ✅ |
### Tokenizer 工厂函数
```python
def get_tokenizer(
tokenizer: Tokenizer,
mode: ValidationMode = ValidationMode.test,
image_encoder: Any = None,
audio_encoder: Any = None,
) -> MistralTokenizer:
"""根据 tokenizer 版本创建相应的 MistralTokenizer"""
validator = get_validator(tokenizer.version, mode=mode)
if tokenizer.version == TokenizerVersion.v1:
return MistralTokenizer(
InstructTokenizerV1(tokenizer),
validator=validator,
request_normalizer=request_normalizer,
)
elif tokenizer.version == TokenizerVersion.v7:
return MistralTokenizer(
InstructTokenizerV7(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),
validator=validator,
request_normalizer=request_normalizer,
)
# ... 其他版本
```
### Tokenized 输出结构
```python
class Tokenized:
"""编码后的 token 结果"""
tokens: list[int] # token ID 列表
text: str | None = None # 文本表示
prefix_ids: list[int] | None = None # FIM 前缀 ID
images: list[np.ndarray] = Field(default_factory=list) # 关联图像
audios: list[Audio] = Field(default_factory=list) # 关联音频
```
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-80]()
---
## OpenAI 格式转换
### 请求转换方法
`ChatCompletionRequest` 提供了 `to_openai()` 方法将请求转换为 OpenAI API 格式：
```python
def to_openai(self, **kwargs: Any) -> dict[str, Any]:
"""将请求转换为 OpenAI 格式"""
```
**转换示例：**
```python
from mistral_common.protocol.instruct.messages import UserMessage
request = ChatCompletionRequest(
messages=[UserMessage(content="Hello, how are you?")],
temperature=0.15
)
# 转换为 OpenAI 格式
openai_request = request.to_openai(stream=True)
# 输出:
# {
# 'temperature': 0.15,
# 'top_p': 1.0,
# 'response_format': {'type': 'text'},
# 'continue_final_message': False,
# 'messages': [{'role': 'user', 'content': 'Hello, how are you?'}],
# 'tool_choice': 'auto',
# 'stream': True
# }
```
资料来源：[src/mistral_common/protocol/instruct/request.py:80-150]()
---
## 特殊控制参数
### continue_final_message 参数
此参数控制模型是否继续生成未完成的最终消息：
| 值 | 行为 |
|---|------|
| `False`（默认） | 模型正常生成完整响应 |
| `True` | 模型继续之前的消息内容进行生成 |
### reasoning_effort 参数
控制模型的推理努力程度：
```python
class ReasoningEffort(str, Enum):
"""推理努力程度枚举"""
low = "low" # 低推理努力
medium = "medium" # 中等推理努力
high = "high" # 高推理努力
```
### truncate_for_context_length 参数
| 值 | 行为 |
|---|------|
| `False`（默认） | 上下文超长时抛出异常 |
| `True` | 自动截断消息以适应上下文长度 |
---
## 完整使用流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant Validator as MistralRequestValidator
participant Normalizer as InstructRequestNormalizer
participant Tokenizer as InstructTokenizer
participant Model as 推理模型
Client->>Validator: 提交 ChatCompletionRequest
Validator->>Validator: 验证消息格式
Validator->>Validator: 验证工具定义
Validator->>Validator: 验证模型设置
Validator-->>Client: 返回验证后的请求
Client->>Normalizer: 标准化请求
Normalizer->>Normalizer: 聚合系统提示
Normalizer->>Normalizer: 聚合消息
Normalizer-->>Client: 返回 InstructRequest
Client->>Tokenizer: 编码为 tokens
Tokenizer->>Model: 发送 token 序列
Model-->>Tokenizer: 返回生成的 token
Tokenizer-->>Client: 返回 Tokenized 结果
```
**完整代码示例：**
```python
from mistral_common.protocol.instruct.request import ChatCompletionRequest
from mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage
from mistral_common.protocol.instruct.tool_calls import Tool, ToolTypes, Function
from mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode
# 1. 创建请求
request = ChatCompletionRequest(
model="mistral-large-latest",
messages=[
UserMessage(content="What is the weather in Paris?"),
AssistantMessage(content="I'll check that for you."),
],
tools=[
Tool(
type=ToolTypes.function,
function=Function(
name="get_weather",
description="Get weather for a location",
parameters={
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
}
)
)
],
tool_choice="auto",
truncate_for_context_length=True,
)
# 2. 验证请求
validator = MistralRequestValidator(mode=ValidationMode.serving)
validated_request = validator.validate_request(request)
# 3. 标准化请求
normalizer = InstructRequestNormalizer.normalizer()
instruct_request = normalizer.from_chat_completion_request(validated_request)
# 4. 编码请求
# tokenized = tokenizer.encode_instruct(instruct_request)
```
---
## 错误处理
### 自定义异常类型
| 异常类型 | 用途 |
|---------|------|
| `InvalidRequestException` | 请求参数验证失败 |
| `InvalidToolSchemaException` | 工具参数 schema 无效 |
| `InvalidToolException` | 工具定义无效 |
| `InvalidMessageException` | 消息格式或内容无效 |
### 常见验证错误
1. **模型名称缺失**：在 serving 模式下必须提供 `model` 参数
2. **工具 schema 无效**：工具参数不符合 JSON Schema Draft-7 规范
3. **工具名称无效**：函数名不符合正则 `^[a-zA-Z0-9_-]{1,64}$`
4. **消息序列错误**：消息顺序不符合协议规定
---
## 总结
mistral-common 库的指令与填充中间协议为 LLM 交互提供了两个互补的接口：
1. **Instruct 协议** (`ChatCompletionRequest`)：适合对话式、工具调用和多轮交互场景，提供完整的验证和标准化流程。
2. **FIM 协议** (`FIMRequest`)：专为代码补全设计，通过 prompt/suffix 模式支持在代码任意位置插入内容。
两个协议都遵循相同的验证-标准化-编码流程，确保请求的正确性和一致性。
---
## 请求验证与标准化
### 相关页面
相关主题：[指令与填充中间（FIM）协议](#p5), [语音与转录协议](#p7), [项目架构总览](#p2)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)
- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)
- [src/mistral_common/protocol/instruct/converters.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/converters.py)
- [src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)
- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)
# 请求验证与标准化
## 概述
请求验证与标准化是 mistral-common 库中处理用户输入请求的核心模块。该模块负责在将用户请求传递给模型之前，对其进行结构验证、内容校验和格式转换。mistral-common 通过 `MistralRequestValidator` 和 `InstructRequestNormalizer` 两个核心类来实现这一功能，确保请求符合 Mistral 模型的输入规范，同时为不同的 tokenizer 版本提供统一的支持。
该模块在整个处理流程中处于关键位置，属于预处理阶段的前置验证环节。验证失败时抛出自定义异常（如 `InvalidRequestException`、`InvalidToolSchemaException` 等），确保错误信息能够被上游调用方正确捕获和处理。资料来源：[src/mistral_common/protocol/instruct/validator.py:1-50]()
## 核心组件
### MistralRequestValidator
`MistralRequestValidator` 是一个泛型类，负责验证 `ChatCompletionRequest` 的结构和内容。它支持三种验证模式，通过 `ValidationMode` 枚举进行配置。资料来源：[src/mistral_common/protocol/instruct/validator.py:19-22]()
| 验证模式 | 用途 | 特定行为 |
|---------|------|---------|
| `serving` | 服务部署模式 | 要求必须提供 model 参数 |
| `finetuning` | 微调模式 | 允许特定的微调参数组合 |
| `test` | 测试/默认模式 | 标准验证规则 |
### InstructRequestNormalizer
`InstructRequestNormalizer` 负责将标准化的 `ChatCompletionRequest` 转换为 `InstructRequest` 格式。该类处理系统提示的聚合、消息的重组以及模型设置的提取。资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-100]()
## 请求验证流程
### 验证架构
```mermaid
graph TD
A[ChatCompletionRequest] --> B[MistralRequestValidator]
B --> C{验证模式}
C -->|serving| D[检查 model 参数]
C -->|其他| E[跳过 model 检查]
D --> F[validate_messages]
E --> F
F --> G[validate_message_list_structure]
F --> H[validate_message_list_content]
G --> I[_validate_tools]
H --> I
I --> J[validate_model_settings]
J --> K[返回 validated_request]
I -.->|工具Schema无效| L[InvalidToolSchemaException]
G -.->|结构错误| M[InvalidRequestException]
```
### 验证步骤详解
#### 1. 模型参数验证
在 `serving` 模式下，系统会检查请求是否包含 `model` 参数。如果缺失，将抛出 `InvalidRequestException`，提示"Model name parameter is required for serving mode"。资料来源：[src/mistral_common/protocol/instruct/validator.py:67-69]()
```python
if self._mode == ValidationMode.serving:
if request.model is None:
raise InvalidRequestException("Model name parameter is required for serving mode")
```
#### 2. 消息列表结构验证
`_validate_message_list_structure` 方法检查消息序列的逻辑完整性：
- 确保消息以 UserMessage 开头
- 验证 `continue_final_message` 标志与最后一条消息类型的兼容性
- 检查角色交替的合法性（User → Assistant → User → ...）
资料来源：[src/mistral_common/protocol/instruct/validator.py:35-42]()
#### 3. 消息内容验证
`_validate_message_list_content` 方法验证消息内容的有效性：
- 检查消息内容非空
- 验证工具调用的格式正确性
- 确保角色与内容的逻辑一致性
资料来源：[src/mistral_common/protocol/instruct/validator.py:43-44]()
#### 4. 工具定义验证
工具验证是该模块的重要组成部分，包含以下检查：资料来源：[src/mistral_common/protocol/instruct/validator.py:55-57]()
| 验证项 | 验证方法 | 异常类型 |
|-------|---------|---------|
| 函数 Schema 有效性 | Draft7Validator.check_schema | InvalidToolSchemaException |
| 函数名称格式 | 正则表达式 `^[a-zA-Z0-9_-]{1,64}$` | InvalidToolException |
| 参数定义完整性 | 检查 required 字段与参数存在性 | InvalidToolSchemaException |
```python
def _validate_function(self, function: Function) -> None:
Draft7Validator.check_schema(function.parameters)
if not re.match(r"^[a-zA-Z0-9_-]{1,64}$", function.name):
raise InvalidToolException(...)
```
资料来源：[src/mistral_common/protocol/instruct/validator.py:85-96]()
## 请求标准化流程
### 标准化架构
```mermaid
graph LR
A[ChatCompletionRequest] --> B[InstructRequestNormalizer]
B --> C[_aggregate_system_prompts]
B --> D[_aggregate_messages]
B --> E[build_settings]
C --> F[system_prompt]
D --> G[messages]
E --> H[settings]
F --> I[InstructRequest]
G --> I
H --> I
```
### 标准化器版本
mistral-common 支持多个标准化器版本，每个版本针对特定的 tokenizer 版本进行了优化：资料来源：[src/mistral_common/protocol/instruct/normalize.py:80-100]()
| 标准化器 | 系统提示位置 | 工具调用+内容支持 |
|---------|------------|-----------------|
| `InstructRequestNormalizer` | 系统消息独立 | 不支持 |
| `InstructRequestNormalizerV7` | 消息开始处 | 支持 |
```python
class InstructRequestNormalizerV7(InstructRequestNormalizer):
_system_prompt_in_begin: bool = True
_allow_tool_call_and_content: bool = True
```
资料来源：[src/mistral_common/protocol/instruct/normalize.py:84-87]()
### 消息聚合
#### 系统提示聚合
系统提示通过 `_aggregate_system_prompts` 方法从消息列表中提取并合并。当存在多个系统消息时，它们会被按顺序拼接为一个统一的系统提示。资料来源：[src/mistral_common/protocol/instruct/normalize.py:40-60]()
#### 消息重组
`_aggregate_messages` 方法移除系统消息，返回仅包含用户消息和助手消息的列表。标准化过程会验证模型设置是否与当前标准化器兼容，不支持的设置将抛出 `InvalidRequestException`。资料来源：[src/mistral_common/protocol/instruct/normalize.py:62-76]()
## 工具调用系统
### ToolChoice 枚举
工具选择策略通过 `ToolChoice` 类型别名定义，支持多种模式：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:20-30]()
| 枚举值 | 描述 | 备注 |
|-------|------|------|
| `auto` | 模型自动决定是否调用工具 | 默认值 |
| `none` | 禁用工具调用 | 不使用任何工具 |
| `any` | 至少调用一个工具 | 已废弃，使用 `required` |
| `required` | 模型必须调用至少一个工具 | 替代 `any` |
### NamedToolChoice
除了枚举选择外，还支持强制指定特定函数调用：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:32-46]()
```python
class NamedToolChoice(MistralBase):
type: ToolTypes = ToolTypes.function
function: FunctionName
```
### 工具定义
`Tool` 类定义了可用的工具，包含函数名称、描述和参数模式：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:48-70]()
| 属性 | 类型 | 描述 |
|-----|------|------|
| `type` | ToolTypes | 工具类型（当前仅支持 function） |
| `function` | Function | 函数定义对象 |
## 请求转换器
### OpenAI 格式转换
`ChatCompletionRequest` 提供了 `to_openai()` 方法用于转换为 OpenAI 兼容格式。该方法处理消息格式转换、工具定义重映射以及额外参数的追加。资料来源：[src/mistral_common/protocol/instruct/request.py:60-90]()
```python
def to_openai(self, **kwargs: Any) -> dict[str, Any]:
r"""Convert the request messages and tools into the OpenAI format."""
```
### 转换示例
```python
request = ChatCompletionRequest(
messages=[UserMessage(content="Hello, how are you?")],
temperature=0.15
)
request.to_openai(stream=True)
# 返回: {'temperature': 0.15, 'top_p': 1.0, 'response_format': {...}, ...}
```
资料来源：[src/mistral_common/protocol/instruct/request.py:70-75]()
## 请求数据结构
### ChatCompletionRequest
`ChatCompletionRequest` 是用户请求的入口数据结构：资料来源：[src/mistral_common/protocol/instruct/request.py:20-40]()
| 字段 | 类型 | 默认值 | 描述 |
|-----|------|-------|------|
| `model` | str \| None | None | 模型名称（serving 模式必需） |
| `messages` | list[ChatMessageType] | - | 消息列表 |
| `response_format` | ResponseFormat | Field(default_factory=ResponseFormat) | 响应格式 |
| `tools` | list[Tool] \| None | None | 可用工具列表 |
| `tool_choice` | ToolChoice | ToolChoiceEnum.auto | 工具选择策略 |
| `truncate_for_context_length` | bool | False | 是否截断以适应上下文长度 |
| `continue_final_message` | bool | False | 继续生成最后一条消息 |
| `reasoning_effort` | ReasoningEffort \| None | None | 推理努力程度 |
### InstructRequest
标准化后的 `InstructRequest` 包含处理后的消息和系统提示：资料来源：[src/mistral_common/protocol/instruct/normalize.py:15-25]()
| 属性 | 类型 | 描述 |
|-----|------|------|
| `messages` | list[UATS] | 处理后的消息列表 |
| `system_prompt` | str \| None | 聚合后的系统提示 |
| `available_tools` | list[Tool] \| None | 可用工具 |
| `continue_final_message` | bool | 是否继续最后消息 |
| `settings` | ModelSettings | 模型设置 |
## 与 Tokenizer 的集成
### 验证流程集成
`MistralTokenizer` 在编码请求时首先调用验证器：资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()
```mermaid
sequenceDiagram
participant User as 用户请求
participant Validator as MistralRequestValidator
participant Normalizer as InstructRequestNormalizer
participant Encoder as InstructTokenizer
User->>Validator: ChatCompletionRequest
Validator->>Validator: validate_request()
Validator-->>Normalizer: validated_request
Normalizer->>Normalizer: from_chat_completion_request()
Normalizer-->>Encoder: InstructRequest
Encoder->>Encoder: encode()
```
### 版本适配
不同的 tokenizer 版本使用不同的标准化器和验证器组合：资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:20-60]()
| Tokenizer 版本 | InstructTokenizer | 验证器 | 标准化器 |
|---------------|-------------------|-------|---------|
| v1 | InstructTokenizerV1 | v1 验证器 | InstructRequestNormalizer |
| v2 | InstructTokenizerV2 | v2 验证器 | InstructRequestNormalizer |
| v3 | InstructTokenizerV3 | v3 验证器 | InstructRequestNormalizer |
| v7 | InstructTokenizerV7 | v7 验证器 | InstructRequestNormalizerV7 |
| v11+ | InstructTokenizerV11+ | v11 验证器 | InstructRequestNormalizerV7 |
## 异常处理
### 异常类型层次
| 异常类 | 基类 | 触发场景 |
|-------|------|---------|
| `InvalidRequestException` | Exception | 请求结构或内容验证失败 |
| `InvalidToolSchemaException` | Exception | 工具 Schema 格式错误 |
| `InvalidToolException` | Exception | 工具名称或定义无效 |
所有自定义异常定义在 `mistral_common.exceptions` 模块中，确保错误处理的一致性。资料来源：[src/mistral_common/protocol/instruct/validator.py:80-95]()
## 使用示例
### 基本验证流程
```python
from mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage
from mistral_common.protocol.instruct.request import ChatCompletionRequest
from mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode
# 创建验证器
validator = MistralRequestValidator(mode=ValidationMode.test)
# 创建请求
request = ChatCompletionRequest(
messages=[
UserMessage(content="Hello how are you?"),
AssistantMessage(content="I'm doing great!")
]
)
# 验证请求
validated_request = validator.validate_request(request)
```
### 带工具调用的请求
```python
from mistral_common.protocol.instruct.tool_calls import ToolTypes, Function, Tool
tool = Tool(
function=Function(
name="get_current_weather",
description="Get the current weather in a given location",
parameters={
"type": "object",
"properties": {
"location": {"type": "string", "description": "City name"}
},
"required": ["location"]
}
)
)
request = ChatCompletionRequest(
messages=[UserMessage(content="What's the weather in Paris?")],
tools=[tool],
tool_choice=ToolChoiceEnum.auto
)
validated_request = validator.validate_request(request)
```
## 最佳实践
### 1. 验证模式选择
- **开发/测试环境**：使用 `ValidationMode.test`，避免强制要求 model 参数
- **生产环境**：使用 `ValidationMode.serving`，确保所有请求包含模型标识
### 2. 工具定义规范
- 函数名称仅包含字母、数字、下划线和连字符，长度不超过 64 字符
- 使用 Draft7 JSON Schema 定义参数
- 明确标记必需参数（required 字段）
### 3. 错误处理
```python
try:
validated_request = validator.validate_request(request)
except InvalidRequestException as e:
logger.error(f"Invalid request: {e}")
except InvalidToolSchemaException as e:
logger.error(f"Invalid tool schema: {e}")
```
### 4. 消息序列设计
- 确保以 UserMessage 开始对话
- 交替的角色顺序：User → Assistant → User → Assistant
- 使用 `continue_final_message=True` 时，最后一条应为 AssistantMessage
## 相关模块索引
| 模块 | 文件路径 | 职责 |
|-----|---------|------|
| 验证器 | `src/mistral_common/protocol/instruct/validator.py` | 请求结构与内容验证 |
| 标准化器 | `src/mistral_common/protocol/instruct/normalize.py` | 请求格式转换 |
| 转换器 | `src/mistral_common/protocol/instruct/converters.py` | 格式转换辅助 |
| 工具调用 | `src/mistral_common/protocol/instruct/tool_calls.py` | 工具定义与选择 |
| 请求定义 | `src/mistral_common/protocol/instruct/request.py` | 请求数据结构 |
| Tokenizer | `src/mistral_common/tokens/tokenizers/mistral.py` | 验证与编码集成 |
---
## 语音与转录协议
### 相关页面
相关主题：[指令与填充中间（FIM）协议](#p5), [请求验证与标准化](#p6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mistral_common/protocol/transcription/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/transcription/request.py)
- [src/mistral_common/tokens/tokenizers/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/audio.py)
- [src/mistral_common/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/audio.py)
- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)
- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
# 语音与转录协议
## 概述
语音与转录协议是 mistral-common 库中处理音频相关请求的核心组件。该协议定义了音频处理的标准化接口，支持语音转文本（Transcription）和文本转语音（Text-to-Speech）等多模态交互场景。
mistral-common 通过协议层与分词器层的协作，将音频数据与文本数据统一处理为模型可接受的 token 序列。音频处理功能主要在 **TokenizerVersion.v7** 及以上版本中可用，集成于 `InstructTokenizerV7` 和 `InstructTokenizerV11` 等分词器实现中。 资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-100]()
## 协议架构
### 模块组织结构
语音与转录协议相关代码分布在以下核心模块中：
| 模块路径 | 功能描述 |
|---------|---------|
| `src/mistral_common/protocol/transcription/request.py` | 转录请求定义 |
| `src/mistral_common/tokens/tokenizers/audio.py` | 音频分词器实现 |
| `src/mistral_common/audio.py` | 音频处理工具类 |
| `src/mistral_common/tokens/tokenizers/base.py` | 基础分词器抽象与特殊token定义 |
### 协议层次关系
```mermaid
graph TD
A[用户请求] --> B[Protocol Layer 协议层]
B --> C[TranscriptionRequest 转录请求]
B --> D[SpeechRequest 语音请求]
C --> E[Tokenizer Layer 分词器层]
D --> E
E --> F[InstructTokenizerV7/V11]
E --> G[Audio Encoder 音频编码器]
F --> H[Tokenized Output]
G --> H
```
## 转录请求协议
### TranscriptionRequest 数据模型
`TranscriptionRequest` 是转录任务的入口请求类型，继承自 `BaseCompletionRequest`。该请求模型封装了音频文件路径或音频数据以及转录相关的配置参数。 资料来源：[src/mistral_common/protocol/transcription/request.py:1-30]()
```python
class TranscriptionRequest(BaseCompletionRequest):
r"""A valid transcription request to be tokenized."""
audio: Audio # 音频数据
language: str | None = None # 可选的语言参数
```
### 请求字段说明
| 字段名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| `audio` | `Audio` | 是 | 待转录的音频数据 |
| `language` | `str \| None` | 否 | 音频语言提示，用于提高转录准确性 |
| 继承字段 | - | - | 继承自 `BaseCompletionRequest` 的基础字段 |
## 音频处理机制
### Audio 类
`Audio` 类是音频数据的核心抽象，提供音频的下载、加载和序列化功能。 资料来源：[src/mistral_common/audio.py:1-50]()
```python
class Audio:
r"""音频处理工具类
Attributes:
url: 音频资源的远程URL
audio_bytes: 音频二进制数据
"""
```
### 音频分词器
`AudioTokenizer` 负责将音频数据转换为模型可处理的 token 序列。该分词器集成在 `InstructTokenizerV7` 及更高版本中。 资料来源：[src/mistral_common/tokens/tokenizers/audio.py:1-50]()
#### 核心功能
| 功能 | 描述 |
|-----|------|
| 音频编码 | 将音频数据编码为 token 序列 |
| 梅尔频谱转换 | 支持 mel-scale 音频特征提取 |
| 多格式支持 | 处理多种音频编码格式 |
## 特殊 Token 定义
在音频处理流程中，系统定义了一系列专用特殊 token，用于标识音频内容的边界和类型。这些 token 在 `SpecialTokens` 枚举中统一管理。 资料来源：[src/mistral_common/tokens/tokenizers/base.py:1-80]()
| Token 名称 | 值 | 用途 |
|-----------|-----|------|
| `audio` | `[AUDIO]` | 音频内容标识 |
| `begin_audio` | `[BEGIN_AUDIO]` | 音频内容开始标记 |
| `transcribe` | `[TRANSCRIBE]` | 转录指令标识 |
| `audio_to_text` | `[REPEAT_AUDIO_TEXT]` | 音频转文本标识 |
| `text_to_audio` | `[NEXT_AUDIO_TEXT]` | 文本转音频标识 |
### Token 序列化格式
```
[AUDIO] + [BEGIN_AUDIO] + <音频编码数据> + [TRANSCRIBE] + [REPEAT_AUDIO_TEXT] + <转录文本>
```
## 分词器版本与音频支持
音频处理能力与分词器版本紧密关联，不同版本支持不同程度的音频功能。
| 分词器版本 | 音频支持 | 图像支持 | 说明 |
|-----------|---------|---------|------|
| `v1` | ❌ | ❌ | 基础文本分词器 |
| `v2` | ❌ | ❌ | 基础文本分词器 |
| `v3` | ❌ | ✅ | 仅支持图像 |
| `v7` | ✅ | ✅ | 首次引入音频支持 |
| `v11` | ✅ | ✅ | 增强的音视频支持 |
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-100]()
### 版本检测与初始化
```python
# 音频编码器在 v7 及以上版本可用
if tokenizer.version >= TokenizerVersion.v7:
audio_encoder = AudioEncoder(...)
# 创建支持音频的分词器
return MistralTokenizer(
InstructTokenizerV7(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),
validator=validator,
request_normalizer=request_normalizer,
)
```
## 请求处理流程
### 转录请求完整流程
```mermaid
sequenceDiagram
participant U as 用户
participant P as Protocol Layer
participant T as Tokenizer
participant A as Audio Encoder
U->>P: TranscriptionRequest(audio_url)
P->>P: 下载并加载音频数据
P->>T: 调用 encode 方法
T->>A: 音频特征提取
A-->>T: 音频 token 序列
T->>T: 合并特殊 token
T-->>U: Tokenized 对象
```
### 验证与规范化
转录请求同样需要经过验证和规范化处理：
1. **消息结构验证**：确保请求格式符合协议规范
2. **音频数据验证**：检查音频数据的完整性和有效性
3. **语言参数验证**：验证语言代码的有效性
资料来源：[src/mistral_common/protocol/instruct/validator.py:1-100]()
## 配置与部署
### 依赖安装
音频功能需要安装相应的可选依赖：
```bash
# 安装音频支持
pip install "mistral-common[audio]"
# 安装完整依赖（包括音频）
pip install "mistral-common[image,audio,hf-hub,sentencepiece,server]"
```
### API 服务配置
在 FastAPI 应用中启用音频处理功能：
```python
from mistral_common.experimental.app import create_app
from mistral_common.protocol.instruct.validator import ValidationMode
app = create_app(
tokenizer="path/to/tokenizer",
validation_mode=ValidationMode.serving,
engine_url="http://127.0.0.1:8080",
engine_backend="llama_cpp",
timeout=60,
)
```
资料来源：[src/mistral_common/experimental/app/main.py:1-80]()
## 最佳实践
### 音频数据准备
1. **格式选择**：推荐使用 MP3、WAV 或 OGG 格式
2. **采样率**：保持原始采样率，避免不必要的重采样
3. **语言提示**：提供准确的 `language` 参数可提高转录准确度
### 错误处理
| 错误类型 | 处理建议 |
|---------|---------|
| 音频加载失败 | 检查 URL 可访问性和格式支持 |
| 分词器版本不匹配 | 确保使用 v7+ 分词器 |
| 音频过长 | 根据模型上下文窗口进行分段处理 |
## 相关文档
- [Instruct 协议](./instruct_protocol.md) - 指令请求处理
- [工具调用协议](./tool_calls.md) - 工具调用定义
- [Tekken 分词器](./tekken_tokenizer.md) - 分词器实现细节
- [Grammar Factory](./grammar_factory.md) - 语法生成器
---
*本页面内容基于 mistral-common 仓库源码生成，最后更新时间跟随仓库最新提交。*
---
## Grammar Factory 与 LLM Guidance
### 相关页面
相关主题：[请求验证与标准化](#p6), [项目架构总览](#p2)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mistral_common/guidance/grammar_factory.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/grammar_factory.py)
- [src/mistral_common/guidance/tokenizer.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/tokenizer.py)
- [src/mistral_common/guidance/data/base_grammar.lark.jinja](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/data/base_grammar.lark.jinja)
- [src/mistral_common/guidance/data/think_grammar.lark.jinja](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/data/think_grammar.lark.jinja)
- [src/mistral_common/guidance/data/plain_text_think_grammar.lark.jinja](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/data/plain_text_think_grammar.lark.jinja)
# Grammar Factory 与 LLM Guidance
## 概述
Grammar Factory 是 mistral-common 库中用于生成结构化输出语法的核心组件。它通过结合 **LLGuidance** 库和 **Jinja2** 模板引擎，将 LLM 的输出约束为符合特定语法规则的结构化格式，支持工具调用、JSON Schema 验证以及思考模式（Thinking Mode）。
该模块的主要功能包括：
- **语法生成**：基于 Jinja2 模板动态生成 Lark 语法规则
- **特殊 token 处理**：将 Tekken 分词器的特殊 token 映射为语法语法
- **多模式支持**：支持基础模式、思考模式（特殊 token）和纯文本思考模式
- **工具调用约束**：支持 function calling 的语法约束和并行调用
资料来源：[src/mistral_common/guidance/grammar_factory.py:1-50]()
## 架构设计
### 组件关系
```mermaid
graph TD
A[用户请求] --> B[ChatCompletionRequest]
B --> C[GrammarFactory]
C --> D{推理模式判断}
D -->|非思考模式| E[base_grammar.lark.jinja]
D -->|v13+ 思考模式| F[think_grammar.lark.jinja]
D -->|v13 之前思考模式| G[plain_text_think_grammar.lark.jinja]
E --> H[Jinja2 渲染]
F --> H
G --> H
H --> I[Lark 语法字符串]
I --> J[llguidance 引擎]
J --> K[结构化输出]
C --> L[TekkenTokenizer]
L --> M[特殊Token映射]
M --> H
```
### 核心依赖
| 依赖库 | 用途 |
|--------|------|
| llguidance | 语法引导的 LLM 推理引擎 |
| jinja2 | Lark 语法模板渲染 |
| lark | 语法解析 |
## GrammarFactory 类
### 初始化与验证
```python
class GrammarFactory:
def __init__(self, tokenizer: MistralTokenizer) -> None:
"""初始化语法工厂"""
assert_llguidance_installed()
assert_jinja2_installed()
self._tokenizer = tokenizer.instruct_tokenizer.tokenizer
if not self.is_supported(tokenizer):
raise ValueError(
f"Guidance requires a Tekken tokenizer with version >= v11, "
f"got {type(self._tokenizer).__name__} {self._tokenizer.version.value}"
)
```
**关键约束**：
- 仅支持 **Tekken 分词器**
- 分词器版本必须 **≥ v11**
- 支持的版本包括 v11 和 v13
资料来源：[src/mistral_common/guidance/grammar_factory.py:35-55]()
### 特殊 Token 映射
GrammarFactory 构建从特殊 token 名称到 Lark 语法语法的映射：
```python
def _build_special_token_map(self) -> dict[str, str]:
"""构建特殊 token 名称到语法语法的映射"""
return {
self._tokenizer.id_to_piece(i): f"<[{i}]>"
for i in range(self._tokenizer.num_special_tokens)
}
def _special_token_lark(self, token_name: str) -> str:
"""将特殊 token 名称转换为 lark 语法语法"""
assert token_name in self._special_token_map
return self._special_token_map[token_name]
def _get_optional_special_token_lark(self, token_name: str) -> str | None:
"""返回特殊 token 的 lark 语法语法，若不存在则返回 None"""
return self._special_token_map.get(token_name)
```
资料来源：[src/mistral_common/guidance/grammar_factory.py:57-70]()
### 版本支持检查
```python
@staticmethod
def is_supported(tokenizer: MistralTokenizer) -> bool:
"""检查分词器是否支持 grammar guidance"""
return (
isinstance(tokenizer.instruct_tokenizer.tokenizer, TekkenTokenizer)
and tokenizer.instruct_tokenizer.tokenizer.version >= TokenizerVersion.v11
)
```
## 语法变体
系统支持三种语法变体，通过 `_GrammarVariant` 枚举定义：
```python
class _GrammarVariant(str, Enum):
base = "base" # 基础模式
plain_think = "plain_think" # 纯文本思考模式
think = "think" # 思考模式（特殊 token）
```
### 变体选择逻辑
```mermaid
graph TD
A[开始] --> B{是否启用推理?}
B -->|否| C[base 变体]
B -->|是| D{分词器版本 >= v13?}
D -->|是| E[think 变体]
D -->|否| F[plain_think 变体]
```
| 推理模式 | 分词器版本 | 选用变体 |
|----------|-----------|----------|
| 关闭 | 任意 | base |
| 开启 | ≥ v13 | think |
| 开启 | < v13 | plain_think |
资料来源：[src/mistral_common/guidance/grammar_factory.py:120-135]()
## Lark 语法模板系统
### 模板文件
| 模板文件 | 用途 |
|----------|------|
| `base_grammar.lark.jinja` | 基础模式的标准语法 |
| `think_grammar.lark.jinja` | 支持特殊 token 思考标签的语法 |
| `plain_text_think_grammar.lark.jinja` | 纯文本格式的思考语法 |
### 模板渲染参数
`_cached_get_lark_from_jinja` 函数接收以下参数生成 Lark 语法：
| 参数 | 类型 | 说明 |
|------|------|------|
| `template` | str | Jinja2 模板字符串 |
| `mode` | str | 输出模式（text/JSON） |
| `fcall` | str | 函数调用格式 |
| `json_schema_str` | str \| None | JSON Schema 字符串 |
| `parallel_tool_calls` | bool | 是否支持并行工具调用 |
| `json_only` | bool | 是否仅输出 JSON |
| `think_with_json` | bool | 思考部分是否使用 JSON 格式 |
| `begin_think_token` | str \| None | 思考开始 token |
| `end_think_token` | str \| None | 思考结束 token |
资料来源：[src/mistral_common/guidance/grammar_factory.py:140-165]()
### 缓存机制
系统使用 `@lru_cache` 装饰器缓存模板和语法结果，避免重复渲染：
```python
@lru_cache()
def _cached_get_jinja_template(
tokenizer_version: TokenizerVersion,
reasoning: bool
) -> str:
"""缓存获取 Jinja 模板"""
if not reasoning:
jinja_key = _GrammarVariant.base
elif tokenizer_version < TokenizerVersion.v13:
jinja_key = _GrammarVariant.plain_think
else:
jinja_key = _GrammarVariant.think
return JINJA_PATHS[jinja_key].read_text(encoding="utf-8")
```
## LLM Guidance Tokenizer 适配器
### TekkenTokenizerAdapter
位于 `src/mistral_common/guidance/tokenizer.py` 的适配器将 Tekken 分词器转换为 llguidance 所需格式：
```python
from mistral_common.guidance.tokenizer import from_mistral_tokenizer
# 将 Mistral 分词器转换为 llguidance 格式
adapter = from_mistral_tokenizer(mistral_tokenizer)
```
资料来源：[src/mistral_common/guidance/tokenizer.py]()
## 使用流程
```mermaid
sequenceDiagram
participant U as 用户
participant GF as GrammarFactory
participant TK as TekkenTokenizer
participant JN as Jinja2
participant LK as Lark 语法
participant LG as LLGuidance
U->>GF: 创建 GrammarFactory 实例
GF->>TK: 获取 instruct_tokenizer
TK-->>GF: 返回 TekkenTokenizer
GF->>GF: 构建特殊 token 映射
U->>GF: 调用 get_lark_grammar()
GF->>GF: 判断推理模式和版本
GF->>JN: 加载并渲染 Jinja 模板
JN-->>GF: 返回 Lark 语法字符串
GF-->>U: 返回 Lark 语法
U->>LG: 使用 Lark 语法进行推理
LG-->>U: 返回结构化输出
```
## API 参考
### GrammarFactory 主要方法
| 方法 | 说明 |
|------|------|
| `is_supported(tokenizer)` | 检查分词器是否支持 |
| `get_lark_grammar(...)` | 生成 Lark 语法字符串 |
| `_build_special_token_map()` | 构建特殊 token 映射 |
| `_special_token_lark(token_name)` | 转换特殊 token 为语法 |
| `_get_optional_special_token_lark(token_name)` | 可选的 token 转换 |
### get_lark_grammar 方法签名
```python
def get_lark_grammar(
self,
mode: str,
json_schema_str: str | None = None,
fcall: str | None = None,
parallel_tool_calls: bool = False,
json_only: bool = False,
think_with_json: bool = False,
begin_think_token: str | None = None,
end_think_token: str | None = None,
) -> str:
"""生成 Lark 语法字符串"""
```
## 工具调用支持
GrammarFactory 原生支持 function calling 场景：
```python
grammar = grammar_factory.get_lark_grammar(
mode="function_call",
json_schema_str=tool.parameters, # JSON Schema
fcall="auto", # 工具选择模式
parallel_tool_calls=True, # 并行调用
)
```
### 工具选择模式
| 模式 | 说明 |
|------|------|
| `auto` | 模型自动选择工具 |
| `none` | 不使用工具 |
| `required` | 强制使用至少一个工具 |
| `any` | 任意工具（已废弃） |
资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:40-55]()
## 最佳实践
### 1. 分词器版本检查
```python
from mistral_common.tokens.tokenizers.mistral import TokenizerVersion
if tokenizer.instruct_tokenizer.tokenizer.version >= TokenizerVersion.v11:
factory = GrammarFactory(tokenizer)
else:
raise ValueError("不支持的分词器版本")
```
### 2. 模板缓存利用
系统自动缓存渲染结果，重复调用应使用相同参数：
```python
# 推荐：批量使用相同配置
grammar1 = factory.get_lark_grammar(mode="json", json_schema_str=schema)
grammar2 = factory.get_lark_grammar(mode="json", json_schema_str=schema) # 使用缓存
```
### 3. 特殊 Token 验证
使用可选方法处理可能不存在的 token：
```python
token_lark = factory._get_optional_special_token_lark("BOS")
if token_lark is None:
# 处理 token 不存在的情况
pass
```
## 局限性
1. **分词器限制**：仅支持 Tekken 分词器 v11 及以上版本
2. **依赖要求**：必须安装 llguidance 和 jinja2
3. **思考模式版本差异**：不同分词器版本使用不同的思考语法模板
## 相关文件
| 文件路径 | 说明 |
|----------|------|
| `src/mistral_common/guidance/grammar_factory.py` | 核心语法工厂实现 |
| `src/mistral_common/guidance/tokenizer.py` | llguidance 分词器适配器 |
| `src/mistral_common/guidance/data/*.lark.jinja` | 语法模板文件 |
| `src/mistral_common/protocol/instruct/tool_calls.py` | 工具调用定义 |
---
## 实验性功能（工具调用、思考解析、FastAPI 服务）
### 相关页面
相关主题：[项目架构总览](#p2), [Grammar Factory 与 LLM Guidance](#p8)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mistral_common/experimental/tools.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/tools.py)
- [src/mistral_common/experimental/think.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/think.py)
- [src/mistral_common/experimental/app/main.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)
- [src/mistral_common/experimental/app/routers.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/routers.py)
- [src/mistral_common/experimental/app/models.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/models.py)
# 实验性功能（工具调用、思考解析、FastAPI 服务）
## 概述
mistral-common 的实验性功能模块（`src/mistral_common/experimental/`）提供了一套用于处理大语言模型推理请求的扩展能力，包括**工具调用解析**、**思考解析**以及基于 FastAPI 的本地推理服务。这些功能属于实验性质，旨在为开发者提供更灵活的方式来与 Mistral 模型进行交互，特别是在处理复杂的多轮对话、函数调用和模型思维链方面。
实验性功能的主要设计目标是：
- 提供独立于核心 tokenization 流水线的专用解析器
- 支持通过 HTTP API 快速部署和测试 tokenizer
- 为工具调用和思考模式提供标准化解析接口
资料来源：[AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)
## 模块架构
实验性功能模块的整体架构由三个核心组件构成，它们各自承担不同的职责：
```mermaid
graph TD
A[experimental 模块] --> B[工具调用解析]
A --> C[思考解析]
A --> D[FastAPI 应用]
D --> D1[main.py 入口]
D --> D2[routers.py 路由]
D --> D3[models.py 数据模型]
B --> B1[tools.py]
C --> C1[think.py]
B1 -.->|使用| E[protocol/instruct/tool_calls.py]
C1 -.->|使用| F[tokens/tokenizers/tekken.py]
```
资料来源：[src/mistral_common/experimental/](https://github.com/mistralai/mistral-common/tree/main/src/mistral_common/experimental)
---
## 工具调用解析
### 功能概述
`tools.py` 模块提供了工具调用（Tool Calls）的解析能力，允许模型在生成响应时调用外部函数或 API。该模块独立于核心的 `protocol/instruct/tool_calls.py`，专注于解析运行时而非定义工具模式。
资料来源：[src/mistral_common/experimental/tools.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/tools.py)
### 核心职责
工具调用解析模块的主要职责包括：
1. **函数识别**：从模型生成的文本中提取函数调用请求
2. **参数解析**：将模型输出解析为结构化的函数参数
3. **结果格式化**：将函数执行结果重新格式化为模型可理解的输入
### 与标准协议的关系
实验性工具调用解析与 `protocol/instruct/tool_calls.py` 中的标准工具定义存在协作关系：
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| 标准工具定义 | `protocol/instruct/tool_calls.py` | 定义 `Tool`、`Function`、`ToolChoice` 等数据模型 |
| 实验性解析器 | `experimental/tools.py` | 运行时解析模型生成的工具调用 |
资料来源：[src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)
---
## 思考解析
### 功能概述
`think.py` 模块提供了对模型"思考过程"的解析能力。在启用 `thinking` 模式的模型中，模型会先生成内部推理步骤（通常以特殊 token 包裹），然后再生成最终响应。`think.py` 模块负责将这些思考过程与最终输出分离解析。
资料来源：[src/mistral_common/experimental/think.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/think.py)
### 思考模式的特殊标记
根据 Tekken tokenizer 的实现，思考模式使用特殊的控制 token：
| Token 名称 | 用途 |
|------------|------|
| `begin_thinking` | 标记思考内容开始 |
| `end_thinking` | 标记思考内容结束 |
| `begin_turn` | 标记对话轮次开始 |
| `end_turn` | 标记对话轮次结束 |
资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)
### 解析工作流
思考解析的基本工作流程如下：
```mermaid
sequenceDiagram
participant User as 用户输入
participant Tokenizer as Tekken Tokenizer
participant ThinkParser as 思考解析器
participant Model as Mistral 模型
User->>Tokenizer: 原始文本
Tokenizer->>Tokenizer: 添加思考标记
Tokenizer->>Model: 带标记的 token 序列
Model-->>Tokenizer: 包含思考的响应
Tokenizer->>ThinkParser: 解析响应
ThinkParser->>User: 分离思考内容与最终输出
```
---
## FastAPI 推理服务
### 应用架构
实验性模块包含一个完整的 FastAPI 应用，用于提供基于 Mistral tokenizer 的 REST API 服务。该应用支持通过命令行快速启动，并提供与模型推理后端的对接能力。
资料来源：[src/mistral_common/experimental/app/main.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)
### 应用入口
`main.py` 定义了 CLI 入口点，使用 Click 框架实现命令行接口：
```python
def serve(
tokenizer_path: str | Path,
validation_mode: ValidationMode | str = ValidationMode.test,
host: str = "127.0.0.1",
port: int = 0,
engine_url: str = "http://127.0.0.1:8080",
engine_backend: str = EngineBackend.llama_cpp.value,
timeout: int = 60,
) -> None:
```
### 启动命令参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tokenizer_path` | str/Path | 必需 | tokenizer 文件路径 |
| `validation_mode` | str | "test" | 验证模式（test/serving/finetuning） |
| `host` | str | "127.0.0.1" | 服务监听地址 |
| `port` | int | 0 | 服务监听端口（0 表示自动分配） |
| `engine_url` | str | "http://127.0.0.1:8080" | 推理引擎 URL |
| `engine_backend` | str | "llama_cpp" | 推理后端类型 |
| `timeout` | int | 60 | 请求超时时间（秒） |
资料来源：[src/mistral_common/experimental/app/main.py:1-90](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)
### 引擎后端支持
系统支持多种推理引擎后端：
| 后端标识 | 说明 |
|----------|------|
| `llama_cpp` | Llama.cpp 推理引擎 |
| `vllm` | vLLM 推理引擎（可选支持） |
### 路由模块
`routers.py` 定义了 API 的路由端点，处理 tokenizer 相关的 HTTP 请求：
```python
# 路由结构示例
@router.post("/tokenize")
async def tokenize(request: TokenizeRequest) -> TokenizeResponse
@router.post("/detokenize")
async def detokenize(request: DetokenizeRequest) -> DetokenizeResponse
```
资料来源：[src/mistral_common/experimental/app/routers.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/routers.py)
### 数据模型
`models.py` 定义了 API 请求和响应的 Pydantic 模型：
| 模型名称 | 类型 | 用途 |
|----------|------|------|
| `TokenizeRequest` | Request | 文本分词请求 |
| `TokenizeResponse` | Response | 分词结果响应 |
| `DetokenizeRequest` | Request | token 反向解析请求 |
| `DetokenizeResponse` | Response | 反解析结果响应 |
| `ValidationRequest` | Request | 请求验证请求 |
| `ValidationResponse` | Response | 验证结果响应 |
资料来源：[src/mistral_common/experimental/app/models.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/models.py)
### 服务启动流程
```mermaid
graph LR
A[命令行参数] --> B[create_app]
B --> C[Uvicorn 运行]
C --> D[监听 HTTP 请求]
D --> E[路由处理]
E --> F[Tokenizer 操作]
```
### 依赖安装
实验性服务功能需要安装 `server` 可选依赖：
```bash
pip install "mistral-common[server]"
```
资料来源：[README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)
---
## 验证模式
实验性应用支持三种验证模式，由 `MistralRequestValidator` 类管理：
| 模式 | 说明 | 使用场景 |
|------|------|----------|
| `test` | 测试模式 | 单元测试和开发 |
| `serving` | 服务模式 | 生产环境部署 |
| `finetuning` | 微调模式 | 模型微调任务 |
资料来源：[src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)
---
## 与其他模块的交互
### 整体数据流
```mermaid
graph TD
subgraph 用户层
A[用户请求]
end
subgraph API层
B[FastAPI 应用]
C[路由处理器]
end
subgraph 协议层
D[ChatCompletionRequest]
E[Validator]
F[Normalizer]
end
subgraph Tokenization层
G[MistralTokenizer]
H[Tekken Tokenizer]
end
A --> B --> C
C --> D --> E
E --> F
F --> G --> H
subgraph 实验性功能
I[工具调用解析]
J[思考解析]
end
G -.->|支持| I
G -.->|支持| J
```
### 验证流程
用户请求首先经过 `MistralRequestValidator` 验证，然后由 `InstructRequestNormalizer` 标准化，最后由 tokenizer 处理：
资料来源：[src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)
---
## 使用示例
### 启动本地服务
```bash
python -m mistral_common.experimental.app.main serve \
--tokenizer-path /path/to/tokenizer \
--validation-mode test \
--host 0.0.0.0 \
--port 8000
```
### API 请求示例
```bash
curl -X POST http://localhost:8000/tokenize \
-H "Content-Type: application/json" \
-d '{"text": "Hello, world!"}'
```
---
## 注意事项
1. **实验性质**：所有 `experimental` 模块下的功能均为实验性质，API 可能在后续版本中发生变化
2. **版本要求**：某些功能需要特定的 tokenizer 版本（如 v11+ 用于 guidance 功能）
3. **依赖管理**：使用前请确保已安装所有必要的可选依赖
4. **线程安全**：Tokenization 操作本身是线程安全的，但需注意并发访问时的资源管理
---
## 数据文件与模型版本管理
### 相关页面
相关主题：[分词器系统详解](#p3), [项目介绍与安装](#p1)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mistral_common/data/tekken_240718.json](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/data/tekken_240718.json)
- [src/mistral_common/data/tekken_240911.json](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/data/tekken_240911.json)
- [src/mistral_common/data/mistral_instruct_tokenizer_241114.model.v7](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/data/mistral_instruct_tokenizer_241114.model.v7)
- [src/mistral_common/tokens/tokenizers/model_settings_builder.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/model_settings_builder.py)
- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
- [src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)
- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)
- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)
# 数据文件与模型版本管理
## 概述
mistral-common 库中的数据文件与模型版本管理系统负责管理分词器（Tokenizer）的配置数据、词汇表（Vocabulary）以及不同模型版本之间的兼容性适配。该系统通过版本化的数据文件和版本感知的构建器模式，确保库能够支持从 v1 到 v13 的多种 Tekken 分词器版本。
数据文件存放在 `src/mistral_common/data/` 目录下，主要包含两类资源：词汇表 JSON 文件（如 `tekken_240718.json`、`tekken_240911.json`）以及 SentencePiece 模型文件（如 `mistral_instruct_tokenizer_241114.model.v7`）。
资料来源：[AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)
---
## 核心架构
### 版本体系
mistral-common 支持的 Tekken 分词器版本演进如下：
| 版本 | 主要特性 | 数据文件 |
|------|----------|----------|
| v1 | 基础分词功能 | 无独立数据文件 |
| v2 | 改进的分词规则 | 无独立数据文件 |
| v3 | 支持图像处理 | 需要 image_encoder |
| v7 | 支持音频处理 | `.v7` 模型文件 |
| v11 | 完整多模态支持 | Tekken JSON 数据 |
| v13 | 最新版本特性 | Tekken JSON 数据 |
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-80](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
### 类关系图
```mermaid
graph TD
A[MistralTokenizer] --> B[InstructTokenizerV*]
B --> C[TekkenTokenizer]
C --> D[模型版本管理器]
E[ModelSettingsBuilder] --> D
F[data/*.json] --> D
G[data/*.model.v7] --> D
```
---
## 数据文件类型
### Tekken 词汇表文件
Tekken 词汇表文件采用 JSON 格式存储，包含分词器的完整词汇信息：
- **命名规范**：`tekken_{YYYYMMDD}.json`
- **内容结构**：
- 词汇表条目（token 到 ID 的映射）
- 特殊 token 定义
- 分词模式（pattern）
- 元数据（版本号、创建日期）
### SentencePiece 模型文件
较旧版本（如 v7）使用 SentencePiece 格式：
- **命名规范**：`mistral_instruct_tokenizer_{YYYYMMDD}.model.v7`
- **用途**：向后兼容旧模型
- **状态**：已弃用，新模型使用 Tekken 格式
资料来源：[README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)
---
## 模型版本管理器
### TokenizerVersion 枚举
所有支持的版本通过 `TokenizerVersion` 枚举进行标识：
```python
class TokenizerVersion(Enum):
v1 = "v1"
v2 = "v2"
v3 = "v3"
v7 = "v7"
v11 = "v11"
v13 = "v13"
```
资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)
### ModelSettingsBuilder
`ModelSettingsBuilder` 类负责根据模型版本构建相应的配置设置：
```python
class ModelSettingsBuilder:
"""根据分词器版本构建模型设置的构建器"""
def build(self, request: ChatCompletionRequest) -> ModelSettings:
"""根据请求构建模型设置"""
...
```
**关键参数说明：**
| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | `str \| None` | 模型名称 |
| `messages` | `list[ChatMessageType]` | 消息列表 |
| `response_format` | `ResponseFormat` | 响应格式 |
| `tools` | `list[Tool] \| None` | 工具定义 |
| `tool_choice` | `ToolChoice` | 工具选择策略 |
| `truncate_for_context_length` | `bool` | 是否截断以适应上下文长度 |
| `continue_final_message` | `bool` | 是否继续最终消息 |
| `reasoning_effort` | `ReasoningEffort \| None` | 推理努力级别 |
资料来源：[src/mistral_common/protocol/instruct/request.py:1-100](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)
---
## 版本选择流程
### 工厂方法模式
mistral-common 使用工厂方法 `create_tokenizer` 来创建适当版本的 tokenizer：
```mermaid
graph TD
A[create_tokenizer 调用] --> B{检查版本}
B -->|v1| C[InstructTokenizerV1]
B -->|v2| D[InstructTokenizerV2]
B -->|v3| E[InstructTokenizerV3 + image_encoder]
B -->|v7| F[InstructTokenizerV7 + audio_encoder]
B -->|v11| G[InstructTokenizerV11]
B -->|v13| H[InstructTokenizerV13]
C --> I[MistralTokenizer 包装]
D --> I
E --> I
F --> I
G --> I
H --> I
```
资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:30-70](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)
### 版本验证
每个版本的 tokenizer 实例化时都会进行严格验证：
```python
if tokenizer.version == TokenizerVersion.v1:
assert image_encoder is None, "Tokenizer version needs to be >= v3"
assert audio_encoder is None, "Tokenizer version needs to be >= v7"
```
---
## InstructRequestNormalizer 版本化
### 版本化规范化器
`InstructRequestNormalizer` 类存在多个版本子类，每个版本针对特定的分词器版本优化：
| 规范化器类 | 分词器版本 | 特性 |
|-----------|-----------|------|
| `InstructRequestNormalizer` | v1/v2 | 基础规范化 |
| `InstructRequestNormalizerV7` | v7 | 支持音频 |
**V7 版本特性：**
```python
class InstructRequestNormalizerV7(InstructRequestNormalizer):
_system_prompt_in_begin: bool = True
_allow_tool_call_and_content: bool = True
```
资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-60](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)
### 规范化流程
```mermaid
graph LR
A[ChatCompletionRequest] --> B[系统提示聚合]
A --> C[消息聚合]
B --> D[build_settings]
C --> D
D --> E[InstructRequest]
E --> F[验证器验证]
F --> G[分词器编码]
```
---
## 特殊 Token 管理
### SpecialTokenInfo 数据结构
每个 Tekken 分词器版本定义了一套特殊 token：
```python
SpecialTokenInfo(rank=1, token_str=SpecialTokens.bos, is_control=True),
SpecialTokenInfo(rank=2, token_str=SpecialTokens.eos, is_control=True),
SpecialTokenInfo(rank=7, token_str=SpecialTokens.begin_tool_results, is_control=True),
SpecialTokenInfo(rank=8, token_str=SpecialTokens.end_tool_results, is_control=True),
```
**特殊 token 完整列表：**
| Token 名称 | 用途 |
|-----------|------|
| `bos` | 序列起始 |
| `eos` | 序列结束 |
| `begin_tool_results` | 工具结果开始 |
| `end_tool_results` | 工具结果结束 |
| `tool_calls` | 工具调用标记 |
| `img` | 图像标记 |
| `img_break` | 图像中断 |
| `img_end` | 图像结束 |
| `begin_system` | 系统消息开始 |
| `end_system` | 系统消息结束 |
| `begin_tool_content` | 工具内容开始 |
资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)
---
## 数据流集成
### 与协议层集成
数据版本管理与协议层紧密协作：
```mermaid
graph TD
A[用户请求] --> B[ChatCompletionRequest]
B --> C[规范化器 Normalizer]
C --> D[验证器 Validator]
D --> E[分词器 Tokenizer]
E --> F[data/ 目录数据]
F --> E
E --> G[模型输出]
```
### 验证模式
系统支持三种验证模式：
| 模式 | 说明 | 模型参数要求 |
|------|------|-------------|
| `test` | 测试模式（默认） | 可选 |
| `serving` | 服务模式 | 必须提供 |
| `finetuning` | 微调模式 | 可选 |
资料来源：[src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)
---
## 版本迁移指南
### 从旧版本迁移
| 源版本 | 目标版本 | 迁移要点 |
|--------|----------|----------|
| v1/v2 | v3+ | 需要配置 `image_encoder` |
| v3-v6 | v7 | 需要配置 `audio_encoder` |
| SentencePiece | Tekken | 使用新的 JSON 数据文件 |
### 兼容性检查
```python
# 检查版本兼容性的示例代码
if tokenizer.version >= TokenizerVersion.v11:
# 使用新的 GrammarFactory 功能
grammar_factory = GrammarFactory(tokenizer)
```
---
## 总结
mistral-common 的数据文件与模型版本管理系统通过以下机制实现多版本支持：
1. **版本化数据文件**：不同版本的词汇表和模型文件存储在 `data/` 目录
2. **版本感知的构建器**：`ModelSettingsBuilder` 根据版本构建正确配置
3. **工厂方法**：`create_tokenizer` 根据版本参数返回适当的 tokenizer 实例
4. **版本化规范化器**：不同版本的规范化器处理特定版本的请求格式
5. **严格验证**：每个版本有独立的验证逻辑和版本检查
---
---
## Doramagic 踩坑日志
项目：mistralai/mistral-common
摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]。
## 1. 安全/权限坑 · 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_750d0089d9e14ad385e0f49195987796 | https://github.com/mistralai/mistral-common/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b87372316a944057aa9d5cf9ae8797b3 | https://github.com/mistralai/mistral-common/issues/209 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_03f994c9b8a649a0a7723f5a7ac9a9c0 | https://github.com/mistralai/mistral-common/issues/210 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call'…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call', ...}
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_598dfde98fb44c46b9d95e5ee2a66d69 | https://github.com/mistralai/mistral-common/issues/211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:786756993 | https://github.com/mistralai/mistral-common | README/documentation is current enough for a first validation pass.
## 6. 维护坑 · 来源证据：v1.11.1: Patch for agentic use
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.11.1: Patch for agentic use
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2858129b86914e6090beed86fafe6db7 | https://github.com/mistralai/mistral-common/releases/tag/v1.11.1 | 来源类型 github_release 暴露的待验证使用条件。
## 7. 维护坑 · 来源证据：v1.8.7: Refactoring and bug fixes.
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.8.7: Refactoring and bug fixes.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cbca40b0e8be4f20a899d193e200fdd3 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。
## 8. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | last_activity_observed missing
## 9. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium
## 10. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium
## 11. 安全/权限坑 · 来源证据：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c55c5c2d9aae479b96c76416b6740fee | https://github.com/mistralai/mistral-common/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 12. 安全/权限坑 · 来源证据：v1.8.6: rm Python 3.9, bug fixes.
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.8.6: rm Python 3.9, bug fixes.
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ffc1eeb338274f6095e43203b2c2e785 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 13. 安全/权限坑 · 来源证据：v1.9.0 - Stream my audio 🎙️
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.0 - Stream my audio 🎙️
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bad0c0ee58ac4386b5bcc2d2c9d226e8 | https://github.com/mistralai/mistral-common/releases/tag/v1.9.0 | 来源类型 github_release 暴露的待验证使用条件。
## 14. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | issue_or_pr_quality=unknown
## 15. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | release_recency=unknown