{
"canonical_name": "mistralai/mistral-common",
"compilation_id": "pack_6f42edf9f18d40f7a5e3e55bee73d618",
"created_at": "2026-05-17T00:46:28.510073+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install mistral-common` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install mistral-common",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_f89ead0d1ea14a97b62804e7bb90745e"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_970225c3e6b611c4a4b163a3a0ca128b",
"canonical_name": "mistralai/mistral-common",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/mistralai/mistral-common",
"slug": "mistral-common",
"source_packet_id": "phit_0e8e794f40bc4f7599fc9eab6be05276",
"source_validation_id": "dval_33f269521c7749d49a5780a5ea981b7b"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 144,
"github_stars": 889,
"one_liner_en": "Official inference library for pre-processing of Mistral models",
"one_liner_zh": "Official inference library for pre-processing of Mistral models",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, ci, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "mistral-common",
"title_zh": "mistral-common 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Visual Workflow Orchestration",
"label_zh": "视觉工作流编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-visual-workflow-orchestration",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Automated Workflow",
"label_zh": "自动化工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-automated-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_0e8e794f40bc4f7599fc9eab6be05276",
"page_model": {
"artifacts": {
"artifact_slug": "mistral-common",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install mistral-common",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/mistralai/mistral-common#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"视觉工作流编排",
"流程自动化",
"自动化工作流",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Official inference library for pre-processing of Mistral models"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_750d0089d9e14ad385e0f49195987796 | https://github.com/mistralai/mistral-common/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_b87372316a944057aa9d5cf9ae8797b3 | https://github.com/mistralai/mistral-common/issues/209 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_03f994c9b8a649a0a7723f5a7ac9a9c0 | https://github.com/mistralai/mistral-common/issues/210 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call', ...}",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_598dfde98fb44c46b9d95e5ee2a66d69 | https://github.com/mistralai/mistral-common/issues/211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call'…",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:786756993 | https://github.com/mistralai/mistral-common | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.11.1: Patch for agentic use",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_2858129b86914e6090beed86fafe6db7 | https://github.com/mistralai/mistral-common/releases/tag/v1.11.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.11.1: Patch for agentic use",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.8.7: Refactoring and bug fixes.",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_cbca40b0e8be4f20a899d193e200fdd3 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.7: Refactoring and bug fixes.",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_c55c5c2d9aae479b96c76416b6740fee | https://github.com/mistralai/mistral-common/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.8.6: rm Python 3.9, bug fixes.",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ffc1eeb338274f6095e43203b2c2e785 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.6: rm Python 3.9, bug fixes.",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.0 - Stream my audio 🎙️",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_bad0c0ee58ac4386b5bcc2d2c9d226e8 | https://github.com/mistralai/mistral-common/releases/tag/v1.9.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.9.0 - Stream my audio 🎙️",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 27,
"forks": 144,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 889
},
"source_url": "https://github.com/mistralai/mistral-common",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Official inference library for pre-processing of Mistral models",
"title": "mistral-common 能力包",
"trial_prompt": "# mistral-common - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mistral-common 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Official inference library for pre-processing of Mistral models 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. p1：项目介绍与安装。围绕“项目介绍与安装”模拟一次用户任务，不展示安装或运行结果。\n2. p2：项目架构总览。围绕“项目架构总览”模拟一次用户任务，不展示安装或运行结果。\n3. p3：分词器系统详解。围绕“分词器系统详解”模拟一次用户任务，不展示安装或运行结果。\n4. p5：指令与填充中间（FIM）协议。围绕“指令与填充中间（FIM）协议”模拟一次用户任务，不展示安装或运行结果。\n5. p6：请求验证与标准化。围绕“请求验证与标准化”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p1\n输入：用户提供的“项目介绍与安装”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p2\n输入：用户提供的“项目架构总览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p3\n输入：用户提供的“分词器系统详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p5\n输入：用户提供的“指令与填充中间（FIM）协议”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p6\n输入：用户提供的“请求验证与标准化”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p1：Step 1 必须围绕“项目介绍与安装”形成一个小中间产物，并等待用户确认。\n- Step 2 / p2：Step 2 必须围绕“项目架构总览”形成一个小中间产物，并等待用户确认。\n- Step 3 / p3：Step 3 必须围绕“分词器系统详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / p5：Step 4 必须围绕“指令与填充中间（FIM）协议”形成一个小中间产物，并等待用户确认。\n- Step 5 / p6：Step 5 必须围绕“请求验证与标准化”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/mistralai/mistral-common\n- https://github.com/mistralai/mistral-common#readme\n- README.md\n- pyproject.toml\n- AGENTS.md\n- src/mistral_common/__init__.py\n- src/mistral_common/tokens/__init__.py\n- src/mistral_common/protocol/__init__.py\n- src/mistral_common/guidance/__init__.py\n- src/mistral_common/experimental/__init__.py\n- src/mistral_common/tokens/tokenizers/tekken.py\n- src/mistral_common/tokens/tokenizers/sentencepiece.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mistral-common 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [BUG: MistralCommonTokenizer from transformers is not supported by trl S（https://github.com/mistralai/mistral-common/issues/148）；github/github_issue: [BUG]: Tests in the tarball downloaded from the PYPI page fail because t（https://github.com/mistralai/mistral-common/issues/209）；github/github_issue: [BUG]: test_hertz_to_mel_array fails: Arrays are not equal（https://github.com/mistralai/mistral-common/issues/210）；github/github_issue: [BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', '（https://github.com/mistralai/mistral-common/issues/211）；github/github_release: v1.11.1: Patch for agentic use（https://github.com/mistralai/mistral-common/releases/tag/v1.11.1）；github/github_release: v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14（https://github.com/mistralai/mistral-common/releases/tag/v1.10.0）；github/github_release: v1.9.1 Patch Release（https://github.com/mistralai/mistral-common/releases/tag/v1.9.1）；github/github_release: v1.9.0 - Stream my audio 🎙️（https://github.com/mistralai/mistral-common/releases/tag/v1.9.0）；github/github_release: v1.8.7: Refactoring and bug fixes.（https://github.com/mistralai/mistral-common/releases/tag/v1.8.7）；github/github_release: v1.8.6: rm Python 3.9, bug fixes.（https://github.com/mistralai/mistral-common/releases/tag/v1.8.6）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[BUG: MistralCommonTokenizer from transformers is not supported by trl S",
"url": "https://github.com/mistralai/mistral-common/issues/148"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG]: Tests in the tarball downloaded from the PYPI page fail because t",
"url": "https://github.com/mistralai/mistral-common/issues/209"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG]: test_hertz_to_mel_array fails: Arrays are not equal",
"url": "https://github.com/mistralai/mistral-common/issues/210"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', '",
"url": "https://github.com/mistralai/mistral-common/issues/211"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.11.1: Patch for agentic use",
"url": "https://github.com/mistralai/mistral-common/releases/tag/v1.11.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14",
"url": "https://github.com/mistralai/mistral-common/releases/tag/v1.10.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.1 Patch Release",
"url": "https://github.com/mistralai/mistral-common/releases/tag/v1.9.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.0 - Stream my audio 🎙️",
"url": "https://github.com/mistralai/mistral-common/releases/tag/v1.9.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.7: Refactoring and bug fixes.",
"url": "https://github.com/mistralai/mistral-common/releases/tag/v1.8.7"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.6: rm Python 3.9, bug fixes.",
"url": "https://github.com/mistralai/mistral-common/releases/tag/v1.8.6"
}
],
"status": "已收录 10 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Official inference library for pre-processing of Mistral models",
"effort": "安装已验证",
"forks": 144,
"icon": "code",
"name": "mistral-common 能力包",
"risk": "可发布",
"slug": "mistral-common",
"stars": 889,
"tags": [
"MCP 工具",
"视觉工作流编排",
"流程自动化",
"自动化工作流",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/mistralai/mistral-common 项目说明书\n\n生成时间：2026-05-17 00:44:16 UTC\n\n## 目录\n\n- [项目介绍与安装](#p1)\n- [项目架构总览](#p2)\n- [分词器系统详解](#p3)\n- [多模态处理（图像与音频）](#p4)\n- [指令与填充中间（FIM）协议](#p5)\n- [请求验证与标准化](#p6)\n- [语音与转录协议](#p7)\n- [Grammar Factory 与 LLM Guidance](#p8)\n- [实验性功能（工具调用、思考解析、FastAPI 服务）](#p9)\n- [数据文件与模型版本管理](#p10)\n\n\n\n## 项目介绍与安装\n\n### 相关页面\n\n相关主题：[数据文件与模型版本管理](#p10), [项目架构总览](#p2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)\n- [AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)\n- [pyproject.toml](https://github.com/mistralai/mistral-common/blob/main/pyproject.toml)\n- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n \n\n# 项目介绍与安装\n\n## 1. 项目概述\n\nmistral-common 是 Mistral AI 开源的工具库集合，旨在帮助开发者更好地使用 Mistral AI 模型。该项目包含了令牌化器（tokenizers）、验证（validation）、规范化（normalization）等核心功能，可与 Mistral AI 的各种模型配合使用。\n\n资料来源：[README.md:1]()\n\n### 1.1 核心功能\n\n| 功能模块 | 描述 |\n|---------|------|\n| **令牌化（Tokenization）** | 提供 Tekken 令牌化器，用于对请求进行编码 |\n| **协议处理（Protocol）** | 支持 Instruct、FIM（Fill-In-The-Middle）和 Transcription 协议 |\n| **验证与规范化** | 对聊天补全请求进行验证和规范化处理 |\n| **多模态支持** | 支持图像和音频处理（可选依赖） |\n| **Grammar 引导** | 使用 llguidance 创建工具调用、JSON schema 和推理的 Lark 语法 |\n\n资料来源：[AGENTS.md:2]()\n\n### 1.2 技术栈\n\n| 技术项 | 要求 |\n|-------|------|\n| 编程语言 | Python 3.10 至 3.14 |\n| 包管理器 | uv |\n| 测试框架 | pytest |\n| 代码格式化 | Ruff |\n| 类型检查 | mypy |\n| 持续集成 | GitHub Actions |\n\n资料来源：[AGENTS.md:1]()\n\n## 2. 项目架构\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"用户请求层\"\n A[ChatCompletionRequest] --> B[验证器 Validator]\n B --> C[规范化器 Normalizer]\n C --> D[InstructRequest]\n end\n \n subgraph \"令牌化层\"\n D --> E[MistralTokenizer]\n E --> F[Tekken Tokenizer]\n end\n \n subgraph \"输出层\"\n F --> G[Tokenized 对象]\n end\n \n subgraph \"可选模块\"\n H[Image Encoder] -.-> E\n I[Audio Encoder] -.-> E\n end\n```\n\n### 2.2 目录结构\n\n```\nmistral-common/\n├── src/\n│ └── mistral_common/\n│ ├── protocol/ # 协议处理\n│ │ ├── instruct/ # Instruct 协议\n│ │ │ ├── request.py # ChatCompletionRequest 定义\n│ │ │ ├── normalize.py # 请求规范化器\n│ │ │ ├── validator.py # 请求验证器\n│ │ │ ├── messages.py # 消息定义\n│ │ │ └── tool_calls.py # 工具调用\n│ │ ├── fim/ # FIM 协议\n│ │ └── transcription/ # 转录协议\n│ ├── tokens/ # 令牌化\n│ │ └── tokenizers/ # 令牌化器实现\n│ │ ├── tekken.py # Tekken 令牌化器\n│ │ ├── mistral.py # Mistral 令牌化器\n│ │ ├── instruct.py # Instruct 令牌化器\n│ │ ├── image.py # 图像处理\n│ │ └── audio.py # 音频处理\n│ ├── guidance/ # Grammar 引导\n│ └── experimental/ # 实验性功能\n├── tests/ # 测试套件\n├── docs/ # 文档\n└── pyproject.toml # 项目配置\n```\n\n资料来源：[AGENTS.md:1-2]()\n\n## 3. 安装指南\n\n### 3.1 基础安装\n\n使用 pip 进行基础安装：\n\n```bash\npip install mistral-common\n```\n\n资料来源：[README.md:2]()\n\n### 3.2 可选依赖安装\n\nmistral-common 包含多个可选依赖模块，可以根据需要选择性安装：\n\n| 依赖项 | 功能 | 安装命令 |\n|-------|------|---------|\n| `image` | 图像处理支持 | `pip install \"mistral-common[image]\"` |\n| `audio` | 音频处理支持 | `pip install \"mistral-common[audio]\"` |\n| `hf-hub` | 从 Hugging Face Hub 下载令牌化器 | `pip install \"mistral-common[hf-hub]\"` |\n| `sentencepiece` | SentencePiece 令牌化器支持（已弃用） | `pip install \"mistral-common[sentencepiece]\"` |\n| `server` | 服务器模式运行令牌化器 | `pip install \"mistral-common[server]\"` |\n\n资料来源：[README.md:2-5]()\n\n### 3.3 安装所有依赖\n\n一次性安装所有可选依赖：\n\n```bash\npip install \"mistral-common[image,audio,hf-hub,sentencepiece,server]\"\n```\n\n资料来源：[README.md:7]()\n\n## 4. 快速入门\n\n### 4.1 基本使用示例\n\n```python\nfrom mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage\nfrom mistral_common.protocol.instruct.request import ChatCompletionRequest\nfrom mistral_common.protocol.instruct.normalize import InstructRequestNormalizer\n\n# 创建聊天补全请求\nrequest = ChatCompletionRequest(\n messages=[\n UserMessage(content=\"你好！\"),\n AssistantMessage(content=\"你好！有什么可以帮助你的吗？\"),\n ],\n)\n\n# 使用规范化器处理请求\nnormalizer = InstructRequestNormalizer.normalizer()\ninstruct_request = normalizer.from_chat_completion_request(request)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:20-30]()\n\n### 4.2 带工具调用的请求\n\n```python\nfrom mistral_common.protocol.instruct.tool_calls import Tool, ToolTypes, Function\n\n# 定义工具\ntool = Tool(\n function=Function(\n name=\"get_weather\",\n description=\"获取指定位置的天气信息\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"城市和州，例如 San Francisco, CA\",\n },\n },\n \"required\": [\"location\"],\n },\n ),\n)\n\n# 创建带工具的请求\nrequest = ChatCompletionRequest(\n messages=[UserMessage(content=\"北京今天天气怎么样？\")],\n tools=[tool],\n tool_choice=\"auto\",\n)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:30-45]()\n\n### 4.3 请求验证\n\n```python\nfrom mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode\nfrom mistral_common.protocol.instruct.messages import UserMessage\n\n# 创建验证器（测试模式）\nvalidator = MistralRequestValidator(mode=ValidationMode.test)\n\n# 创建请求\nrequest = ChatCompletionRequest(\n model=\"mistral-large-latest\",\n messages=[UserMessage(content=\"Hello!\")],\n)\n\n# 验证请求\nvalidated_request = validator.validate_request(request)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:20-40]()\n\n## 5. 开发环境配置\n\n### 5.1 环境设置\n\n使用 uv 进行开发环境配置：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/mistralai/mistral-common.git\ncd mistral-common\n\n# 创建虚拟环境\nuv venv\nsource .venv/bin/activate\n\n# 同步所有依赖和开发依赖\nuv sync --frozen --all-extras --group dev\n\n# 安装预提交钩子\nuv run pre-commit install\n```\n\n资料来源：[README.md:40-50]()\n\n### 5.2 代码质量检查\n\n项目使用以下工具进行代码质量控制：\n\n| 工具 | 用途 | 命令 |\n|-----|------|------|\n| Ruff | 代码格式化和检查 | `uv run ruff check .` |\n| mypy | 类型检查 | `uv run mypy src/` |\n| pytest | 测试运行 | `uv run pytest tests/` |\n| pre-commit | 自动化检查 | `uv run pre-commit run --all-files` |\n\n### 5.3 开发工作流\n\n```mermaid\ngraph LR\n A[修改代码] --> B[编写测试]\n B --> C[运行预提交检查]\n C --> D{Ruff 格式化}\n D --> E{类型检查}\n E --> F{运行测试}\n F --> G[提交代码]\n```\n\n资料来源：[AGENTS.md:25-35]()\n\n## 6. 核心组件详解\n\n### 6.1 ChatCompletionRequest\n\n`ChatCompletionRequest` 是用户查询的入口点，定义在 `src/mistral_common/protocol/instruct/request.py` 中。\n\n| 属性 | 类型 | 描述 |\n|-----|------|------|\n| `model` | `str \\| None` | 模型名称 |\n| `messages` | `list[ChatMessageType]` | 消息列表 |\n| `response_format` | `ResponseFormat` | 响应格式 |\n| `tools` | `list[Tool] \\| None` | 可用工具列表 |\n| `tool_choice` | `ToolChoice` | 工具选择策略 |\n| `truncate_for_context_length` | `bool` | 是否截断以适应上下文长度 |\n| `continue_final_message` | `bool` | 是否继续最终消息 |\n| `reasoning_effort` | `ReasoningEffort \\| None` | 推理努力程度 |\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:20-35]()\n\n### 6.2 令牌化器版本\n\nmistral-common 支持多个令牌化器版本：\n\n| 版本 | 图像支持 | 音频支持 | 说明 |\n|-----|---------|---------|------|\n| v1 | ❌ | ❌ | 基础版本 |\n| v2 | ❌ | ❌ | 改进版本 |\n| v3 | ✅ | ❌ | 支持图像处理 |\n| v7 | ✅ | ✅ | 支持图像和音频 |\n| v11 | ✅ | ✅ | 进一步改进 |\n| v13 | ✅ | ✅ | 最新版本 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()\n\n### 6.3 特殊令牌\n\nTekken 令牌化器定义了一系列特殊令牌：\n\n| 令牌名称 | 用途 |\n|---------|------|\n| `bos` | 句子开始 |\n| `eos` | 句子结束 |\n| `unk` | 未知词元 |\n| `eop` | 段落结束 |\n| `eod` | 文档结束 |\n| `begin_tool_results` | 工具结果开始 |\n| `end_tool_results` | 工具结果结束 |\n| `begin_tool_content` | 工具内容开始 |\n| `img` | 图像标记 |\n| `pad` | 填充令牌 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py:1-30]()\n\n## 7. 高级功能\n\n### 7.1 多模态处理\n\n#### 7.1.1 图像处理\n\n使用图像令牌化器需要安装 `image` 依赖：\n\n```bash\npip install \"mistral-common[image]\"\n```\n\n图像处理流程：\n\n```mermaid\ngraph TD\n A[图像文件] --> B[ImageEncoder]\n B --> C[编码的图像数据]\n C --> D[Tokenized 对象]\n```\n\n#### 7.1.2 音频处理\n\n使用音频令牌化器需要安装 `audio` 依赖：\n\n```bash\npip install \"mistral-common[audio]\"\n```\n\n### 7.2 服务器模式\n\n提供 FastAPI 服务器模式运行令牌化器：\n\n```bash\npip install \"mistral-common[server]\"\n```\n\n启动服务器：\n\n```bash\npython -m mistral_common.experimental.app.main serve \\\n --tokenizer-path /path/to/tokenizer \\\n --validation-mode test \\\n --host 127.0.0.1 \\\n --port 8000\n```\n\n资料来源：[src/mistral_common/experimental/app/main.py:1-50]()\n\n### 7.3 Grammar 引导\n\n使用 llguidance 创建语法引导的输出：\n\n```python\nfrom mistral_common.guidance.grammar_factory import GrammarFactory\n\n# 创建语法工厂\ngrammar_factory = GrammarFactory()\n\n# 生成工具调用的语法\ngrammar = grammar_factory.create_tool_call_grammar(tools=[tool])\n```\n\n资料来源：[AGENTS.md:12-15]()\n\n## 8. 贡献指南\n\n### 8.1 代码风格规范\n\n| 规范 | 要求 |\n|-----|------|\n| 命名规范 | 函数/变量使用 snake_case，类使用 PascalCase |\n| 类型提示 | 必须使用 Python 类型提示 |\n| 文档字符串 | 必须使用 Google 风格文档字符串 |\n| 导入规范 | 使用绝对导入，禁止通配符导入 |\n\n资料来源：[AGENTS.md:18-30]()\n\n### 8.2 提交规范\n\n- 使用祈使语气\n- 以动词开头\n- 保持简洁明了\n\n### 8.3 向后兼容性\n\n新增功能时必须确保不破坏现有功能。\n\n资料来源：[AGENTS.md:35-40]()\n\n## 9. 许可协议\n\nmistral-common 库采用 Apache 2.0 许可证。\n\n> **重要提示**：您不得以侵犯、侵犯或以其他方式违反任何第三方权利（包括知识产权）的方式使用本库或我们的模型。\n\n资料来源：[README.md:55-60]()\n\n## 10. 相关资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方文档 | https://mistralai.github.io/mistral-common/ |\n| PyPI 主页 | https://pypi.org/project/mistral-common/ |\n| GitHub Issues | https://github.com/mistralai/mistral-common/issues |\n| 模型下载 | Hugging Face Hub |\n\n---\n\n\n\n## 项目架构总览\n\n### 相关页面\n\n相关主题：[项目介绍与安装](#p1), [分词器系统详解](#p3), [请求验证与标准化](#p6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)\n- [AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/misturalai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n \n\n# 项目架构总览\n\n## 概述\n\nmistral-common 是 Mistral AI 官方开源的预处理库，专为 Mistral 大语言模型（LLM）设计。该库提供了一套完整的工具集，用于将用户请求编码为模型可处理的 token 序列，同时支持图像、音频等多模态数据的处理 资料来源：[README.md:1]()。\n\n### 技术栈\n\n| 类别 | 技术选型 |\n|------|---------|\n| 语言版本 | Python 3.10 - 3.14 |\n| 包管理器 | uv |\n| 测试框架 | pytest |\n| 代码格式 | Ruff |\n| 类型检查 | mypy |\n| 持续集成 | GitHub Actions |\n| 协议许可 | Apache 2.0 |\n\n资料来源：[AGENTS.md:1-10]()\n\n---\n\n## 核心架构设计\n\nmistral-common 采用分层架构设计，主要包含以下核心模块：\n\n```mermaid\ngraph TB\n subgraph \"表现层 (Protocol)\"\n P1[Instruct Protocol]\n P2[FIM Protocol]\n P3[Transcription Protocol]\n end\n \n subgraph \"处理层 (Tokens)\"\n T1[Instruct Tokenizer]\n T2[Mistral Tokenizer]\n T3[Tekken Tokenizer]\n end\n \n subgraph \"指导层 (Guidance)\"\n G1[Grammar Factory]\n G2[Token Guidance]\n end\n \n subgraph \"实验层 (Experimental)\"\n E1[Tool Calls Parser]\n E2[Think Parser]\n end\n \n P1 --> T1\n P2 --> T1\n P3 --> T1\n T1 --> T2\n T2 --> T3\n G1 --> G2\n```\n\n---\n\n## 模块详解\n\n### 1. 协议层 (Protocol)\n\n协议层是用户请求的入口点，负责定义和验证不同类型的请求格式 资料来源：[AGENTS.md:38-57]()。\n\n#### 1.1 Instruct Protocol\n\nInstruct Protocol 处理对话补全请求，是最常用的协议类型。\n\n| 组件文件 | 功能描述 |\n|---------|---------|\n| `request.py` | 定义 `ChatCompletionRequest`，用户查询的入口点 |\n| `messages.py` | 定义指导消息类型（UserMessage、AssistantMessage 等） |\n| `validator.py` | 验证请求结构和内容 |\n| `normalize.py` | 将请求转换为内部 instruct 格式 |\n| `tool_calls.py` | 工具调用逻辑处理 |\n| `converters.py` | 与 OpenAI 格式的转换辅助工具 |\n| `chunk.py` | 消息内容分块处理 |\n\n资料来源：[AGENTS.md:40-48]()\n\n#### 1.2 FIM Protocol\n\nFill-in-the-Middle 协议用于代码补全等中间填空任务：\n\n```python\n# 入口文件: src/mistral_common/protocol/fim/request.py\nclass FIMRequest(BaseCompletionRequest)\n```\n\n#### 1.3 Transcription Protocol\n\n音频转录协议处理音频文件的转录请求：\n\n```python\n# 入口文件: src/mistral_common/protocol/transcription/request.py\nclass TranscriptionRequest(BaseCompletionRequest)\n```\n\n---\n\n### 2. 令牌化层 (Tokens)\n\n令牌化层是核心处理引擎，负责将规范化后的请求编码为 token 序列 资料来源：[AGENTS.md:50-68]()。\n\n#### 2.1 架构层级\n\n```mermaid\ngraph LR\n A[用户请求] --> B[Validator 验证]\n B --> C[Normalizer 规范化]\n C --> D[MistralTokenizer]\n D --> E[InstructTokenizer]\n E --> F[TekkenTokenizer]\n F --> G[Token IDs]\n```\n\n#### 2.2 Tokenizer 类体系\n\n| Tokenizer 类型 | 文件位置 | 功能说明 |\n|---------------|---------|---------|\n| `Tokenizer` | `base.py` | 抽象基类，定义通用接口 |\n| `TekkenTokenizer` | `tekken.py` | Tekken 分词器，所有最新模型使用 |\n| `InstructTokenizerV1-V11` | `instruct.py` | Instruct 令牌化器版本实现 |\n| `MistralTokenizer` | `mistral.py` | 主令牌化器，编排验证和规范化流程 |\n| `AudioTokenizer` | `audio.py` | 音频数据处理 |\n\n资料来源：[AGENTS.md:50-66]()\n\n#### 2.3 Tokenizer 版本支持\n\nmistral-common 支持从 v1 到 v13 的多种 tokenizer 版本：\n\n| 版本 | 图像支持 | 音频支持 | 特殊说明 |\n|------|---------|---------|---------|\n| v1 | ❌ | ❌ | 基础版本 |\n| v2 | ❌ | ❌ | 增强验证 |\n| v3 | ✅ | ❌ | 引入图像编码器 |\n| v7 | ✅ | ✅ | 引入音频编码器 |\n| v11 | ✅ | ✅ | 性能优化 |\n| v13 | ✅ | ✅ | 最新版本 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-60]()\n\n---\n\n### 3. 验证与规范化流程\n\n#### 3.1 验证模式\n\n`MistralRequestValidator` 支持三种验证模式：\n\n| 模式 | 用途 |\n|------|------|\n| `test` | 默认模式，用于标准测试 |\n| `serving` | 服务模式，要求提供模型名称 |\n| `finetuning` | 微调模式 |\n\n```python\nclass ValidationMode(str, Enum):\n serving = \"serving\"\n finetuning = \"finetuning\"\n test = \"test\"\n```\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:1-20]()\n\n#### 3.2 规范化器\n\n`InstructRequestNormalizer` 负责将 `ChatCompletionRequest` 转换为内部 instruct 格式：\n\n```python\nclass InstructRequestNormalizer:\n def from_chat_completion_request(self, request: ChatCompletionRequest) -> InstructRequest\n```\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-40]()\n\n---\n\n### 4. 指导层 (Guidance)\n\nGuidance 模块使用 llguidance 库创建 Lark 语法，用于约束模型输出格式 资料来源：[AGENTS.md:70-77]()。\n\n| 组件 | 功能 |\n|------|------|\n| `grammar_factory.py` | 从 Jinja 模板构建和渲染 Lark 语法 |\n| `tokenizer.py` | 适配 Tekken 分词器用于 llguidance |\n| `data/` | 包含 base、thinking 等模式的语法模板文件 |\n\n---\n\n### 5. 实验性功能 (Experimental)\n\nexperimental 模块包含尚未稳定的功能：\n\n| 组件 | 功能 |\n|------|------|\n| `tools.py` | 工具调用解析器 |\n| `think.py` | 思考模式解析器 |\n| `utils.py` | 通用工具函数 |\n| `app/` | FastAPI 应用，包含路由器和入口点 |\n\n资料来源：[AGENTS.md:79-88]()\n\n---\n\n### 6. 根级工具模块\n\n| 模块文件 | 功能描述 |\n|---------|---------|\n| `audio.py` | 音频处理工具，包含 Audio 类和梅尔刻度转换 |\n| `image.py` | 图像下载和序列化处理 |\n| `base.py` | Pydantic 模型基础配置 |\n| `exceptions.py` | 自定义异常类 |\n| `imports.py` | 导入工具和依赖检查 |\n\n资料来源：[AGENTS.md:28-37]()\n\n---\n\n## 数据流架构\n\n```mermaid\nflowchart TD\n A[ChatCompletionRequest] --> B[MistralRequestValidator]\n B --> C{验证通过?}\n C -->|否| D[抛出异常]\n C -->|是| E[InstructRequestNormalizer]\n E --> F[InstructRequest]\n F --> G[MistralTokenizer]\n G --> H[InstructTokenizer]\n H --> I[TekkenTokenizer]\n I --> J[Tokenized 对象]\n \n K[Tokenized.tokens] --> L[模型输入]\n M[Tokenized.images] --> N[多模态处理]\n O[Tokenized.audios] --> P[音频处理]\n```\n\n---\n\n## 项目目录结构\n\n```\nmistral-common/\n├── src/\n│ └── mistral_common/\n│ ├── protocol/ # 协议层\n│ │ ├── instruct/ # 对话补全协议\n│ │ ├── fim/ # 填空协议\n│ │ ├── transcription/ # 转录协议\n│ │ ├── base.py # 基础请求类\n│ │ └── utils.py # 工具函数\n│ ├── tokens/ # 令牌化层\n│ │ ├── tokenizers/ # 分词器实现\n│ │ └── instruct/ # (已废弃)\n│ ├── guidance/ # 指导层\n│ ├── experimental/ # 实验性功能\n│ ├── audio.py # 音频处理\n│ ├── image.py # 图像处理\n│ ├── base.py # 基础配置\n│ └── exceptions.py # 异常定义\n├── tests/ # 测试套件\n├── docs/ # 文档\n├── .github/workflows/ # CI/CD 工作流\n├── pyproject.toml # 项目配置\n└── README.md # 项目说明\n```\n\n资料来源：[AGENTS.md:12-26]()\n\n---\n\n## 依赖管理\n\nmistral-common 采用可选依赖设计，各功能模块可独立安装：\n\n```sh\n# 图像处理\npip install \"mistral-common[image]\"\n\n# 音频处理\npip install \"mistral-common[audio]\"\n\n# HuggingFace Hub 支持\npip install \"mistral-common[hf-hub]\"\n\n# SentencePiece 支持 (已废弃)\npip install \"mistral-common[sentencepiece]\"\n\n# 服务器模式\npip install \"mistral-common[server]\"\n\n# 安装全部依赖\npip install \"mistral-common[image,audio,hf-hub,sentencepiece,server]\"\n```\n\n资料来源：[README.md:1-20]()\n\n---\n\n## 核心类关系图\n\n```mermaid\nclassDiagram\n class BaseCompletionRequest {\n <>\n }\n \n class ChatCompletionRequest {\n +messages: list[ChatMessageType]\n +tools: list[Tool]\n +response_format: ResponseFormat\n +to_openai(): dict\n }\n \n class InstructRequest {\n +messages\n +system_prompt\n +available_tools\n }\n \n class Tokenized {\n +tokens: list[int]\n +text: str\n +prefix_ids: list[int]\n +images: list[np.ndarray]\n +audios: list[Audio]\n }\n \n class MistralRequestValidator {\n +validate_request()\n +validate_messages()\n +_validate_tools()\n }\n \n class InstructRequestNormalizer {\n +from_chat_completion_request()\n }\n \n class Tokenizer {\n <>\n +vocab()\n +id_to_piece()\n }\n \n BaseCompletionRequest <|-- ChatCompletionRequest\n ChatCompletionRequest --> MistralRequestValidator\n ChatCompletionRequest --> InstructRequestNormalizer\n InstructRequestNormalizer ..> InstructRequest\n MistralTokenizer --> Tokenized\n MistralTokenizer --> InstructRequestNormalizer\n MistralTokenizer --|> Tokenizer\n```\n\n---\n\n## 开发指南\n\n### 代码规范\n\n| 规范类型 | 具体要求 |\n|---------|---------|\n| 命名 | 函数/变量使用 snake_case，类使用 PascalCase |\n| 类型提示 | 必须使用，优先采用 Python 3.10+ 语法 |\n| 文档字符串 | 采用 Google 风格，包含 Args/Returns |\n| 错误处理 | 使用 `mistral_common.exceptions` 中的自定义异常 |\n\n资料来源：[AGENTS.md:95-110]()\n\n### 开发工作流\n\n1. **环境配置**：使用 uv 同步开发环境\n2. **代码编写**：遵循代码规范，编写测试用例\n3. **代码检查**：运行 Ruff、mypy、pytest\n4. **提交**：安装 pre-commit hooks 后提交\n\n```bash\nuv sync --frozen --all-extras --group dev --python 3.12\nsource .venv/bin/activate\nuv run pre-commit install\n```\n\n资料来源：[AGENTS.md:112-126]()\n\n---\n\n## 总结\n\nmistral-common 作为 Mistral AI 模型的官方预处理库，通过分层架构实现了请求验证、规范化和令牌化的完整流程。库的设计强调模块化、可扩展性和类型安全，支持从简单的文本对话到复杂的多模态输入场景。开发者可通过清晰定义的接口扩展新功能，同时保持与现有系统的高度兼容性。\n\n---\n\n\n\n## 分词器系统详解\n\n### 相关页面\n\n相关主题：[多模态处理（图像与音频）](#p4), [指令与填充中间（FIM）协议](#p5), [项目架构总览](#p2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n- [src/mistral_common/tokens/tokenizers/sentencepiece.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/sentencepiece.py)\n- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n- [src/mistral_common/tokens/tokenizers/instruct.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/instruct.py)\n \n\n# 分词器系统详解\n\n## 概述\n\nmistral-common 的分词器系统是连接文本请求与大语言模型的核心组件，负责将用户输入的文本转换为模型可处理的 token 序列，以及将模型的输出 token 序列还原为可读文本。该系统支持多种 tokenizer 版本，从早期的 SentencePiece 实现到最新的 Tekken 分词器，为 Mistral 各代模型提供统一的文本处理能力。\n\n分词器系统的主要职责包括：\n- **编码（Encode）**：将原始文本转换为 token ID 序列\n- **解码（Decode）**：将 token ID 序列转换回可读文本\n- **特殊标记处理**：管理模型使用的特殊标记（如 ``、``、`[INST]` 等）\n- **多模态支持**：处理图像和音频内容（部分版本）\n- **请求验证**：在编码前验证请求格式的正确性\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n\n## 架构设计\n\n### 分词器类型层次\n\n分词器系统采用分层架构设计，从底层的字符级别编码到高层的请求处理，形成清晰的职责划分：\n\n```mermaid\ngraph TD\n A[MistralTokenizer
高层入口] --> B[InstructTokenizer
指令编码器]\n B --> C[TekkenTokenizer
核心分词器]\n C --> D[Base Model
底层编码模型]\n \n E[SentencePieceTokenizer
已废弃] -.-> D\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n### 核心组件关系\n\n| 组件 | 文件位置 | 职责 | 状态 |\n|------|---------|------|------|\n| `MistralTokenizer` | mistral.py | 高层工厂类，负责版本选择和组件组装 | 活跃 |\n| `InstructTokenizer` | instruct.py | 将请求编码为 token 序列 | 活跃 |\n| `TekkenTokenizer` | tekken.py | 核心分词实现，支持 v11+ | 活跃 |\n| `SentencePieceTokenizer` | sentencepiece.py | 旧版分词实现 | 已废弃 |\n\n## Tekken 分词器\n\nTekken 是 Mistral 最新模型使用的分词器实现，相比 SentencePiece 具有更好的性能和更丰富的功能支持。\n\n### 特殊标记定义\n\nTekken 分词器定义了一套完整的特殊标记系统，用于标识文本结构、工具调用、图像等不同内容类型：\n\n| 标记名称 | 标记字符串 | 用途 | 优先级 |\n|---------|-----------|------|--------|\n| unk | `` | 未知词元 | 1 |\n| bos | `` | 序列起始 | 2 |\n| eos | `` | 序列结束 | 3 |\n| begin_inst | `[INST]` | 指令开始 | 4 |\n| end_inst | `[/INST]` | 指令结束 | 5 |\n| begin_tools | `[AVAILABLE_TOOLS]` | 工具列表开始 | 6 |\n| end_tools | `[/AVAILABLE_TOOLS]` | 工具列表结束 | 7 |\n| begin_tool_results | `[TOOL_RESULTS]` | 工具结果开始 | 8 |\n| end_tool_results | `[/TOOL_RESULTS]` | 工具结果结束 | 9 |\n| tool_calls | `[TOOL_CALLS]` | 工具调用标记 | 10 |\n| img | `[IMG]` | 图像标记 | 11 |\n| pad | `` | 填充标记 | 12 |\n| img_break | `[IMG_BREAK]` | 图像截断标记 | 13 |\n| img_end | `[IMG_END]` | 图像结束标记 | 14 |\n| prefix | `[PREFIX]` | FIM 前缀标记 | 15 |\n| middle | `[MIDDLE]` | FIM 中间标记 | 16 |\n| suffix | `[SUFFIX]` | FIM 后缀标记 | 17 |\n| begin_system | `[SYSTEM_PROMPT]` | 系统提示开始 | 18 |\n| end_system | `[/SYSTEM_PROMPT]` | 系统提示结束 | 19 |\n| begin_tool_content | `[TOOL_CONTENT]` | 工具内容开始 | 20 |\n| begin_think | `[THINK]` | 思考开始 | 21 |\n| end_think | `[/THINK]` | 思考结束 | 22 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n### 特殊标记策略\n\n`SpecialTokenPolicy` 枚举控制分词器在解码时如何处理特殊标记：\n\n```python\nclass SpecialTokenPolicy(str, Enum):\n \"\"\"What to do with special tokens when encoding/decoding.\"\"\"\n \n IGNORE = \"ignore\" # 解码时跳过特殊标记\n KEEP = \"keep\" # 解码时保留特殊标记\n RAISE = \"raise\" # 遇到特殊标记时抛出异常\n```\n\n使用示例：\n```python\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\nfrom mistral_common.tokens.tokenizers.tekken import SpecialTokenPolicy\n\ntokenizer = MistralTokenizer.v3(is_tekken=True)\ntekken = tokenizer.instruct_tokenizer.tokenizer\ntekken.special_token_policy = SpecialTokenPolicy.IGNORE\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n### 核心 API\n\nTekkenTokenizer 提供以下核心接口：\n\n| 方法/属性 | 返回类型 | 说明 |\n|----------|---------|------|\n| `n_words` | `int` | 词表大小 |\n| `special_ids` | `set[int]` | 特殊标记的 ID 集合 |\n| `num_special_tokens` | `int` | 特殊标记数量 |\n| `vocab()` | `list[str]` | 返回所有词表 token |\n| `id_to_piece(token_id)` | `str` | 将 token ID 转换为字符串 |\n| `encode(text)` | `Tokenized` | 编码文本 |\n| `decode(tokens)` | `str` | 解码 token 序列 |\n| `is_byte(token_id)` | `bool` | 检查是否为字节 token |\n| `is_special(token)` | `bool` | 检查是否为特殊标记 |\n| `get_special_token(s)` | `int` | 获取特殊标记的 ID |\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n\n## Tokenized 数据结构\n\n`Tokenized` 是分词结果的核心数据结构，用于在系统各组件间传递编码后的数据：\n\n```python\nclass Tokenized:\n \"\"\"Represents a tokenized request or response.\"\"\"\n \n model_config = ConfigDict(arbitrary_types_allowed=True)\n tokens: list[int] # Token ID 列表\n text: str | None = None # 原始文本（解码时使用）\n prefix_ids: list[int] | None = None # FIM 前缀 ID\n images: list[np.ndarray] = Field(default_factory=list) # 关联图像\n audios: list[Audio] = Field(default_factory=list) # 关联音频\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n\n## 分词器版本演进\n\nmistral-common 支持多个 tokenizer 版本，以适配不同代际的 Mistral 模型：\n\n| 版本 | 图像支持 | 音频支持 | 推荐用途 |\n|------|---------|---------|---------|\n| v1 | ❌ | ❌ | 早期模型兼容 |\n| v2 | ❌ | ❌ | 早期模型兼容 |\n| v3 | ✅ | ❌ | 图像支持模型 |\n| v7 | ✅ | ❌ | 高级推理模型 |\n| v11 | ✅ | ✅ | 最新模型（推荐） |\n| v13 | ✅ | ✅ | 最新模型（最新） |\n\n版本创建逻辑：\n```python\nif tokenizer.version == TokenizerVersion.v1:\n return MistralTokenizer(InstructTokenizerV1(tokenizer), ...)\nelif tokenizer.version == TokenizerVersion.v11:\n return MistralTokenizer(\n InstructTokenizerV11(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),\n ...\n )\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n## MistralTokenizer 工厂类\n\n`MistralTokenizer` 是系统的高层入口，提供版本感知的分词器创建能力：\n\n### 创建方法\n\n| 静态方法 | 说明 | 适用版本 |\n|---------|------|---------|\n| `v1()` | 创建 v1 分词器 | v1 |\n| `v2()` | 创建 v2 分词器 | v2 |\n| `v3()` | 创建 v3 分词器 | v3 |\n| `v7()` | 创建 v7 分词器 | v7 |\n| `v11()` | 创建 v11 分词器 | v11 |\n| `v13()` | 创建 v13 分词器 | v13 |\n| `from_path(path)` | 从路径加载分词器 | 所有版本 |\n\n### 核心属性\n\n| 属性 | 类型 | 说明 |\n|-----|------|------|\n| `instruct_tokenizer` | `InstructTokenizer` | 指令编码器实例 |\n| `validator` | `MistralRequestValidator` | 请求验证器 |\n| `request_normalizer` | `InstructRequestNormalizer` | 请求标准化器 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n## 解码流程\n\n解码过程处理 token 序列到文本的转换，需要正确处理特殊标记：\n\n```mermaid\ngraph LR\n A[Token ID 序列] --> B{特殊标记策略?}\n B -->|KEEP| C[保留特殊标记字符串]\n B -->|IGNORE| D[跳过特殊标记]\n B -->|RAISE| E[抛出异常]\n C --> F[普通 token 解码]\n D --> F\n F --> G[拼接结果]\n C --> G\n```\n\n解码实现核心逻辑：\n```python\ndef decode(self, tokens: list[int], ...) -> str:\n decoded = []\n for t in tokens:\n if t in self._all_special_tokens:\n if special_token_policy == SpecialTokenPolicy.RAISE:\n raise ValueError(\"...\")\n elif special_token_policy == SpecialTokenPolicy.KEEP:\n decoded.append(self._all_special_tokens[t][\"token_str\"])\n elif special_token_policy == SpecialTokenPolicy.IGNORE:\n continue\n else:\n decoded.append(self._model.decode([t - self.num_special_tokens]))\n return \"\".join(decoded)\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n## 与 Guidance 系统集成\n\nGrammarFactory 使用分词器生成语法约束，用于控制模型输出的格式。该集成需要 Tekken tokenizer 版本 >= v11：\n\n```python\nclass GrammarFactory:\n def __init__(self, tokenizer):\n assert_llguidance_installed()\n assert_jinja2_installed()\n self._tokenizer = tokenizer.instruct_tokenizer.tokenizer\n \n if not self.is_supported(tokenizer):\n raise ValueError(\n f\"Guidance requires a Tekken tokenizer with version >= v11, \"\n f\"got {type(self._tokenizer).__name__} {self._tokenizer.version.value}\"\n )\n self._llg_tokenizer = from_mistral_tokenizer(tokenizer)\n self._special_token_map = self._build_special_token_map()\n```\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/grammar_factory.py)\n\n## 使用示例\n\n### 基础编码解码\n\n```python\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\n\n# 加载分词器\ntokenizer = MistralTokenizer.v3()\n\n# 编码文本\ntokenized = tokenizer.instruct_tokenizer.encode(\"Hello, how are you?\")\nprint(f\"Token IDs: {tokenized.tokens}\")\nprint(f\"Token count: {len(tokenized.tokens)}\")\n\n# 解码文本\ndecoded = tokenizer.instruct_tokenizer.decode(tokenized.tokens)\nprint(f\"Decoded: {decoded}\")\n```\n\n### 处理多模态内容（v11+）\n\n```python\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\nfrom mistral_common.image import Image\n\ntokenizer = MistralTokenizer.v11()\n\n# 处理包含图像的请求\nimage = Image.from_url(\"https://example.com/image.jpg\")\ntokenized = tokenizer.instruct_tokenizer.encode(\n \"Describe this image\",\n images=[image]\n)\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n## 弃用说明\n\n### SentencePieceTokenizer\n\n`SentencePieceTokenizer` 已弃用，仅保留用于向后兼容。推荐使用 Tekken 分词器：\n\n| 特性 | SentencePiece | Tekken |\n|------|--------------|--------|\n| 性能 | 较低 | 高 |\n| 特殊标记支持 | 有限 | 完整 |\n| 多模态支持 | ❌ | ✅ |\n| Guidance 集成 | ❌ | ✅ |\n| 状态 | 已废弃 | 活跃 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/sentencepiece.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/sentencepiece.py)\n\n## 总结\n\nmistral-common 的分词器系统提供了从底层编码到高层请求处理的完整能力栈。核心要点：\n\n1. **Tekken 是推荐的实现**：相比废弃的 SentencePiece，提供更好的性能和更完整的功能\n2. **版本分层设计**：通过 `MistralTokenizer` 工厂类统一管理不同版本的分词器\n3. **特殊标记策略**：通过 `SpecialTokenPolicy` 灵活控制特殊标记的解码行为\n4. **多模态扩展**：v3+ 版本支持图像处理，v11+ 版本支持音频处理\n5. **与 Guidance 集成**：v11+ 版本可与 GrammarFactory 配合进行结构化输出控制\n\n---\n\n\n\n## 多模态处理（图像与音频）\n\n### 相关页面\n\n相关主题：[分词器系统详解](#p3), [指令与填充中间（FIM）协议](#p5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/tokens/tokenizers/image.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/image.py)\n- [src/mistral_common/tokens/tokenizers/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/audio.py)\n- [src/mistral_common/image.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/image.py)\n- [src/mistral_common/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/audio.py)\n- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n \n\n# 多模态处理（图像与音频）\n\n## 概述\n\nmistral-common 库提供了完整的多模态处理能力，支持在文本对话中嵌入图像和音频内容。该模块是预处理管道的核心组成部分，负责将用户提供的多模态数据（图像、音频）转换为模型可处理的 token 序列。\n\n多模态处理的核心设计目标是：\n\n- **图像支持**：从 v3 版本 tokenizer 开始引入，支持图像下载、预处理和 token 化\n- **音频支持**：从 v7 版本 tokenizer 开始引入，支持音频编码和解码\n- **无缝集成**：与现有的 ChatCompletionRequest 协议完全兼容\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()\n\n## 架构设计\n\n### 多模态处理流程\n\n```mermaid\ngraph TD\n A[ChatCompletionRequest] --> B[请求验证 Validator]\n B --> C[请求标准化 Normalizer]\n C --> D{多模态类型判断}\n \n D -->|仅文本| E[InstructTokenizer - 纯文本编码]\n D -->|含图像| F[ImageEncoder + InstructTokenizerV3/V7/V11/V13/V15]\n D -->|含音频| G[AudioEncoder + InstructTokenizerV7/V11/V13/V15]\n D -->|图像+音频| H[ImageEncoder + AudioEncoder + 组合Tokenizer]\n \n E --> I[Tokenized 对象]\n F --> I\n G --> I\n H --> I\n \n I --> J[模型输入]\n```\n\n### 核心组件关系\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| Tokenized | `tokens/tokenizers/base.py` | 多模态 token 化结果的数据结构 |\n| ImageEncoder | `tokens/tokenizers/image.py` | 图像编码器接口 |\n| AudioEncoder | `tokens/tokenizers/audio.py` | 音频编码器接口 |\n| MistralTokenizer | `tokens/tokenizers/mistral.py` | 综合 tokenizer，支持图像和音频 |\n| Image 工具类 | `image.py` | 图像下载和序列化工具 |\n| Audio 工具类 | `audio.py` | 音频处理和 mel-scale 转换 |\n\n## Tokenized 数据结构\n\n多模态处理的结果通过 `Tokenized` 类表示，该类继承自 Pydantic BaseModel，支持灵活的多模态数据存储：\n\n```python\nclass Tokenized(MistralBase):\n \"\"\"Represents the tokenized output of a tokenizer.\n \n Attributes:\n tokens: The token ids.\n text: The text representation of the tokens.\n prefix_ids: The prefix ids for FIM.\n images: The loaded images associated with the tokens.\n audios: The audio objects associated with the tokens.\n \"\"\"\n model_config = ConfigDict(arbitrary_types_allowed=True)\n tokens: list[int]\n text: str | None = None\n prefix_ids: list[int] | None = None\n images: list[np.ndarray] = Field(default_factory=list)\n audios: list[Audio] = Field(default_factory=list)\n```\n\n**字段说明**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `tokens` | `list[int]` | token ID 序列，模型的核心输入 |\n| `text` | `str \\| None` | token 对应的文本表示 |\n| `prefix_ids` | `list[int] \\| None` | FIM（Fill-In-The-Middle）任务的 prefix token |\n| `images` | `list[np.ndarray]` | 预处理后的图像 NumPy 数组列表 |\n| `audios` | `list[Audio]` | 处理后的音频对象列表 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py:50-65]()\n\n## 图像处理\n\n### 安装依赖\n\n图像处理需要安装 `image` 额外依赖：\n\n```sh\npip install \"mistral-common[image]\"\n```\n\n### ImageEncoder 接口\n\n`ImageEncoder` 是一个抽象基类，定义了图像编码的标准接口：\n\n```python\nclass ImageEncoder(ABC):\n @abstractmethod\n def encode_images(self, images: list[np.ndarray]) -> list[ImageOutput]:\n \"\"\"Encode a list of images into model input format.\"\"\"\n \n @property\n @abstractmethod\n def image_token_id(self) -> int:\n \"\"\"The token id for image tokens.\"\"\"\n```\n\n### 图像处理工具类\n\n`mistral_common.image` 模块提供了图像处理的核心工具函数：\n\n```python\nclass Image(MistralBase):\n \"\"\"Image representation with download and serialization support.\"\"\"\n url: str | None = None\n base64: str | None = None\n content: bytes | None = None\n```\n\n主要功能：\n\n- **图像下载**：支持从 URL 下载图像内容\n- **Base64 编码/解码**：支持 base64 格式的图像数据\n- **预处理**：将图像转换为 NumPy 数组格式\n- **序列化**：支持图像数据的序列化和反序列化\n\n资料来源：[src/mistral_common/image.py:1-100]()\n\n### 特殊 Token\n\n图像相关的特殊 Token 定义在 `SpecialTokens` 类中：\n\n| Token | 标识 | 用途 |\n|-------|------|------|\n| `img` | `[IMG]` | 图像开始标记 |\n| `img_break` | `[IMG_BREAK]` | 多图像分隔标记 |\n| `img_end` | `[IMG_END]` | 图像结束标记 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py:100-110]()\n\n## 音频处理\n\n### 安装依赖\n\n音频处理需要安装 `audio` 额外依赖：\n\n```sh\npip install \"mistral-common[audio]\"\n```\n\n### AudioEncoder 接口\n\n`AudioEncoder` 是音频编码器的抽象基类：\n\n```python\nclass AudioEncoder(ABC):\n @abstractmethod\n def encode_audio(self, audio: Audio) -> AudioOutput:\n \"\"\"Encode a single audio object into model input format.\"\"\"\n```\n\n### Audio 数据类\n\n`Audio` 类是音频数据的核心表示：\n\n```python\nclass Audio(MistralBase):\n \"\"\"Audio representation with mel-scale conversion support.\"\"\"\n # 音频采样数据\n samples: np.ndarray\n # 采样率\n sample_rate: int\n # 编码格式\n format: str | None = None\n```\n\n主要功能：\n\n- **音频采样表示**：以 NumPy 数组形式存储音频采样数据\n- **采样率管理**：记录和验证音频采样率\n- **Mel-scale 转换**：支持梅尔频谱转换用于模型处理\n- **格式支持**：支持多种音频编码格式\n\n资料来源：[src/mistral_common/audio.py:1-100]()\n\n### 音频相关特殊 Token\n\n| Token | 标识 | 用途 |\n|-------|------|------|\n| `audio` | `[AUDIO]` | 音频 token 标记 |\n| `begin_audio` | `[BEGIN_AUDIO]` | 音频内容开始 |\n| `transcribe` | `[TRANSCRIBE]` | 转录指令 |\n| `text_to_audio` | `[NEXT_AUDIO_TEXT]` | 文本转语音输出标记 |\n| `audio_to_text` | `[REPEAT_AUDIO_TEXT]` | 语音转文本标记 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py:110-120]()\n\n## Tokenizer 版本与多模态支持\n\n不同版本的 tokenizer 支持不同的多模态功能：\n\n| Tokenizer 版本 | 图像支持 | 音频支持 | 特点 |\n|----------------|----------|----------|------|\n| v1 | ❌ | ❌ | 纯文本 tokenizer |\n| v2 | ❌ | ❌ | 纯文本 tokenizer |\n| v3 | ✅ | ❌ | 引入图像支持 |\n| v7 | ✅ | ✅ | 引入音频支持 |\n| v11 | ✅ | ✅ | 增强的多模态支持 |\n| v13 | ✅ | ✅ | 最新稳定版本 |\n| v15 | ✅ | ✅ | 最新版本 |\n\n**版本断言检查**：\n\n```python\ndef create_tokenizer(tokenizer_filename, image_encoder=None, audio_encoder=None):\n if tokenizer.version == TokenizerVersion.v3:\n assert image_encoder is not None, \"Tokenizer version v3 requires image_encoder\"\n assert audio_encoder is None, \"Tokenizer version v3 does not support audio\"\n elif tokenizer.version == TokenizerVersion.v7:\n # v7+ 支持音频编码器\n ...\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:30-80]()\n\n## ChatCompletionRequest 中的多模态支持\n\n`ChatCompletionRequest` 是多模态请求的入口点，通过 `messages` 字段携带多模态内容：\n\n```python\nclass ChatCompletionRequest(MistralBase):\n \"\"\"Chat completion request with multimodal support.\"\"\"\n \n model: str | None = None\n messages: list[ChatMessageType] # 可包含图像/音频消息\n response_format: ResponseFormat = Field(default_factory=ResponseFormat)\n tools: list[Tool] | None = None\n tool_choice: ToolChoice = ToolChoiceEnum.auto\n truncate_for_context_length: bool = False\n continue_final_message: bool = False\n reasoning_effort: ReasoningEffort | None = None # 推理控制参数\n```\n\n**消息类型层次结构**：\n\n- `UserMessage`：用户消息，可包含文本、图像、音频\n- `AssistantMessage`：助手回复消息\n- `SystemMessage`：系统提示消息\n- `ToolMessage`：工具调用结果消息\n\n## 完整编码流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Validator as MistralRequestValidator\n participant Normalizer as InstructRequestNormalizer\n participant Tokenizer as MistralTokenizer\n participant Encoder as Image/Audio Encoder\n participant Model as 底座模型\n\n Client->>Validator: ChatCompletionRequest (含多模态)\n Validator->>Validator: 验证消息结构\n Validator->>Validator: 验证工具定义\n Validator->>Normalizer: 验证通过的请求\n Normalizer->>Normalizer: 标准化消息格式\n Normalizer->>Tokenizer: InstructRequest\n alt 包含图像\n Tokenizer->>Encoder: 调用 ImageEncoder\n Encoder-->>Tokenizer: ImageOutput\n end\n alt 包含音频\n Tokenizer->>Encoder: 调用 AudioEncoder\n Encoder-->>Tokenizer: AudioOutput\n end\n Tokenizer->>Tokenizer: 生成 token 序列\n Tokenizer-->>Client: Tokenized 对象\n Client->>Model: tokens + images + audios\n```\n\n## 使用示例\n\n### 基本图像编码\n\n```python\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\nfrom mistral_common.image import Image\nimport numpy as np\n\n# 初始化 tokenizer\ntokenizer = MistralTokenizer.from_filename(\"path/to/tokenizer\")\n\n# 准备图像数据\nimage_array = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)\n\n# 创建 Tokenized 结果\ntokenized = tokenizer.encode_images([image_array])\n```\n\n### 音频编码\n\n```python\nfrom mistral_common.audio import Audio\nfrom mistral_common.tokens.tokenizers.audio import AudioEncoder\nimport numpy as np\n\n# 创建音频对象\naudio = Audio(\n samples=np.random.randn(16000), # 1秒音频，16kHz采样率\n sample_rate=16000\n)\n\n# 通过 tokenizer 编码\ntokenized = tokenizer.encode(audio)\n```\n\n### 完整对话请求\n\n```python\nfrom mistral_common.protocol.instruct.request import ChatCompletionRequest\nfrom mistral_common.protocol.instruct.messages import UserMessage\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\n\n# 创建带图像的用户消息\nrequest = ChatCompletionRequest(\n messages=[\n UserMessage(\n content=\"这张图片中有什么?\",\n images=[image_data] # 图像数据\n )\n ],\n model=\"mistral-large-latest\"\n)\n\n# 编码请求\ntokenizer = MistralTokenizer.from_filename(\"path/to/tokenizer\")\ntokenized = tokenizer.encode_chat_completion(request)\n```\n\n## 最佳实践\n\n1. **版本选择**：生产环境建议使用 v13 或 v15 版本，以获得完整的多模态支持\n2. **图像预处理**：在传入 tokenizer 前，确保图像尺寸符合模型要求\n3. **音频采样率**：验证音频采样率与模型预期一致（通常为 16kHz 或 24kHz）\n4. **上下文截断**：设置 `truncate_for_context_length=True` 以处理超长输入\n5. **错误处理**：使用 `InvalidRequestException` 捕获验证错误\n\n## 相关文档\n\n- [工具调用（Tool Calls）](./tool_calls.md)\n- [指导语法（Grammar）](./grammar.md)\n- [请求协议（Request Protocol）](./request_protocol.md)\n- [API 参考文档](https://mistralai.github.io/mistral-common/)\n\n---\n\n\n\n## 指令与填充中间（FIM）协议\n\n### 相关页面\n\n相关主题：[请求验证与标准化](#p6), [语音与转录协议](#p7), [分词器系统详解](#p3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n- [src/mistral_common/protocol/fim/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/fim/request.py)\n- [src/mistral_common/protocol/instruct/messages.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/messages.py)\n- [src/mistral_common/protocol/instruct/chunk.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/chunk.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n- [src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n \n\n# 指令与填充中间（FIM）协议\n\n## 概述\n\nmistral-common 库支持两种主要的协议类型，用于处理不同场景下的请求：\n\n| 协议类型 | 用途 | 请求类 | 主要特性 |\n|---------|------|--------|---------|\n| **Instruct 协议** | 对话式指令任务 | `ChatCompletionRequest` | 支持多轮对话、工具调用、响应格式控制 |\n| **FIM 协议** | 填充中间代码补全 | `FIMRequest` | 支持 prompt/suffix 模式进行代码补全 |\n\nInstruct 协议是用户查询 Instruct 请求的入口点，而 FIM（Fill-in-the-Middle）协议专门用于代码补全场景，模型需要在给定的前缀（prompt）和后缀（suffix）之间生成内容。资料来源：[src/mistral_common/protocol/fim/request.py:1-15]()\n\n---\n\n## FIM 协议\n\n### 概述\n\nFIM（Fill-in-the-Middle）协议是一种用于代码补全的特殊协议。与传统的前缀补全不同，FIM 允许模型在两个已知部分（prefix 和 suffix）之间生成内容，这非常适合以下场景：\n\n- 在函数签名和函数结尾之间补全函数体\n- 在类的开头和结尾之间补全类成员\n- 在代码块的开始和结束标记之间补全内容\n\n### 数据模型\n\n```python\nclass FIMRequest(BaseCompletionRequest):\n \"\"\"填充中间请求模型\"\"\"\n \n prompt: str # 前缀内容\n suffix: str | None = None # 后缀内容（可选）\n```\n\n**字段说明：**\n\n| 字段名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `prompt` | `str` | 是 | 要补全内容的前缀部分 |\n| `suffix` | `str \\| None` | 否 | 要补全内容的后缀部分。如果提供，模型将在 prompt 和 suffix 之间生成文本 |\n\n### 使用示例\n\n```python\nfrom mistral_common.protocol.fim.request import FIMRequest\n\n# 基础用法\nrequest = FIMRequest(prompt='def calculate_sum(a, b):\\n \"\"\"Calculate sum of two numbers\"\"\"\\n return')\n\n# 带后缀的用法\nrequest = FIMRequest(\n prompt='class MyClass:\\n def __init__',\n suffix='\\n\\n# Usage\\nobj = MyClass(10)'\n)\n```\n\n资料来源：[src/mistral_common/protocol/fim/request.py:1-17]()\n\n---\n\n## Instruct 协议\n\n### 概述\n\nInstruct 协议是处理对话式指令任务的核心协议。用户通过 `ChatCompletionRequest` 类发起请求，该请求经过验证、标准化后转换为内部指令格式，再由 tokenizer 编码为 token 序列。\n\n### 架构流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B[ChatCompletionRequest]\n B --> C[MistralRequestValidator 验证]\n C --> D[InstructRequestNormalizer 标准化]\n D --> E[InstructRequest]\n E --> F[InstructTokenizer 编码]\n F --> G[Tokenized 输出]\n \n H[消息列表] --> B\n I[工具定义] --> B\n J[响应格式] --> B\n```\n\n### ChatCompletionRequest 数据模型\n\n```python\nclass ChatCompletionRequest(BaseCompletionRequest[UserMessageType, AssistantMessageType, ToolMessageType, SystemMessageType]):\n \"\"\"Instruct 协议请求模型\"\"\"\n \n model: str | None = None # 模型名称\n messages: list[ChatMessageType] # 消息列表\n response_format: ResponseFormat = Field(...) # 响应格式\n tools: list[Tool] | None = None # 工具定义列表\n tool_choice: ToolChoice = ToolChoiceEnum.auto # 工具选择策略\n truncate_for_context_length: bool = False # 是否截断超长内容\n continue_final_message: bool = False # 继续生成最终消息\n reasoning_effort: ReasoningEffort | None = None # 推理努力程度\n```\n\n**核心字段说明：**\n\n| 字段名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `model` | `str \\| None` | `None` | 模型标识符，用于服务模式验证 |\n| `messages` | `list[ChatMessageType]` | 必填 | 对话消息列表，包含用户、助手、系统消息 |\n| `response_format` | `ResponseFormat` | `text` | 期望的响应格式 |\n| `tools` | `list[Tool] \\| None` | `None` | 可用工具定义列表 |\n| `tool_choice` | `ToolChoice` | `auto` | 工具选择策略（auto/none/required/指定工具） |\n| `truncate_for_context_length` | `bool` | `False` | 上下文超长时是否自动截断 |\n| `continue_final_message` | `bool` | `False` | 是否继续生成未完成的最终消息 |\n| `reasoning_effort` | `ReasoningEffort \\| None` | `None` | 控制模型的推理努力程度 |\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:1-100]()\n\n---\n\n## 消息类型系统\n\n### 消息类型分类\n\n```mermaid\ngraph TD\n A[ChatMessageType] --> B[UserMessage]\n A --> C[AssistantMessage]\n A --> D[SystemMessage]\n A --> E[ToolMessage]\n \n B --> F[文本内容]\n B --> G[多媒体内容]\n C --> H[文本内容]\n C --> I[工具调用]\n D --> J[系统提示]\n```\n\n### 消息基类与子类型\n\n| 消息类型 | 角色标识 | 说明 |\n|---------|---------|------|\n| `UserMessage` | `user` | 用户消息，支持文本和多媒体内容 |\n| `AssistantMessage` | `assistant` | 助手消息，可包含文本和工具调用结果 |\n| `SystemMessage` | `system` | 系统级指令和上下文设置 |\n| `ToolMessage` | `tool` | 工具执行结果返回消息 |\n\n### 消息内容结构\n\n消息内容支持多种格式的块（Chunk）：\n\n```python\n# 文本块\nTextChunk(content=\"Hello, how can I help you?\")\n\n# 图片块\nImageChunk(image=image_data)\n\n# 音频块 \nAudioChunk(audio=audio_data)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/chunk.py:1-30]()\n\n---\n\n## 验证与标准化\n\n### 请求验证流程\n\n```mermaid\ngraph TD\n A[ChatCompletionRequest] --> B{ValidationMode}\n B -->|serving| C[检查 model 字段]\n B -->|test/finetuning| D[跳过 model 检查]\n \n C --> E[validate_messages]\n D --> E\n \n E --> F[validate_tools]\n F --> G[validate_model_settings]\n G --> H[返回验证后的请求]\n```\n\n### 验证模式\n\n| 模式 | 说明 | model 字段要求 |\n|-----|------|---------------|\n| `ValidationMode.serving` | 生产服务模式 | 必须提供 |\n| `ValidationMode.test` | 测试模式 | 可选 |\n| `ValidationMode.finetuning` | 微调模式 | 可选 |\n\n### 消息列表验证规则\n\n1. **结构验证**：检查消息列表的起止位置是否符合预期\n2. **内容验证**：检查每条消息的内容格式和字段完整性\n3. **角色序列验证**：确保消息角色按合法顺序排列\n4. **继续消息验证**：当 `continue_final_message=True` 时，验证最终消息格式\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:1-80]()\n\n### 标准化处理器\n\n标准化器将 `ChatCompletionRequest` 转换为内部 `InstructRequest` 格式：\n\n```python\nclass InstructRequestNormalizer:\n \"\"\"请求标准化器基类\"\"\"\n \n def from_chat_completion_request(self, request: ChatCompletionRequest) -> InstructRequest:\n \"\"\"将聊天补全请求转换为指令请求\"\"\"\n system_prompt = self._aggregate_system_prompts(request.messages)\n messages = self._aggregate_messages(request.messages)\n settings = self.build_settings(request)\n return self._instruct_request_class(\n messages=messages,\n system_prompt=system_prompt,\n available_tools=request.tools,\n continue_final_message=request.continue_final_message,\n settings=settings,\n )\n```\n\n### 版本化标准化器\n\n| 标准化器 | 版本 | 特性 |\n|---------|------|------|\n| `InstructRequestNormalizerV1` | v1 | 基础版本 |\n| `InstructRequestNormalizerV2` | v2 | 支持更多配置 |\n| `InstructRequestNormalizerV7` | v7 | 系统提示在开头，允许工具调用与内容共存 |\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-60]()\n\n---\n\n## 工具调用系统\n\n### 工具定义结构\n\n```python\nclass Tool(MistralBase):\n \"\"\"工具定义\"\"\"\n \n type: ToolTypes = ToolTypes.function\n function: Function\n\nclass Function:\n \"\"\"函数定义\"\"\"\n \n name: str # 函数名（正则: ^[a-zA-Z0-9_-]{1,64}$）\n description: str | None = None # 函数描述\n parameters: dict # JSON Schema 参数定义\n```\n\n### 工具选择策略\n\n| 策略 | 说明 |\n|-----|------|\n| `ToolChoiceEnum.auto` | 模型自动决定是否调用工具 |\n| `ToolChoiceEnum.none` | 禁止调用工具 |\n| `ToolChoiceEnum.required` | 必须调用至少一个工具 |\n| `NamedToolChoice` | 指定调用特定工具 |\n\n### 工具参数 JSON Schema 验证\n\n工具参数必须符合 JSON Schema Draft-7 规范：\n\n```python\n# 有效工具示例\ntool = Tool(\n function=Function(\n name=\"get_current_weather\",\n description=\"获取指定位置的当前天气\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"城市和州，例如 San Francisco, CA\"\n },\n \"unit\": {\"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"]}\n },\n \"required\": [\"location\"]\n }\n )\n)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:1-100]()\n\n---\n\n## Tokenizer 与编码\n\n### Tokenizer 版本支持\n\n| Tokenizer 版本 | 特性 | 图像支持 | 音频支持 |\n|---------------|------|---------|---------|\n| `TokenizerVersion.v1` | 基础 | ❌ | ❌ |\n| `TokenizerVersion.v2` | 扩展 | ❌ | ❌ |\n| `TokenizerVersion.v3` | 图像支持 | ✅ | ❌ |\n| `TokenizerVersion.v7` | 图像+音频 | ✅ | ✅ |\n| `TokenizerVersion.v11` | 高级 | ✅ | ✅ |\n| `TokenizerVersion.v13` | 最新 | ✅ | ✅ |\n\n### Tokenizer 工厂函数\n\n```python\ndef get_tokenizer(\n tokenizer: Tokenizer,\n mode: ValidationMode = ValidationMode.test,\n image_encoder: Any = None,\n audio_encoder: Any = None,\n) -> MistralTokenizer:\n \"\"\"根据 tokenizer 版本创建相应的 MistralTokenizer\"\"\"\n \n validator = get_validator(tokenizer.version, mode=mode)\n \n if tokenizer.version == TokenizerVersion.v1:\n return MistralTokenizer(\n InstructTokenizerV1(tokenizer),\n validator=validator,\n request_normalizer=request_normalizer,\n )\n elif tokenizer.version == TokenizerVersion.v7:\n return MistralTokenizer(\n InstructTokenizerV7(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),\n validator=validator,\n request_normalizer=request_normalizer,\n )\n # ... 其他版本\n```\n\n### Tokenized 输出结构\n\n```python\nclass Tokenized:\n \"\"\"编码后的 token 结果\"\"\"\n \n tokens: list[int] # token ID 列表\n text: str | None = None # 文本表示\n prefix_ids: list[int] | None = None # FIM 前缀 ID\n images: list[np.ndarray] = Field(default_factory=list) # 关联图像\n audios: list[Audio] = Field(default_factory=list) # 关联音频\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-80]()\n\n---\n\n## OpenAI 格式转换\n\n### 请求转换方法\n\n`ChatCompletionRequest` 提供了 `to_openai()` 方法将请求转换为 OpenAI API 格式：\n\n```python\ndef to_openai(self, **kwargs: Any) -> dict[str, Any]:\n \"\"\"将请求转换为 OpenAI 格式\"\"\"\n```\n\n**转换示例：**\n\n```python\nfrom mistral_common.protocol.instruct.messages import UserMessage\n\nrequest = ChatCompletionRequest(\n messages=[UserMessage(content=\"Hello, how are you?\")],\n temperature=0.15\n)\n\n# 转换为 OpenAI 格式\nopenai_request = request.to_openai(stream=True)\n# 输出:\n# {\n# 'temperature': 0.15,\n# 'top_p': 1.0,\n# 'response_format': {'type': 'text'},\n# 'continue_final_message': False,\n# 'messages': [{'role': 'user', 'content': 'Hello, how are you?'}],\n# 'tool_choice': 'auto',\n# 'stream': True\n# }\n```\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:80-150]()\n\n---\n\n## 特殊控制参数\n\n### continue_final_message 参数\n\n此参数控制模型是否继续生成未完成的最终消息：\n\n| 值 | 行为 |\n|---|------|\n| `False`（默认） | 模型正常生成完整响应 |\n| `True` | 模型继续之前的消息内容进行生成 |\n\n### reasoning_effort 参数\n\n控制模型的推理努力程度：\n\n```python\nclass ReasoningEffort(str, Enum):\n \"\"\"推理努力程度枚举\"\"\"\n \n low = \"low\" # 低推理努力\n medium = \"medium\" # 中等推理努力\n high = \"high\" # 高推理努力\n```\n\n### truncate_for_context_length 参数\n\n| 值 | 行为 |\n|---|------|\n| `False`（默认） | 上下文超长时抛出异常 |\n| `True` | 自动截断消息以适应上下文长度 |\n\n---\n\n## 完整使用流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Validator as MistralRequestValidator\n participant Normalizer as InstructRequestNormalizer\n participant Tokenizer as InstructTokenizer\n participant Model as 推理模型\n\n Client->>Validator: 提交 ChatCompletionRequest\n Validator->>Validator: 验证消息格式\n Validator->>Validator: 验证工具定义\n Validator->>Validator: 验证模型设置\n Validator-->>Client: 返回验证后的请求\n \n Client->>Normalizer: 标准化请求\n Normalizer->>Normalizer: 聚合系统提示\n Normalizer->>Normalizer: 聚合消息\n Normalizer-->>Client: 返回 InstructRequest\n \n Client->>Tokenizer: 编码为 tokens\n Tokenizer->>Model: 发送 token 序列\n Model-->>Tokenizer: 返回生成的 token\n Tokenizer-->>Client: 返回 Tokenized 结果\n```\n\n**完整代码示例：**\n\n```python\nfrom mistral_common.protocol.instruct.request import ChatCompletionRequest\nfrom mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage\nfrom mistral_common.protocol.instruct.tool_calls import Tool, ToolTypes, Function\nfrom mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode\n\n# 1. 创建请求\nrequest = ChatCompletionRequest(\n model=\"mistral-large-latest\",\n messages=[\n UserMessage(content=\"What is the weather in Paris?\"),\n AssistantMessage(content=\"I'll check that for you.\"),\n ],\n tools=[\n Tool(\n type=ToolTypes.function,\n function=Function(\n name=\"get_weather\",\n description=\"Get weather for a location\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\"type\": \"string\"}\n },\n \"required\": [\"location\"]\n }\n )\n )\n ],\n tool_choice=\"auto\",\n truncate_for_context_length=True,\n)\n\n# 2. 验证请求\nvalidator = MistralRequestValidator(mode=ValidationMode.serving)\nvalidated_request = validator.validate_request(request)\n\n# 3. 标准化请求\nnormalizer = InstructRequestNormalizer.normalizer()\ninstruct_request = normalizer.from_chat_completion_request(validated_request)\n\n# 4. 编码请求\n# tokenized = tokenizer.encode_instruct(instruct_request)\n```\n\n---\n\n## 错误处理\n\n### 自定义异常类型\n\n| 异常类型 | 用途 |\n|---------|------|\n| `InvalidRequestException` | 请求参数验证失败 |\n| `InvalidToolSchemaException` | 工具参数 schema 无效 |\n| `InvalidToolException` | 工具定义无效 |\n| `InvalidMessageException` | 消息格式或内容无效 |\n\n### 常见验证错误\n\n1. **模型名称缺失**：在 serving 模式下必须提供 `model` 参数\n2. **工具 schema 无效**：工具参数不符合 JSON Schema Draft-7 规范\n3. **工具名称无效**：函数名不符合正则 `^[a-zA-Z0-9_-]{1,64}$`\n4. **消息序列错误**：消息顺序不符合协议规定\n\n---\n\n## 总结\n\nmistral-common 库的指令与填充中间协议为 LLM 交互提供了两个互补的接口：\n\n1. **Instruct 协议** (`ChatCompletionRequest`)：适合对话式、工具调用和多轮交互场景，提供完整的验证和标准化流程。\n\n2. **FIM 协议** (`FIMRequest`)：专为代码补全设计，通过 prompt/suffix 模式支持在代码任意位置插入内容。\n\n两个协议都遵循相同的验证-标准化-编码流程，确保请求的正确性和一致性。\n\n---\n\n\n\n## 请求验证与标准化\n\n### 相关页面\n\n相关主题：[指令与填充中间（FIM）协议](#p5), [语音与转录协议](#p7), [项目架构总览](#p2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n- [src/mistral_common/protocol/instruct/converters.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/converters.py)\n- [src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)\n- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n \n\n# 请求验证与标准化\n\n## 概述\n\n请求验证与标准化是 mistral-common 库中处理用户输入请求的核心模块。该模块负责在将用户请求传递给模型之前，对其进行结构验证、内容校验和格式转换。mistral-common 通过 `MistralRequestValidator` 和 `InstructRequestNormalizer` 两个核心类来实现这一功能，确保请求符合 Mistral 模型的输入规范，同时为不同的 tokenizer 版本提供统一的支持。\n\n该模块在整个处理流程中处于关键位置，属于预处理阶段的前置验证环节。验证失败时抛出自定义异常（如 `InvalidRequestException`、`InvalidToolSchemaException` 等），确保错误信息能够被上游调用方正确捕获和处理。资料来源：[src/mistral_common/protocol/instruct/validator.py:1-50]()\n\n## 核心组件\n\n### MistralRequestValidator\n\n`MistralRequestValidator` 是一个泛型类，负责验证 `ChatCompletionRequest` 的结构和内容。它支持三种验证模式，通过 `ValidationMode` 枚举进行配置。资料来源：[src/mistral_common/protocol/instruct/validator.py:19-22]()\n\n| 验证模式 | 用途 | 特定行为 |\n|---------|------|---------|\n| `serving` | 服务部署模式 | 要求必须提供 model 参数 |\n| `finetuning` | 微调模式 | 允许特定的微调参数组合 |\n| `test` | 测试/默认模式 | 标准验证规则 |\n\n### InstructRequestNormalizer\n\n`InstructRequestNormalizer` 负责将标准化的 `ChatCompletionRequest` 转换为 `InstructRequest` 格式。该类处理系统提示的聚合、消息的重组以及模型设置的提取。资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-100]()\n\n## 请求验证流程\n\n### 验证架构\n\n```mermaid\ngraph TD\n A[ChatCompletionRequest] --> B[MistralRequestValidator]\n B --> C{验证模式}\n C -->|serving| D[检查 model 参数]\n C -->|其他| E[跳过 model 检查]\n D --> F[validate_messages]\n E --> F\n F --> G[validate_message_list_structure]\n F --> H[validate_message_list_content]\n G --> I[_validate_tools]\n H --> I\n I --> J[validate_model_settings]\n J --> K[返回 validated_request]\n I -.->|工具Schema无效| L[InvalidToolSchemaException]\n G -.->|结构错误| M[InvalidRequestException]\n```\n\n### 验证步骤详解\n\n#### 1. 模型参数验证\n\n在 `serving` 模式下，系统会检查请求是否包含 `model` 参数。如果缺失，将抛出 `InvalidRequestException`，提示\"Model name parameter is required for serving mode\"。资料来源：[src/mistral_common/protocol/instruct/validator.py:67-69]()\n\n```python\nif self._mode == ValidationMode.serving:\n if request.model is None:\n raise InvalidRequestException(\"Model name parameter is required for serving mode\")\n```\n\n#### 2. 消息列表结构验证\n\n`_validate_message_list_structure` 方法检查消息序列的逻辑完整性：\n\n- 确保消息以 UserMessage 开头\n- 验证 `continue_final_message` 标志与最后一条消息类型的兼容性\n- 检查角色交替的合法性（User → Assistant → User → ...）\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:35-42]()\n\n#### 3. 消息内容验证\n\n`_validate_message_list_content` 方法验证消息内容的有效性：\n\n- 检查消息内容非空\n- 验证工具调用的格式正确性\n- 确保角色与内容的逻辑一致性\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:43-44]()\n\n#### 4. 工具定义验证\n\n工具验证是该模块的重要组成部分，包含以下检查：资料来源：[src/mistral_common/protocol/instruct/validator.py:55-57]()\n\n| 验证项 | 验证方法 | 异常类型 |\n|-------|---------|---------|\n| 函数 Schema 有效性 | Draft7Validator.check_schema | InvalidToolSchemaException |\n| 函数名称格式 | 正则表达式 `^[a-zA-Z0-9_-]{1,64}$` | InvalidToolException |\n| 参数定义完整性 | 检查 required 字段与参数存在性 | InvalidToolSchemaException |\n\n```python\ndef _validate_function(self, function: Function) -> None:\n Draft7Validator.check_schema(function.parameters)\n if not re.match(r\"^[a-zA-Z0-9_-]{1,64}$\", function.name):\n raise InvalidToolException(...)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:85-96]()\n\n## 请求标准化流程\n\n### 标准化架构\n\n```mermaid\ngraph LR\n A[ChatCompletionRequest] --> B[InstructRequestNormalizer]\n B --> C[_aggregate_system_prompts]\n B --> D[_aggregate_messages]\n B --> E[build_settings]\n C --> F[system_prompt]\n D --> G[messages]\n E --> H[settings]\n F --> I[InstructRequest]\n G --> I\n H --> I\n```\n\n### 标准化器版本\n\nmistral-common 支持多个标准化器版本，每个版本针对特定的 tokenizer 版本进行了优化：资料来源：[src/mistral_common/protocol/instruct/normalize.py:80-100]()\n\n| 标准化器 | 系统提示位置 | 工具调用+内容支持 |\n|---------|------------|-----------------|\n| `InstructRequestNormalizer` | 系统消息独立 | 不支持 |\n| `InstructRequestNormalizerV7` | 消息开始处 | 支持 |\n\n```python\nclass InstructRequestNormalizerV7(InstructRequestNormalizer):\n _system_prompt_in_begin: bool = True\n _allow_tool_call_and_content: bool = True\n```\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py:84-87]()\n\n### 消息聚合\n\n#### 系统提示聚合\n\n系统提示通过 `_aggregate_system_prompts` 方法从消息列表中提取并合并。当存在多个系统消息时，它们会被按顺序拼接为一个统一的系统提示。资料来源：[src/mistral_common/protocol/instruct/normalize.py:40-60]()\n\n#### 消息重组\n\n`_aggregate_messages` 方法移除系统消息，返回仅包含用户消息和助手消息的列表。标准化过程会验证模型设置是否与当前标准化器兼容，不支持的设置将抛出 `InvalidRequestException`。资料来源：[src/mistral_common/protocol/instruct/normalize.py:62-76]()\n\n## 工具调用系统\n\n### ToolChoice 枚举\n\n工具选择策略通过 `ToolChoice` 类型别名定义，支持多种模式：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:20-30]()\n\n| 枚举值 | 描述 | 备注 |\n|-------|------|------|\n| `auto` | 模型自动决定是否调用工具 | 默认值 |\n| `none` | 禁用工具调用 | 不使用任何工具 |\n| `any` | 至少调用一个工具 | 已废弃，使用 `required` |\n| `required` | 模型必须调用至少一个工具 | 替代 `any` |\n\n### NamedToolChoice\n\n除了枚举选择外，还支持强制指定特定函数调用：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:32-46]()\n\n```python\nclass NamedToolChoice(MistralBase):\n type: ToolTypes = ToolTypes.function\n function: FunctionName\n```\n\n### 工具定义\n\n`Tool` 类定义了可用的工具，包含函数名称、描述和参数模式：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:48-70]()\n\n| 属性 | 类型 | 描述 |\n|-----|------|------|\n| `type` | ToolTypes | 工具类型（当前仅支持 function） |\n| `function` | Function | 函数定义对象 |\n\n## 请求转换器\n\n### OpenAI 格式转换\n\n`ChatCompletionRequest` 提供了 `to_openai()` 方法用于转换为 OpenAI 兼容格式。该方法处理消息格式转换、工具定义重映射以及额外参数的追加。资料来源：[src/mistral_common/protocol/instruct/request.py:60-90]()\n\n```python\ndef to_openai(self, **kwargs: Any) -> dict[str, Any]:\n r\"\"\"Convert the request messages and tools into the OpenAI format.\"\"\"\n```\n\n### 转换示例\n\n```python\nrequest = ChatCompletionRequest(\n messages=[UserMessage(content=\"Hello, how are you?\")],\n temperature=0.15\n)\nrequest.to_openai(stream=True)\n# 返回: {'temperature': 0.15, 'top_p': 1.0, 'response_format': {...}, ...}\n```\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:70-75]()\n\n## 请求数据结构\n\n### ChatCompletionRequest\n\n`ChatCompletionRequest` 是用户请求的入口数据结构：资料来源：[src/mistral_common/protocol/instruct/request.py:20-40]()\n\n| 字段 | 类型 | 默认值 | 描述 |\n|-----|------|-------|------|\n| `model` | str \\| None | None | 模型名称（serving 模式必需） |\n| `messages` | list[ChatMessageType] | - | 消息列表 |\n| `response_format` | ResponseFormat | Field(default_factory=ResponseFormat) | 响应格式 |\n| `tools` | list[Tool] \\| None | None | 可用工具列表 |\n| `tool_choice` | ToolChoice | ToolChoiceEnum.auto | 工具选择策略 |\n| `truncate_for_context_length` | bool | False | 是否截断以适应上下文长度 |\n| `continue_final_message` | bool | False | 继续生成最后一条消息 |\n| `reasoning_effort` | ReasoningEffort \\| None | None | 推理努力程度 |\n\n### InstructRequest\n\n标准化后的 `InstructRequest` 包含处理后的消息和系统提示：资料来源：[src/mistral_common/protocol/instruct/normalize.py:15-25]()\n\n| 属性 | 类型 | 描述 |\n|-----|------|------|\n| `messages` | list[UATS] | 处理后的消息列表 |\n| `system_prompt` | str \\| None | 聚合后的系统提示 |\n| `available_tools` | list[Tool] \\| None | 可用工具 |\n| `continue_final_message` | bool | 是否继续最后消息 |\n| `settings` | ModelSettings | 模型设置 |\n\n## 与 Tokenizer 的集成\n\n### 验证流程集成\n\n`MistralTokenizer` 在编码请求时首先调用验证器：资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()\n\n```mermaid\nsequenceDiagram\n participant User as 用户请求\n participant Validator as MistralRequestValidator\n participant Normalizer as InstructRequestNormalizer\n participant Encoder as InstructTokenizer\n \n User->>Validator: ChatCompletionRequest\n Validator->>Validator: validate_request()\n Validator-->>Normalizer: validated_request\n Normalizer->>Normalizer: from_chat_completion_request()\n Normalizer-->>Encoder: InstructRequest\n Encoder->>Encoder: encode()\n```\n\n### 版本适配\n\n不同的 tokenizer 版本使用不同的标准化器和验证器组合：资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:20-60]()\n\n| Tokenizer 版本 | InstructTokenizer | 验证器 | 标准化器 |\n|---------------|-------------------|-------|---------|\n| v1 | InstructTokenizerV1 | v1 验证器 | InstructRequestNormalizer |\n| v2 | InstructTokenizerV2 | v2 验证器 | InstructRequestNormalizer |\n| v3 | InstructTokenizerV3 | v3 验证器 | InstructRequestNormalizer |\n| v7 | InstructTokenizerV7 | v7 验证器 | InstructRequestNormalizerV7 |\n| v11+ | InstructTokenizerV11+ | v11 验证器 | InstructRequestNormalizerV7 |\n\n## 异常处理\n\n### 异常类型层次\n\n| 异常类 | 基类 | 触发场景 |\n|-------|------|---------|\n| `InvalidRequestException` | Exception | 请求结构或内容验证失败 |\n| `InvalidToolSchemaException` | Exception | 工具 Schema 格式错误 |\n| `InvalidToolException` | Exception | 工具名称或定义无效 |\n\n所有自定义异常定义在 `mistral_common.exceptions` 模块中，确保错误处理的一致性。资料来源：[src/mistral_common/protocol/instruct/validator.py:80-95]()\n\n## 使用示例\n\n### 基本验证流程\n\n```python\nfrom mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage\nfrom mistral_common.protocol.instruct.request import ChatCompletionRequest\nfrom mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode\n\n# 创建验证器\nvalidator = MistralRequestValidator(mode=ValidationMode.test)\n\n# 创建请求\nrequest = ChatCompletionRequest(\n messages=[\n UserMessage(content=\"Hello how are you?\"),\n AssistantMessage(content=\"I'm doing great!\")\n ]\n)\n\n# 验证请求\nvalidated_request = validator.validate_request(request)\n```\n\n### 带工具调用的请求\n\n```python\nfrom mistral_common.protocol.instruct.tool_calls import ToolTypes, Function, Tool\n\ntool = Tool(\n function=Function(\n name=\"get_current_weather\",\n description=\"Get the current weather in a given location\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\"type\": \"string\", \"description\": \"City name\"}\n },\n \"required\": [\"location\"]\n }\n )\n)\n\nrequest = ChatCompletionRequest(\n messages=[UserMessage(content=\"What's the weather in Paris?\")],\n tools=[tool],\n tool_choice=ToolChoiceEnum.auto\n)\n\nvalidated_request = validator.validate_request(request)\n```\n\n## 最佳实践\n\n### 1. 验证模式选择\n\n- **开发/测试环境**：使用 `ValidationMode.test`，避免强制要求 model 参数\n- **生产环境**：使用 `ValidationMode.serving`，确保所有请求包含模型标识\n\n### 2. 工具定义规范\n\n- 函数名称仅包含字母、数字、下划线和连字符，长度不超过 64 字符\n- 使用 Draft7 JSON Schema 定义参数\n- 明确标记必需参数（required 字段）\n\n### 3. 错误处理\n\n```python\ntry:\n validated_request = validator.validate_request(request)\nexcept InvalidRequestException as e:\n logger.error(f\"Invalid request: {e}\")\nexcept InvalidToolSchemaException as e:\n logger.error(f\"Invalid tool schema: {e}\")\n```\n\n### 4. 消息序列设计\n\n- 确保以 UserMessage 开始对话\n- 交替的角色顺序：User → Assistant → User → Assistant\n- 使用 `continue_final_message=True` 时，最后一条应为 AssistantMessage\n\n## 相关模块索引\n\n| 模块 | 文件路径 | 职责 |\n|-----|---------|------|\n| 验证器 | `src/mistral_common/protocol/instruct/validator.py` | 请求结构与内容验证 |\n| 标准化器 | `src/mistral_common/protocol/instruct/normalize.py` | 请求格式转换 |\n| 转换器 | `src/mistral_common/protocol/instruct/converters.py` | 格式转换辅助 |\n| 工具调用 | `src/mistral_common/protocol/instruct/tool_calls.py` | 工具定义与选择 |\n| 请求定义 | `src/mistral_common/protocol/instruct/request.py` | 请求数据结构 |\n| Tokenizer | `src/mistral_common/tokens/tokenizers/mistral.py` | 验证与编码集成 |\n\n---\n\n\n\n## 语音与转录协议\n\n### 相关页面\n\n相关主题：[指令与填充中间（FIM）协议](#p5), [请求验证与标准化](#p6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/protocol/transcription/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/transcription/request.py)\n- [src/mistral_common/tokens/tokenizers/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/audio.py)\n- [src/mistral_common/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/audio.py)\n- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n \n\n# 语音与转录协议\n\n## 概述\n\n语音与转录协议是 mistral-common 库中处理音频相关请求的核心组件。该协议定义了音频处理的标准化接口，支持语音转文本（Transcription）和文本转语音（Text-to-Speech）等多模态交互场景。\n\nmistral-common 通过协议层与分词器层的协作，将音频数据与文本数据统一处理为模型可接受的 token 序列。音频处理功能主要在 **TokenizerVersion.v7** 及以上版本中可用，集成于 `InstructTokenizerV7` 和 `InstructTokenizerV11` 等分词器实现中。 资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-100]()\n\n## 协议架构\n\n### 模块组织结构\n\n语音与转录协议相关代码分布在以下核心模块中：\n\n| 模块路径 | 功能描述 |\n|---------|---------|\n| `src/mistral_common/protocol/transcription/request.py` | 转录请求定义 |\n| `src/mistral_common/tokens/tokenizers/audio.py` | 音频分词器实现 |\n| `src/mistral_common/audio.py` | 音频处理工具类 |\n| `src/mistral_common/tokens/tokenizers/base.py` | 基础分词器抽象与特殊token定义 |\n\n### 协议层次关系\n\n```mermaid\ngraph TD\n A[用户请求] --> B[Protocol Layer 协议层]\n B --> C[TranscriptionRequest 转录请求]\n B --> D[SpeechRequest 语音请求]\n C --> E[Tokenizer Layer 分词器层]\n D --> E\n E --> F[InstructTokenizerV7/V11]\n E --> G[Audio Encoder 音频编码器]\n F --> H[Tokenized Output]\n G --> H\n```\n\n## 转录请求协议\n\n### TranscriptionRequest 数据模型\n\n`TranscriptionRequest` 是转录任务的入口请求类型，继承自 `BaseCompletionRequest`。该请求模型封装了音频文件路径或音频数据以及转录相关的配置参数。 资料来源：[src/mistral_common/protocol/transcription/request.py:1-30]()\n\n```python\nclass TranscriptionRequest(BaseCompletionRequest):\n r\"\"\"A valid transcription request to be tokenized.\"\"\"\n \n audio: Audio # 音频数据\n language: str | None = None # 可选的语言参数\n```\n\n### 请求字段说明\n\n| 字段名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| `audio` | `Audio` | 是 | 待转录的音频数据 |\n| `language` | `str \\| None` | 否 | 音频语言提示，用于提高转录准确性 |\n| 继承字段 | - | - | 继承自 `BaseCompletionRequest` 的基础字段 |\n\n## 音频处理机制\n\n### Audio 类\n\n`Audio` 类是音频数据的核心抽象，提供音频的下载、加载和序列化功能。 资料来源：[src/mistral_common/audio.py:1-50]()\n\n```python\nclass Audio:\n r\"\"\"音频处理工具类\n \n Attributes:\n url: 音频资源的远程URL\n audio_bytes: 音频二进制数据\n \"\"\"\n```\n\n### 音频分词器\n\n`AudioTokenizer` 负责将音频数据转换为模型可处理的 token 序列。该分词器集成在 `InstructTokenizerV7` 及更高版本中。 资料来源：[src/mistral_common/tokens/tokenizers/audio.py:1-50]()\n\n#### 核心功能\n\n| 功能 | 描述 |\n|-----|------|\n| 音频编码 | 将音频数据编码为 token 序列 |\n| 梅尔频谱转换 | 支持 mel-scale 音频特征提取 |\n| 多格式支持 | 处理多种音频编码格式 |\n\n## 特殊 Token 定义\n\n在音频处理流程中，系统定义了一系列专用特殊 token，用于标识音频内容的边界和类型。这些 token 在 `SpecialTokens` 枚举中统一管理。 资料来源：[src/mistral_common/tokens/tokenizers/base.py:1-80]()\n\n| Token 名称 | 值 | 用途 |\n|-----------|-----|------|\n| `audio` | `[AUDIO]` | 音频内容标识 |\n| `begin_audio` | `[BEGIN_AUDIO]` | 音频内容开始标记 |\n| `transcribe` | `[TRANSCRIBE]` | 转录指令标识 |\n| `audio_to_text` | `[REPEAT_AUDIO_TEXT]` | 音频转文本标识 |\n| `text_to_audio` | `[NEXT_AUDIO_TEXT]` | 文本转音频标识 |\n\n### Token 序列化格式\n\n```\n[AUDIO] + [BEGIN_AUDIO] + <音频编码数据> + [TRANSCRIBE] + [REPEAT_AUDIO_TEXT] + <转录文本>\n```\n\n## 分词器版本与音频支持\n\n音频处理能力与分词器版本紧密关联，不同版本支持不同程度的音频功能。\n\n| 分词器版本 | 音频支持 | 图像支持 | 说明 |\n|-----------|---------|---------|------|\n| `v1` | ❌ | ❌ | 基础文本分词器 |\n| `v2` | ❌ | ❌ | 基础文本分词器 |\n| `v3` | ❌ | ✅ | 仅支持图像 |\n| `v7` | ✅ | ✅ | 首次引入音频支持 |\n| `v11` | ✅ | ✅ | 增强的音视频支持 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-100]()\n\n### 版本检测与初始化\n\n```python\n# 音频编码器在 v7 及以上版本可用\nif tokenizer.version >= TokenizerVersion.v7:\n audio_encoder = AudioEncoder(...)\n \n# 创建支持音频的分词器\nreturn MistralTokenizer(\n InstructTokenizerV7(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),\n validator=validator,\n request_normalizer=request_normalizer,\n)\n```\n\n## 请求处理流程\n\n### 转录请求完整流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant P as Protocol Layer\n participant T as Tokenizer\n participant A as Audio Encoder\n \n U->>P: TranscriptionRequest(audio_url)\n P->>P: 下载并加载音频数据\n P->>T: 调用 encode 方法\n T->>A: 音频特征提取\n A-->>T: 音频 token 序列\n T->>T: 合并特殊 token\n T-->>U: Tokenized 对象\n```\n\n### 验证与规范化\n\n转录请求同样需要经过验证和规范化处理：\n\n1. **消息结构验证**：确保请求格式符合协议规范\n2. **音频数据验证**：检查音频数据的完整性和有效性\n3. **语言参数验证**：验证语言代码的有效性\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:1-100]()\n\n## 配置与部署\n\n### 依赖安装\n\n音频功能需要安装相应的可选依赖：\n\n```bash\n# 安装音频支持\npip install \"mistral-common[audio]\"\n\n# 安装完整依赖（包括音频）\npip install \"mistral-common[image,audio,hf-hub,sentencepiece,server]\"\n```\n\n### API 服务配置\n\n在 FastAPI 应用中启用音频处理功能：\n\n```python\nfrom mistral_common.experimental.app import create_app\nfrom mistral_common.protocol.instruct.validator import ValidationMode\n\napp = create_app(\n tokenizer=\"path/to/tokenizer\",\n validation_mode=ValidationMode.serving,\n engine_url=\"http://127.0.0.1:8080\",\n engine_backend=\"llama_cpp\",\n timeout=60,\n)\n```\n\n资料来源：[src/mistral_common/experimental/app/main.py:1-80]()\n\n## 最佳实践\n\n### 音频数据准备\n\n1. **格式选择**：推荐使用 MP3、WAV 或 OGG 格式\n2. **采样率**：保持原始采样率，避免不必要的重采样\n3. **语言提示**：提供准确的 `language` 参数可提高转录准确度\n\n### 错误处理\n\n| 错误类型 | 处理建议 |\n|---------|---------|\n| 音频加载失败 | 检查 URL 可访问性和格式支持 |\n| 分词器版本不匹配 | 确保使用 v7+ 分词器 |\n| 音频过长 | 根据模型上下文窗口进行分段处理 |\n\n## 相关文档\n\n- [Instruct 协议](./instruct_protocol.md) - 指令请求处理\n- [工具调用协议](./tool_calls.md) - 工具调用定义\n- [Tekken 分词器](./tekken_tokenizer.md) - 分词器实现细节\n- [Grammar Factory](./grammar_factory.md) - 语法生成器\n\n---\n\n*本页面内容基于 mistral-common 仓库源码生成，最后更新时间跟随仓库最新提交。*\n\n---\n\n\n\n## Grammar Factory 与 LLM Guidance\n\n### 相关页面\n\n相关主题：[请求验证与标准化](#p6), [项目架构总览](#p2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/guidance/grammar_factory.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/grammar_factory.py)\n- [src/mistral_common/guidance/tokenizer.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/tokenizer.py)\n- [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)\n- [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)\n- [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)\n \n\n# Grammar Factory 与 LLM Guidance\n\n## 概述\n\nGrammar Factory 是 mistral-common 库中用于生成结构化输出语法的核心组件。它通过结合 **LLGuidance** 库和 **Jinja2** 模板引擎，将 LLM 的输出约束为符合特定语法规则的结构化格式，支持工具调用、JSON Schema 验证以及思考模式（Thinking Mode）。\n\n该模块的主要功能包括：\n\n- **语法生成**：基于 Jinja2 模板动态生成 Lark 语法规则\n- **特殊 token 处理**：将 Tekken 分词器的特殊 token 映射为语法语法\n- **多模式支持**：支持基础模式、思考模式（特殊 token）和纯文本思考模式\n- **工具调用约束**：支持 function calling 的语法约束和并行调用\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:1-50]()\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[用户请求] --> B[ChatCompletionRequest]\n B --> C[GrammarFactory]\n C --> D{推理模式判断}\n D -->|非思考模式| E[base_grammar.lark.jinja]\n D -->|v13+ 思考模式| F[think_grammar.lark.jinja]\n D -->|v13 之前思考模式| G[plain_text_think_grammar.lark.jinja]\n E --> H[Jinja2 渲染]\n F --> H\n G --> H\n H --> I[Lark 语法字符串]\n I --> J[llguidance 引擎]\n J --> K[结构化输出]\n \n C --> L[TekkenTokenizer]\n L --> M[特殊Token映射]\n M --> H\n```\n\n### 核心依赖\n\n| 依赖库 | 用途 |\n|--------|------|\n| llguidance | 语法引导的 LLM 推理引擎 |\n| jinja2 | Lark 语法模板渲染 |\n| lark | 语法解析 |\n\n## GrammarFactory 类\n\n### 初始化与验证\n\n```python\nclass GrammarFactory:\n def __init__(self, tokenizer: MistralTokenizer) -> None:\n \"\"\"初始化语法工厂\"\"\"\n assert_llguidance_installed()\n assert_jinja2_installed()\n self._tokenizer = tokenizer.instruct_tokenizer.tokenizer\n \n if not self.is_supported(tokenizer):\n raise ValueError(\n f\"Guidance requires a Tekken tokenizer with version >= v11, \"\n f\"got {type(self._tokenizer).__name__} {self._tokenizer.version.value}\"\n )\n```\n\n**关键约束**：\n\n- 仅支持 **Tekken 分词器**\n- 分词器版本必须 **≥ v11**\n- 支持的版本包括 v11 和 v13\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:35-55]()\n\n### 特殊 Token 映射\n\nGrammarFactory 构建从特殊 token 名称到 Lark 语法语法的映射：\n\n```python\ndef _build_special_token_map(self) -> dict[str, str]:\n \"\"\"构建特殊 token 名称到语法语法的映射\"\"\"\n return {\n self._tokenizer.id_to_piece(i): f\"<[{i}]>\" \n for i in range(self._tokenizer.num_special_tokens)\n }\n\ndef _special_token_lark(self, token_name: str) -> str:\n \"\"\"将特殊 token 名称转换为 lark 语法语法\"\"\"\n assert token_name in self._special_token_map\n return self._special_token_map[token_name]\n\ndef _get_optional_special_token_lark(self, token_name: str) -> str | None:\n \"\"\"返回特殊 token 的 lark 语法语法，若不存在则返回 None\"\"\"\n return self._special_token_map.get(token_name)\n```\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:57-70]()\n\n### 版本支持检查\n\n```python\n@staticmethod\ndef is_supported(tokenizer: MistralTokenizer) -> bool:\n \"\"\"检查分词器是否支持 grammar guidance\"\"\"\n return (\n isinstance(tokenizer.instruct_tokenizer.tokenizer, TekkenTokenizer)\n and tokenizer.instruct_tokenizer.tokenizer.version >= TokenizerVersion.v11\n )\n```\n\n## 语法变体\n\n系统支持三种语法变体，通过 `_GrammarVariant` 枚举定义：\n\n```python\nclass _GrammarVariant(str, Enum):\n base = \"base\" # 基础模式\n plain_think = \"plain_think\" # 纯文本思考模式\n think = \"think\" # 思考模式（特殊 token）\n```\n\n### 变体选择逻辑\n\n```mermaid\ngraph TD\n A[开始] --> B{是否启用推理?}\n B -->|否| C[base 变体]\n B -->|是| D{分词器版本 >= v13?}\n D -->|是| E[think 变体]\n D -->|否| F[plain_think 变体]\n```\n\n| 推理模式 | 分词器版本 | 选用变体 |\n|----------|-----------|----------|\n| 关闭 | 任意 | base |\n| 开启 | ≥ v13 | think |\n| 开启 | < v13 | plain_think |\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:120-135]()\n\n## Lark 语法模板系统\n\n### 模板文件\n\n| 模板文件 | 用途 |\n|----------|------|\n| `base_grammar.lark.jinja` | 基础模式的标准语法 |\n| `think_grammar.lark.jinja` | 支持特殊 token 思考标签的语法 |\n| `plain_text_think_grammar.lark.jinja` | 纯文本格式的思考语法 |\n\n### 模板渲染参数\n\n`_cached_get_lark_from_jinja` 函数接收以下参数生成 Lark 语法：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `template` | str | Jinja2 模板字符串 |\n| `mode` | str | 输出模式（text/JSON） |\n| `fcall` | str | 函数调用格式 |\n| `json_schema_str` | str \\| None | JSON Schema 字符串 |\n| `parallel_tool_calls` | bool | 是否支持并行工具调用 |\n| `json_only` | bool | 是否仅输出 JSON |\n| `think_with_json` | bool | 思考部分是否使用 JSON 格式 |\n| `begin_think_token` | str \\| None | 思考开始 token |\n| `end_think_token` | str \\| None | 思考结束 token |\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:140-165]()\n\n### 缓存机制\n\n系统使用 `@lru_cache` 装饰器缓存模板和语法结果，避免重复渲染：\n\n```python\n@lru_cache()\ndef _cached_get_jinja_template(\n tokenizer_version: TokenizerVersion, \n reasoning: bool\n) -> str:\n \"\"\"缓存获取 Jinja 模板\"\"\"\n if not reasoning:\n jinja_key = _GrammarVariant.base\n elif tokenizer_version < TokenizerVersion.v13:\n jinja_key = _GrammarVariant.plain_think\n else:\n jinja_key = _GrammarVariant.think\n \n return JINJA_PATHS[jinja_key].read_text(encoding=\"utf-8\")\n```\n\n## LLM Guidance Tokenizer 适配器\n\n### TekkenTokenizerAdapter\n\n位于 `src/mistral_common/guidance/tokenizer.py` 的适配器将 Tekken 分词器转换为 llguidance 所需格式：\n\n```python\nfrom mistral_common.guidance.tokenizer import from_mistral_tokenizer\n\n# 将 Mistral 分词器转换为 llguidance 格式\nadapter = from_mistral_tokenizer(mistral_tokenizer)\n```\n\n资料来源：[src/mistral_common/guidance/tokenizer.py]()\n\n## 使用流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant GF as GrammarFactory\n participant TK as TekkenTokenizer\n participant JN as Jinja2\n participant LK as Lark 语法\n participant LG as LLGuidance\n\n U->>GF: 创建 GrammarFactory 实例\n GF->>TK: 获取 instruct_tokenizer\n TK-->>GF: 返回 TekkenTokenizer\n GF->>GF: 构建特殊 token 映射\n \n U->>GF: 调用 get_lark_grammar()\n GF->>GF: 判断推理模式和版本\n GF->>JN: 加载并渲染 Jinja 模板\n JN-->>GF: 返回 Lark 语法字符串\n GF-->>U: 返回 Lark 语法\n \n U->>LG: 使用 Lark 语法进行推理\n LG-->>U: 返回结构化输出\n```\n\n## API 参考\n\n### GrammarFactory 主要方法\n\n| 方法 | 说明 |\n|------|------|\n| `is_supported(tokenizer)` | 检查分词器是否支持 |\n| `get_lark_grammar(...)` | 生成 Lark 语法字符串 |\n| `_build_special_token_map()` | 构建特殊 token 映射 |\n| `_special_token_lark(token_name)` | 转换特殊 token 为语法 |\n| `_get_optional_special_token_lark(token_name)` | 可选的 token 转换 |\n\n### get_lark_grammar 方法签名\n\n```python\ndef get_lark_grammar(\n self,\n mode: str,\n json_schema_str: str | None = None,\n fcall: str | None = None,\n parallel_tool_calls: bool = False,\n json_only: bool = False,\n think_with_json: bool = False,\n begin_think_token: str | None = None,\n end_think_token: str | None = None,\n) -> str:\n \"\"\"生成 Lark 语法字符串\"\"\"\n```\n\n## 工具调用支持\n\nGrammarFactory 原生支持 function calling 场景：\n\n```python\ngrammar = grammar_factory.get_lark_grammar(\n mode=\"function_call\",\n json_schema_str=tool.parameters, # JSON Schema\n fcall=\"auto\", # 工具选择模式\n parallel_tool_calls=True, # 并行调用\n)\n```\n\n### 工具选择模式\n\n| 模式 | 说明 |\n|------|------|\n| `auto` | 模型自动选择工具 |\n| `none` | 不使用工具 |\n| `required` | 强制使用至少一个工具 |\n| `any` | 任意工具（已废弃） |\n\n资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:40-55]()\n\n## 最佳实践\n\n### 1. 分词器版本检查\n\n```python\nfrom mistral_common.tokens.tokenizers.mistral import TokenizerVersion\n\nif tokenizer.instruct_tokenizer.tokenizer.version >= TokenizerVersion.v11:\n factory = GrammarFactory(tokenizer)\nelse:\n raise ValueError(\"不支持的分词器版本\")\n```\n\n### 2. 模板缓存利用\n\n系统自动缓存渲染结果，重复调用应使用相同参数：\n\n```python\n# 推荐：批量使用相同配置\ngrammar1 = factory.get_lark_grammar(mode=\"json\", json_schema_str=schema)\ngrammar2 = factory.get_lark_grammar(mode=\"json\", json_schema_str=schema) # 使用缓存\n```\n\n### 3. 特殊 Token 验证\n\n使用可选方法处理可能不存在的 token：\n\n```python\ntoken_lark = factory._get_optional_special_token_lark(\"BOS\")\nif token_lark is None:\n # 处理 token 不存在的情况\n pass\n```\n\n## 局限性\n\n1. **分词器限制**：仅支持 Tekken 分词器 v11 及以上版本\n2. **依赖要求**：必须安装 llguidance 和 jinja2\n3. **思考模式版本差异**：不同分词器版本使用不同的思考语法模板\n\n## 相关文件\n\n| 文件路径 | 说明 |\n|----------|------|\n| `src/mistral_common/guidance/grammar_factory.py` | 核心语法工厂实现 |\n| `src/mistral_common/guidance/tokenizer.py` | llguidance 分词器适配器 |\n| `src/mistral_common/guidance/data/*.lark.jinja` | 语法模板文件 |\n| `src/mistral_common/protocol/instruct/tool_calls.py` | 工具调用定义 |\n\n---\n\n\n\n## 实验性功能（工具调用、思考解析、FastAPI 服务）\n\n### 相关页面\n\n相关主题：[项目架构总览](#p2), [Grammar Factory 与 LLM Guidance](#p8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/experimental/tools.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/tools.py)\n- [src/mistral_common/experimental/think.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/think.py)\n- [src/mistral_common/experimental/app/main.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)\n- [src/mistral_common/experimental/app/routers.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/routers.py)\n- [src/mistral_common/experimental/app/models.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/models.py)\n \n\n# 实验性功能（工具调用、思考解析、FastAPI 服务）\n\n## 概述\n\nmistral-common 的实验性功能模块（`src/mistral_common/experimental/`）提供了一套用于处理大语言模型推理请求的扩展能力，包括**工具调用解析**、**思考解析**以及基于 FastAPI 的本地推理服务。这些功能属于实验性质，旨在为开发者提供更灵活的方式来与 Mistral 模型进行交互，特别是在处理复杂的多轮对话、函数调用和模型思维链方面。\n\n实验性功能的主要设计目标是：\n\n- 提供独立于核心 tokenization 流水线的专用解析器\n- 支持通过 HTTP API 快速部署和测试 tokenizer\n- 为工具调用和思考模式提供标准化解析接口\n\n资料来源：[AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)\n\n## 模块架构\n\n实验性功能模块的整体架构由三个核心组件构成，它们各自承担不同的职责：\n\n```mermaid\ngraph TD\n A[experimental 模块] --> B[工具调用解析]\n A --> C[思考解析]\n A --> D[FastAPI 应用]\n \n D --> D1[main.py 入口]\n D --> D2[routers.py 路由]\n D --> D3[models.py 数据模型]\n \n B --> B1[tools.py]\n C --> C1[think.py]\n \n B1 -.->|使用| E[protocol/instruct/tool_calls.py]\n C1 -.->|使用| F[tokens/tokenizers/tekken.py]\n```\n\n资料来源：[src/mistral_common/experimental/](https://github.com/mistralai/mistral-common/tree/main/src/mistral_common/experimental)\n\n---\n\n## 工具调用解析\n\n### 功能概述\n\n`tools.py` 模块提供了工具调用（Tool Calls）的解析能力，允许模型在生成响应时调用外部函数或 API。该模块独立于核心的 `protocol/instruct/tool_calls.py`，专注于解析运行时而非定义工具模式。\n\n资料来源：[src/mistral_common/experimental/tools.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/tools.py)\n\n### 核心职责\n\n工具调用解析模块的主要职责包括：\n\n1. **函数识别**：从模型生成的文本中提取函数调用请求\n2. **参数解析**：将模型输出解析为结构化的函数参数\n3. **结果格式化**：将函数执行结果重新格式化为模型可理解的输入\n\n### 与标准协议的关系\n\n实验性工具调用解析与 `protocol/instruct/tool_calls.py` 中的标准工具定义存在协作关系：\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| 标准工具定义 | `protocol/instruct/tool_calls.py` | 定义 `Tool`、`Function`、`ToolChoice` 等数据模型 |\n| 实验性解析器 | `experimental/tools.py` | 运行时解析模型生成的工具调用 |\n\n资料来源：[src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)\n\n---\n\n## 思考解析\n\n### 功能概述\n\n`think.py` 模块提供了对模型\"思考过程\"的解析能力。在启用 `thinking` 模式的模型中，模型会先生成内部推理步骤（通常以特殊 token 包裹），然后再生成最终响应。`think.py` 模块负责将这些思考过程与最终输出分离解析。\n\n资料来源：[src/mistral_common/experimental/think.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/think.py)\n\n### 思考模式的特殊标记\n\n根据 Tekken tokenizer 的实现，思考模式使用特殊的控制 token：\n\n| Token 名称 | 用途 |\n|------------|------|\n| `begin_thinking` | 标记思考内容开始 |\n| `end_thinking` | 标记思考内容结束 |\n| `begin_turn` | 标记对话轮次开始 |\n| `end_turn` | 标记对话轮次结束 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n### 解析工作流\n\n思考解析的基本工作流程如下：\n\n```mermaid\nsequenceDiagram\n participant User as 用户输入\n participant Tokenizer as Tekken Tokenizer\n participant ThinkParser as 思考解析器\n participant Model as Mistral 模型\n \n User->>Tokenizer: 原始文本\n Tokenizer->>Tokenizer: 添加思考标记\n Tokenizer->>Model: 带标记的 token 序列\n Model-->>Tokenizer: 包含思考的响应\n Tokenizer->>ThinkParser: 解析响应\n ThinkParser->>User: 分离思考内容与最终输出\n```\n\n---\n\n## FastAPI 推理服务\n\n### 应用架构\n\n实验性模块包含一个完整的 FastAPI 应用，用于提供基于 Mistral tokenizer 的 REST API 服务。该应用支持通过命令行快速启动，并提供与模型推理后端的对接能力。\n\n资料来源：[src/mistral_common/experimental/app/main.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)\n\n### 应用入口\n\n`main.py` 定义了 CLI 入口点，使用 Click 框架实现命令行接口：\n\n```python\ndef serve(\n tokenizer_path: str | Path,\n validation_mode: ValidationMode | str = ValidationMode.test,\n host: str = \"127.0.0.1\",\n port: int = 0,\n engine_url: str = \"http://127.0.0.1:8080\",\n engine_backend: str = EngineBackend.llama_cpp.value,\n timeout: int = 60,\n) -> None:\n```\n\n### 启动命令参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `tokenizer_path` | str/Path | 必需 | tokenizer 文件路径 |\n| `validation_mode` | str | \"test\" | 验证模式（test/serving/finetuning） |\n| `host` | str | \"127.0.0.1\" | 服务监听地址 |\n| `port` | int | 0 | 服务监听端口（0 表示自动分配） |\n| `engine_url` | str | \"http://127.0.0.1:8080\" | 推理引擎 URL |\n| `engine_backend` | str | \"llama_cpp\" | 推理后端类型 |\n| `timeout` | int | 60 | 请求超时时间（秒） |\n\n资料来源：[src/mistral_common/experimental/app/main.py:1-90](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)\n\n### 引擎后端支持\n\n系统支持多种推理引擎后端：\n\n| 后端标识 | 说明 |\n|----------|------|\n| `llama_cpp` | Llama.cpp 推理引擎 |\n| `vllm` | vLLM 推理引擎（可选支持） |\n\n### 路由模块\n\n`routers.py` 定义了 API 的路由端点，处理 tokenizer 相关的 HTTP 请求：\n\n```python\n# 路由结构示例\n@router.post(\"/tokenize\")\nasync def tokenize(request: TokenizeRequest) -> TokenizeResponse\n\n@router.post(\"/detokenize\")\nasync def detokenize(request: DetokenizeRequest) -> DetokenizeResponse\n```\n\n资料来源：[src/mistral_common/experimental/app/routers.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/routers.py)\n\n### 数据模型\n\n`models.py` 定义了 API 请求和响应的 Pydantic 模型：\n\n| 模型名称 | 类型 | 用途 |\n|----------|------|------|\n| `TokenizeRequest` | Request | 文本分词请求 |\n| `TokenizeResponse` | Response | 分词结果响应 |\n| `DetokenizeRequest` | Request | token 反向解析请求 |\n| `DetokenizeResponse` | Response | 反解析结果响应 |\n| `ValidationRequest` | Request | 请求验证请求 |\n| `ValidationResponse` | Response | 验证结果响应 |\n\n资料来源：[src/mistral_common/experimental/app/models.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/models.py)\n\n### 服务启动流程\n\n```mermaid\ngraph LR\n A[命令行参数] --> B[create_app]\n B --> C[Uvicorn 运行]\n C --> D[监听 HTTP 请求]\n D --> E[路由处理]\n E --> F[Tokenizer 操作]\n```\n\n### 依赖安装\n\n实验性服务功能需要安装 `server` 可选依赖：\n\n```bash\npip install \"mistral-common[server]\"\n```\n\n资料来源：[README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)\n\n---\n\n## 验证模式\n\n实验性应用支持三种验证模式，由 `MistralRequestValidator` 类管理：\n\n| 模式 | 说明 | 使用场景 |\n|------|------|----------|\n| `test` | 测试模式 | 单元测试和开发 |\n| `serving` | 服务模式 | 生产环境部署 |\n| `finetuning` | 微调模式 | 模型微调任务 |\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n\n---\n\n## 与其他模块的交互\n\n### 整体数据流\n\n```mermaid\ngraph TD\n subgraph 用户层\n A[用户请求]\n end\n \n subgraph API层\n B[FastAPI 应用]\n C[路由处理器]\n end\n \n subgraph 协议层\n D[ChatCompletionRequest]\n E[Validator]\n F[Normalizer]\n end\n \n subgraph Tokenization层\n G[MistralTokenizer]\n H[Tekken Tokenizer]\n end\n \n A --> B --> C\n C --> D --> E\n E --> F\n F --> G --> H\n \n subgraph 实验性功能\n I[工具调用解析]\n J[思考解析]\n end\n \n G -.->|支持| I\n G -.->|支持| J\n```\n\n### 验证流程\n\n用户请求首先经过 `MistralRequestValidator` 验证，然后由 `InstructRequestNormalizer` 标准化，最后由 tokenizer 处理：\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n\n---\n\n## 使用示例\n\n### 启动本地服务\n\n```bash\npython -m mistral_common.experimental.app.main serve \\\n --tokenizer-path /path/to/tokenizer \\\n --validation-mode test \\\n --host 0.0.0.0 \\\n --port 8000\n```\n\n### API 请求示例\n\n```bash\ncurl -X POST http://localhost:8000/tokenize \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\": \"Hello, world!\"}'\n```\n\n---\n\n## 注意事项\n\n1. **实验性质**：所有 `experimental` 模块下的功能均为实验性质，API 可能在后续版本中发生变化\n2. **版本要求**：某些功能需要特定的 tokenizer 版本（如 v11+ 用于 guidance 功能）\n3. **依赖管理**：使用前请确保已安装所有必要的可选依赖\n4. **线程安全**：Tokenization 操作本身是线程安全的，但需注意并发访问时的资源管理\n\n---\n\n\n\n## 数据文件与模型版本管理\n\n### 相关页面\n\n相关主题：[分词器系统详解](#p3), [项目介绍与安装](#p1)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/data/tekken_240718.json](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/data/tekken_240718.json)\n- [src/mistral_common/data/tekken_240911.json](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/data/tekken_240911.json)\n- [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)\n- [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)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n- [src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n \n\n# 数据文件与模型版本管理\n\n## 概述\n\nmistral-common 库中的数据文件与模型版本管理系统负责管理分词器（Tokenizer）的配置数据、词汇表（Vocabulary）以及不同模型版本之间的兼容性适配。该系统通过版本化的数据文件和版本感知的构建器模式，确保库能够支持从 v1 到 v13 的多种 Tekken 分词器版本。\n\n数据文件存放在 `src/mistral_common/data/` 目录下，主要包含两类资源：词汇表 JSON 文件（如 `tekken_240718.json`、`tekken_240911.json`）以及 SentencePiece 模型文件（如 `mistral_instruct_tokenizer_241114.model.v7`）。\n\n资料来源：[AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)\n\n---\n\n## 核心架构\n\n### 版本体系\n\nmistral-common 支持的 Tekken 分词器版本演进如下：\n\n| 版本 | 主要特性 | 数据文件 |\n|------|----------|----------|\n| v1 | 基础分词功能 | 无独立数据文件 |\n| v2 | 改进的分词规则 | 无独立数据文件 |\n| v3 | 支持图像处理 | 需要 image_encoder |\n| v7 | 支持音频处理 | `.v7` 模型文件 |\n| v11 | 完整多模态支持 | Tekken JSON 数据 |\n| v13 | 最新版本特性 | Tekken JSON 数据 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-80](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n### 类关系图\n\n```mermaid\ngraph TD\n A[MistralTokenizer] --> B[InstructTokenizerV*]\n B --> C[TekkenTokenizer]\n C --> D[模型版本管理器]\n E[ModelSettingsBuilder] --> D\n F[data/*.json] --> D\n G[data/*.model.v7] --> D\n```\n\n---\n\n## 数据文件类型\n\n### Tekken 词汇表文件\n\nTekken 词汇表文件采用 JSON 格式存储，包含分词器的完整词汇信息：\n\n- **命名规范**：`tekken_{YYYYMMDD}.json`\n- **内容结构**：\n - 词汇表条目（token 到 ID 的映射）\n - 特殊 token 定义\n - 分词模式（pattern）\n - 元数据（版本号、创建日期）\n\n### SentencePiece 模型文件\n\n较旧版本（如 v7）使用 SentencePiece 格式：\n\n- **命名规范**：`mistral_instruct_tokenizer_{YYYYMMDD}.model.v7`\n- **用途**：向后兼容旧模型\n- **状态**：已弃用，新模型使用 Tekken 格式\n\n资料来源：[README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)\n\n---\n\n## 模型版本管理器\n\n### TokenizerVersion 枚举\n\n所有支持的版本通过 `TokenizerVersion` 枚举进行标识：\n\n```python\nclass TokenizerVersion(Enum):\n v1 = \"v1\"\n v2 = \"v2\"\n v3 = \"v3\"\n v7 = \"v7\"\n v11 = \"v11\"\n v13 = \"v13\"\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n### ModelSettingsBuilder\n\n`ModelSettingsBuilder` 类负责根据模型版本构建相应的配置设置：\n\n```python\nclass ModelSettingsBuilder:\n \"\"\"根据分词器版本构建模型设置的构建器\"\"\"\n \n def build(self, request: ChatCompletionRequest) -> ModelSettings:\n \"\"\"根据请求构建模型设置\"\"\"\n ...\n```\n\n**关键参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `str \\| None` | 模型名称 |\n| `messages` | `list[ChatMessageType]` | 消息列表 |\n| `response_format` | `ResponseFormat` | 响应格式 |\n| `tools` | `list[Tool] \\| None` | 工具定义 |\n| `tool_choice` | `ToolChoice` | 工具选择策略 |\n| `truncate_for_context_length` | `bool` | 是否截断以适应上下文长度 |\n| `continue_final_message` | `bool` | 是否继续最终消息 |\n| `reasoning_effort` | `ReasoningEffort \\| None` | 推理努力级别 |\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:1-100](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n\n---\n\n## 版本选择流程\n\n### 工厂方法模式\n\nmistral-common 使用工厂方法 `create_tokenizer` 来创建适当版本的 tokenizer：\n\n```mermaid\ngraph TD\n A[create_tokenizer 调用] --> B{检查版本}\n B -->|v1| C[InstructTokenizerV1]\n B -->|v2| D[InstructTokenizerV2]\n B -->|v3| E[InstructTokenizerV3 + image_encoder]\n B -->|v7| F[InstructTokenizerV7 + audio_encoder]\n B -->|v11| G[InstructTokenizerV11]\n B -->|v13| H[InstructTokenizerV13]\n C --> I[MistralTokenizer 包装]\n D --> I\n E --> I\n F --> I\n G --> I\n H --> I\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:30-70](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n### 版本验证\n\n每个版本的 tokenizer 实例化时都会进行严格验证：\n\n```python\nif tokenizer.version == TokenizerVersion.v1:\n assert image_encoder is None, \"Tokenizer version needs to be >= v3\"\n assert audio_encoder is None, \"Tokenizer version needs to be >= v7\"\n```\n\n---\n\n## InstructRequestNormalizer 版本化\n\n### 版本化规范化器\n\n`InstructRequestNormalizer` 类存在多个版本子类，每个版本针对特定的分词器版本优化：\n\n| 规范化器类 | 分词器版本 | 特性 |\n|-----------|-----------|------|\n| `InstructRequestNormalizer` | v1/v2 | 基础规范化 |\n| `InstructRequestNormalizerV7` | v7 | 支持音频 |\n\n**V7 版本特性：**\n\n```python\nclass InstructRequestNormalizerV7(InstructRequestNormalizer):\n _system_prompt_in_begin: bool = True\n _allow_tool_call_and_content: bool = True\n```\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-60](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n\n### 规范化流程\n\n```mermaid\ngraph LR\n A[ChatCompletionRequest] --> B[系统提示聚合]\n A --> C[消息聚合]\n B --> D[build_settings]\n C --> D\n D --> E[InstructRequest]\n E --> F[验证器验证]\n F --> G[分词器编码]\n```\n\n---\n\n## 特殊 Token 管理\n\n### SpecialTokenInfo 数据结构\n\n每个 Tekken 分词器版本定义了一套特殊 token：\n\n```python\nSpecialTokenInfo(rank=1, token_str=SpecialTokens.bos, is_control=True),\nSpecialTokenInfo(rank=2, token_str=SpecialTokens.eos, is_control=True),\nSpecialTokenInfo(rank=7, token_str=SpecialTokens.begin_tool_results, is_control=True),\nSpecialTokenInfo(rank=8, token_str=SpecialTokens.end_tool_results, is_control=True),\n```\n\n**特殊 token 完整列表：**\n\n| Token 名称 | 用途 |\n|-----------|------|\n| `bos` | 序列起始 |\n| `eos` | 序列结束 |\n| `begin_tool_results` | 工具结果开始 |\n| `end_tool_results` | 工具结果结束 |\n| `tool_calls` | 工具调用标记 |\n| `img` | 图像标记 |\n| `img_break` | 图像中断 |\n| `img_end` | 图像结束 |\n| `begin_system` | 系统消息开始 |\n| `end_system` | 系统消息结束 |\n| `begin_tool_content` | 工具内容开始 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n---\n\n## 数据流集成\n\n### 与协议层集成\n\n数据版本管理与协议层紧密协作：\n\n```mermaid\ngraph TD\n A[用户请求] --> B[ChatCompletionRequest]\n B --> C[规范化器 Normalizer]\n C --> D[验证器 Validator]\n D --> E[分词器 Tokenizer]\n E --> F[data/ 目录数据]\n F --> E\n E --> G[模型输出]\n```\n\n### 验证模式\n\n系统支持三种验证模式：\n\n| 模式 | 说明 | 模型参数要求 |\n|------|------|-------------|\n| `test` | 测试模式（默认） | 可选 |\n| `serving` | 服务模式 | 必须提供 |\n| `finetuning` | 微调模式 | 可选 |\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n\n---\n\n## 版本迁移指南\n\n### 从旧版本迁移\n\n| 源版本 | 目标版本 | 迁移要点 |\n|--------|----------|----------|\n| v1/v2 | v3+ | 需要配置 `image_encoder` |\n| v3-v6 | v7 | 需要配置 `audio_encoder` |\n| SentencePiece | Tekken | 使用新的 JSON 数据文件 |\n\n### 兼容性检查\n\n```python\n# 检查版本兼容性的示例代码\nif tokenizer.version >= TokenizerVersion.v11:\n # 使用新的 GrammarFactory 功能\n grammar_factory = GrammarFactory(tokenizer)\n```\n\n---\n\n## 总结\n\nmistral-common 的数据文件与模型版本管理系统通过以下机制实现多版本支持：\n\n1. **版本化数据文件**：不同版本的词汇表和模型文件存储在 `data/` 目录\n2. **版本感知的构建器**：`ModelSettingsBuilder` 根据版本构建正确配置\n3. **工厂方法**：`create_tokenizer` 根据版本参数返回适当的 tokenizer 实例\n4. **版本化规范化器**：不同版本的规范化器处理特定版本的请求格式\n5. **严格验证**：每个版本有独立的验证逻辑和版本检查\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：mistralai/mistral-common\n\n摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]。\n\n## 1. 安全/权限坑 · 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_750d0089d9e14ad385e0f49195987796 | https://github.com/mistralai/mistral-common/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b87372316a944057aa9d5cf9ae8797b3 | https://github.com/mistralai/mistral-common/issues/209 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03f994c9b8a649a0a7723f5a7ac9a9c0 | https://github.com/mistralai/mistral-common/issues/210 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call'…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call', ...}\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_598dfde98fb44c46b9d95e5ee2a66d69 | https://github.com/mistralai/mistral-common/issues/211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:786756993 | https://github.com/mistralai/mistral-common | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 来源证据：v1.11.1: Patch for agentic use\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.11.1: Patch for agentic use\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2858129b86914e6090beed86fafe6db7 | https://github.com/mistralai/mistral-common/releases/tag/v1.11.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 来源证据：v1.8.7: Refactoring and bug fixes.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.8.7: Refactoring and bug fixes.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cbca40b0e8be4f20a899d193e200fdd3 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c55c5c2d9aae479b96c76416b6740fee | https://github.com/mistralai/mistral-common/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：v1.8.6: rm Python 3.9, bug fixes.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.8.6: rm Python 3.9, bug fixes.\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ffc1eeb338274f6095e43203b2c2e785 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v1.9.0 - Stream my audio 🎙️\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.0 - Stream my audio 🎙️\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bad0c0ee58ac4386b5bcc2d2c9d226e8 | https://github.com/mistralai/mistral-common/releases/tag/v1.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | release_recency=unknown\n\n\n",
"markdown_key": "mistral-common",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:786756993",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/mistralai/mistral-common"
},
{
"evidence_id": "art_0ddd2801c1dc40dd869dac82cb76a525",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/mistralai/mistral-common#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mistral-common 说明书",
"toc": [
"https://github.com/mistralai/mistral-common 项目说明书",
"目录",
"项目介绍与安装",
"1. 项目概述",
"2. 项目架构",
"3. 安装指南",
"4. 快速入门",
"创建聊天补全请求",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "5693a4092b98828d68fac62d2fd44aa431b20165",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/index.md",
"docs/gen_api_pages.py",
"docs/examples/inference.md",
"docs/usage/tools.md",
"docs/usage/index.md",
"docs/usage/experimental.md",
"docs/usage/install.md",
"docs/usage/tokenizers.md",
"docs/usage/images.md",
"docs/usage/requests.md",
"src/mistral_common/exceptions.py",
"src/mistral_common/image.py",
"src/mistral_common/multimodal.py",
"src/mistral_common/__init__.py",
"src/mistral_common/imports.py",
"src/mistral_common/audio.py",
"src/mistral_common/base.py",
"src/mistral_common/tokens/__init__.py",
"src/mistral_common/experimental/tools.py",
"src/mistral_common/experimental/think.py",
"src/mistral_common/experimental/utils.py",
"src/mistral_common/experimental/__init__.py",
"src/mistral_common/guidance/tokenizer.py",
"src/mistral_common/guidance/grammar_factory.py",
"src/mistral_common/guidance/__init__.py",
"src/mistral_common/data/tekken_240718.json",
"src/mistral_common/data/tekken_240911.json",
"src/mistral_common/protocol/utils.py",
"src/mistral_common/protocol/__init__.py",
"src/mistral_common/protocol/base.py",
"src/mistral_common/tokens/tokenizers/instruct.py",
"src/mistral_common/tokens/tokenizers/image.py",
"src/mistral_common/tokens/tokenizers/model_settings_builder.py",
"src/mistral_common/tokens/tokenizers/sentencepiece.py",
"src/mistral_common/tokens/tokenizers/multimodal.py",
"src/mistral_common/tokens/tokenizers/utils.py",
"src/mistral_common/tokens/tokenizers/mistral.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# mistral-common - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 mistral-common 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `docs/usage/install.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install mistral-common` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86 等\n- `pip install \"mistral-common[image]\"` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0009` supported 0.86\n- `pip install \"mistral-common[audio]\"` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `pip install \"mistral-common[hf-hub]\"` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `pip install \"mistral-common[sentencepiece]\"` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `pip install \"mistral-common[server]\"` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install \"mistral-common[image,audio,hf-hub,sentencepiece,server]\"` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `git clone https://github.com//mistral-common.git` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `git clone https://github.com/mistralai/mistral-common.git` 证据：`docs/usage/install.md` Claim：`clm_0011` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `docs/usage/install.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `docs/usage/install.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `docs/usage/install.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0012` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `docs/usage/install.md` Claim：`clm_0013` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `docs/usage/install.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：156\n- 重要文件覆盖：40/156\n- 证据索引条目：39\n- 角色 / Skill 条目：11\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 mistral-common 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 mistral-common 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 mistral-common 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 11 个角色 / Skill / 项目文档条目。\n\n- **Install**（project_doc）：You can install the library using pip: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usage/install.md`\n- **AGENTS.md**（project_doc）：Mistral-Common is a preprocessing library for Mistral's Large Language Models LLMs . It encodes requests for Instruct, Transcription or Fill-In-The-Middle FIM tasks to tokens and optionally processed images or audios. - Language: Python 3.10 to 3.14 - Package Manager: uv - Testing: pytest - Formatting and Linting: Ruff - Type checker: mypy - CI: GitHub Actions 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **Mistral-common**（project_doc）：! PyPI version https://img.shields.io/pypi/v/mistral-common?label=release&logo=pypi&logoColor=white https://pypi.org/project/mistral-common/ ! Tests https://img.shields.io/github/actions/workflow/status/mistralai/mistral-common/lint build test.yaml?label=tests&branch=main https://github.com/mistralai/mistral-common/actions/workflows/lint build test.yaml ! Documentation https://img.shields.io/website?url=https%3A%2F%… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Introduction**（project_doc）：mistral-common is a set of tools to help you work with Mistral models. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **Inference**（project_doc）：We have a few examples of how to use the library with our models: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/inference.md`\n- **Mistral-common Experimental API**（project_doc）：The experimental module provides access to a FastAPI server designed to handle tokenization and detokenization operations through a REST API. This server features: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usage/experimental.md`\n- **Images**（project_doc）：Most of the recently released Mistral models https://huggingface.co/mistralai/models support image inputs. Images are represented as BaseContentChunk mistral common.protocol.instruct.chunk.BaseContentChunk objects within the messages field of the ChatCompletionRequest mistral common.protocol.instruct.request.ChatCompletionRequest . Encoding an image via a ImageEncoder mistral common.tokens.tokenizers.image.ImageEnco… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usage/images.md`\n- **Usage**（project_doc）：See installation instructions ./install.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usage/index.md`\n- **Requests**（project_doc）：To query an AI assistant like Mistral's LeChat https://chat.mistral.ai/chat or ChatGPT you need to provide the following: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usage/requests.md`\n- **Tokenizers**（project_doc）：Tokenization is the process of converting a sequence of characters into a sequence of tokens. To dive deeper into the tokenization process, you can read the tokenization guide https://docs.mistral.ai/guides/tokenization/ on our website. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usage/tokenizers.md`\n- **Tools**（project_doc）：To execute external tools, like searching the web, LLMs need to be given the ability to call such tools whenever they see fit. This is usually achieved by adding all available tools that the LLM can call into the context of the ChatCompletionRequest mistral common.protocol.instruct.request.ChatCompletionRequest and representing tool calls as well as tool message as its own objects. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usage/tools.md`\n\n## 证据索引\n\n- 共索引 39 条证据。\n\n- **Install**（documentation）：You can install the library using pip: 证据：`docs/usage/install.md`\n- **AGENTS.md**（documentation）：Mistral-Common is a preprocessing library for Mistral's Large Language Models LLMs . It encodes requests for Instruct, Transcription or Fill-In-The-Middle FIM tasks to tokens and optionally processed images or audios. - Language: Python 3.10 to 3.14 - Package Manager: uv - Testing: pytest - Formatting and Linting: Ruff - Type checker: mypy - CI: GitHub Actions 证据：`AGENTS.md`\n- **Mistral-common**（documentation）：! PyPI version https://img.shields.io/pypi/v/mistral-common?label=release&logo=pypi&logoColor=white https://pypi.org/project/mistral-common/ ! Tests https://img.shields.io/github/actions/workflow/status/mistralai/mistral-common/lint build test.yaml?label=tests&branch=main https://github.com/mistralai/mistral-common/actions/workflows/lint build test.yaml ! Documentation https://img.shields.io/website?url=https%3A%2F%2Fmistralai.github.io%2Fmistral-common%2F&up message=online&down message=offline&label=docs https://mistralai.github.io/mistral-common/ ! Python version https://img.shields.io/badge/dynamic/json?query=info.requires python&label=python&url=https%3A%2F%2Fpypi.org%2Fpypi%2Fmistral-c… 证据：`README.md`\n- **Introduction**（documentation）：mistral-common is a set of tools to help you work with Mistral models. 证据：`docs/index.md`\n- **Inference**（documentation）：We have a few examples of how to use the library with our models: 证据：`docs/examples/inference.md`\n- **Mistral-common Experimental API**（documentation）：The experimental module provides access to a FastAPI server designed to handle tokenization and detokenization operations through a REST API. This server features: 证据：`docs/usage/experimental.md`\n- **Images**（documentation）：Most of the recently released Mistral models https://huggingface.co/mistralai/models support image inputs. Images are represented as BaseContentChunk mistral common.protocol.instruct.chunk.BaseContentChunk objects within the messages field of the ChatCompletionRequest mistral common.protocol.instruct.request.ChatCompletionRequest . Encoding an image via a ImageEncoder mistral common.tokens.tokenizers.image.ImageEncoder will return: 证据：`docs/usage/images.md`\n- **Usage**（documentation）：See installation instructions ./install.md . 证据：`docs/usage/index.md`\n- **Requests**（documentation）：To query an AI assistant like Mistral's LeChat https://chat.mistral.ai/chat or ChatGPT you need to provide the following: 证据：`docs/usage/requests.md`\n- **Tokenizers**（documentation）：Tokenization is the process of converting a sequence of characters into a sequence of tokens. To dive deeper into the tokenization process, you can read the tokenization guide https://docs.mistral.ai/guides/tokenization/ on our website. 证据：`docs/usage/tokenizers.md`\n- **Tools**（documentation）：To execute external tools, like searching the web, LLMs need to be given the ability to call such tools whenever they see fit. This is usually achieved by adding all available tools that the LLM can call into the context of the ChatCompletionRequest mistral common.protocol.instruct.request.ChatCompletionRequest and representing tool calls as well as tool message as its own objects. 证据：`docs/usage/tools.md`\n- **Tekken 240718**（structured_config）：{ \"config\": { \"pattern\": \" ^\\\\r\\\\n\\\\p{L}\\\\p{N} ? \\\\p{Lu}\\\\p{Lt}\\\\p{Lm}\\\\p{Lo}\\\\p{M} \\\\p{Ll}\\\\p{Lm}\\\\p{Lo}\\\\p{M} + ^\\\\r\\\\n\\\\p{L}\\\\p{N} ? \\\\p{Lu}\\\\p{Lt}\\\\p{Lm}\\\\p{Lo}\\\\p{M} + \\\\p{Ll}\\\\p{Lm}\\\\p{Lo}\\\\p{M} \\\\p{N} ? ^\\\\s\\\\p{L}\\\\p{N} + \\\\r\\\\n/ \\\\s \\\\r\\\\n + \\\\s+ ?!\\\\S \\\\s+\", \"num vocab tokens\": 150000, \"default vocab size\": 131072, \"default num special tokens\": 1000, \"version\": \"v3\" }, \"vocab\": { \"rank\": 0, \"token bytes\": \"AA==\", \"token str\": \"\\u0000\" }, { \"rank\": 1, \"token bytes\": \"AQ==\", \"token str\": \"\\u0001\" }, { \"rank\": 2, \"token bytes\": \"Ag==\", \"token str\": \"\\u0002\" }, { \"rank\": 3, \"token bytes\": \"Aw==\", \"token str\": \"\\u0003\" }, { \"rank\": 4, \"token bytes\": \"BA==\", \"token str\": \"\\u0004\" }, { \"r… 证据：`src/mistral_common/data/tekken_240718.json`\n- **Tekken 240911**（structured_config）：{ \"config\": { \"pattern\": \" ^\\\\r\\\\n\\\\p{L}\\\\p{N} ? \\\\p{Lu}\\\\p{Lt}\\\\p{Lm}\\\\p{Lo}\\\\p{M} \\\\p{Ll}\\\\p{Lm}\\\\p{Lo}\\\\p{M} + ^\\\\r\\\\n\\\\p{L}\\\\p{N} ? \\\\p{Lu}\\\\p{Lt}\\\\p{Lm}\\\\p{Lo}\\\\p{M} + \\\\p{Ll}\\\\p{Lm}\\\\p{Lo}\\\\p{M} \\\\p{N} ? ^\\\\s\\\\p{L}\\\\p{N} + \\\\r\\\\n/ \\\\s \\\\r\\\\n + \\\\s+ ?!\\\\S \\\\s+\", \"num vocab tokens\": 150000, \"default vocab size\": 131072, \"default num special tokens\": 1000, \"version\": \"v3\" }, \"vocab\": { \"rank\": 0, \"token bytes\": \"AA==\", \"token str\": \"\\u0000\" }, { \"rank\": 1, \"token bytes\": \"AQ==\", \"token str\": \"\\u0001\" }, { \"rank\": 2, \"token bytes\": \"Ag==\", \"token str\": \"\\u0002\" }, { \"rank\": 3, \"token bytes\": \"Aw==\", \"token str\": \"\\u0003\" }, { \"rank\": 4, \"token bytes\": \"BA==\", \"token str\": \"\\u0004\" }, { \"r… 证据：`src/mistral_common/data/tekken_240911.json`\n- **Sample**（structured_config）：{ \"messages\": { \"role\": \"system\", \"content\": \"Don't make assumptions about what values to plug into functions.\" }, { \"role\": \"system\", \"content\": \"Ask for clarification if a user request is ambiguous.\" }, { \"role\": \"user\", \"content\": \"What's the weather like today\" }, { \"role\": \"assistant\", \"content\": \"Sure, can you please provide me with your location?\" 证据：`tests/data/samples/get_weather_full/sample.json`\n- **Tokens V2**（structured_config）：{ \"tokens\": 1, 3, 2592, 29510, 29481, 1040, 8854, 1505, 3922, 4, 13643, 29493, 1309, 1136, 5433, 3852, 1296, 1163, 1342, 5491, 29572, 2, 3, 1083, 29510, 29487, 1065, 6233, 29493, 5611, 29491, 4, 1183, 2636, 8409, 1065, 6233, 29493, 5611, 1117, 29473, 29518, 29518, 11950, 1102, 1958, 3938, 29491, 2, 3, 1535, 1117, 1040, 8854, 2172, 1066, 1115, 1505, 1065, 6233, 29493, 5611, 1522, 1040, 2447, 2086, 2970, 4, 6687, 2680, 1296, 1040, 2242, 1070, 2970, 1136, 1715, 1040, 8854, 20680, 1122, 29491, 2, 6, 1501, 7567, 1891, 2032, 1113, 3396, 1316, 1113, 3396, 2032, 10598, 1629, 2032, 1113, 1295, 29498, 3790, 29498, 1537, 1991, 1316, 1113, 7286, 2032, 1113, 2226, 1040, 2636, 8854, 1316, 1113, 12206, 20… 证据：`tests/data/samples/get_weather_full/tokens_v2.json`\n- **Tokens V3**（structured_config）：{ \"tokens\": 1, 3, 2592, 29510, 29481, 1040, 8854, 1505, 3922, 4, 13643, 29493, 1309, 1136, 5433, 3852, 1296, 1163, 1342, 5491, 29572, 2, 3, 1083, 29510, 29487, 1065, 6233, 29493, 5611, 29491, 4, 5, 1501, 7567, 1629, 2032, 1113, 1295, 29498, 3790, 29498, 1537, 1991, 1316, 1113, 17452, 2032, 10598, 3501, 2032, 1113, 4684, 1046, 29493, 5611, 1316, 1113, 4530, 2032, 1113, 29485, 1958, 3938, 8474, 1113, 1081, 2032, 1113, 29508, 29518, 29538, 29549, 29550, 29552, 29555, 29551, 29542, 29507, 10925, 2, 8, 10598, 4557, 2032, 29473, 29518, 29518, 29493, 1113, 3613, 29498, 1081, 2032, 1113, 29508, 29518, 29538, 29549, 29550, 29552, 29555, 29551, 29542, 18163, 9, 1183, 2636, 8409, 1065, 6233, 29493, 56… 证据：`tests/data/samples/get_weather_full/tokens_v3.json`\n- **Sample**（structured_config）：{ \"messages\": { \"role\": \"system\", \"content\": \"Don't make assumptions about what values to plug into functions.\" }, { \"role\": \"system\", \"content\": \"Ask for clarification if a user request is ambiguous.\" }, { \"role\": \"user\", \"content\": \"What's the weather like today\" }, { \"role\": \"assistant\", \"content\": \"Sure, can you please provide me with your location?\", \"tool calls\": null }, { \"role\": \"user\", \"content\": \"I'm in Paris, France.\" }, { \"content\": \"The current temperature in Paris, France is 22 degrees Celsius.\", \"role\": \"assistant\", \"tool calls\": null }, { \"role\": \"user\", \"content\": \"what is the weather going to be like in Paris, France over the next x days\" }, { \"content\": \"Please tell me th… 证据：`tests/data/samples/get_weather_no_history/sample.json`\n- **Tokens V2**（structured_config）：{ \"tokens\": 1, 3, 2592, 29510, 29481, 1040, 8854, 1505, 3922, 4, 13643, 29493, 1309, 1136, 5433, 3852, 1296, 1163, 1342, 5491, 29572, 2, 3, 1083, 29510, 29487, 1065, 6233, 29493, 5611, 29491, 4, 1183, 2636, 8409, 1065, 6233, 29493, 5611, 1117, 29473, 29518, 29518, 11950, 1102, 1958, 3938, 29491, 2, 3, 1535, 1117, 1040, 8854, 2172, 1066, 1115, 1505, 1065, 6233, 29493, 5611, 1522, 1040, 2447, 2086, 2970, 4, 6687, 2680, 1296, 1040, 2242, 1070, 2970, 1136, 1715, 1040, 8854, 20680, 1122, 29491, 2, 6, 1501, 7567, 1891, 2032, 1113, 3396, 1316, 1113, 3396, 2032, 10598, 1629, 2032, 1113, 1295, 29498, 3790, 29498, 1537, 1991, 1316, 1113, 7286, 2032, 1113, 2226, 1040, 2636, 8854, 1316, 1113, 12206, 20… 证据：`tests/data/samples/get_weather_no_history/tokens_v2.json`\n- **Tokens V3**（structured_config）：{ \"tokens\": 1, 3, 2592, 29510, 29481, 1040, 8854, 1505, 3922, 4, 13643, 29493, 1309, 1136, 5433, 3852, 1296, 1163, 1342, 5491, 29572, 2, 3, 1083, 29510, 29487, 1065, 6233, 29493, 5611, 29491, 4, 1183, 2636, 8409, 1065, 6233, 29493, 5611, 1117, 29473, 29518, 29518, 11950, 1102, 1958, 3938, 29491, 2 , 3, 1535, 1117, 1040, 8854, 2172, 1066, 1115, 1505, 1065, 6233, 29493, 5611, 1522, 1040, 2447, 2086, 2970, 4, 6687, 2680, 1296, 1040, 2242, 1070, 2970, 1136, 1715, 1040, 8854, 20680, 1122, 29491, 2, 6, 1501, 7567, 1891, 2032, 1113, 3396, 1316, 1113, 3396, 2032, 10598, 1629, 2032, 1113, 1295, 29498, 3790, 29498, 1537, 1991, 1316, 1113, 7286, 2032, 1113, 2226, 1040, 2636, 8854, 1316, 1113, 12206, 2… 证据：`tests/data/samples/get_weather_no_history/tokens_v3.json`\n- **Sample**（structured_config）：{ \"messages\": { \"role\": \"user\", \"content\": \"What's the weather like today\" }, { \"role\": \"assistant\", \"content\": \"Sure, can you please provide me with your location?\", \"tool calls\": null }, { \"role\": \"user\", \"content\": \"I'm in Paris, France.\" }, { \"content\": null, \"role\": \"assistant\", \"tool calls\": { \"id\": \"123456789\", \"function\": { \"arguments\": \"{\\n \\\"location\\\": \\\"Paris, France\\\",\\n \\\"format\\\": \\\"celsius\\\"\\n}\", \"name\": \"get current weather\" }, \"type\": \"function\" } }, { \"tool call id\": \"123456789\", \"role\": \"tool\", \"name\": \"get current weather\", \"content\": \"22\" }, { \"content\": \"The current temperature in Paris, France is 22 degrees Celsius.\", \"role\": \"assistant\", \"tool calls\": null }, { \"rol… 证据：`tests/data/samples/get_weather_no_system_prompt/sample.json`\n- **Tokens V2**（structured_config）：{ \"tokens\": 1, 3, 2592, 29510, 29481, 1040, 8854, 1505, 3922, 4, 13643, 29493, 1309, 1136, 5433, 3852, 1296, 1163, 1342, 5491, 29572, 2, 3, 1083, 29510, 29487, 1065, 6233, 29493, 5611, 29491, 4, 1183, 2636, 8409, 1065, 6233, 29493, 5611, 1117, 29473, 29518, 29518, 11950, 1102, 1958, 3938, 29491, 2, 3, 1535, 1117, 1040, 8854, 2172, 1066, 1115, 1505, 1065, 6233, 29493, 5611, 1522, 1040, 2447, 2086, 2970, 4, 6687, 2680, 1296, 1040, 2242, 1070, 2970, 1136, 1715, 1040, 8854, 20680, 1122, 29491, 2, 6, 1501, 7567, 1891, 2032, 1113, 3396, 1316, 1113, 3396, 2032, 10598, 1629, 2032, 1113, 1295, 29498, 3790, 29498, 1537, 1991, 1316, 1113, 7286, 2032, 1113, 2226, 1040, 2636, 8854, 1316, 1113, 12206, 20… 证据：`tests/data/samples/get_weather_no_system_prompt/tokens_v2.json`\n- **Tokens V3**（structured_config）：{ \"tokens\": 1, 3, 2592, 29510, 29481, 1040, 8854, 1505, 3922, 4, 13643, 29493, 1309, 1136, 5433, 3852, 1296, 1163, 1342, 5491, 29572, 2, 3, 1083, 29510, 29487, 1065, 6233, 29493, 5611, 29491, 4, 5, 1501, 7567, 1629, 2032, 1113, 1295, 29498, 3790, 29498, 1537, 1991, 1316, 1113, 17452, 2032, 10598, 3501, 2032, 1113, 4684, 1046, 29493, 5611, 1316, 1113, 4530, 2032, 1113, 29485, 1958, 3938, 8474, 1113, 1081, 2032, 1113, 29508, 29518, 29538, 29549, 29550, 29552, 29555, 29551, 29542, 29507, 10925, 2, 8, 10598, 4557, 2032, 29473, 29518, 29518, 29493, 1113, 3613, 29498, 1081, 2032, 1113, 29508, 29518, 29538, 29549, 29550, 29552, 29555, 29551, 29542, 18163, 9, 1183, 2636, 8409, 1065, 6233, 29493, 56… 证据：`tests/data/samples/get_weather_no_system_prompt/tokens_v3.json`\n- **Sample**（structured_config）：{ \"messages\": { \"role\": \"user\", \"content\": \"What's the result of 5 + 5?\" }, { \"role\": \"assistant\", \"content\": \"The result of 5 + 5 is 10.\", \"tool calls\": null }, { \"role\": \"user\", \"content\": \"What is the square root of 64?\" }, { \"role\": \"assistant\", \"content\": \"The square root of 64 is 8, because 8 x 8 equals 64.\", \"tool calls\": null }, { \"role\": \"user\", \"content\": \"Can you multiply the results of the previous two questions?\" }, { \"role\": \"assistant\", \"content\": \"Sure! The result of 10 x 8 is 80.\", \"tool calls\": null }, { \"role\": \"user\", \"content\": \"Thanks\" } , \"tools\": } 证据：`tests/data/samples/no_tools/sample.json`\n- **Tokens V1**（structured_config）：{ \"tokens\": 1, 733, 16289, 28793, 1824, 28742, 28713, 272, 1204, 302, 28705, 28782, 648, 28705, 28782, 28804, 733, 28748, 16289, 28793, 415, 1204, 302, 28705, 28782, 648, 28705, 28782, 349, 28705, 28740, 28734, 28723, 2, 733, 16289, 28793, 1824, 349, 272, 7930, 5557, 302, 28705, 28784, 28781, 28804, 733, 28748, 16289, 28793, 415, 7930, 5557, 302, 28705, 28784, 28781, 349, 28705, 28783, 28725, 1096, 28705, 28783, 1318, 28705, 28783, 21588, 28705, 28784, 28781, 28723, 2, 733, 16289, 28793, 2418, 368, 17669, 346, 272, 2903, 302, 272, 3454, 989, 4224, 28804, 733, 28748, 16289, 28793, 12875, 28808, 415, 1204, 302, 28705, 28740, 28734, 1318, 28705, 28783, 349, 28705, 28783, 28734, 28723, 2, 733,… 证据：`tests/data/samples/no_tools/tokens_v1.json`\n- **Tokens V2**（structured_config）：{ \"tokens\": 1, 3, 2592, 29510, 29481, 1040, 1972, 1070, 29473, 29550, 1416, 29473, 29550, 29572, 4, 1183, 1972, 1070, 29473, 29550, 1416, 29473, 29550, 1117, 29473, 29508, 29502, 29491, 2, 3, 2592, 1117, 1040, 8698, 6325, 1070, 29473, 29552, 29549, 29572, 4, 1183, 8698, 6325, 1070, 29473, 29552, 29549, 1117, 29473, 29551, 29493, 1864, 29473, 29551, 2086, 29473, 29551, 22356, 29473, 29552, 29549, 29491, 2, 3, 3186, 1136, 18437, 1114, 1040, 3671, 1070, 1040, 4222, 1757, 4992, 29572, 4, 13643, 29576, 1183, 1972, 1070, 29473, 29508, 29502, 2086, 29473, 29551, 1117, 29473, 29551, 29502, 29491, 2, 3, 9636, 4 } 证据：`tests/data/samples/no_tools/tokens_v2.json`\n- **Tokens V3**（structured_config）：{ \"tokens\": 1, 3, 2592, 29510, 29481, 1040, 1972, 1070, 29473, 29550, 1416, 29473, 29550, 29572, 4, 1183, 1972, 1070, 29473, 29550, 1416, 29473, 29550, 1117, 29473, 29508, 29502, 29491, 2, 3, 2592, 1117, 1040, 8698, 6325, 1070, 29473, 29552, 29549, 29572, 4, 1183, 8698, 6325, 1070, 29473, 29552, 29549, 1117, 29473, 29551, 29493, 1864, 29473, 29551, 2086, 29473, 29551, 22356, 29473, 29552, 29549, 29491, 2, 3, 3186, 1136, 18437, 1114, 1040, 3671, 1070, 1040, 4222, 1757, 4992, 29572, 4, 13643, 29576, 1183, 1972, 1070, 29473, 29508, 29502, 2086, 29473, 29551, 1117, 29473, 29551, 29502, 29491, 2, 3, 9636, 4 } 证据：`tests/data/samples/no_tools/tokens_v3.json`\n- **Sample**（structured_config）：{ \"tools\": { \"type\": \"function\", \"function\": { \"name\": \"send email\", \"description\": \"Send an email to a recipient\", \"parameters\": { \"type\": \"object\", \"properties\": { \"attachment\": { \"type\": \"string\", \"description\": \"The path or URL of an attachment optional \" }, \"body\": { \"type\": \"string\", \"description\": \"The body/content of the email\" }, \"subject\": { \"type\": \"string\", \"description\": \"The subject of the email\" }, \"to\": { \"type\": \"string\", \"description\": \"The email address of the recipient\" } }, \"required\": \"to\", \"subject\", \"body\" } } } , \"messages\": { \"role\": \"user\", \"content\": \"I need to send a report to my manager. The report is saved as a PDF at 'report.pdf'. The email address is manager… 证据：`tests/data/samples/parallel_calls/sample.json`\n- **Tokens V2**（structured_config）：{ \"tokens\": 1, 3, 1083, 1695, 1066, 4848, 1032, 3032, 1066, 1354, 7824, 29491, 1183, 3032, 1117, 9454, 1158, 1032, 19288, 1206, 1232, 10914, 29491, 9752, 4903, 1183, 5695, 3730, 1117, 7824, 29586, 18766, 29491, 1443, 29491, 1183, 4585, 1791, 1115, 1113, 16373, 1114, 8199, 29507, 1072, 1040, 2955, 1791, 2083, 1113, 3285, 3462, 1117, 1040, 15658, 3032, 1122, 1342, 4826, 1379, 4, 1083, 29510, 1101, 3430, 1040, 3032, 1066, 1342, 7824, 29491, 28753, 1880, 29572, 2, 6, 1501, 7567, 1891, 2032, 1113, 3396, 1316, 1113, 3396, 2032, 10598, 1629, 2032, 1113, 5989, 29498, 7372, 1316, 1113, 7286, 2032, 1113, 9131, 1164, 5695, 1066, 1032, 24609, 1316, 1113, 12206, 2032, 10598, 1891, 2032, 1113, 3582, 1316… 证据：`tests/data/samples/parallel_calls/tokens_v2.json`\n- **Tokens V3**（structured_config）：{ \"tokens\": 1, 3, 1083, 1695, 1066, 4848, 1032, 3032, 1066, 1354, 7824, 29491, 1183, 3032, 1117, 9454, 1158, 1032, 19288, 1206, 1232, 10914, 29491, 9752, 4903, 1183, 5695, 3730, 1117, 7824, 29586, 18766, 29491, 1443, 29491, 1183, 4585, 1791, 1115, 1113, 16373, 1114, 8199, 29507, 1072, 1040, 2955, 1791, 2083, 1113, 3285, 3462, 1117, 1040, 15658, 3032, 1122, 1342, 4826, 1379, 4, 5, 1501, 7567, 1629, 2032, 1113, 5989, 29498, 7372, 1316, 1113, 17452, 2032, 10598, 28918, 2032, 1113, 10914, 29491, 9752, 1316, 1113, 3448, 2032, 1113, 3285, 3462, 1117, 1040, 15658, 3032, 1122, 1342, 4826, 9959, 1113, 17334, 2032, 1113, 16373, 1114, 8199, 1316, 1113, 1300, 2032, 1113, 10075, 29586, 18766, 29491, 144… 证据：`tests/data/samples/parallel_calls/tokens_v3.json`\n- **Sample**（structured_config）：{ \"tools\": { \"type\": \"function\", \"function\": { \"name\": \"send email\", \"description\": \"Send an email to a recipient\", \"parameters\": { \"type\": \"object\", \"properties\": { \"attachment\": { \"type\": \"string\", \"description\": \"The path or URL of an attachment optional \" }, \"body\": { \"type\": \"string\", \"description\": \"The body/content of the email\" }, \"subject\": { \"type\": \"string\", \"description\": \"The subject of the email\" }, \"to\": { \"type\": \"string\", \"description\": \"The email address of the recipient\" } }, \"required\": \"to\", \"subject\", \"body\" } } } , \"messages\": { \"role\": \"user\", \"content\": \"I need to send a report to my manager. The report is saved as a PDF at 'report.pdf'. The email address is manager… 证据：`tests/data/samples/several_calls/sample.json`\n- **Tokens V2**（structured_config）：{ \"tokens\": 1, 3, 1083, 1695, 1066, 4848, 1032, 3032, 1066, 1354, 7824, 29491, 1183, 3032, 1117, 9454, 1158, 1032, 19288, 1206, 1232, 10914, 29491, 9752, 4903, 1183, 5695, 3730, 1117, 7824, 29586, 18766, 29491, 1443, 29491, 1183, 4585, 1791, 1115, 1113, 16373, 1114, 8199, 29507, 1072, 1040, 2955, 1791, 2083, 1113, 3285, 3462, 1117, 1040, 15658, 3032, 1122, 1342, 4826, 1379, 4, 1083, 29510, 1101, 3430, 1040, 3032, 1066, 1342, 7824, 29491, 28753, 1880, 29572, 2, 6, 1501, 7567, 1891, 2032, 1113, 3396, 1316, 1113, 3396, 2032, 10598, 1629, 2032, 1113, 5989, 29498, 7372, 1316, 1113, 7286, 2032, 1113, 9131, 1164, 5695, 1066, 1032, 24609, 1316, 1113, 12206, 2032, 10598, 1891, 2032, 1113, 3582, 1316… 证据：`tests/data/samples/several_calls/tokens_v2.json`\n- **Tokens V3**（structured_config）：{ \"tokens\": 1, 3, 1083, 1695, 1066, 4848, 1032, 3032, 1066, 1354, 7824, 29491, 1183, 3032, 1117, 9454, 1158, 1032, 19288, 1206, 1232, 10914, 29491, 9752, 4903, 1183, 5695, 3730, 1117, 7824, 29586, 18766, 29491, 1443, 29491, 1183, 4585, 1791, 1115, 1113, 16373, 1114, 8199, 29507, 1072, 1040, 2955, 1791, 2083, 1113, 3285, 3462, 1117, 1040, 15658, 3032, 1122, 1342, 4826, 1379, 4, 5, 1501, 7567, 1629, 2032, 1113, 5989, 29498, 7372, 1316, 1113, 17452, 2032, 10598, 28918, 2032, 1113, 10914, 29491, 9752, 1316, 1113, 3448, 2032, 1113, 3285, 3462, 1117, 1040, 15658, 3032, 1122, 1342, 4826, 9959, 1113, 17334, 2032, 1113, 16373, 1114, 8199, 1316, 1113, 1300, 2032, 1113, 10075, 29586, 18766, 29491, 144… 证据：`tests/data/samples/several_calls/tokens_v3.json`\n- **Byte-compiled / optimized / DLL files**（source_file）：Byte-compiled / optimized / DLL files pycache / .py cod $py.class 证据：`.gitignore`\n- **.Pre Commit Config**（source_file）：repos: - repo: https://github.com/rhysd/actionlint rev: v1.7.7 hooks: - id: actionlint entry: actionlint -shellcheck='' - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.12.7 hooks: - id: ruff-check args: --fix, --exit-non-zero-on-fix, --unsafe-fixes - id: ruff-format - repo: https://github.com/astral-sh/uv-pre-commit rev: 0.8.4 hooks: - id: uv-lock 证据：`.pre-commit-config.yaml`\n- **Licence**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENCE`\n- **Include every file under src/mistral common**（source_file）：Include every file under src/mistral common recursive-include src/mistral common 证据：`MANIFEST.in`\n- **Create root index file**（source_file）：\"\"\"Generate the code API reference pages 证据：`docs/gen_api_pages.py`\n- **Mkdocs**（source_file）：site name: Mistral-common site url: https://mistralai.github.io/mistral-common/ site description: Mistral-common is a library of common utilities for Mistral AI. theme: name: material custom dir: ./docs/overrides logo: assets/logo.svg logo dark: assets/logo-dark.svg favicon: assets/logo favicon.png icon: repo: fontawesome/brands/github palette: - media: \" prefers-color-scheme: light \" primary: custom scheme: default toggle: icon: material/brightness-7 name: Switch to dark mode - media: \" prefers-color-scheme: dark \" primary: custom scheme: slate toggle: icon: material/brightness-4 name: Switch to light mode font: text: Poppins features: - navigation.instant - navigation.tabs - navigation.ta… 证据：`mkdocs.yml`\n- **Pyproject**（source_file）：build-system requires = \"setuptools =42\", \"wheel\", \"build\" build-backend = \"setuptools.build meta\" 证据：`pyproject.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/usage/install.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/usage/install.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍与安装**：importance `high`\n - source_paths: README.md, pyproject.toml, AGENTS.md\n- **项目架构总览**：importance `high`\n - source_paths: src/mistral_common/__init__.py, src/mistral_common/tokens/__init__.py, src/mistral_common/protocol/__init__.py, src/mistral_common/guidance/__init__.py, src/mistral_common/experimental/__init__.py\n- **分词器系统详解**：importance `high`\n - source_paths: src/mistral_common/tokens/tokenizers/tekken.py, src/mistral_common/tokens/tokenizers/sentencepiece.py, src/mistral_common/tokens/tokenizers/base.py, src/mistral_common/tokens/tokenizers/mistral.py, src/mistral_common/tokens/tokenizers/instruct.py\n- **多模态处理（图像与音频）**：importance `medium`\n - source_paths: src/mistral_common/tokens/tokenizers/image.py, src/mistral_common/tokens/tokenizers/audio.py, src/mistral_common/image.py, src/mistral_common/audio.py\n- **指令与填充中间（FIM）协议**：importance `high`\n - source_paths: src/mistral_common/protocol/instruct/request.py, src/mistral_common/protocol/fim/request.py, src/mistral_common/protocol/instruct/messages.py, src/mistral_common/protocol/instruct/chunk.py\n- **请求验证与标准化**：importance `high`\n - source_paths: 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\n- **语音与转录协议**：importance `medium`\n - source_paths: src/mistral_common/protocol/speech/request.py, src/mistral_common/protocol/transcription/request.py\n- **Grammar Factory 与 LLM Guidance**：importance `medium`\n - source_paths: src/mistral_common/guidance/grammar_factory.py, src/mistral_common/guidance/tokenizer.py, src/mistral_common/guidance/data/base_grammar.lark.jinja, src/mistral_common/guidance/data/think_grammar.lark.jinja, src/mistral_common/guidance/data/plain_text_think_grammar.lark.jinja\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `5693a4092b98828d68fac62d2fd44aa431b20165`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/index.md`, `docs/gen_api_pages.py`, `docs/examples/inference.md`, `docs/usage/tools.md`, `docs/usage/index.md`, `docs/usage/experimental.md`, `docs/usage/install.md`, `docs/usage/tokenizers.md`, `docs/usage/images.md`, `docs/usage/requests.md`, `src/mistral_common/exceptions.py`, `src/mistral_common/image.py`, `src/mistral_common/multimodal.py`, `src/mistral_common/__init__.py`, `src/mistral_common/imports.py`, `src/mistral_common/audio.py`, `src/mistral_common/base.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_750d0089d9e14ad385e0f49195987796 | https://github.com/mistralai/mistral-common/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b87372316a944057aa9d5cf9ae8797b3 | https://github.com/mistralai/mistral-common/issues/209 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_03f994c9b8a649a0a7723f5a7ac9a9c0 | https://github.com/mistralai/mistral-common/issues/210 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call'…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call', ...}\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_598dfde98fb44c46b9d95e5ee2a66d69 | https://github.com/mistralai/mistral-common/issues/211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:786756993 | https://github.com/mistralai/mistral-common | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.11.1: Patch for agentic use\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.11.1: Patch for agentic use\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2858129b86914e6090beed86fafe6db7 | https://github.com/mistralai/mistral-common/releases/tag/v1.11.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.8.7: Refactoring and bug fixes.\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.8.7: Refactoring and bug fixes.\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_cbca40b0e8be4f20a899d193e200fdd3 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：mistralai/mistral-common\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call'…（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/mistralai/mistral-common 项目说明书\n\n生成时间：2026-05-17 00:44:16 UTC\n\n## 目录\n\n- [项目介绍与安装](#p1)\n- [项目架构总览](#p2)\n- [分词器系统详解](#p3)\n- [多模态处理（图像与音频）](#p4)\n- [指令与填充中间（FIM）协议](#p5)\n- [请求验证与标准化](#p6)\n- [语音与转录协议](#p7)\n- [Grammar Factory 与 LLM Guidance](#p8)\n- [实验性功能（工具调用、思考解析、FastAPI 服务）](#p9)\n- [数据文件与模型版本管理](#p10)\n\n\n\n## 项目介绍与安装\n\n### 相关页面\n\n相关主题：[数据文件与模型版本管理](#p10), [项目架构总览](#p2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)\n- [AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)\n- [pyproject.toml](https://github.com/mistralai/mistral-common/blob/main/pyproject.toml)\n- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n \n\n# 项目介绍与安装\n\n## 1. 项目概述\n\nmistral-common 是 Mistral AI 开源的工具库集合，旨在帮助开发者更好地使用 Mistral AI 模型。该项目包含了令牌化器（tokenizers）、验证（validation）、规范化（normalization）等核心功能，可与 Mistral AI 的各种模型配合使用。\n\n资料来源：[README.md:1]()\n\n### 1.1 核心功能\n\n| 功能模块 | 描述 |\n|---------|------|\n| **令牌化（Tokenization）** | 提供 Tekken 令牌化器，用于对请求进行编码 |\n| **协议处理（Protocol）** | 支持 Instruct、FIM（Fill-In-The-Middle）和 Transcription 协议 |\n| **验证与规范化** | 对聊天补全请求进行验证和规范化处理 |\n| **多模态支持** | 支持图像和音频处理（可选依赖） |\n| **Grammar 引导** | 使用 llguidance 创建工具调用、JSON schema 和推理的 Lark 语法 |\n\n资料来源：[AGENTS.md:2]()\n\n### 1.2 技术栈\n\n| 技术项 | 要求 |\n|-------|------|\n| 编程语言 | Python 3.10 至 3.14 |\n| 包管理器 | uv |\n| 测试框架 | pytest |\n| 代码格式化 | Ruff |\n| 类型检查 | mypy |\n| 持续集成 | GitHub Actions |\n\n资料来源：[AGENTS.md:1]()\n\n## 2. 项目架构\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"用户请求层\"\n A[ChatCompletionRequest] --> B[验证器 Validator]\n B --> C[规范化器 Normalizer]\n C --> D[InstructRequest]\n end\n \n subgraph \"令牌化层\"\n D --> E[MistralTokenizer]\n E --> F[Tekken Tokenizer]\n end\n \n subgraph \"输出层\"\n F --> G[Tokenized 对象]\n end\n \n subgraph \"可选模块\"\n H[Image Encoder] -.-> E\n I[Audio Encoder] -.-> E\n end\n```\n\n### 2.2 目录结构\n\n```\nmistral-common/\n├── src/\n│ └── mistral_common/\n│ ├── protocol/ # 协议处理\n│ │ ├── instruct/ # Instruct 协议\n│ │ │ ├── request.py # ChatCompletionRequest 定义\n│ │ │ ├── normalize.py # 请求规范化器\n│ │ │ ├── validator.py # 请求验证器\n│ │ │ ├── messages.py # 消息定义\n│ │ │ └── tool_calls.py # 工具调用\n│ │ ├── fim/ # FIM 协议\n│ │ └── transcription/ # 转录协议\n│ ├── tokens/ # 令牌化\n│ │ └── tokenizers/ # 令牌化器实现\n│ │ ├── tekken.py # Tekken 令牌化器\n│ │ ├── mistral.py # Mistral 令牌化器\n│ │ ├── instruct.py # Instruct 令牌化器\n│ │ ├── image.py # 图像处理\n│ │ └── audio.py # 音频处理\n│ ├── guidance/ # Grammar 引导\n│ └── experimental/ # 实验性功能\n├── tests/ # 测试套件\n├── docs/ # 文档\n└── pyproject.toml # 项目配置\n```\n\n资料来源：[AGENTS.md:1-2]()\n\n## 3. 安装指南\n\n### 3.1 基础安装\n\n使用 pip 进行基础安装：\n\n```bash\npip install mistral-common\n```\n\n资料来源：[README.md:2]()\n\n### 3.2 可选依赖安装\n\nmistral-common 包含多个可选依赖模块，可以根据需要选择性安装：\n\n| 依赖项 | 功能 | 安装命令 |\n|-------|------|---------|\n| `image` | 图像处理支持 | `pip install \"mistral-common[image]\"` |\n| `audio` | 音频处理支持 | `pip install \"mistral-common[audio]\"` |\n| `hf-hub` | 从 Hugging Face Hub 下载令牌化器 | `pip install \"mistral-common[hf-hub]\"` |\n| `sentencepiece` | SentencePiece 令牌化器支持（已弃用） | `pip install \"mistral-common[sentencepiece]\"` |\n| `server` | 服务器模式运行令牌化器 | `pip install \"mistral-common[server]\"` |\n\n资料来源：[README.md:2-5]()\n\n### 3.3 安装所有依赖\n\n一次性安装所有可选依赖：\n\n```bash\npip install \"mistral-common[image,audio,hf-hub,sentencepiece,server]\"\n```\n\n资料来源：[README.md:7]()\n\n## 4. 快速入门\n\n### 4.1 基本使用示例\n\n```python\nfrom mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage\nfrom mistral_common.protocol.instruct.request import ChatCompletionRequest\nfrom mistral_common.protocol.instruct.normalize import InstructRequestNormalizer\n\n# 创建聊天补全请求\nrequest = ChatCompletionRequest(\n messages=[\n UserMessage(content=\"你好！\"),\n AssistantMessage(content=\"你好！有什么可以帮助你的吗？\"),\n ],\n)\n\n# 使用规范化器处理请求\nnormalizer = InstructRequestNormalizer.normalizer()\ninstruct_request = normalizer.from_chat_completion_request(request)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:20-30]()\n\n### 4.2 带工具调用的请求\n\n```python\nfrom mistral_common.protocol.instruct.tool_calls import Tool, ToolTypes, Function\n\n# 定义工具\ntool = Tool(\n function=Function(\n name=\"get_weather\",\n description=\"获取指定位置的天气信息\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"城市和州，例如 San Francisco, CA\",\n },\n },\n \"required\": [\"location\"],\n },\n ),\n)\n\n# 创建带工具的请求\nrequest = ChatCompletionRequest(\n messages=[UserMessage(content=\"北京今天天气怎么样？\")],\n tools=[tool],\n tool_choice=\"auto\",\n)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:30-45]()\n\n### 4.3 请求验证\n\n```python\nfrom mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode\nfrom mistral_common.protocol.instruct.messages import UserMessage\n\n# 创建验证器（测试模式）\nvalidator = MistralRequestValidator(mode=ValidationMode.test)\n\n# 创建请求\nrequest = ChatCompletionRequest(\n model=\"mistral-large-latest\",\n messages=[UserMessage(content=\"Hello!\")],\n)\n\n# 验证请求\nvalidated_request = validator.validate_request(request)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:20-40]()\n\n## 5. 开发环境配置\n\n### 5.1 环境设置\n\n使用 uv 进行开发环境配置：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/mistralai/mistral-common.git\ncd mistral-common\n\n# 创建虚拟环境\nuv venv\nsource .venv/bin/activate\n\n# 同步所有依赖和开发依赖\nuv sync --frozen --all-extras --group dev\n\n# 安装预提交钩子\nuv run pre-commit install\n```\n\n资料来源：[README.md:40-50]()\n\n### 5.2 代码质量检查\n\n项目使用以下工具进行代码质量控制：\n\n| 工具 | 用途 | 命令 |\n|-----|------|------|\n| Ruff | 代码格式化和检查 | `uv run ruff check .` |\n| mypy | 类型检查 | `uv run mypy src/` |\n| pytest | 测试运行 | `uv run pytest tests/` |\n| pre-commit | 自动化检查 | `uv run pre-commit run --all-files` |\n\n### 5.3 开发工作流\n\n```mermaid\ngraph LR\n A[修改代码] --> B[编写测试]\n B --> C[运行预提交检查]\n C --> D{Ruff 格式化}\n D --> E{类型检查}\n E --> F{运行测试}\n F --> G[提交代码]\n```\n\n资料来源：[AGENTS.md:25-35]()\n\n## 6. 核心组件详解\n\n### 6.1 ChatCompletionRequest\n\n`ChatCompletionRequest` 是用户查询的入口点，定义在 `src/mistral_common/protocol/instruct/request.py` 中。\n\n| 属性 | 类型 | 描述 |\n|-----|------|------|\n| `model` | `str \\| None` | 模型名称 |\n| `messages` | `list[ChatMessageType]` | 消息列表 |\n| `response_format` | `ResponseFormat` | 响应格式 |\n| `tools` | `list[Tool] \\| None` | 可用工具列表 |\n| `tool_choice` | `ToolChoice` | 工具选择策略 |\n| `truncate_for_context_length` | `bool` | 是否截断以适应上下文长度 |\n| `continue_final_message` | `bool` | 是否继续最终消息 |\n| `reasoning_effort` | `ReasoningEffort \\| None` | 推理努力程度 |\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:20-35]()\n\n### 6.2 令牌化器版本\n\nmistral-common 支持多个令牌化器版本：\n\n| 版本 | 图像支持 | 音频支持 | 说明 |\n|-----|---------|---------|------|\n| v1 | ❌ | ❌ | 基础版本 |\n| v2 | ❌ | ❌ | 改进版本 |\n| v3 | ✅ | ❌ | 支持图像处理 |\n| v7 | ✅ | ✅ | 支持图像和音频 |\n| v11 | ✅ | ✅ | 进一步改进 |\n| v13 | ✅ | ✅ | 最新版本 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()\n\n### 6.3 特殊令牌\n\nTekken 令牌化器定义了一系列特殊令牌：\n\n| 令牌名称 | 用途 |\n|---------|------|\n| `bos` | 句子开始 |\n| `eos` | 句子结束 |\n| `unk` | 未知词元 |\n| `eop` | 段落结束 |\n| `eod` | 文档结束 |\n| `begin_tool_results` | 工具结果开始 |\n| `end_tool_results` | 工具结果结束 |\n| `begin_tool_content` | 工具内容开始 |\n| `img` | 图像标记 |\n| `pad` | 填充令牌 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py:1-30]()\n\n## 7. 高级功能\n\n### 7.1 多模态处理\n\n#### 7.1.1 图像处理\n\n使用图像令牌化器需要安装 `image` 依赖：\n\n```bash\npip install \"mistral-common[image]\"\n```\n\n图像处理流程：\n\n```mermaid\ngraph TD\n A[图像文件] --> B[ImageEncoder]\n B --> C[编码的图像数据]\n C --> D[Tokenized 对象]\n```\n\n#### 7.1.2 音频处理\n\n使用音频令牌化器需要安装 `audio` 依赖：\n\n```bash\npip install \"mistral-common[audio]\"\n```\n\n### 7.2 服务器模式\n\n提供 FastAPI 服务器模式运行令牌化器：\n\n```bash\npip install \"mistral-common[server]\"\n```\n\n启动服务器：\n\n```bash\npython -m mistral_common.experimental.app.main serve \\\n --tokenizer-path /path/to/tokenizer \\\n --validation-mode test \\\n --host 127.0.0.1 \\\n --port 8000\n```\n\n资料来源：[src/mistral_common/experimental/app/main.py:1-50]()\n\n### 7.3 Grammar 引导\n\n使用 llguidance 创建语法引导的输出：\n\n```python\nfrom mistral_common.guidance.grammar_factory import GrammarFactory\n\n# 创建语法工厂\ngrammar_factory = GrammarFactory()\n\n# 生成工具调用的语法\ngrammar = grammar_factory.create_tool_call_grammar(tools=[tool])\n```\n\n资料来源：[AGENTS.md:12-15]()\n\n## 8. 贡献指南\n\n### 8.1 代码风格规范\n\n| 规范 | 要求 |\n|-----|------|\n| 命名规范 | 函数/变量使用 snake_case，类使用 PascalCase |\n| 类型提示 | 必须使用 Python 类型提示 |\n| 文档字符串 | 必须使用 Google 风格文档字符串 |\n| 导入规范 | 使用绝对导入，禁止通配符导入 |\n\n资料来源：[AGENTS.md:18-30]()\n\n### 8.2 提交规范\n\n- 使用祈使语气\n- 以动词开头\n- 保持简洁明了\n\n### 8.3 向后兼容性\n\n新增功能时必须确保不破坏现有功能。\n\n资料来源：[AGENTS.md:35-40]()\n\n## 9. 许可协议\n\nmistral-common 库采用 Apache 2.0 许可证。\n\n> **重要提示**：您不得以侵犯、侵犯或以其他方式违反任何第三方权利（包括知识产权）的方式使用本库或我们的模型。\n\n资料来源：[README.md:55-60]()\n\n## 10. 相关资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方文档 | https://mistralai.github.io/mistral-common/ |\n| PyPI 主页 | https://pypi.org/project/mistral-common/ |\n| GitHub Issues | https://github.com/mistralai/mistral-common/issues |\n| 模型下载 | Hugging Face Hub |\n\n---\n\n\n\n## 项目架构总览\n\n### 相关页面\n\n相关主题：[项目介绍与安装](#p1), [分词器系统详解](#p3), [请求验证与标准化](#p6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)\n- [AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/misturalai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n \n\n# 项目架构总览\n\n## 概述\n\nmistral-common 是 Mistral AI 官方开源的预处理库，专为 Mistral 大语言模型（LLM）设计。该库提供了一套完整的工具集，用于将用户请求编码为模型可处理的 token 序列，同时支持图像、音频等多模态数据的处理 资料来源：[README.md:1]()。\n\n### 技术栈\n\n| 类别 | 技术选型 |\n|------|---------|\n| 语言版本 | Python 3.10 - 3.14 |\n| 包管理器 | uv |\n| 测试框架 | pytest |\n| 代码格式 | Ruff |\n| 类型检查 | mypy |\n| 持续集成 | GitHub Actions |\n| 协议许可 | Apache 2.0 |\n\n资料来源：[AGENTS.md:1-10]()\n\n---\n\n## 核心架构设计\n\nmistral-common 采用分层架构设计，主要包含以下核心模块：\n\n```mermaid\ngraph TB\n subgraph \"表现层 (Protocol)\"\n P1[Instruct Protocol]\n P2[FIM Protocol]\n P3[Transcription Protocol]\n end\n \n subgraph \"处理层 (Tokens)\"\n T1[Instruct Tokenizer]\n T2[Mistral Tokenizer]\n T3[Tekken Tokenizer]\n end\n \n subgraph \"指导层 (Guidance)\"\n G1[Grammar Factory]\n G2[Token Guidance]\n end\n \n subgraph \"实验层 (Experimental)\"\n E1[Tool Calls Parser]\n E2[Think Parser]\n end\n \n P1 --> T1\n P2 --> T1\n P3 --> T1\n T1 --> T2\n T2 --> T3\n G1 --> G2\n```\n\n---\n\n## 模块详解\n\n### 1. 协议层 (Protocol)\n\n协议层是用户请求的入口点，负责定义和验证不同类型的请求格式 资料来源：[AGENTS.md:38-57]()。\n\n#### 1.1 Instruct Protocol\n\nInstruct Protocol 处理对话补全请求，是最常用的协议类型。\n\n| 组件文件 | 功能描述 |\n|---------|---------|\n| `request.py` | 定义 `ChatCompletionRequest`，用户查询的入口点 |\n| `messages.py` | 定义指导消息类型（UserMessage、AssistantMessage 等） |\n| `validator.py` | 验证请求结构和内容 |\n| `normalize.py` | 将请求转换为内部 instruct 格式 |\n| `tool_calls.py` | 工具调用逻辑处理 |\n| `converters.py` | 与 OpenAI 格式的转换辅助工具 |\n| `chunk.py` | 消息内容分块处理 |\n\n资料来源：[AGENTS.md:40-48]()\n\n#### 1.2 FIM Protocol\n\nFill-in-the-Middle 协议用于代码补全等中间填空任务：\n\n```python\n# 入口文件: src/mistral_common/protocol/fim/request.py\nclass FIMRequest(BaseCompletionRequest)\n```\n\n#### 1.3 Transcription Protocol\n\n音频转录协议处理音频文件的转录请求：\n\n```python\n# 入口文件: src/mistral_common/protocol/transcription/request.py\nclass TranscriptionRequest(BaseCompletionRequest)\n```\n\n---\n\n### 2. 令牌化层 (Tokens)\n\n令牌化层是核心处理引擎，负责将规范化后的请求编码为 token 序列 资料来源：[AGENTS.md:50-68]()。\n\n#### 2.1 架构层级\n\n```mermaid\ngraph LR\n A[用户请求] --> B[Validator 验证]\n B --> C[Normalizer 规范化]\n C --> D[MistralTokenizer]\n D --> E[InstructTokenizer]\n E --> F[TekkenTokenizer]\n F --> G[Token IDs]\n```\n\n#### 2.2 Tokenizer 类体系\n\n| Tokenizer 类型 | 文件位置 | 功能说明 |\n|---------------|---------|---------|\n| `Tokenizer` | `base.py` | 抽象基类，定义通用接口 |\n| `TekkenTokenizer` | `tekken.py` | Tekken 分词器，所有最新模型使用 |\n| `InstructTokenizerV1-V11` | `instruct.py` | Instruct 令牌化器版本实现 |\n| `MistralTokenizer` | `mistral.py` | 主令牌化器，编排验证和规范化流程 |\n| `AudioTokenizer` | `audio.py` | 音频数据处理 |\n\n资料来源：[AGENTS.md:50-66]()\n\n#### 2.3 Tokenizer 版本支持\n\nmistral-common 支持从 v1 到 v13 的多种 tokenizer 版本：\n\n| 版本 | 图像支持 | 音频支持 | 特殊说明 |\n|------|---------|---------|---------|\n| v1 | ❌ | ❌ | 基础版本 |\n| v2 | ❌ | ❌ | 增强验证 |\n| v3 | ✅ | ❌ | 引入图像编码器 |\n| v7 | ✅ | ✅ | 引入音频编码器 |\n| v11 | ✅ | ✅ | 性能优化 |\n| v13 | ✅ | ✅ | 最新版本 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-60]()\n\n---\n\n### 3. 验证与规范化流程\n\n#### 3.1 验证模式\n\n`MistralRequestValidator` 支持三种验证模式：\n\n| 模式 | 用途 |\n|------|------|\n| `test` | 默认模式，用于标准测试 |\n| `serving` | 服务模式，要求提供模型名称 |\n| `finetuning` | 微调模式 |\n\n```python\nclass ValidationMode(str, Enum):\n serving = \"serving\"\n finetuning = \"finetuning\"\n test = \"test\"\n```\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:1-20]()\n\n#### 3.2 规范化器\n\n`InstructRequestNormalizer` 负责将 `ChatCompletionRequest` 转换为内部 instruct 格式：\n\n```python\nclass InstructRequestNormalizer:\n def from_chat_completion_request(self, request: ChatCompletionRequest) -> InstructRequest\n```\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-40]()\n\n---\n\n### 4. 指导层 (Guidance)\n\nGuidance 模块使用 llguidance 库创建 Lark 语法，用于约束模型输出格式 资料来源：[AGENTS.md:70-77]()。\n\n| 组件 | 功能 |\n|------|------|\n| `grammar_factory.py` | 从 Jinja 模板构建和渲染 Lark 语法 |\n| `tokenizer.py` | 适配 Tekken 分词器用于 llguidance |\n| `data/` | 包含 base、thinking 等模式的语法模板文件 |\n\n---\n\n### 5. 实验性功能 (Experimental)\n\nexperimental 模块包含尚未稳定的功能：\n\n| 组件 | 功能 |\n|------|------|\n| `tools.py` | 工具调用解析器 |\n| `think.py` | 思考模式解析器 |\n| `utils.py` | 通用工具函数 |\n| `app/` | FastAPI 应用，包含路由器和入口点 |\n\n资料来源：[AGENTS.md:79-88]()\n\n---\n\n### 6. 根级工具模块\n\n| 模块文件 | 功能描述 |\n|---------|---------|\n| `audio.py` | 音频处理工具，包含 Audio 类和梅尔刻度转换 |\n| `image.py` | 图像下载和序列化处理 |\n| `base.py` | Pydantic 模型基础配置 |\n| `exceptions.py` | 自定义异常类 |\n| `imports.py` | 导入工具和依赖检查 |\n\n资料来源：[AGENTS.md:28-37]()\n\n---\n\n## 数据流架构\n\n```mermaid\nflowchart TD\n A[ChatCompletionRequest] --> B[MistralRequestValidator]\n B --> C{验证通过?}\n C -->|否| D[抛出异常]\n C -->|是| E[InstructRequestNormalizer]\n E --> F[InstructRequest]\n F --> G[MistralTokenizer]\n G --> H[InstructTokenizer]\n H --> I[TekkenTokenizer]\n I --> J[Tokenized 对象]\n \n K[Tokenized.tokens] --> L[模型输入]\n M[Tokenized.images] --> N[多模态处理]\n O[Tokenized.audios] --> P[音频处理]\n```\n\n---\n\n## 项目目录结构\n\n```\nmistral-common/\n├── src/\n│ └── mistral_common/\n│ ├── protocol/ # 协议层\n│ │ ├── instruct/ # 对话补全协议\n│ │ ├── fim/ # 填空协议\n│ │ ├── transcription/ # 转录协议\n│ │ ├── base.py # 基础请求类\n│ │ └── utils.py # 工具函数\n│ ├── tokens/ # 令牌化层\n│ │ ├── tokenizers/ # 分词器实现\n│ │ └── instruct/ # (已废弃)\n│ ├── guidance/ # 指导层\n│ ├── experimental/ # 实验性功能\n│ ├── audio.py # 音频处理\n│ ├── image.py # 图像处理\n│ ├── base.py # 基础配置\n│ └── exceptions.py # 异常定义\n├── tests/ # 测试套件\n├── docs/ # 文档\n├── .github/workflows/ # CI/CD 工作流\n├── pyproject.toml # 项目配置\n└── README.md # 项目说明\n```\n\n资料来源：[AGENTS.md:12-26]()\n\n---\n\n## 依赖管理\n\nmistral-common 采用可选依赖设计，各功能模块可独立安装：\n\n```sh\n# 图像处理\npip install \"mistral-common[image]\"\n\n# 音频处理\npip install \"mistral-common[audio]\"\n\n# HuggingFace Hub 支持\npip install \"mistral-common[hf-hub]\"\n\n# SentencePiece 支持 (已废弃)\npip install \"mistral-common[sentencepiece]\"\n\n# 服务器模式\npip install \"mistral-common[server]\"\n\n# 安装全部依赖\npip install \"mistral-common[image,audio,hf-hub,sentencepiece,server]\"\n```\n\n资料来源：[README.md:1-20]()\n\n---\n\n## 核心类关系图\n\n```mermaid\nclassDiagram\n class BaseCompletionRequest {\n <>\n }\n \n class ChatCompletionRequest {\n +messages: list[ChatMessageType]\n +tools: list[Tool]\n +response_format: ResponseFormat\n +to_openai(): dict\n }\n \n class InstructRequest {\n +messages\n +system_prompt\n +available_tools\n }\n \n class Tokenized {\n +tokens: list[int]\n +text: str\n +prefix_ids: list[int]\n +images: list[np.ndarray]\n +audios: list[Audio]\n }\n \n class MistralRequestValidator {\n +validate_request()\n +validate_messages()\n +_validate_tools()\n }\n \n class InstructRequestNormalizer {\n +from_chat_completion_request()\n }\n \n class Tokenizer {\n <>\n +vocab()\n +id_to_piece()\n }\n \n BaseCompletionRequest <|-- ChatCompletionRequest\n ChatCompletionRequest --> MistralRequestValidator\n ChatCompletionRequest --> InstructRequestNormalizer\n InstructRequestNormalizer ..> InstructRequest\n MistralTokenizer --> Tokenized\n MistralTokenizer --> InstructRequestNormalizer\n MistralTokenizer --|> Tokenizer\n```\n\n---\n\n## 开发指南\n\n### 代码规范\n\n| 规范类型 | 具体要求 |\n|---------|---------|\n| 命名 | 函数/变量使用 snake_case，类使用 PascalCase |\n| 类型提示 | 必须使用，优先采用 Python 3.10+ 语法 |\n| 文档字符串 | 采用 Google 风格，包含 Args/Returns |\n| 错误处理 | 使用 `mistral_common.exceptions` 中的自定义异常 |\n\n资料来源：[AGENTS.md:95-110]()\n\n### 开发工作流\n\n1. **环境配置**：使用 uv 同步开发环境\n2. **代码编写**：遵循代码规范，编写测试用例\n3. **代码检查**：运行 Ruff、mypy、pytest\n4. **提交**：安装 pre-commit hooks 后提交\n\n```bash\nuv sync --frozen --all-extras --group dev --python 3.12\nsource .venv/bin/activate\nuv run pre-commit install\n```\n\n资料来源：[AGENTS.md:112-126]()\n\n---\n\n## 总结\n\nmistral-common 作为 Mistral AI 模型的官方预处理库，通过分层架构实现了请求验证、规范化和令牌化的完整流程。库的设计强调模块化、可扩展性和类型安全，支持从简单的文本对话到复杂的多模态输入场景。开发者可通过清晰定义的接口扩展新功能，同时保持与现有系统的高度兼容性。\n\n---\n\n\n\n## 分词器系统详解\n\n### 相关页面\n\n相关主题：[多模态处理（图像与音频）](#p4), [指令与填充中间（FIM）协议](#p5), [项目架构总览](#p2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n- [src/mistral_common/tokens/tokenizers/sentencepiece.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/sentencepiece.py)\n- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n- [src/mistral_common/tokens/tokenizers/instruct.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/instruct.py)\n \n\n# 分词器系统详解\n\n## 概述\n\nmistral-common 的分词器系统是连接文本请求与大语言模型的核心组件，负责将用户输入的文本转换为模型可处理的 token 序列，以及将模型的输出 token 序列还原为可读文本。该系统支持多种 tokenizer 版本，从早期的 SentencePiece 实现到最新的 Tekken 分词器，为 Mistral 各代模型提供统一的文本处理能力。\n\n分词器系统的主要职责包括：\n- **编码（Encode）**：将原始文本转换为 token ID 序列\n- **解码（Decode）**：将 token ID 序列转换回可读文本\n- **特殊标记处理**：管理模型使用的特殊标记（如 ``、``、`[INST]` 等）\n- **多模态支持**：处理图像和音频内容（部分版本）\n- **请求验证**：在编码前验证请求格式的正确性\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n\n## 架构设计\n\n### 分词器类型层次\n\n分词器系统采用分层架构设计，从底层的字符级别编码到高层的请求处理，形成清晰的职责划分：\n\n```mermaid\ngraph TD\n A[MistralTokenizer
高层入口] --> B[InstructTokenizer
指令编码器]\n B --> C[TekkenTokenizer
核心分词器]\n C --> D[Base Model
底层编码模型]\n \n E[SentencePieceTokenizer
已废弃] -.-> D\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n### 核心组件关系\n\n| 组件 | 文件位置 | 职责 | 状态 |\n|------|---------|------|------|\n| `MistralTokenizer` | mistral.py | 高层工厂类，负责版本选择和组件组装 | 活跃 |\n| `InstructTokenizer` | instruct.py | 将请求编码为 token 序列 | 活跃 |\n| `TekkenTokenizer` | tekken.py | 核心分词实现，支持 v11+ | 活跃 |\n| `SentencePieceTokenizer` | sentencepiece.py | 旧版分词实现 | 已废弃 |\n\n## Tekken 分词器\n\nTekken 是 Mistral 最新模型使用的分词器实现，相比 SentencePiece 具有更好的性能和更丰富的功能支持。\n\n### 特殊标记定义\n\nTekken 分词器定义了一套完整的特殊标记系统，用于标识文本结构、工具调用、图像等不同内容类型：\n\n| 标记名称 | 标记字符串 | 用途 | 优先级 |\n|---------|-----------|------|--------|\n| unk | `` | 未知词元 | 1 |\n| bos | `` | 序列起始 | 2 |\n| eos | `` | 序列结束 | 3 |\n| begin_inst | `[INST]` | 指令开始 | 4 |\n| end_inst | `[/INST]` | 指令结束 | 5 |\n| begin_tools | `[AVAILABLE_TOOLS]` | 工具列表开始 | 6 |\n| end_tools | `[/AVAILABLE_TOOLS]` | 工具列表结束 | 7 |\n| begin_tool_results | `[TOOL_RESULTS]` | 工具结果开始 | 8 |\n| end_tool_results | `[/TOOL_RESULTS]` | 工具结果结束 | 9 |\n| tool_calls | `[TOOL_CALLS]` | 工具调用标记 | 10 |\n| img | `[IMG]` | 图像标记 | 11 |\n| pad | `` | 填充标记 | 12 |\n| img_break | `[IMG_BREAK]` | 图像截断标记 | 13 |\n| img_end | `[IMG_END]` | 图像结束标记 | 14 |\n| prefix | `[PREFIX]` | FIM 前缀标记 | 15 |\n| middle | `[MIDDLE]` | FIM 中间标记 | 16 |\n| suffix | `[SUFFIX]` | FIM 后缀标记 | 17 |\n| begin_system | `[SYSTEM_PROMPT]` | 系统提示开始 | 18 |\n| end_system | `[/SYSTEM_PROMPT]` | 系统提示结束 | 19 |\n| begin_tool_content | `[TOOL_CONTENT]` | 工具内容开始 | 20 |\n| begin_think | `[THINK]` | 思考开始 | 21 |\n| end_think | `[/THINK]` | 思考结束 | 22 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n### 特殊标记策略\n\n`SpecialTokenPolicy` 枚举控制分词器在解码时如何处理特殊标记：\n\n```python\nclass SpecialTokenPolicy(str, Enum):\n \"\"\"What to do with special tokens when encoding/decoding.\"\"\"\n \n IGNORE = \"ignore\" # 解码时跳过特殊标记\n KEEP = \"keep\" # 解码时保留特殊标记\n RAISE = \"raise\" # 遇到特殊标记时抛出异常\n```\n\n使用示例：\n```python\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\nfrom mistral_common.tokens.tokenizers.tekken import SpecialTokenPolicy\n\ntokenizer = MistralTokenizer.v3(is_tekken=True)\ntekken = tokenizer.instruct_tokenizer.tokenizer\ntekken.special_token_policy = SpecialTokenPolicy.IGNORE\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n### 核心 API\n\nTekkenTokenizer 提供以下核心接口：\n\n| 方法/属性 | 返回类型 | 说明 |\n|----------|---------|------|\n| `n_words` | `int` | 词表大小 |\n| `special_ids` | `set[int]` | 特殊标记的 ID 集合 |\n| `num_special_tokens` | `int` | 特殊标记数量 |\n| `vocab()` | `list[str]` | 返回所有词表 token |\n| `id_to_piece(token_id)` | `str` | 将 token ID 转换为字符串 |\n| `encode(text)` | `Tokenized` | 编码文本 |\n| `decode(tokens)` | `str` | 解码 token 序列 |\n| `is_byte(token_id)` | `bool` | 检查是否为字节 token |\n| `is_special(token)` | `bool` | 检查是否为特殊标记 |\n| `get_special_token(s)` | `int` | 获取特殊标记的 ID |\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n\n## Tokenized 数据结构\n\n`Tokenized` 是分词结果的核心数据结构，用于在系统各组件间传递编码后的数据：\n\n```python\nclass Tokenized:\n \"\"\"Represents a tokenized request or response.\"\"\"\n \n model_config = ConfigDict(arbitrary_types_allowed=True)\n tokens: list[int] # Token ID 列表\n text: str | None = None # 原始文本（解码时使用）\n prefix_ids: list[int] | None = None # FIM 前缀 ID\n images: list[np.ndarray] = Field(default_factory=list) # 关联图像\n audios: list[Audio] = Field(default_factory=list) # 关联音频\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n\n## 分词器版本演进\n\nmistral-common 支持多个 tokenizer 版本，以适配不同代际的 Mistral 模型：\n\n| 版本 | 图像支持 | 音频支持 | 推荐用途 |\n|------|---------|---------|---------|\n| v1 | ❌ | ❌ | 早期模型兼容 |\n| v2 | ❌ | ❌ | 早期模型兼容 |\n| v3 | ✅ | ❌ | 图像支持模型 |\n| v7 | ✅ | ❌ | 高级推理模型 |\n| v11 | ✅ | ✅ | 最新模型（推荐） |\n| v13 | ✅ | ✅ | 最新模型（最新） |\n\n版本创建逻辑：\n```python\nif tokenizer.version == TokenizerVersion.v1:\n return MistralTokenizer(InstructTokenizerV1(tokenizer), ...)\nelif tokenizer.version == TokenizerVersion.v11:\n return MistralTokenizer(\n InstructTokenizerV11(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),\n ...\n )\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n## MistralTokenizer 工厂类\n\n`MistralTokenizer` 是系统的高层入口，提供版本感知的分词器创建能力：\n\n### 创建方法\n\n| 静态方法 | 说明 | 适用版本 |\n|---------|------|---------|\n| `v1()` | 创建 v1 分词器 | v1 |\n| `v2()` | 创建 v2 分词器 | v2 |\n| `v3()` | 创建 v3 分词器 | v3 |\n| `v7()` | 创建 v7 分词器 | v7 |\n| `v11()` | 创建 v11 分词器 | v11 |\n| `v13()` | 创建 v13 分词器 | v13 |\n| `from_path(path)` | 从路径加载分词器 | 所有版本 |\n\n### 核心属性\n\n| 属性 | 类型 | 说明 |\n|-----|------|------|\n| `instruct_tokenizer` | `InstructTokenizer` | 指令编码器实例 |\n| `validator` | `MistralRequestValidator` | 请求验证器 |\n| `request_normalizer` | `InstructRequestNormalizer` | 请求标准化器 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n## 解码流程\n\n解码过程处理 token 序列到文本的转换，需要正确处理特殊标记：\n\n```mermaid\ngraph LR\n A[Token ID 序列] --> B{特殊标记策略?}\n B -->|KEEP| C[保留特殊标记字符串]\n B -->|IGNORE| D[跳过特殊标记]\n B -->|RAISE| E[抛出异常]\n C --> F[普通 token 解码]\n D --> F\n F --> G[拼接结果]\n C --> G\n```\n\n解码实现核心逻辑：\n```python\ndef decode(self, tokens: list[int], ...) -> str:\n decoded = []\n for t in tokens:\n if t in self._all_special_tokens:\n if special_token_policy == SpecialTokenPolicy.RAISE:\n raise ValueError(\"...\")\n elif special_token_policy == SpecialTokenPolicy.KEEP:\n decoded.append(self._all_special_tokens[t][\"token_str\"])\n elif special_token_policy == SpecialTokenPolicy.IGNORE:\n continue\n else:\n decoded.append(self._model.decode([t - self.num_special_tokens]))\n return \"\".join(decoded)\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n## 与 Guidance 系统集成\n\nGrammarFactory 使用分词器生成语法约束，用于控制模型输出的格式。该集成需要 Tekken tokenizer 版本 >= v11：\n\n```python\nclass GrammarFactory:\n def __init__(self, tokenizer):\n assert_llguidance_installed()\n assert_jinja2_installed()\n self._tokenizer = tokenizer.instruct_tokenizer.tokenizer\n \n if not self.is_supported(tokenizer):\n raise ValueError(\n f\"Guidance requires a Tekken tokenizer with version >= v11, \"\n f\"got {type(self._tokenizer).__name__} {self._tokenizer.version.value}\"\n )\n self._llg_tokenizer = from_mistral_tokenizer(tokenizer)\n self._special_token_map = self._build_special_token_map()\n```\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/grammar_factory.py)\n\n## 使用示例\n\n### 基础编码解码\n\n```python\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\n\n# 加载分词器\ntokenizer = MistralTokenizer.v3()\n\n# 编码文本\ntokenized = tokenizer.instruct_tokenizer.encode(\"Hello, how are you?\")\nprint(f\"Token IDs: {tokenized.tokens}\")\nprint(f\"Token count: {len(tokenized.tokens)}\")\n\n# 解码文本\ndecoded = tokenizer.instruct_tokenizer.decode(tokenized.tokens)\nprint(f\"Decoded: {decoded}\")\n```\n\n### 处理多模态内容（v11+）\n\n```python\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\nfrom mistral_common.image import Image\n\ntokenizer = MistralTokenizer.v11()\n\n# 处理包含图像的请求\nimage = Image.from_url(\"https://example.com/image.jpg\")\ntokenized = tokenizer.instruct_tokenizer.encode(\n \"Describe this image\",\n images=[image]\n)\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n## 弃用说明\n\n### SentencePieceTokenizer\n\n`SentencePieceTokenizer` 已弃用，仅保留用于向后兼容。推荐使用 Tekken 分词器：\n\n| 特性 | SentencePiece | Tekken |\n|------|--------------|--------|\n| 性能 | 较低 | 高 |\n| 特殊标记支持 | 有限 | 完整 |\n| 多模态支持 | ❌ | ✅ |\n| Guidance 集成 | ❌ | ✅ |\n| 状态 | 已废弃 | 活跃 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/sentencepiece.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/sentencepiece.py)\n\n## 总结\n\nmistral-common 的分词器系统提供了从底层编码到高层请求处理的完整能力栈。核心要点：\n\n1. **Tekken 是推荐的实现**：相比废弃的 SentencePiece，提供更好的性能和更完整的功能\n2. **版本分层设计**：通过 `MistralTokenizer` 工厂类统一管理不同版本的分词器\n3. **特殊标记策略**：通过 `SpecialTokenPolicy` 灵活控制特殊标记的解码行为\n4. **多模态扩展**：v3+ 版本支持图像处理，v11+ 版本支持音频处理\n5. **与 Guidance 集成**：v11+ 版本可与 GrammarFactory 配合进行结构化输出控制\n\n---\n\n\n\n## 多模态处理（图像与音频）\n\n### 相关页面\n\n相关主题：[分词器系统详解](#p3), [指令与填充中间（FIM）协议](#p5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/tokens/tokenizers/image.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/image.py)\n- [src/mistral_common/tokens/tokenizers/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/audio.py)\n- [src/mistral_common/image.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/image.py)\n- [src/mistral_common/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/audio.py)\n- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n \n\n# 多模态处理（图像与音频）\n\n## 概述\n\nmistral-common 库提供了完整的多模态处理能力，支持在文本对话中嵌入图像和音频内容。该模块是预处理管道的核心组成部分，负责将用户提供的多模态数据（图像、音频）转换为模型可处理的 token 序列。\n\n多模态处理的核心设计目标是：\n\n- **图像支持**：从 v3 版本 tokenizer 开始引入，支持图像下载、预处理和 token 化\n- **音频支持**：从 v7 版本 tokenizer 开始引入，支持音频编码和解码\n- **无缝集成**：与现有的 ChatCompletionRequest 协议完全兼容\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()\n\n## 架构设计\n\n### 多模态处理流程\n\n```mermaid\ngraph TD\n A[ChatCompletionRequest] --> B[请求验证 Validator]\n B --> C[请求标准化 Normalizer]\n C --> D{多模态类型判断}\n \n D -->|仅文本| E[InstructTokenizer - 纯文本编码]\n D -->|含图像| F[ImageEncoder + InstructTokenizerV3/V7/V11/V13/V15]\n D -->|含音频| G[AudioEncoder + InstructTokenizerV7/V11/V13/V15]\n D -->|图像+音频| H[ImageEncoder + AudioEncoder + 组合Tokenizer]\n \n E --> I[Tokenized 对象]\n F --> I\n G --> I\n H --> I\n \n I --> J[模型输入]\n```\n\n### 核心组件关系\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| Tokenized | `tokens/tokenizers/base.py` | 多模态 token 化结果的数据结构 |\n| ImageEncoder | `tokens/tokenizers/image.py` | 图像编码器接口 |\n| AudioEncoder | `tokens/tokenizers/audio.py` | 音频编码器接口 |\n| MistralTokenizer | `tokens/tokenizers/mistral.py` | 综合 tokenizer，支持图像和音频 |\n| Image 工具类 | `image.py` | 图像下载和序列化工具 |\n| Audio 工具类 | `audio.py` | 音频处理和 mel-scale 转换 |\n\n## Tokenized 数据结构\n\n多模态处理的结果通过 `Tokenized` 类表示，该类继承自 Pydantic BaseModel，支持灵活的多模态数据存储：\n\n```python\nclass Tokenized(MistralBase):\n \"\"\"Represents the tokenized output of a tokenizer.\n \n Attributes:\n tokens: The token ids.\n text: The text representation of the tokens.\n prefix_ids: The prefix ids for FIM.\n images: The loaded images associated with the tokens.\n audios: The audio objects associated with the tokens.\n \"\"\"\n model_config = ConfigDict(arbitrary_types_allowed=True)\n tokens: list[int]\n text: str | None = None\n prefix_ids: list[int] | None = None\n images: list[np.ndarray] = Field(default_factory=list)\n audios: list[Audio] = Field(default_factory=list)\n```\n\n**字段说明**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `tokens` | `list[int]` | token ID 序列，模型的核心输入 |\n| `text` | `str \\| None` | token 对应的文本表示 |\n| `prefix_ids` | `list[int] \\| None` | FIM（Fill-In-The-Middle）任务的 prefix token |\n| `images` | `list[np.ndarray]` | 预处理后的图像 NumPy 数组列表 |\n| `audios` | `list[Audio]` | 处理后的音频对象列表 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py:50-65]()\n\n## 图像处理\n\n### 安装依赖\n\n图像处理需要安装 `image` 额外依赖：\n\n```sh\npip install \"mistral-common[image]\"\n```\n\n### ImageEncoder 接口\n\n`ImageEncoder` 是一个抽象基类，定义了图像编码的标准接口：\n\n```python\nclass ImageEncoder(ABC):\n @abstractmethod\n def encode_images(self, images: list[np.ndarray]) -> list[ImageOutput]:\n \"\"\"Encode a list of images into model input format.\"\"\"\n \n @property\n @abstractmethod\n def image_token_id(self) -> int:\n \"\"\"The token id for image tokens.\"\"\"\n```\n\n### 图像处理工具类\n\n`mistral_common.image` 模块提供了图像处理的核心工具函数：\n\n```python\nclass Image(MistralBase):\n \"\"\"Image representation with download and serialization support.\"\"\"\n url: str | None = None\n base64: str | None = None\n content: bytes | None = None\n```\n\n主要功能：\n\n- **图像下载**：支持从 URL 下载图像内容\n- **Base64 编码/解码**：支持 base64 格式的图像数据\n- **预处理**：将图像转换为 NumPy 数组格式\n- **序列化**：支持图像数据的序列化和反序列化\n\n资料来源：[src/mistral_common/image.py:1-100]()\n\n### 特殊 Token\n\n图像相关的特殊 Token 定义在 `SpecialTokens` 类中：\n\n| Token | 标识 | 用途 |\n|-------|------|------|\n| `img` | `[IMG]` | 图像开始标记 |\n| `img_break` | `[IMG_BREAK]` | 多图像分隔标记 |\n| `img_end` | `[IMG_END]` | 图像结束标记 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py:100-110]()\n\n## 音频处理\n\n### 安装依赖\n\n音频处理需要安装 `audio` 额外依赖：\n\n```sh\npip install \"mistral-common[audio]\"\n```\n\n### AudioEncoder 接口\n\n`AudioEncoder` 是音频编码器的抽象基类：\n\n```python\nclass AudioEncoder(ABC):\n @abstractmethod\n def encode_audio(self, audio: Audio) -> AudioOutput:\n \"\"\"Encode a single audio object into model input format.\"\"\"\n```\n\n### Audio 数据类\n\n`Audio` 类是音频数据的核心表示：\n\n```python\nclass Audio(MistralBase):\n \"\"\"Audio representation with mel-scale conversion support.\"\"\"\n # 音频采样数据\n samples: np.ndarray\n # 采样率\n sample_rate: int\n # 编码格式\n format: str | None = None\n```\n\n主要功能：\n\n- **音频采样表示**：以 NumPy 数组形式存储音频采样数据\n- **采样率管理**：记录和验证音频采样率\n- **Mel-scale 转换**：支持梅尔频谱转换用于模型处理\n- **格式支持**：支持多种音频编码格式\n\n资料来源：[src/mistral_common/audio.py:1-100]()\n\n### 音频相关特殊 Token\n\n| Token | 标识 | 用途 |\n|-------|------|------|\n| `audio` | `[AUDIO]` | 音频 token 标记 |\n| `begin_audio` | `[BEGIN_AUDIO]` | 音频内容开始 |\n| `transcribe` | `[TRANSCRIBE]` | 转录指令 |\n| `text_to_audio` | `[NEXT_AUDIO_TEXT]` | 文本转语音输出标记 |\n| `audio_to_text` | `[REPEAT_AUDIO_TEXT]` | 语音转文本标记 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/base.py:110-120]()\n\n## Tokenizer 版本与多模态支持\n\n不同版本的 tokenizer 支持不同的多模态功能：\n\n| Tokenizer 版本 | 图像支持 | 音频支持 | 特点 |\n|----------------|----------|----------|------|\n| v1 | ❌ | ❌ | 纯文本 tokenizer |\n| v2 | ❌ | ❌ | 纯文本 tokenizer |\n| v3 | ✅ | ❌ | 引入图像支持 |\n| v7 | ✅ | ✅ | 引入音频支持 |\n| v11 | ✅ | ✅ | 增强的多模态支持 |\n| v13 | ✅ | ✅ | 最新稳定版本 |\n| v15 | ✅ | ✅ | 最新版本 |\n\n**版本断言检查**：\n\n```python\ndef create_tokenizer(tokenizer_filename, image_encoder=None, audio_encoder=None):\n if tokenizer.version == TokenizerVersion.v3:\n assert image_encoder is not None, \"Tokenizer version v3 requires image_encoder\"\n assert audio_encoder is None, \"Tokenizer version v3 does not support audio\"\n elif tokenizer.version == TokenizerVersion.v7:\n # v7+ 支持音频编码器\n ...\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:30-80]()\n\n## ChatCompletionRequest 中的多模态支持\n\n`ChatCompletionRequest` 是多模态请求的入口点，通过 `messages` 字段携带多模态内容：\n\n```python\nclass ChatCompletionRequest(MistralBase):\n \"\"\"Chat completion request with multimodal support.\"\"\"\n \n model: str | None = None\n messages: list[ChatMessageType] # 可包含图像/音频消息\n response_format: ResponseFormat = Field(default_factory=ResponseFormat)\n tools: list[Tool] | None = None\n tool_choice: ToolChoice = ToolChoiceEnum.auto\n truncate_for_context_length: bool = False\n continue_final_message: bool = False\n reasoning_effort: ReasoningEffort | None = None # 推理控制参数\n```\n\n**消息类型层次结构**：\n\n- `UserMessage`：用户消息，可包含文本、图像、音频\n- `AssistantMessage`：助手回复消息\n- `SystemMessage`：系统提示消息\n- `ToolMessage`：工具调用结果消息\n\n## 完整编码流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Validator as MistralRequestValidator\n participant Normalizer as InstructRequestNormalizer\n participant Tokenizer as MistralTokenizer\n participant Encoder as Image/Audio Encoder\n participant Model as 底座模型\n\n Client->>Validator: ChatCompletionRequest (含多模态)\n Validator->>Validator: 验证消息结构\n Validator->>Validator: 验证工具定义\n Validator->>Normalizer: 验证通过的请求\n Normalizer->>Normalizer: 标准化消息格式\n Normalizer->>Tokenizer: InstructRequest\n alt 包含图像\n Tokenizer->>Encoder: 调用 ImageEncoder\n Encoder-->>Tokenizer: ImageOutput\n end\n alt 包含音频\n Tokenizer->>Encoder: 调用 AudioEncoder\n Encoder-->>Tokenizer: AudioOutput\n end\n Tokenizer->>Tokenizer: 生成 token 序列\n Tokenizer-->>Client: Tokenized 对象\n Client->>Model: tokens + images + audios\n```\n\n## 使用示例\n\n### 基本图像编码\n\n```python\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\nfrom mistral_common.image import Image\nimport numpy as np\n\n# 初始化 tokenizer\ntokenizer = MistralTokenizer.from_filename(\"path/to/tokenizer\")\n\n# 准备图像数据\nimage_array = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)\n\n# 创建 Tokenized 结果\ntokenized = tokenizer.encode_images([image_array])\n```\n\n### 音频编码\n\n```python\nfrom mistral_common.audio import Audio\nfrom mistral_common.tokens.tokenizers.audio import AudioEncoder\nimport numpy as np\n\n# 创建音频对象\naudio = Audio(\n samples=np.random.randn(16000), # 1秒音频，16kHz采样率\n sample_rate=16000\n)\n\n# 通过 tokenizer 编码\ntokenized = tokenizer.encode(audio)\n```\n\n### 完整对话请求\n\n```python\nfrom mistral_common.protocol.instruct.request import ChatCompletionRequest\nfrom mistral_common.protocol.instruct.messages import UserMessage\nfrom mistral_common.tokens.tokenizers.mistral import MistralTokenizer\n\n# 创建带图像的用户消息\nrequest = ChatCompletionRequest(\n messages=[\n UserMessage(\n content=\"这张图片中有什么?\",\n images=[image_data] # 图像数据\n )\n ],\n model=\"mistral-large-latest\"\n)\n\n# 编码请求\ntokenizer = MistralTokenizer.from_filename(\"path/to/tokenizer\")\ntokenized = tokenizer.encode_chat_completion(request)\n```\n\n## 最佳实践\n\n1. **版本选择**：生产环境建议使用 v13 或 v15 版本，以获得完整的多模态支持\n2. **图像预处理**：在传入 tokenizer 前，确保图像尺寸符合模型要求\n3. **音频采样率**：验证音频采样率与模型预期一致（通常为 16kHz 或 24kHz）\n4. **上下文截断**：设置 `truncate_for_context_length=True` 以处理超长输入\n5. **错误处理**：使用 `InvalidRequestException` 捕获验证错误\n\n## 相关文档\n\n- [工具调用（Tool Calls）](./tool_calls.md)\n- [指导语法（Grammar）](./grammar.md)\n- [请求协议（Request Protocol）](./request_protocol.md)\n- [API 参考文档](https://mistralai.github.io/mistral-common/)\n\n---\n\n\n\n## 指令与填充中间（FIM）协议\n\n### 相关页面\n\n相关主题：[请求验证与标准化](#p6), [语音与转录协议](#p7), [分词器系统详解](#p3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n- [src/mistral_common/protocol/fim/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/fim/request.py)\n- [src/mistral_common/protocol/instruct/messages.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/messages.py)\n- [src/mistral_common/protocol/instruct/chunk.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/chunk.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n- [src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n \n\n# 指令与填充中间（FIM）协议\n\n## 概述\n\nmistral-common 库支持两种主要的协议类型，用于处理不同场景下的请求：\n\n| 协议类型 | 用途 | 请求类 | 主要特性 |\n|---------|------|--------|---------|\n| **Instruct 协议** | 对话式指令任务 | `ChatCompletionRequest` | 支持多轮对话、工具调用、响应格式控制 |\n| **FIM 协议** | 填充中间代码补全 | `FIMRequest` | 支持 prompt/suffix 模式进行代码补全 |\n\nInstruct 协议是用户查询 Instruct 请求的入口点，而 FIM（Fill-in-the-Middle）协议专门用于代码补全场景，模型需要在给定的前缀（prompt）和后缀（suffix）之间生成内容。资料来源：[src/mistral_common/protocol/fim/request.py:1-15]()\n\n---\n\n## FIM 协议\n\n### 概述\n\nFIM（Fill-in-the-Middle）协议是一种用于代码补全的特殊协议。与传统的前缀补全不同，FIM 允许模型在两个已知部分（prefix 和 suffix）之间生成内容，这非常适合以下场景：\n\n- 在函数签名和函数结尾之间补全函数体\n- 在类的开头和结尾之间补全类成员\n- 在代码块的开始和结束标记之间补全内容\n\n### 数据模型\n\n```python\nclass FIMRequest(BaseCompletionRequest):\n \"\"\"填充中间请求模型\"\"\"\n \n prompt: str # 前缀内容\n suffix: str | None = None # 后缀内容（可选）\n```\n\n**字段说明：**\n\n| 字段名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `prompt` | `str` | 是 | 要补全内容的前缀部分 |\n| `suffix` | `str \\| None` | 否 | 要补全内容的后缀部分。如果提供，模型将在 prompt 和 suffix 之间生成文本 |\n\n### 使用示例\n\n```python\nfrom mistral_common.protocol.fim.request import FIMRequest\n\n# 基础用法\nrequest = FIMRequest(prompt='def calculate_sum(a, b):\\n \"\"\"Calculate sum of two numbers\"\"\"\\n return')\n\n# 带后缀的用法\nrequest = FIMRequest(\n prompt='class MyClass:\\n def __init__',\n suffix='\\n\\n# Usage\\nobj = MyClass(10)'\n)\n```\n\n资料来源：[src/mistral_common/protocol/fim/request.py:1-17]()\n\n---\n\n## Instruct 协议\n\n### 概述\n\nInstruct 协议是处理对话式指令任务的核心协议。用户通过 `ChatCompletionRequest` 类发起请求，该请求经过验证、标准化后转换为内部指令格式，再由 tokenizer 编码为 token 序列。\n\n### 架构流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B[ChatCompletionRequest]\n B --> C[MistralRequestValidator 验证]\n C --> D[InstructRequestNormalizer 标准化]\n D --> E[InstructRequest]\n E --> F[InstructTokenizer 编码]\n F --> G[Tokenized 输出]\n \n H[消息列表] --> B\n I[工具定义] --> B\n J[响应格式] --> B\n```\n\n### ChatCompletionRequest 数据模型\n\n```python\nclass ChatCompletionRequest(BaseCompletionRequest[UserMessageType, AssistantMessageType, ToolMessageType, SystemMessageType]):\n \"\"\"Instruct 协议请求模型\"\"\"\n \n model: str | None = None # 模型名称\n messages: list[ChatMessageType] # 消息列表\n response_format: ResponseFormat = Field(...) # 响应格式\n tools: list[Tool] | None = None # 工具定义列表\n tool_choice: ToolChoice = ToolChoiceEnum.auto # 工具选择策略\n truncate_for_context_length: bool = False # 是否截断超长内容\n continue_final_message: bool = False # 继续生成最终消息\n reasoning_effort: ReasoningEffort | None = None # 推理努力程度\n```\n\n**核心字段说明：**\n\n| 字段名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `model` | `str \\| None` | `None` | 模型标识符，用于服务模式验证 |\n| `messages` | `list[ChatMessageType]` | 必填 | 对话消息列表，包含用户、助手、系统消息 |\n| `response_format` | `ResponseFormat` | `text` | 期望的响应格式 |\n| `tools` | `list[Tool] \\| None` | `None` | 可用工具定义列表 |\n| `tool_choice` | `ToolChoice` | `auto` | 工具选择策略（auto/none/required/指定工具） |\n| `truncate_for_context_length` | `bool` | `False` | 上下文超长时是否自动截断 |\n| `continue_final_message` | `bool` | `False` | 是否继续生成未完成的最终消息 |\n| `reasoning_effort` | `ReasoningEffort \\| None` | `None` | 控制模型的推理努力程度 |\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:1-100]()\n\n---\n\n## 消息类型系统\n\n### 消息类型分类\n\n```mermaid\ngraph TD\n A[ChatMessageType] --> B[UserMessage]\n A --> C[AssistantMessage]\n A --> D[SystemMessage]\n A --> E[ToolMessage]\n \n B --> F[文本内容]\n B --> G[多媒体内容]\n C --> H[文本内容]\n C --> I[工具调用]\n D --> J[系统提示]\n```\n\n### 消息基类与子类型\n\n| 消息类型 | 角色标识 | 说明 |\n|---------|---------|------|\n| `UserMessage` | `user` | 用户消息，支持文本和多媒体内容 |\n| `AssistantMessage` | `assistant` | 助手消息，可包含文本和工具调用结果 |\n| `SystemMessage` | `system` | 系统级指令和上下文设置 |\n| `ToolMessage` | `tool` | 工具执行结果返回消息 |\n\n### 消息内容结构\n\n消息内容支持多种格式的块（Chunk）：\n\n```python\n# 文本块\nTextChunk(content=\"Hello, how can I help you?\")\n\n# 图片块\nImageChunk(image=image_data)\n\n# 音频块 \nAudioChunk(audio=audio_data)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/chunk.py:1-30]()\n\n---\n\n## 验证与标准化\n\n### 请求验证流程\n\n```mermaid\ngraph TD\n A[ChatCompletionRequest] --> B{ValidationMode}\n B -->|serving| C[检查 model 字段]\n B -->|test/finetuning| D[跳过 model 检查]\n \n C --> E[validate_messages]\n D --> E\n \n E --> F[validate_tools]\n F --> G[validate_model_settings]\n G --> H[返回验证后的请求]\n```\n\n### 验证模式\n\n| 模式 | 说明 | model 字段要求 |\n|-----|------|---------------|\n| `ValidationMode.serving` | 生产服务模式 | 必须提供 |\n| `ValidationMode.test` | 测试模式 | 可选 |\n| `ValidationMode.finetuning` | 微调模式 | 可选 |\n\n### 消息列表验证规则\n\n1. **结构验证**：检查消息列表的起止位置是否符合预期\n2. **内容验证**：检查每条消息的内容格式和字段完整性\n3. **角色序列验证**：确保消息角色按合法顺序排列\n4. **继续消息验证**：当 `continue_final_message=True` 时，验证最终消息格式\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:1-80]()\n\n### 标准化处理器\n\n标准化器将 `ChatCompletionRequest` 转换为内部 `InstructRequest` 格式：\n\n```python\nclass InstructRequestNormalizer:\n \"\"\"请求标准化器基类\"\"\"\n \n def from_chat_completion_request(self, request: ChatCompletionRequest) -> InstructRequest:\n \"\"\"将聊天补全请求转换为指令请求\"\"\"\n system_prompt = self._aggregate_system_prompts(request.messages)\n messages = self._aggregate_messages(request.messages)\n settings = self.build_settings(request)\n return self._instruct_request_class(\n messages=messages,\n system_prompt=system_prompt,\n available_tools=request.tools,\n continue_final_message=request.continue_final_message,\n settings=settings,\n )\n```\n\n### 版本化标准化器\n\n| 标准化器 | 版本 | 特性 |\n|---------|------|------|\n| `InstructRequestNormalizerV1` | v1 | 基础版本 |\n| `InstructRequestNormalizerV2` | v2 | 支持更多配置 |\n| `InstructRequestNormalizerV7` | v7 | 系统提示在开头，允许工具调用与内容共存 |\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-60]()\n\n---\n\n## 工具调用系统\n\n### 工具定义结构\n\n```python\nclass Tool(MistralBase):\n \"\"\"工具定义\"\"\"\n \n type: ToolTypes = ToolTypes.function\n function: Function\n\nclass Function:\n \"\"\"函数定义\"\"\"\n \n name: str # 函数名（正则: ^[a-zA-Z0-9_-]{1,64}$）\n description: str | None = None # 函数描述\n parameters: dict # JSON Schema 参数定义\n```\n\n### 工具选择策略\n\n| 策略 | 说明 |\n|-----|------|\n| `ToolChoiceEnum.auto` | 模型自动决定是否调用工具 |\n| `ToolChoiceEnum.none` | 禁止调用工具 |\n| `ToolChoiceEnum.required` | 必须调用至少一个工具 |\n| `NamedToolChoice` | 指定调用特定工具 |\n\n### 工具参数 JSON Schema 验证\n\n工具参数必须符合 JSON Schema Draft-7 规范：\n\n```python\n# 有效工具示例\ntool = Tool(\n function=Function(\n name=\"get_current_weather\",\n description=\"获取指定位置的当前天气\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"城市和州，例如 San Francisco, CA\"\n },\n \"unit\": {\"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"]}\n },\n \"required\": [\"location\"]\n }\n )\n)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:1-100]()\n\n---\n\n## Tokenizer 与编码\n\n### Tokenizer 版本支持\n\n| Tokenizer 版本 | 特性 | 图像支持 | 音频支持 |\n|---------------|------|---------|---------|\n| `TokenizerVersion.v1` | 基础 | ❌ | ❌ |\n| `TokenizerVersion.v2` | 扩展 | ❌ | ❌ |\n| `TokenizerVersion.v3` | 图像支持 | ✅ | ❌ |\n| `TokenizerVersion.v7` | 图像+音频 | ✅ | ✅ |\n| `TokenizerVersion.v11` | 高级 | ✅ | ✅ |\n| `TokenizerVersion.v13` | 最新 | ✅ | ✅ |\n\n### Tokenizer 工厂函数\n\n```python\ndef get_tokenizer(\n tokenizer: Tokenizer,\n mode: ValidationMode = ValidationMode.test,\n image_encoder: Any = None,\n audio_encoder: Any = None,\n) -> MistralTokenizer:\n \"\"\"根据 tokenizer 版本创建相应的 MistralTokenizer\"\"\"\n \n validator = get_validator(tokenizer.version, mode=mode)\n \n if tokenizer.version == TokenizerVersion.v1:\n return MistralTokenizer(\n InstructTokenizerV1(tokenizer),\n validator=validator,\n request_normalizer=request_normalizer,\n )\n elif tokenizer.version == TokenizerVersion.v7:\n return MistralTokenizer(\n InstructTokenizerV7(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),\n validator=validator,\n request_normalizer=request_normalizer,\n )\n # ... 其他版本\n```\n\n### Tokenized 输出结构\n\n```python\nclass Tokenized:\n \"\"\"编码后的 token 结果\"\"\"\n \n tokens: list[int] # token ID 列表\n text: str | None = None # 文本表示\n prefix_ids: list[int] | None = None # FIM 前缀 ID\n images: list[np.ndarray] = Field(default_factory=list) # 关联图像\n audios: list[Audio] = Field(default_factory=list) # 关联音频\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-80]()\n\n---\n\n## OpenAI 格式转换\n\n### 请求转换方法\n\n`ChatCompletionRequest` 提供了 `to_openai()` 方法将请求转换为 OpenAI API 格式：\n\n```python\ndef to_openai(self, **kwargs: Any) -> dict[str, Any]:\n \"\"\"将请求转换为 OpenAI 格式\"\"\"\n```\n\n**转换示例：**\n\n```python\nfrom mistral_common.protocol.instruct.messages import UserMessage\n\nrequest = ChatCompletionRequest(\n messages=[UserMessage(content=\"Hello, how are you?\")],\n temperature=0.15\n)\n\n# 转换为 OpenAI 格式\nopenai_request = request.to_openai(stream=True)\n# 输出:\n# {\n# 'temperature': 0.15,\n# 'top_p': 1.0,\n# 'response_format': {'type': 'text'},\n# 'continue_final_message': False,\n# 'messages': [{'role': 'user', 'content': 'Hello, how are you?'}],\n# 'tool_choice': 'auto',\n# 'stream': True\n# }\n```\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:80-150]()\n\n---\n\n## 特殊控制参数\n\n### continue_final_message 参数\n\n此参数控制模型是否继续生成未完成的最终消息：\n\n| 值 | 行为 |\n|---|------|\n| `False`（默认） | 模型正常生成完整响应 |\n| `True` | 模型继续之前的消息内容进行生成 |\n\n### reasoning_effort 参数\n\n控制模型的推理努力程度：\n\n```python\nclass ReasoningEffort(str, Enum):\n \"\"\"推理努力程度枚举\"\"\"\n \n low = \"low\" # 低推理努力\n medium = \"medium\" # 中等推理努力\n high = \"high\" # 高推理努力\n```\n\n### truncate_for_context_length 参数\n\n| 值 | 行为 |\n|---|------|\n| `False`（默认） | 上下文超长时抛出异常 |\n| `True` | 自动截断消息以适应上下文长度 |\n\n---\n\n## 完整使用流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Validator as MistralRequestValidator\n participant Normalizer as InstructRequestNormalizer\n participant Tokenizer as InstructTokenizer\n participant Model as 推理模型\n\n Client->>Validator: 提交 ChatCompletionRequest\n Validator->>Validator: 验证消息格式\n Validator->>Validator: 验证工具定义\n Validator->>Validator: 验证模型设置\n Validator-->>Client: 返回验证后的请求\n \n Client->>Normalizer: 标准化请求\n Normalizer->>Normalizer: 聚合系统提示\n Normalizer->>Normalizer: 聚合消息\n Normalizer-->>Client: 返回 InstructRequest\n \n Client->>Tokenizer: 编码为 tokens\n Tokenizer->>Model: 发送 token 序列\n Model-->>Tokenizer: 返回生成的 token\n Tokenizer-->>Client: 返回 Tokenized 结果\n```\n\n**完整代码示例：**\n\n```python\nfrom mistral_common.protocol.instruct.request import ChatCompletionRequest\nfrom mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage\nfrom mistral_common.protocol.instruct.tool_calls import Tool, ToolTypes, Function\nfrom mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode\n\n# 1. 创建请求\nrequest = ChatCompletionRequest(\n model=\"mistral-large-latest\",\n messages=[\n UserMessage(content=\"What is the weather in Paris?\"),\n AssistantMessage(content=\"I'll check that for you.\"),\n ],\n tools=[\n Tool(\n type=ToolTypes.function,\n function=Function(\n name=\"get_weather\",\n description=\"Get weather for a location\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\"type\": \"string\"}\n },\n \"required\": [\"location\"]\n }\n )\n )\n ],\n tool_choice=\"auto\",\n truncate_for_context_length=True,\n)\n\n# 2. 验证请求\nvalidator = MistralRequestValidator(mode=ValidationMode.serving)\nvalidated_request = validator.validate_request(request)\n\n# 3. 标准化请求\nnormalizer = InstructRequestNormalizer.normalizer()\ninstruct_request = normalizer.from_chat_completion_request(validated_request)\n\n# 4. 编码请求\n# tokenized = tokenizer.encode_instruct(instruct_request)\n```\n\n---\n\n## 错误处理\n\n### 自定义异常类型\n\n| 异常类型 | 用途 |\n|---------|------|\n| `InvalidRequestException` | 请求参数验证失败 |\n| `InvalidToolSchemaException` | 工具参数 schema 无效 |\n| `InvalidToolException` | 工具定义无效 |\n| `InvalidMessageException` | 消息格式或内容无效 |\n\n### 常见验证错误\n\n1. **模型名称缺失**：在 serving 模式下必须提供 `model` 参数\n2. **工具 schema 无效**：工具参数不符合 JSON Schema Draft-7 规范\n3. **工具名称无效**：函数名不符合正则 `^[a-zA-Z0-9_-]{1,64}$`\n4. **消息序列错误**：消息顺序不符合协议规定\n\n---\n\n## 总结\n\nmistral-common 库的指令与填充中间协议为 LLM 交互提供了两个互补的接口：\n\n1. **Instruct 协议** (`ChatCompletionRequest`)：适合对话式、工具调用和多轮交互场景，提供完整的验证和标准化流程。\n\n2. **FIM 协议** (`FIMRequest`)：专为代码补全设计，通过 prompt/suffix 模式支持在代码任意位置插入内容。\n\n两个协议都遵循相同的验证-标准化-编码流程，确保请求的正确性和一致性。\n\n---\n\n\n\n## 请求验证与标准化\n\n### 相关页面\n\n相关主题：[指令与填充中间（FIM）协议](#p5), [语音与转录协议](#p7), [项目架构总览](#p2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n- [src/mistral_common/protocol/instruct/converters.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/converters.py)\n- [src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)\n- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n \n\n# 请求验证与标准化\n\n## 概述\n\n请求验证与标准化是 mistral-common 库中处理用户输入请求的核心模块。该模块负责在将用户请求传递给模型之前，对其进行结构验证、内容校验和格式转换。mistral-common 通过 `MistralRequestValidator` 和 `InstructRequestNormalizer` 两个核心类来实现这一功能，确保请求符合 Mistral 模型的输入规范，同时为不同的 tokenizer 版本提供统一的支持。\n\n该模块在整个处理流程中处于关键位置，属于预处理阶段的前置验证环节。验证失败时抛出自定义异常（如 `InvalidRequestException`、`InvalidToolSchemaException` 等），确保错误信息能够被上游调用方正确捕获和处理。资料来源：[src/mistral_common/protocol/instruct/validator.py:1-50]()\n\n## 核心组件\n\n### MistralRequestValidator\n\n`MistralRequestValidator` 是一个泛型类，负责验证 `ChatCompletionRequest` 的结构和内容。它支持三种验证模式，通过 `ValidationMode` 枚举进行配置。资料来源：[src/mistral_common/protocol/instruct/validator.py:19-22]()\n\n| 验证模式 | 用途 | 特定行为 |\n|---------|------|---------|\n| `serving` | 服务部署模式 | 要求必须提供 model 参数 |\n| `finetuning` | 微调模式 | 允许特定的微调参数组合 |\n| `test` | 测试/默认模式 | 标准验证规则 |\n\n### InstructRequestNormalizer\n\n`InstructRequestNormalizer` 负责将标准化的 `ChatCompletionRequest` 转换为 `InstructRequest` 格式。该类处理系统提示的聚合、消息的重组以及模型设置的提取。资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-100]()\n\n## 请求验证流程\n\n### 验证架构\n\n```mermaid\ngraph TD\n A[ChatCompletionRequest] --> B[MistralRequestValidator]\n B --> C{验证模式}\n C -->|serving| D[检查 model 参数]\n C -->|其他| E[跳过 model 检查]\n D --> F[validate_messages]\n E --> F\n F --> G[validate_message_list_structure]\n F --> H[validate_message_list_content]\n G --> I[_validate_tools]\n H --> I\n I --> J[validate_model_settings]\n J --> K[返回 validated_request]\n I -.->|工具Schema无效| L[InvalidToolSchemaException]\n G -.->|结构错误| M[InvalidRequestException]\n```\n\n### 验证步骤详解\n\n#### 1. 模型参数验证\n\n在 `serving` 模式下，系统会检查请求是否包含 `model` 参数。如果缺失，将抛出 `InvalidRequestException`，提示\"Model name parameter is required for serving mode\"。资料来源：[src/mistral_common/protocol/instruct/validator.py:67-69]()\n\n```python\nif self._mode == ValidationMode.serving:\n if request.model is None:\n raise InvalidRequestException(\"Model name parameter is required for serving mode\")\n```\n\n#### 2. 消息列表结构验证\n\n`_validate_message_list_structure` 方法检查消息序列的逻辑完整性：\n\n- 确保消息以 UserMessage 开头\n- 验证 `continue_final_message` 标志与最后一条消息类型的兼容性\n- 检查角色交替的合法性（User → Assistant → User → ...）\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:35-42]()\n\n#### 3. 消息内容验证\n\n`_validate_message_list_content` 方法验证消息内容的有效性：\n\n- 检查消息内容非空\n- 验证工具调用的格式正确性\n- 确保角色与内容的逻辑一致性\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:43-44]()\n\n#### 4. 工具定义验证\n\n工具验证是该模块的重要组成部分，包含以下检查：资料来源：[src/mistral_common/protocol/instruct/validator.py:55-57]()\n\n| 验证项 | 验证方法 | 异常类型 |\n|-------|---------|---------|\n| 函数 Schema 有效性 | Draft7Validator.check_schema | InvalidToolSchemaException |\n| 函数名称格式 | 正则表达式 `^[a-zA-Z0-9_-]{1,64}$` | InvalidToolException |\n| 参数定义完整性 | 检查 required 字段与参数存在性 | InvalidToolSchemaException |\n\n```python\ndef _validate_function(self, function: Function) -> None:\n Draft7Validator.check_schema(function.parameters)\n if not re.match(r\"^[a-zA-Z0-9_-]{1,64}$\", function.name):\n raise InvalidToolException(...)\n```\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:85-96]()\n\n## 请求标准化流程\n\n### 标准化架构\n\n```mermaid\ngraph LR\n A[ChatCompletionRequest] --> B[InstructRequestNormalizer]\n B --> C[_aggregate_system_prompts]\n B --> D[_aggregate_messages]\n B --> E[build_settings]\n C --> F[system_prompt]\n D --> G[messages]\n E --> H[settings]\n F --> I[InstructRequest]\n G --> I\n H --> I\n```\n\n### 标准化器版本\n\nmistral-common 支持多个标准化器版本，每个版本针对特定的 tokenizer 版本进行了优化：资料来源：[src/mistral_common/protocol/instruct/normalize.py:80-100]()\n\n| 标准化器 | 系统提示位置 | 工具调用+内容支持 |\n|---------|------------|-----------------|\n| `InstructRequestNormalizer` | 系统消息独立 | 不支持 |\n| `InstructRequestNormalizerV7` | 消息开始处 | 支持 |\n\n```python\nclass InstructRequestNormalizerV7(InstructRequestNormalizer):\n _system_prompt_in_begin: bool = True\n _allow_tool_call_and_content: bool = True\n```\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py:84-87]()\n\n### 消息聚合\n\n#### 系统提示聚合\n\n系统提示通过 `_aggregate_system_prompts` 方法从消息列表中提取并合并。当存在多个系统消息时，它们会被按顺序拼接为一个统一的系统提示。资料来源：[src/mistral_common/protocol/instruct/normalize.py:40-60]()\n\n#### 消息重组\n\n`_aggregate_messages` 方法移除系统消息，返回仅包含用户消息和助手消息的列表。标准化过程会验证模型设置是否与当前标准化器兼容，不支持的设置将抛出 `InvalidRequestException`。资料来源：[src/mistral_common/protocol/instruct/normalize.py:62-76]()\n\n## 工具调用系统\n\n### ToolChoice 枚举\n\n工具选择策略通过 `ToolChoice` 类型别名定义，支持多种模式：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:20-30]()\n\n| 枚举值 | 描述 | 备注 |\n|-------|------|------|\n| `auto` | 模型自动决定是否调用工具 | 默认值 |\n| `none` | 禁用工具调用 | 不使用任何工具 |\n| `any` | 至少调用一个工具 | 已废弃，使用 `required` |\n| `required` | 模型必须调用至少一个工具 | 替代 `any` |\n\n### NamedToolChoice\n\n除了枚举选择外，还支持强制指定特定函数调用：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:32-46]()\n\n```python\nclass NamedToolChoice(MistralBase):\n type: ToolTypes = ToolTypes.function\n function: FunctionName\n```\n\n### 工具定义\n\n`Tool` 类定义了可用的工具，包含函数名称、描述和参数模式：资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:48-70]()\n\n| 属性 | 类型 | 描述 |\n|-----|------|------|\n| `type` | ToolTypes | 工具类型（当前仅支持 function） |\n| `function` | Function | 函数定义对象 |\n\n## 请求转换器\n\n### OpenAI 格式转换\n\n`ChatCompletionRequest` 提供了 `to_openai()` 方法用于转换为 OpenAI 兼容格式。该方法处理消息格式转换、工具定义重映射以及额外参数的追加。资料来源：[src/mistral_common/protocol/instruct/request.py:60-90]()\n\n```python\ndef to_openai(self, **kwargs: Any) -> dict[str, Any]:\n r\"\"\"Convert the request messages and tools into the OpenAI format.\"\"\"\n```\n\n### 转换示例\n\n```python\nrequest = ChatCompletionRequest(\n messages=[UserMessage(content=\"Hello, how are you?\")],\n temperature=0.15\n)\nrequest.to_openai(stream=True)\n# 返回: {'temperature': 0.15, 'top_p': 1.0, 'response_format': {...}, ...}\n```\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:70-75]()\n\n## 请求数据结构\n\n### ChatCompletionRequest\n\n`ChatCompletionRequest` 是用户请求的入口数据结构：资料来源：[src/mistral_common/protocol/instruct/request.py:20-40]()\n\n| 字段 | 类型 | 默认值 | 描述 |\n|-----|------|-------|------|\n| `model` | str \\| None | None | 模型名称（serving 模式必需） |\n| `messages` | list[ChatMessageType] | - | 消息列表 |\n| `response_format` | ResponseFormat | Field(default_factory=ResponseFormat) | 响应格式 |\n| `tools` | list[Tool] \\| None | None | 可用工具列表 |\n| `tool_choice` | ToolChoice | ToolChoiceEnum.auto | 工具选择策略 |\n| `truncate_for_context_length` | bool | False | 是否截断以适应上下文长度 |\n| `continue_final_message` | bool | False | 继续生成最后一条消息 |\n| `reasoning_effort` | ReasoningEffort \\| None | None | 推理努力程度 |\n\n### InstructRequest\n\n标准化后的 `InstructRequest` 包含处理后的消息和系统提示：资料来源：[src/mistral_common/protocol/instruct/normalize.py:15-25]()\n\n| 属性 | 类型 | 描述 |\n|-----|------|------|\n| `messages` | list[UATS] | 处理后的消息列表 |\n| `system_prompt` | str \\| None | 聚合后的系统提示 |\n| `available_tools` | list[Tool] \\| None | 可用工具 |\n| `continue_final_message` | bool | 是否继续最后消息 |\n| `settings` | ModelSettings | 模型设置 |\n\n## 与 Tokenizer 的集成\n\n### 验证流程集成\n\n`MistralTokenizer` 在编码请求时首先调用验证器：资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-50]()\n\n```mermaid\nsequenceDiagram\n participant User as 用户请求\n participant Validator as MistralRequestValidator\n participant Normalizer as InstructRequestNormalizer\n participant Encoder as InstructTokenizer\n \n User->>Validator: ChatCompletionRequest\n Validator->>Validator: validate_request()\n Validator-->>Normalizer: validated_request\n Normalizer->>Normalizer: from_chat_completion_request()\n Normalizer-->>Encoder: InstructRequest\n Encoder->>Encoder: encode()\n```\n\n### 版本适配\n\n不同的 tokenizer 版本使用不同的标准化器和验证器组合：资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:20-60]()\n\n| Tokenizer 版本 | InstructTokenizer | 验证器 | 标准化器 |\n|---------------|-------------------|-------|---------|\n| v1 | InstructTokenizerV1 | v1 验证器 | InstructRequestNormalizer |\n| v2 | InstructTokenizerV2 | v2 验证器 | InstructRequestNormalizer |\n| v3 | InstructTokenizerV3 | v3 验证器 | InstructRequestNormalizer |\n| v7 | InstructTokenizerV7 | v7 验证器 | InstructRequestNormalizerV7 |\n| v11+ | InstructTokenizerV11+ | v11 验证器 | InstructRequestNormalizerV7 |\n\n## 异常处理\n\n### 异常类型层次\n\n| 异常类 | 基类 | 触发场景 |\n|-------|------|---------|\n| `InvalidRequestException` | Exception | 请求结构或内容验证失败 |\n| `InvalidToolSchemaException` | Exception | 工具 Schema 格式错误 |\n| `InvalidToolException` | Exception | 工具名称或定义无效 |\n\n所有自定义异常定义在 `mistral_common.exceptions` 模块中，确保错误处理的一致性。资料来源：[src/mistral_common/protocol/instruct/validator.py:80-95]()\n\n## 使用示例\n\n### 基本验证流程\n\n```python\nfrom mistral_common.protocol.instruct.messages import UserMessage, AssistantMessage\nfrom mistral_common.protocol.instruct.request import ChatCompletionRequest\nfrom mistral_common.protocol.instruct.validator import MistralRequestValidator, ValidationMode\n\n# 创建验证器\nvalidator = MistralRequestValidator(mode=ValidationMode.test)\n\n# 创建请求\nrequest = ChatCompletionRequest(\n messages=[\n UserMessage(content=\"Hello how are you?\"),\n AssistantMessage(content=\"I'm doing great!\")\n ]\n)\n\n# 验证请求\nvalidated_request = validator.validate_request(request)\n```\n\n### 带工具调用的请求\n\n```python\nfrom mistral_common.protocol.instruct.tool_calls import ToolTypes, Function, Tool\n\ntool = Tool(\n function=Function(\n name=\"get_current_weather\",\n description=\"Get the current weather in a given location\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\"type\": \"string\", \"description\": \"City name\"}\n },\n \"required\": [\"location\"]\n }\n )\n)\n\nrequest = ChatCompletionRequest(\n messages=[UserMessage(content=\"What's the weather in Paris?\")],\n tools=[tool],\n tool_choice=ToolChoiceEnum.auto\n)\n\nvalidated_request = validator.validate_request(request)\n```\n\n## 最佳实践\n\n### 1. 验证模式选择\n\n- **开发/测试环境**：使用 `ValidationMode.test`，避免强制要求 model 参数\n- **生产环境**：使用 `ValidationMode.serving`，确保所有请求包含模型标识\n\n### 2. 工具定义规范\n\n- 函数名称仅包含字母、数字、下划线和连字符，长度不超过 64 字符\n- 使用 Draft7 JSON Schema 定义参数\n- 明确标记必需参数（required 字段）\n\n### 3. 错误处理\n\n```python\ntry:\n validated_request = validator.validate_request(request)\nexcept InvalidRequestException as e:\n logger.error(f\"Invalid request: {e}\")\nexcept InvalidToolSchemaException as e:\n logger.error(f\"Invalid tool schema: {e}\")\n```\n\n### 4. 消息序列设计\n\n- 确保以 UserMessage 开始对话\n- 交替的角色顺序：User → Assistant → User → Assistant\n- 使用 `continue_final_message=True` 时，最后一条应为 AssistantMessage\n\n## 相关模块索引\n\n| 模块 | 文件路径 | 职责 |\n|-----|---------|------|\n| 验证器 | `src/mistral_common/protocol/instruct/validator.py` | 请求结构与内容验证 |\n| 标准化器 | `src/mistral_common/protocol/instruct/normalize.py` | 请求格式转换 |\n| 转换器 | `src/mistral_common/protocol/instruct/converters.py` | 格式转换辅助 |\n| 工具调用 | `src/mistral_common/protocol/instruct/tool_calls.py` | 工具定义与选择 |\n| 请求定义 | `src/mistral_common/protocol/instruct/request.py` | 请求数据结构 |\n| Tokenizer | `src/mistral_common/tokens/tokenizers/mistral.py` | 验证与编码集成 |\n\n---\n\n\n\n## 语音与转录协议\n\n### 相关页面\n\n相关主题：[指令与填充中间（FIM）协议](#p5), [请求验证与标准化](#p6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/protocol/transcription/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/transcription/request.py)\n- [src/mistral_common/tokens/tokenizers/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/audio.py)\n- [src/mistral_common/audio.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/audio.py)\n- [src/mistral_common/tokens/tokenizers/base.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/base.py)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n \n\n# 语音与转录协议\n\n## 概述\n\n语音与转录协议是 mistral-common 库中处理音频相关请求的核心组件。该协议定义了音频处理的标准化接口，支持语音转文本（Transcription）和文本转语音（Text-to-Speech）等多模态交互场景。\n\nmistral-common 通过协议层与分词器层的协作，将音频数据与文本数据统一处理为模型可接受的 token 序列。音频处理功能主要在 **TokenizerVersion.v7** 及以上版本中可用，集成于 `InstructTokenizerV7` 和 `InstructTokenizerV11` 等分词器实现中。 资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-100]()\n\n## 协议架构\n\n### 模块组织结构\n\n语音与转录协议相关代码分布在以下核心模块中：\n\n| 模块路径 | 功能描述 |\n|---------|---------|\n| `src/mistral_common/protocol/transcription/request.py` | 转录请求定义 |\n| `src/mistral_common/tokens/tokenizers/audio.py` | 音频分词器实现 |\n| `src/mistral_common/audio.py` | 音频处理工具类 |\n| `src/mistral_common/tokens/tokenizers/base.py` | 基础分词器抽象与特殊token定义 |\n\n### 协议层次关系\n\n```mermaid\ngraph TD\n A[用户请求] --> B[Protocol Layer 协议层]\n B --> C[TranscriptionRequest 转录请求]\n B --> D[SpeechRequest 语音请求]\n C --> E[Tokenizer Layer 分词器层]\n D --> E\n E --> F[InstructTokenizerV7/V11]\n E --> G[Audio Encoder 音频编码器]\n F --> H[Tokenized Output]\n G --> H\n```\n\n## 转录请求协议\n\n### TranscriptionRequest 数据模型\n\n`TranscriptionRequest` 是转录任务的入口请求类型，继承自 `BaseCompletionRequest`。该请求模型封装了音频文件路径或音频数据以及转录相关的配置参数。 资料来源：[src/mistral_common/protocol/transcription/request.py:1-30]()\n\n```python\nclass TranscriptionRequest(BaseCompletionRequest):\n r\"\"\"A valid transcription request to be tokenized.\"\"\"\n \n audio: Audio # 音频数据\n language: str | None = None # 可选的语言参数\n```\n\n### 请求字段说明\n\n| 字段名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| `audio` | `Audio` | 是 | 待转录的音频数据 |\n| `language` | `str \\| None` | 否 | 音频语言提示，用于提高转录准确性 |\n| 继承字段 | - | - | 继承自 `BaseCompletionRequest` 的基础字段 |\n\n## 音频处理机制\n\n### Audio 类\n\n`Audio` 类是音频数据的核心抽象，提供音频的下载、加载和序列化功能。 资料来源：[src/mistral_common/audio.py:1-50]()\n\n```python\nclass Audio:\n r\"\"\"音频处理工具类\n \n Attributes:\n url: 音频资源的远程URL\n audio_bytes: 音频二进制数据\n \"\"\"\n```\n\n### 音频分词器\n\n`AudioTokenizer` 负责将音频数据转换为模型可处理的 token 序列。该分词器集成在 `InstructTokenizerV7` 及更高版本中。 资料来源：[src/mistral_common/tokens/tokenizers/audio.py:1-50]()\n\n#### 核心功能\n\n| 功能 | 描述 |\n|-----|------|\n| 音频编码 | 将音频数据编码为 token 序列 |\n| 梅尔频谱转换 | 支持 mel-scale 音频特征提取 |\n| 多格式支持 | 处理多种音频编码格式 |\n\n## 特殊 Token 定义\n\n在音频处理流程中，系统定义了一系列专用特殊 token，用于标识音频内容的边界和类型。这些 token 在 `SpecialTokens` 枚举中统一管理。 资料来源：[src/mistral_common/tokens/tokenizers/base.py:1-80]()\n\n| Token 名称 | 值 | 用途 |\n|-----------|-----|------|\n| `audio` | `[AUDIO]` | 音频内容标识 |\n| `begin_audio` | `[BEGIN_AUDIO]` | 音频内容开始标记 |\n| `transcribe` | `[TRANSCRIBE]` | 转录指令标识 |\n| `audio_to_text` | `[REPEAT_AUDIO_TEXT]` | 音频转文本标识 |\n| `text_to_audio` | `[NEXT_AUDIO_TEXT]` | 文本转音频标识 |\n\n### Token 序列化格式\n\n```\n[AUDIO] + [BEGIN_AUDIO] + <音频编码数据> + [TRANSCRIBE] + [REPEAT_AUDIO_TEXT] + <转录文本>\n```\n\n## 分词器版本与音频支持\n\n音频处理能力与分词器版本紧密关联，不同版本支持不同程度的音频功能。\n\n| 分词器版本 | 音频支持 | 图像支持 | 说明 |\n|-----------|---------|---------|------|\n| `v1` | ❌ | ❌ | 基础文本分词器 |\n| `v2` | ❌ | ❌ | 基础文本分词器 |\n| `v3` | ❌ | ✅ | 仅支持图像 |\n| `v7` | ✅ | ✅ | 首次引入音频支持 |\n| `v11` | ✅ | ✅ | 增强的音视频支持 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-100]()\n\n### 版本检测与初始化\n\n```python\n# 音频编码器在 v7 及以上版本可用\nif tokenizer.version >= TokenizerVersion.v7:\n audio_encoder = AudioEncoder(...)\n \n# 创建支持音频的分词器\nreturn MistralTokenizer(\n InstructTokenizerV7(tokenizer, image_encoder=image_encoder, audio_encoder=audio_encoder),\n validator=validator,\n request_normalizer=request_normalizer,\n)\n```\n\n## 请求处理流程\n\n### 转录请求完整流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant P as Protocol Layer\n participant T as Tokenizer\n participant A as Audio Encoder\n \n U->>P: TranscriptionRequest(audio_url)\n P->>P: 下载并加载音频数据\n P->>T: 调用 encode 方法\n T->>A: 音频特征提取\n A-->>T: 音频 token 序列\n T->>T: 合并特殊 token\n T-->>U: Tokenized 对象\n```\n\n### 验证与规范化\n\n转录请求同样需要经过验证和规范化处理：\n\n1. **消息结构验证**：确保请求格式符合协议规范\n2. **音频数据验证**：检查音频数据的完整性和有效性\n3. **语言参数验证**：验证语言代码的有效性\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py:1-100]()\n\n## 配置与部署\n\n### 依赖安装\n\n音频功能需要安装相应的可选依赖：\n\n```bash\n# 安装音频支持\npip install \"mistral-common[audio]\"\n\n# 安装完整依赖（包括音频）\npip install \"mistral-common[image,audio,hf-hub,sentencepiece,server]\"\n```\n\n### API 服务配置\n\n在 FastAPI 应用中启用音频处理功能：\n\n```python\nfrom mistral_common.experimental.app import create_app\nfrom mistral_common.protocol.instruct.validator import ValidationMode\n\napp = create_app(\n tokenizer=\"path/to/tokenizer\",\n validation_mode=ValidationMode.serving,\n engine_url=\"http://127.0.0.1:8080\",\n engine_backend=\"llama_cpp\",\n timeout=60,\n)\n```\n\n资料来源：[src/mistral_common/experimental/app/main.py:1-80]()\n\n## 最佳实践\n\n### 音频数据准备\n\n1. **格式选择**：推荐使用 MP3、WAV 或 OGG 格式\n2. **采样率**：保持原始采样率，避免不必要的重采样\n3. **语言提示**：提供准确的 `language` 参数可提高转录准确度\n\n### 错误处理\n\n| 错误类型 | 处理建议 |\n|---------|---------|\n| 音频加载失败 | 检查 URL 可访问性和格式支持 |\n| 分词器版本不匹配 | 确保使用 v7+ 分词器 |\n| 音频过长 | 根据模型上下文窗口进行分段处理 |\n\n## 相关文档\n\n- [Instruct 协议](./instruct_protocol.md) - 指令请求处理\n- [工具调用协议](./tool_calls.md) - 工具调用定义\n- [Tekken 分词器](./tekken_tokenizer.md) - 分词器实现细节\n- [Grammar Factory](./grammar_factory.md) - 语法生成器\n\n---\n\n*本页面内容基于 mistral-common 仓库源码生成，最后更新时间跟随仓库最新提交。*\n\n---\n\n\n\n## Grammar Factory 与 LLM Guidance\n\n### 相关页面\n\n相关主题：[请求验证与标准化](#p6), [项目架构总览](#p2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/guidance/grammar_factory.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/grammar_factory.py)\n- [src/mistral_common/guidance/tokenizer.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/guidance/tokenizer.py)\n- [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)\n- [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)\n- [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)\n \n\n# Grammar Factory 与 LLM Guidance\n\n## 概述\n\nGrammar Factory 是 mistral-common 库中用于生成结构化输出语法的核心组件。它通过结合 **LLGuidance** 库和 **Jinja2** 模板引擎，将 LLM 的输出约束为符合特定语法规则的结构化格式，支持工具调用、JSON Schema 验证以及思考模式（Thinking Mode）。\n\n该模块的主要功能包括：\n\n- **语法生成**：基于 Jinja2 模板动态生成 Lark 语法规则\n- **特殊 token 处理**：将 Tekken 分词器的特殊 token 映射为语法语法\n- **多模式支持**：支持基础模式、思考模式（特殊 token）和纯文本思考模式\n- **工具调用约束**：支持 function calling 的语法约束和并行调用\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:1-50]()\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[用户请求] --> B[ChatCompletionRequest]\n B --> C[GrammarFactory]\n C --> D{推理模式判断}\n D -->|非思考模式| E[base_grammar.lark.jinja]\n D -->|v13+ 思考模式| F[think_grammar.lark.jinja]\n D -->|v13 之前思考模式| G[plain_text_think_grammar.lark.jinja]\n E --> H[Jinja2 渲染]\n F --> H\n G --> H\n H --> I[Lark 语法字符串]\n I --> J[llguidance 引擎]\n J --> K[结构化输出]\n \n C --> L[TekkenTokenizer]\n L --> M[特殊Token映射]\n M --> H\n```\n\n### 核心依赖\n\n| 依赖库 | 用途 |\n|--------|------|\n| llguidance | 语法引导的 LLM 推理引擎 |\n| jinja2 | Lark 语法模板渲染 |\n| lark | 语法解析 |\n\n## GrammarFactory 类\n\n### 初始化与验证\n\n```python\nclass GrammarFactory:\n def __init__(self, tokenizer: MistralTokenizer) -> None:\n \"\"\"初始化语法工厂\"\"\"\n assert_llguidance_installed()\n assert_jinja2_installed()\n self._tokenizer = tokenizer.instruct_tokenizer.tokenizer\n \n if not self.is_supported(tokenizer):\n raise ValueError(\n f\"Guidance requires a Tekken tokenizer with version >= v11, \"\n f\"got {type(self._tokenizer).__name__} {self._tokenizer.version.value}\"\n )\n```\n\n**关键约束**：\n\n- 仅支持 **Tekken 分词器**\n- 分词器版本必须 **≥ v11**\n- 支持的版本包括 v11 和 v13\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:35-55]()\n\n### 特殊 Token 映射\n\nGrammarFactory 构建从特殊 token 名称到 Lark 语法语法的映射：\n\n```python\ndef _build_special_token_map(self) -> dict[str, str]:\n \"\"\"构建特殊 token 名称到语法语法的映射\"\"\"\n return {\n self._tokenizer.id_to_piece(i): f\"<[{i}]>\" \n for i in range(self._tokenizer.num_special_tokens)\n }\n\ndef _special_token_lark(self, token_name: str) -> str:\n \"\"\"将特殊 token 名称转换为 lark 语法语法\"\"\"\n assert token_name in self._special_token_map\n return self._special_token_map[token_name]\n\ndef _get_optional_special_token_lark(self, token_name: str) -> str | None:\n \"\"\"返回特殊 token 的 lark 语法语法，若不存在则返回 None\"\"\"\n return self._special_token_map.get(token_name)\n```\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:57-70]()\n\n### 版本支持检查\n\n```python\n@staticmethod\ndef is_supported(tokenizer: MistralTokenizer) -> bool:\n \"\"\"检查分词器是否支持 grammar guidance\"\"\"\n return (\n isinstance(tokenizer.instruct_tokenizer.tokenizer, TekkenTokenizer)\n and tokenizer.instruct_tokenizer.tokenizer.version >= TokenizerVersion.v11\n )\n```\n\n## 语法变体\n\n系统支持三种语法变体，通过 `_GrammarVariant` 枚举定义：\n\n```python\nclass _GrammarVariant(str, Enum):\n base = \"base\" # 基础模式\n plain_think = \"plain_think\" # 纯文本思考模式\n think = \"think\" # 思考模式（特殊 token）\n```\n\n### 变体选择逻辑\n\n```mermaid\ngraph TD\n A[开始] --> B{是否启用推理?}\n B -->|否| C[base 变体]\n B -->|是| D{分词器版本 >= v13?}\n D -->|是| E[think 变体]\n D -->|否| F[plain_think 变体]\n```\n\n| 推理模式 | 分词器版本 | 选用变体 |\n|----------|-----------|----------|\n| 关闭 | 任意 | base |\n| 开启 | ≥ v13 | think |\n| 开启 | < v13 | plain_think |\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:120-135]()\n\n## Lark 语法模板系统\n\n### 模板文件\n\n| 模板文件 | 用途 |\n|----------|------|\n| `base_grammar.lark.jinja` | 基础模式的标准语法 |\n| `think_grammar.lark.jinja` | 支持特殊 token 思考标签的语法 |\n| `plain_text_think_grammar.lark.jinja` | 纯文本格式的思考语法 |\n\n### 模板渲染参数\n\n`_cached_get_lark_from_jinja` 函数接收以下参数生成 Lark 语法：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `template` | str | Jinja2 模板字符串 |\n| `mode` | str | 输出模式（text/JSON） |\n| `fcall` | str | 函数调用格式 |\n| `json_schema_str` | str \\| None | JSON Schema 字符串 |\n| `parallel_tool_calls` | bool | 是否支持并行工具调用 |\n| `json_only` | bool | 是否仅输出 JSON |\n| `think_with_json` | bool | 思考部分是否使用 JSON 格式 |\n| `begin_think_token` | str \\| None | 思考开始 token |\n| `end_think_token` | str \\| None | 思考结束 token |\n\n资料来源：[src/mistral_common/guidance/grammar_factory.py:140-165]()\n\n### 缓存机制\n\n系统使用 `@lru_cache` 装饰器缓存模板和语法结果，避免重复渲染：\n\n```python\n@lru_cache()\ndef _cached_get_jinja_template(\n tokenizer_version: TokenizerVersion, \n reasoning: bool\n) -> str:\n \"\"\"缓存获取 Jinja 模板\"\"\"\n if not reasoning:\n jinja_key = _GrammarVariant.base\n elif tokenizer_version < TokenizerVersion.v13:\n jinja_key = _GrammarVariant.plain_think\n else:\n jinja_key = _GrammarVariant.think\n \n return JINJA_PATHS[jinja_key].read_text(encoding=\"utf-8\")\n```\n\n## LLM Guidance Tokenizer 适配器\n\n### TekkenTokenizerAdapter\n\n位于 `src/mistral_common/guidance/tokenizer.py` 的适配器将 Tekken 分词器转换为 llguidance 所需格式：\n\n```python\nfrom mistral_common.guidance.tokenizer import from_mistral_tokenizer\n\n# 将 Mistral 分词器转换为 llguidance 格式\nadapter = from_mistral_tokenizer(mistral_tokenizer)\n```\n\n资料来源：[src/mistral_common/guidance/tokenizer.py]()\n\n## 使用流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant GF as GrammarFactory\n participant TK as TekkenTokenizer\n participant JN as Jinja2\n participant LK as Lark 语法\n participant LG as LLGuidance\n\n U->>GF: 创建 GrammarFactory 实例\n GF->>TK: 获取 instruct_tokenizer\n TK-->>GF: 返回 TekkenTokenizer\n GF->>GF: 构建特殊 token 映射\n \n U->>GF: 调用 get_lark_grammar()\n GF->>GF: 判断推理模式和版本\n GF->>JN: 加载并渲染 Jinja 模板\n JN-->>GF: 返回 Lark 语法字符串\n GF-->>U: 返回 Lark 语法\n \n U->>LG: 使用 Lark 语法进行推理\n LG-->>U: 返回结构化输出\n```\n\n## API 参考\n\n### GrammarFactory 主要方法\n\n| 方法 | 说明 |\n|------|------|\n| `is_supported(tokenizer)` | 检查分词器是否支持 |\n| `get_lark_grammar(...)` | 生成 Lark 语法字符串 |\n| `_build_special_token_map()` | 构建特殊 token 映射 |\n| `_special_token_lark(token_name)` | 转换特殊 token 为语法 |\n| `_get_optional_special_token_lark(token_name)` | 可选的 token 转换 |\n\n### get_lark_grammar 方法签名\n\n```python\ndef get_lark_grammar(\n self,\n mode: str,\n json_schema_str: str | None = None,\n fcall: str | None = None,\n parallel_tool_calls: bool = False,\n json_only: bool = False,\n think_with_json: bool = False,\n begin_think_token: str | None = None,\n end_think_token: str | None = None,\n) -> str:\n \"\"\"生成 Lark 语法字符串\"\"\"\n```\n\n## 工具调用支持\n\nGrammarFactory 原生支持 function calling 场景：\n\n```python\ngrammar = grammar_factory.get_lark_grammar(\n mode=\"function_call\",\n json_schema_str=tool.parameters, # JSON Schema\n fcall=\"auto\", # 工具选择模式\n parallel_tool_calls=True, # 并行调用\n)\n```\n\n### 工具选择模式\n\n| 模式 | 说明 |\n|------|------|\n| `auto` | 模型自动选择工具 |\n| `none` | 不使用工具 |\n| `required` | 强制使用至少一个工具 |\n| `any` | 任意工具（已废弃） |\n\n资料来源：[src/mistral_common/protocol/instruct/tool_calls.py:40-55]()\n\n## 最佳实践\n\n### 1. 分词器版本检查\n\n```python\nfrom mistral_common.tokens.tokenizers.mistral import TokenizerVersion\n\nif tokenizer.instruct_tokenizer.tokenizer.version >= TokenizerVersion.v11:\n factory = GrammarFactory(tokenizer)\nelse:\n raise ValueError(\"不支持的分词器版本\")\n```\n\n### 2. 模板缓存利用\n\n系统自动缓存渲染结果，重复调用应使用相同参数：\n\n```python\n# 推荐：批量使用相同配置\ngrammar1 = factory.get_lark_grammar(mode=\"json\", json_schema_str=schema)\ngrammar2 = factory.get_lark_grammar(mode=\"json\", json_schema_str=schema) # 使用缓存\n```\n\n### 3. 特殊 Token 验证\n\n使用可选方法处理可能不存在的 token：\n\n```python\ntoken_lark = factory._get_optional_special_token_lark(\"BOS\")\nif token_lark is None:\n # 处理 token 不存在的情况\n pass\n```\n\n## 局限性\n\n1. **分词器限制**：仅支持 Tekken 分词器 v11 及以上版本\n2. **依赖要求**：必须安装 llguidance 和 jinja2\n3. **思考模式版本差异**：不同分词器版本使用不同的思考语法模板\n\n## 相关文件\n\n| 文件路径 | 说明 |\n|----------|------|\n| `src/mistral_common/guidance/grammar_factory.py` | 核心语法工厂实现 |\n| `src/mistral_common/guidance/tokenizer.py` | llguidance 分词器适配器 |\n| `src/mistral_common/guidance/data/*.lark.jinja` | 语法模板文件 |\n| `src/mistral_common/protocol/instruct/tool_calls.py` | 工具调用定义 |\n\n---\n\n\n\n## 实验性功能（工具调用、思考解析、FastAPI 服务）\n\n### 相关页面\n\n相关主题：[项目架构总览](#p2), [Grammar Factory 与 LLM Guidance](#p8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/experimental/tools.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/tools.py)\n- [src/mistral_common/experimental/think.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/think.py)\n- [src/mistral_common/experimental/app/main.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)\n- [src/mistral_common/experimental/app/routers.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/routers.py)\n- [src/mistral_common/experimental/app/models.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/models.py)\n \n\n# 实验性功能（工具调用、思考解析、FastAPI 服务）\n\n## 概述\n\nmistral-common 的实验性功能模块（`src/mistral_common/experimental/`）提供了一套用于处理大语言模型推理请求的扩展能力，包括**工具调用解析**、**思考解析**以及基于 FastAPI 的本地推理服务。这些功能属于实验性质，旨在为开发者提供更灵活的方式来与 Mistral 模型进行交互，特别是在处理复杂的多轮对话、函数调用和模型思维链方面。\n\n实验性功能的主要设计目标是：\n\n- 提供独立于核心 tokenization 流水线的专用解析器\n- 支持通过 HTTP API 快速部署和测试 tokenizer\n- 为工具调用和思考模式提供标准化解析接口\n\n资料来源：[AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)\n\n## 模块架构\n\n实验性功能模块的整体架构由三个核心组件构成，它们各自承担不同的职责：\n\n```mermaid\ngraph TD\n A[experimental 模块] --> B[工具调用解析]\n A --> C[思考解析]\n A --> D[FastAPI 应用]\n \n D --> D1[main.py 入口]\n D --> D2[routers.py 路由]\n D --> D3[models.py 数据模型]\n \n B --> B1[tools.py]\n C --> C1[think.py]\n \n B1 -.->|使用| E[protocol/instruct/tool_calls.py]\n C1 -.->|使用| F[tokens/tokenizers/tekken.py]\n```\n\n资料来源：[src/mistral_common/experimental/](https://github.com/mistralai/mistral-common/tree/main/src/mistral_common/experimental)\n\n---\n\n## 工具调用解析\n\n### 功能概述\n\n`tools.py` 模块提供了工具调用（Tool Calls）的解析能力，允许模型在生成响应时调用外部函数或 API。该模块独立于核心的 `protocol/instruct/tool_calls.py`，专注于解析运行时而非定义工具模式。\n\n资料来源：[src/mistral_common/experimental/tools.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/tools.py)\n\n### 核心职责\n\n工具调用解析模块的主要职责包括：\n\n1. **函数识别**：从模型生成的文本中提取函数调用请求\n2. **参数解析**：将模型输出解析为结构化的函数参数\n3. **结果格式化**：将函数执行结果重新格式化为模型可理解的输入\n\n### 与标准协议的关系\n\n实验性工具调用解析与 `protocol/instruct/tool_calls.py` 中的标准工具定义存在协作关系：\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| 标准工具定义 | `protocol/instruct/tool_calls.py` | 定义 `Tool`、`Function`、`ToolChoice` 等数据模型 |\n| 实验性解析器 | `experimental/tools.py` | 运行时解析模型生成的工具调用 |\n\n资料来源：[src/mistral_common/protocol/instruct/tool_calls.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/tool_calls.py)\n\n---\n\n## 思考解析\n\n### 功能概述\n\n`think.py` 模块提供了对模型\"思考过程\"的解析能力。在启用 `thinking` 模式的模型中，模型会先生成内部推理步骤（通常以特殊 token 包裹），然后再生成最终响应。`think.py` 模块负责将这些思考过程与最终输出分离解析。\n\n资料来源：[src/mistral_common/experimental/think.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/think.py)\n\n### 思考模式的特殊标记\n\n根据 Tekken tokenizer 的实现，思考模式使用特殊的控制 token：\n\n| Token 名称 | 用途 |\n|------------|------|\n| `begin_thinking` | 标记思考内容开始 |\n| `end_thinking` | 标记思考内容结束 |\n| `begin_turn` | 标记对话轮次开始 |\n| `end_turn` | 标记对话轮次结束 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n### 解析工作流\n\n思考解析的基本工作流程如下：\n\n```mermaid\nsequenceDiagram\n participant User as 用户输入\n participant Tokenizer as Tekken Tokenizer\n participant ThinkParser as 思考解析器\n participant Model as Mistral 模型\n \n User->>Tokenizer: 原始文本\n Tokenizer->>Tokenizer: 添加思考标记\n Tokenizer->>Model: 带标记的 token 序列\n Model-->>Tokenizer: 包含思考的响应\n Tokenizer->>ThinkParser: 解析响应\n ThinkParser->>User: 分离思考内容与最终输出\n```\n\n---\n\n## FastAPI 推理服务\n\n### 应用架构\n\n实验性模块包含一个完整的 FastAPI 应用，用于提供基于 Mistral tokenizer 的 REST API 服务。该应用支持通过命令行快速启动，并提供与模型推理后端的对接能力。\n\n资料来源：[src/mistral_common/experimental/app/main.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)\n\n### 应用入口\n\n`main.py` 定义了 CLI 入口点，使用 Click 框架实现命令行接口：\n\n```python\ndef serve(\n tokenizer_path: str | Path,\n validation_mode: ValidationMode | str = ValidationMode.test,\n host: str = \"127.0.0.1\",\n port: int = 0,\n engine_url: str = \"http://127.0.0.1:8080\",\n engine_backend: str = EngineBackend.llama_cpp.value,\n timeout: int = 60,\n) -> None:\n```\n\n### 启动命令参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `tokenizer_path` | str/Path | 必需 | tokenizer 文件路径 |\n| `validation_mode` | str | \"test\" | 验证模式（test/serving/finetuning） |\n| `host` | str | \"127.0.0.1\" | 服务监听地址 |\n| `port` | int | 0 | 服务监听端口（0 表示自动分配） |\n| `engine_url` | str | \"http://127.0.0.1:8080\" | 推理引擎 URL |\n| `engine_backend` | str | \"llama_cpp\" | 推理后端类型 |\n| `timeout` | int | 60 | 请求超时时间（秒） |\n\n资料来源：[src/mistral_common/experimental/app/main.py:1-90](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/main.py)\n\n### 引擎后端支持\n\n系统支持多种推理引擎后端：\n\n| 后端标识 | 说明 |\n|----------|------|\n| `llama_cpp` | Llama.cpp 推理引擎 |\n| `vllm` | vLLM 推理引擎（可选支持） |\n\n### 路由模块\n\n`routers.py` 定义了 API 的路由端点，处理 tokenizer 相关的 HTTP 请求：\n\n```python\n# 路由结构示例\n@router.post(\"/tokenize\")\nasync def tokenize(request: TokenizeRequest) -> TokenizeResponse\n\n@router.post(\"/detokenize\")\nasync def detokenize(request: DetokenizeRequest) -> DetokenizeResponse\n```\n\n资料来源：[src/mistral_common/experimental/app/routers.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/routers.py)\n\n### 数据模型\n\n`models.py` 定义了 API 请求和响应的 Pydantic 模型：\n\n| 模型名称 | 类型 | 用途 |\n|----------|------|------|\n| `TokenizeRequest` | Request | 文本分词请求 |\n| `TokenizeResponse` | Response | 分词结果响应 |\n| `DetokenizeRequest` | Request | token 反向解析请求 |\n| `DetokenizeResponse` | Response | 反解析结果响应 |\n| `ValidationRequest` | Request | 请求验证请求 |\n| `ValidationResponse` | Response | 验证结果响应 |\n\n资料来源：[src/mistral_common/experimental/app/models.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/experimental/app/models.py)\n\n### 服务启动流程\n\n```mermaid\ngraph LR\n A[命令行参数] --> B[create_app]\n B --> C[Uvicorn 运行]\n C --> D[监听 HTTP 请求]\n D --> E[路由处理]\n E --> F[Tokenizer 操作]\n```\n\n### 依赖安装\n\n实验性服务功能需要安装 `server` 可选依赖：\n\n```bash\npip install \"mistral-common[server]\"\n```\n\n资料来源：[README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)\n\n---\n\n## 验证模式\n\n实验性应用支持三种验证模式，由 `MistralRequestValidator` 类管理：\n\n| 模式 | 说明 | 使用场景 |\n|------|------|----------|\n| `test` | 测试模式 | 单元测试和开发 |\n| `serving` | 服务模式 | 生产环境部署 |\n| `finetuning` | 微调模式 | 模型微调任务 |\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n\n---\n\n## 与其他模块的交互\n\n### 整体数据流\n\n```mermaid\ngraph TD\n subgraph 用户层\n A[用户请求]\n end\n \n subgraph API层\n B[FastAPI 应用]\n C[路由处理器]\n end\n \n subgraph 协议层\n D[ChatCompletionRequest]\n E[Validator]\n F[Normalizer]\n end\n \n subgraph Tokenization层\n G[MistralTokenizer]\n H[Tekken Tokenizer]\n end\n \n A --> B --> C\n C --> D --> E\n E --> F\n F --> G --> H\n \n subgraph 实验性功能\n I[工具调用解析]\n J[思考解析]\n end\n \n G -.->|支持| I\n G -.->|支持| J\n```\n\n### 验证流程\n\n用户请求首先经过 `MistralRequestValidator` 验证，然后由 `InstructRequestNormalizer` 标准化，最后由 tokenizer 处理：\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n\n---\n\n## 使用示例\n\n### 启动本地服务\n\n```bash\npython -m mistral_common.experimental.app.main serve \\\n --tokenizer-path /path/to/tokenizer \\\n --validation-mode test \\\n --host 0.0.0.0 \\\n --port 8000\n```\n\n### API 请求示例\n\n```bash\ncurl -X POST http://localhost:8000/tokenize \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\": \"Hello, world!\"}'\n```\n\n---\n\n## 注意事项\n\n1. **实验性质**：所有 `experimental` 模块下的功能均为实验性质，API 可能在后续版本中发生变化\n2. **版本要求**：某些功能需要特定的 tokenizer 版本（如 v11+ 用于 guidance 功能）\n3. **依赖管理**：使用前请确保已安装所有必要的可选依赖\n4. **线程安全**：Tokenization 操作本身是线程安全的，但需注意并发访问时的资源管理\n\n---\n\n\n\n## 数据文件与模型版本管理\n\n### 相关页面\n\n相关主题：[分词器系统详解](#p3), [项目介绍与安装](#p1)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mistral_common/data/tekken_240718.json](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/data/tekken_240718.json)\n- [src/mistral_common/data/tekken_240911.json](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/data/tekken_240911.json)\n- [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)\n- [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)\n- [src/mistral_common/tokens/tokenizers/mistral.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n- [src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n- [src/mistral_common/protocol/instruct/request.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n- [src/mistral_common/protocol/instruct/normalize.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n \n\n# 数据文件与模型版本管理\n\n## 概述\n\nmistral-common 库中的数据文件与模型版本管理系统负责管理分词器（Tokenizer）的配置数据、词汇表（Vocabulary）以及不同模型版本之间的兼容性适配。该系统通过版本化的数据文件和版本感知的构建器模式，确保库能够支持从 v1 到 v13 的多种 Tekken 分词器版本。\n\n数据文件存放在 `src/mistral_common/data/` 目录下，主要包含两类资源：词汇表 JSON 文件（如 `tekken_240718.json`、`tekken_240911.json`）以及 SentencePiece 模型文件（如 `mistral_instruct_tokenizer_241114.model.v7`）。\n\n资料来源：[AGENTS.md](https://github.com/mistralai/mistral-common/blob/main/AGENTS.md)\n\n---\n\n## 核心架构\n\n### 版本体系\n\nmistral-common 支持的 Tekken 分词器版本演进如下：\n\n| 版本 | 主要特性 | 数据文件 |\n|------|----------|----------|\n| v1 | 基础分词功能 | 无独立数据文件 |\n| v2 | 改进的分词规则 | 无独立数据文件 |\n| v3 | 支持图像处理 | 需要 image_encoder |\n| v7 | 支持音频处理 | `.v7` 模型文件 |\n| v11 | 完整多模态支持 | Tekken JSON 数据 |\n| v13 | 最新版本特性 | Tekken JSON 数据 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:1-80](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n### 类关系图\n\n```mermaid\ngraph TD\n A[MistralTokenizer] --> B[InstructTokenizerV*]\n B --> C[TekkenTokenizer]\n C --> D[模型版本管理器]\n E[ModelSettingsBuilder] --> D\n F[data/*.json] --> D\n G[data/*.model.v7] --> D\n```\n\n---\n\n## 数据文件类型\n\n### Tekken 词汇表文件\n\nTekken 词汇表文件采用 JSON 格式存储，包含分词器的完整词汇信息：\n\n- **命名规范**：`tekken_{YYYYMMDD}.json`\n- **内容结构**：\n - 词汇表条目（token 到 ID 的映射）\n - 特殊 token 定义\n - 分词模式（pattern）\n - 元数据（版本号、创建日期）\n\n### SentencePiece 模型文件\n\n较旧版本（如 v7）使用 SentencePiece 格式：\n\n- **命名规范**：`mistral_instruct_tokenizer_{YYYYMMDD}.model.v7`\n- **用途**：向后兼容旧模型\n- **状态**：已弃用，新模型使用 Tekken 格式\n\n资料来源：[README.md](https://github.com/mistralai/mistral-common/blob/main/README.md)\n\n---\n\n## 模型版本管理器\n\n### TokenizerVersion 枚举\n\n所有支持的版本通过 `TokenizerVersion` 枚举进行标识：\n\n```python\nclass TokenizerVersion(Enum):\n v1 = \"v1\"\n v2 = \"v2\"\n v3 = \"v3\"\n v7 = \"v7\"\n v11 = \"v11\"\n v13 = \"v13\"\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n### ModelSettingsBuilder\n\n`ModelSettingsBuilder` 类负责根据模型版本构建相应的配置设置：\n\n```python\nclass ModelSettingsBuilder:\n \"\"\"根据分词器版本构建模型设置的构建器\"\"\"\n \n def build(self, request: ChatCompletionRequest) -> ModelSettings:\n \"\"\"根据请求构建模型设置\"\"\"\n ...\n```\n\n**关键参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `str \\| None` | 模型名称 |\n| `messages` | `list[ChatMessageType]` | 消息列表 |\n| `response_format` | `ResponseFormat` | 响应格式 |\n| `tools` | `list[Tool] \\| None` | 工具定义 |\n| `tool_choice` | `ToolChoice` | 工具选择策略 |\n| `truncate_for_context_length` | `bool` | 是否截断以适应上下文长度 |\n| `continue_final_message` | `bool` | 是否继续最终消息 |\n| `reasoning_effort` | `ReasoningEffort \\| None` | 推理努力级别 |\n\n资料来源：[src/mistral_common/protocol/instruct/request.py:1-100](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/request.py)\n\n---\n\n## 版本选择流程\n\n### 工厂方法模式\n\nmistral-common 使用工厂方法 `create_tokenizer` 来创建适当版本的 tokenizer：\n\n```mermaid\ngraph TD\n A[create_tokenizer 调用] --> B{检查版本}\n B -->|v1| C[InstructTokenizerV1]\n B -->|v2| D[InstructTokenizerV2]\n B -->|v3| E[InstructTokenizerV3 + image_encoder]\n B -->|v7| F[InstructTokenizerV7 + audio_encoder]\n B -->|v11| G[InstructTokenizerV11]\n B -->|v13| H[InstructTokenizerV13]\n C --> I[MistralTokenizer 包装]\n D --> I\n E --> I\n F --> I\n G --> I\n H --> I\n```\n\n资料来源：[src/mistral_common/tokens/tokenizers/mistral.py:30-70](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/mistral.py)\n\n### 版本验证\n\n每个版本的 tokenizer 实例化时都会进行严格验证：\n\n```python\nif tokenizer.version == TokenizerVersion.v1:\n assert image_encoder is None, \"Tokenizer version needs to be >= v3\"\n assert audio_encoder is None, \"Tokenizer version needs to be >= v7\"\n```\n\n---\n\n## InstructRequestNormalizer 版本化\n\n### 版本化规范化器\n\n`InstructRequestNormalizer` 类存在多个版本子类，每个版本针对特定的分词器版本优化：\n\n| 规范化器类 | 分词器版本 | 特性 |\n|-----------|-----------|------|\n| `InstructRequestNormalizer` | v1/v2 | 基础规范化 |\n| `InstructRequestNormalizerV7` | v7 | 支持音频 |\n\n**V7 版本特性：**\n\n```python\nclass InstructRequestNormalizerV7(InstructRequestNormalizer):\n _system_prompt_in_begin: bool = True\n _allow_tool_call_and_content: bool = True\n```\n\n资料来源：[src/mistral_common/protocol/instruct/normalize.py:1-60](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/normalize.py)\n\n### 规范化流程\n\n```mermaid\ngraph LR\n A[ChatCompletionRequest] --> B[系统提示聚合]\n A --> C[消息聚合]\n B --> D[build_settings]\n C --> D\n D --> E[InstructRequest]\n E --> F[验证器验证]\n F --> G[分词器编码]\n```\n\n---\n\n## 特殊 Token 管理\n\n### SpecialTokenInfo 数据结构\n\n每个 Tekken 分词器版本定义了一套特殊 token：\n\n```python\nSpecialTokenInfo(rank=1, token_str=SpecialTokens.bos, is_control=True),\nSpecialTokenInfo(rank=2, token_str=SpecialTokens.eos, is_control=True),\nSpecialTokenInfo(rank=7, token_str=SpecialTokens.begin_tool_results, is_control=True),\nSpecialTokenInfo(rank=8, token_str=SpecialTokens.end_tool_results, is_control=True),\n```\n\n**特殊 token 完整列表：**\n\n| Token 名称 | 用途 |\n|-----------|------|\n| `bos` | 序列起始 |\n| `eos` | 序列结束 |\n| `begin_tool_results` | 工具结果开始 |\n| `end_tool_results` | 工具结果结束 |\n| `tool_calls` | 工具调用标记 |\n| `img` | 图像标记 |\n| `img_break` | 图像中断 |\n| `img_end` | 图像结束 |\n| `begin_system` | 系统消息开始 |\n| `end_system` | 系统消息结束 |\n| `begin_tool_content` | 工具内容开始 |\n\n资料来源：[src/mistral_common/tokens/tokenizers/tekken.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/tokens/tokenizers/tekken.py)\n\n---\n\n## 数据流集成\n\n### 与协议层集成\n\n数据版本管理与协议层紧密协作：\n\n```mermaid\ngraph TD\n A[用户请求] --> B[ChatCompletionRequest]\n B --> C[规范化器 Normalizer]\n C --> D[验证器 Validator]\n D --> E[分词器 Tokenizer]\n E --> F[data/ 目录数据]\n F --> E\n E --> G[模型输出]\n```\n\n### 验证模式\n\n系统支持三种验证模式：\n\n| 模式 | 说明 | 模型参数要求 |\n|------|------|-------------|\n| `test` | 测试模式（默认） | 可选 |\n| `serving` | 服务模式 | 必须提供 |\n| `finetuning` | 微调模式 | 可选 |\n\n资料来源：[src/mistral_common/protocol/instruct/validator.py](https://github.com/mistralai/mistral-common/blob/main/src/mistral_common/protocol/instruct/validator.py)\n\n---\n\n## 版本迁移指南\n\n### 从旧版本迁移\n\n| 源版本 | 目标版本 | 迁移要点 |\n|--------|----------|----------|\n| v1/v2 | v3+ | 需要配置 `image_encoder` |\n| v3-v6 | v7 | 需要配置 `audio_encoder` |\n| SentencePiece | Tekken | 使用新的 JSON 数据文件 |\n\n### 兼容性检查\n\n```python\n# 检查版本兼容性的示例代码\nif tokenizer.version >= TokenizerVersion.v11:\n # 使用新的 GrammarFactory 功能\n grammar_factory = GrammarFactory(tokenizer)\n```\n\n---\n\n## 总结\n\nmistral-common 的数据文件与模型版本管理系统通过以下机制实现多版本支持：\n\n1. **版本化数据文件**：不同版本的词汇表和模型文件存储在 `data/` 目录\n2. **版本感知的构建器**：`ModelSettingsBuilder` 根据版本构建正确配置\n3. **工厂方法**：`create_tokenizer` 根据版本参数返回适当的 tokenizer 实例\n4. **版本化规范化器**：不同版本的规范化器处理特定版本的请求格式\n5. **严格验证**：每个版本有独立的验证逻辑和版本检查\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：mistralai/mistral-common\n\n摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]。\n\n## 1. 安全/权限坑 · 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_750d0089d9e14ad385e0f49195987796 | https://github.com/mistralai/mistral-common/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b87372316a944057aa9d5cf9ae8797b3 | https://github.com/mistralai/mistral-common/issues/209 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03f994c9b8a649a0a7723f5a7ac9a9c0 | https://github.com/mistralai/mistral-common/issues/210 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call'…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call', ...}\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_598dfde98fb44c46b9d95e5ee2a66d69 | https://github.com/mistralai/mistral-common/issues/211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:786756993 | https://github.com/mistralai/mistral-common | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 来源证据：v1.11.1: Patch for agentic use\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.11.1: Patch for agentic use\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2858129b86914e6090beed86fafe6db7 | https://github.com/mistralai/mistral-common/releases/tag/v1.11.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 来源证据：v1.8.7: Refactoring and bug fixes.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.8.7: Refactoring and bug fixes.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cbca40b0e8be4f20a899d193e200fdd3 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c55c5c2d9aae479b96c76416b6740fee | https://github.com/mistralai/mistral-common/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：v1.8.6: rm Python 3.9, bug fixes.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.8.6: rm Python 3.9, bug fixes.\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ffc1eeb338274f6095e43203b2c2e785 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v1.9.0 - Stream my audio 🎙️\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.0 - Stream my audio 🎙️\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bad0c0ee58ac4386b5bcc2d2c9d226e8 | https://github.com/mistralai/mistral-common/releases/tag/v1.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：mistralai/mistral-common\n\n摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]。\n\n## 1. 安全/权限坑 · 来源证据：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG: MistralCommonTokenizer from transformers is not supported by trl SFT]\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_750d0089d9e14ad385e0f49195987796 | https://github.com/mistralai/mistral-common/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: Tests in the tarball downloaded from the PYPI page fail because the samples directory doesn't exist\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b87372316a944057aa9d5cf9ae8797b3 | https://github.com/mistralai/mistral-common/issues/209 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_hertz_to_mel_array fails: Arrays are not equal\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03f994c9b8a649a0a7723f5a7ac9a9c0 | https://github.com/mistralai/mistral-common/issues/210 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call'…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: test_openai_chat_fields fails: AssertionError: assert {'audio', 'ex...on_call', ...} == {'audio', 'ex...on_call', ...}\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_598dfde98fb44c46b9d95e5ee2a66d69 | https://github.com/mistralai/mistral-common/issues/211 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:786756993 | https://github.com/mistralai/mistral-common | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 来源证据：v1.11.1: Patch for agentic use\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.11.1: Patch for agentic use\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2858129b86914e6090beed86fafe6db7 | https://github.com/mistralai/mistral-common/releases/tag/v1.11.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 来源证据：v1.8.7: Refactoring and bug fixes.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.8.7: Refactoring and bug fixes.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cbca40b0e8be4f20a899d193e200fdd3 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:786756993 | https://github.com/mistralai/mistral-common | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.10.0: Tokenizer v15, Reasoning Effort and Python 3.14\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c55c5c2d9aae479b96c76416b6740fee | https://github.com/mistralai/mistral-common/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：v1.8.6: rm Python 3.9, bug fixes.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.8.6: rm Python 3.9, bug fixes.\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ffc1eeb338274f6095e43203b2c2e785 | https://github.com/mistralai/mistral-common/releases/tag/v1.8.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v1.9.0 - Stream my audio 🎙️\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.0 - Stream my audio 🎙️\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bad0c0ee58ac4386b5bcc2d2c9d226e8 | https://github.com/mistralai/mistral-common/releases/tag/v1.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:786756993 | https://github.com/mistralai/mistral-common | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mistral-common - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mistral-common 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Official inference library for pre-processing of Mistral models 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. p1：项目介绍与安装。围绕“项目介绍与安装”模拟一次用户任务，不展示安装或运行结果。\n2. p2：项目架构总览。围绕“项目架构总览”模拟一次用户任务，不展示安装或运行结果。\n3. p3：分词器系统详解。围绕“分词器系统详解”模拟一次用户任务，不展示安装或运行结果。\n4. p5：指令与填充中间（FIM）协议。围绕“指令与填充中间（FIM）协议”模拟一次用户任务，不展示安装或运行结果。\n5. p6：请求验证与标准化。围绕“请求验证与标准化”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p1\n输入：用户提供的“项目介绍与安装”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p2\n输入：用户提供的“项目架构总览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p3\n输入：用户提供的“分词器系统详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p5\n输入：用户提供的“指令与填充中间（FIM）协议”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p6\n输入：用户提供的“请求验证与标准化”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p1：Step 1 必须围绕“项目介绍与安装”形成一个小中间产物，并等待用户确认。\n- Step 2 / p2：Step 2 必须围绕“项目架构总览”形成一个小中间产物，并等待用户确认。\n- Step 3 / p3：Step 3 必须围绕“分词器系统详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / p5：Step 4 必须围绕“指令与填充中间（FIM）协议”形成一个小中间产物，并等待用户确认。\n- Step 5 / p6：Step 5 必须围绕“请求验证与标准化”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/mistralai/mistral-common\n- https://github.com/mistralai/mistral-common#readme\n- README.md\n- pyproject.toml\n- AGENTS.md\n- src/mistral_common/__init__.py\n- src/mistral_common/tokens/__init__.py\n- src/mistral_common/protocol/__init__.py\n- src/mistral_common/guidance/__init__.py\n- src/mistral_common/experimental/__init__.py\n- src/mistral_common/tokens/tokenizers/tekken.py\n- src/mistral_common/tokens/tokenizers/sentencepiece.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mistral-common 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：mistralai/mistral-common\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install mistral-common\n```\n\n来源：https://github.com/mistralai/mistral-common#readme\n\n## 来源\n\n- repo: https://github.com/mistralai/mistral-common\n- docs: https://github.com/mistralai/mistral-common#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_33f269521c7749d49a5780a5ea981b7b"
}