> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/mo-xing/tutorials/devstral-how-to-run-and-fine-tune.md). # Devstral：如何运行和微调 **Devstral-Small-2507** （Devstral 1.1）是 Mistral 面向软件工程的新型 agentic LLM。它在工具调用、探索代码库以及驱动编码代理方面表现出色。Mistral AI 于 2025 年 5 月发布了原始的 2505 版本。 微调自 [**Mistral-Small-3.1**](https://huggingface.co/unsloth/Mistral-Small-3.1-24B-Instruct-2503-GGUF)，Devstral 支持 128k 上下文窗口。Devstral Small 1.1 的性能有所提升，在 [SWE-bench verified](https://openai.com/index/introducing-swe-bench-verified/)上取得了 53.6% 的性能得分，使其（2025 年 7 月 10 日）成为该基准上的第 1 个开源模型。 Unsloth Devstral 1.1 GGUF 包含额外的 **工具调用支持** 以及 **聊天模板修复**。Devstral 1.1 仍然与 OpenHands 配合良好，但现在也能更好地泛化到其他提示和编码环境。 由于是纯文本模型，Devstral 的视觉编码器在微调前已被移除。我们添加了 [***可选的视觉支持***](#possible-vision-support) 到该模型中。 {% hint style="success" %} 我们还在幕后与 Mistral 合作，帮助调试、测试并修正任何可能的漏洞和问题！务必 **下载 Mistral 的官方下载包或 Unsloth 的 GGUF** / dynamic quants，以获得 **正确的实现** （即正确的系统提示、正确的聊天模板等） 请使用 `--jinja` 在 llama.cpp 中启用系统提示！ {% endhint %} 所有 Devstral 上传都使用我们的 Unsloth [Dynamic 2.0](/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs.md) 方法，在 5-shot MMLU 和 KL 散度基准上提供最佳性能。这意味着，你可以以极小的精度损失运行并微调量化的 Mistral LLM！ #### **Devstral - Unsloth Dynamic** 量化： | Devstral 2507（新版） | Devstral 2505 | | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | GGUF： [Devstral-Small-2507-GGUF](https://huggingface.co/unsloth/Devstral-Small-2507-GGUF) | [Devstral-Small-2505-GGUF](https://huggingface.co/unsloth/Devstral-Small-2505-GGUF) | | 4-bit BnB： [Devstral-Small-2507-unsloth-bnb-4bit](https://huggingface.co/unsloth/Devstral-Small-2507-unsloth-bnb-4bit) | [Devstral-Small-2505-unsloth-bnb-4bit](https://huggingface.co/unsloth/Devstral-Small-2505-unsloth-bnb-4bit) | ## 🖥️ **运行 Devstral** ### :gear: 官方推荐设置 根据 Mistral AI，以下是推理推荐设置： * **温度从 0.0 到 0.15** * Min\_P 为 0.01（可选，但 0.01 效果很好，llama.cpp 默认值为 0.1） * **使用**** ****`--jinja`**** ****以启用系统提示。** **建议使用系统提示**，它是 Open Hands 系统提示的衍生版本。完整系统提示如下所示 [这里](https://huggingface.co/unsloth/Devstral-Small-2505/blob/main/SYSTEM_PROMPT.txt). ``` 你是 Devstral，一个由 Mistral AI 训练、使用 OpenHands 脚手架的有帮助的 agentic 模型。你可以与计算机交互来解决任务。 你的主要职责是通过执行命令、修改代码并有效解决技术问题来帮助用户。你应当全面、系统，并优先保证质量而非速度。 * 如果用户提出问题，例如“为什么会发生 X”，不要试图修复问题。只需回答这个问题。 .... 系统提示继续 .... ``` {% hint style="success" %} 我们的动态上传文件名前缀是 '`UD`'。没有这个前缀的不是动态版本，但仍然使用我们的校准数据集。 {% endhint %} ## :llama: 教程：如何在 Ollama 中运行 Devstral 1. 安装 `ollama` 如果你还没安装的话！ ```bash apt-get update apt-get install pciutils -y curl -fsSL https://ollama.com/install.sh | sh ``` 2. 使用我们的动态量化运行模型。注意你也可以在 `ollama serve &`失败时在另一个终端中运行！我们将所有建议参数（temperature 等）包含在 `params` 中，位于我们的 Hugging Face 上传里！ 3. 此外，Devstral 支持 128K 上下文长度，所以最好启用 [**KV 缓存量化**](https://github.com/ollama/ollama/blob/main/docs/faq.md#how-can-i-set-the-quantization-type-for-the-kv-cache)。我们使用 8bit 量化，可节省 50% 的内存。你也可以尝试 `"q4_0"` ```bash export OLLAMA_KV_CACHE_TYPE="q8_0" ollama run hf.co/unsloth/Devstral-Small-2507-GGUF:UD-Q4_K_XL ``` ## 📖 教程：如何在 llama.cpp 中运行 Devstral 1. 获取最新的 `llama.cpp` 默认开启 [GitHub 仓库](https://github.com/ggml-org/llama.cpp)。你也可以按照下面的构建说明进行。将 `-DGGML_CUDA=ON` 到 `-DGGML_CUDA=OFF` 改为适用于没有 GPU 或只想进行 CPU 推理的情况。 **对于 Apple Mac / Metal 设备**，设置 `-DGGML_CUDA=OFF` 然后照常继续——Metal 支持默认开启。 ```bash apt-get update apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y git clone https://github.com/ggml-org/llama.cpp cmake llama.cpp -B llama.cpp/build \ -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON -DLLAMA_CURL=ON cmake --build llama.cpp/build --config Release -j --clean-first --target llama-quantize llama-cli llama-gguf-split llama-mtmd-cli cp llama.cpp/build/bin/llama-* llama.cpp ``` 2. 如果你想使用 `llama.cpp` 直接加载模型，你可以使用下面的方法：（:Q4\_K\_XL）是量化类型。你也可以通过 Hugging Face 下载（第 3 点）。这与 `ollama run` ```bash ./llama.cpp/llama-cli -hf unsloth/Devstral-Small-2507-GGUF:UD-Q4_K_XL --jinja ``` 3. **或者** 通过（在安装之后）下载模型 `pip install huggingface_hub hf_transfer` 。你可以选择 Q4\_K\_M，或其他量化版本（如 BF16 全精度）。 ```python # !pip install huggingface_hub hf_transfer import os os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1" from huggingface_hub import snapshot_download snapshot_download( repo_id = "unsloth/Devstral-Small-2507-GGUF", local_dir = "unsloth/Devstral-Small-2507-GGUF", allow_patterns = ["*Q4_K_XL*", "*mmproj-F16*"], # For Q4_K_XL ) ``` 4. 运行模型。 5. 编辑 `--threads -1` 以使用最大 CPU 线程数， `--ctx-size 131072` 用于上下文长度（Devstral 支持 128K 上下文长度！）， `--n-gpu-layers 99` 用于 GPU 下放的层数。如果你的 GPU 内存不足，请尝试调整它。如果你只使用 CPU 推理，也请移除它。我们还使用 8bit 量化作为 K 缓存以减少内存使用。 6. 对于对话模式： 
./llama.cpp/llama-cli \
    --model unsloth/Devstral-Small-2507-GGUF/Devstral-Small-2507-UD-Q4_K_XL.gguf \
    --threads -1 \
    --ctx-size 131072 \
    --cache-type-k q8_0 \
    --n-gpu-layers 99 \
    --seed 3407 \
    --prio 2 \
    --temp 0.15 \
    --repeat-penalty 1.0 \
    --min-p 0.01 \
    --top-k 64 \
    --top-p 0.95 \
    --jinja
7. 对于非对话模式，以测试我们的 Flappy Bird 提示词： 
./llama.cpp/llama-cli \
    --model unsloth/Devstral-Small-2507-GGUF/Devstral-Small-2507-UD-Q4_K_XL.gguf \
    --threads -1 \
    --ctx-size 131072 \
    --cache-type-k q8_0 \
    --n-gpu-layers 99 \
    --seed 3407 \
    --prio 2 \
    --temp 0.15 \
    --repeat-penalty 1.0 \
    --min-p 0.01 \
    --top-k 64 \
    --top-p 0.95 \
    -no-cnv \
    --prompt "[SYSTEM_PROMPT]你是 Devstral，一个由 Mistral AI 训练、使用 OpenHands 脚手架的有帮助的 agentic 模型。你可以与计算机交互来解决任务。\n\n<ROLE>\n你的主要职责是通过执行命令、修改代码并有效解决技术问题来帮助用户。你应当全面、系统，并优先保证质量而非速度。\n* 如果用户提出问题，例如 \"为什么会发生 X\"，不要试图修复问题。只需回答这个问题。\n</ROLE>\n\n<EFFICIENCY>\n* 你采取的每个动作都有一定成本。只要可能，就将多个动作合并为一个动作，例如使用 sed 和 grep 一次性编辑/查看多个文件，把多个 bash 命令合并为一个。\n* 在探索代码库时，使用 find、grep 和 git 等高效工具，并配合适当的过滤条件，以尽量减少不必要的操作。\n</EFFICIENCY>\n\n<FILE_SYSTEM_GUIDELINES>\n* 当用户提供文件路径时，不要假设它相对于当前工作目录。先探索文件系统以定位该文件，再对其进行操作。\n* 如果要求编辑文件，直接编辑该文件，而不是创建一个不同文件名的新文件。\n* 对于全局搜索和替换操作，考虑使用 `sed`，而不是多次打开文件编辑器。\n</FILE_SYSTEM_GUIDELINES>\n\n<CODE_QUALITY>\n* 编写简洁、高效的代码，尽量少写注释。避免注释中的重复：不要重复那些可以从代码本身轻易推断的信息。\n* 在实现解决方案时，专注于做解决问题所需的最小更改。\n* 在实施任何更改之前，先通过探索彻底理解代码库。\n* 如果你要向函数或文件中添加大量代码，必要时考虑将函数或文件拆分成更小的部分。\n</CODE_QUALITY>\n\n<VERSION_CONTROL>\n* 配置 git 凭据时，默认使用 \"openhands\" 作为 user.name，使用 \"openhands@all-hands.dev\" 作为 user.email，除非另有明确指示。\n* 对 git 操作要谨慎。除非被明确要求，否则不要做可能有危险的更改（例如推送到 main、删除仓库）。\n* 提交更改时，使用 `git status` 查看所有已修改文件，并暂存提交所需的全部文件。尽可能使用 `git commit -a`。\n* 不要提交通常不应进入版本控制的文件（例如 node_modules/、.env 文件、构建目录、缓存文件、大型二进制文件），除非用户明确指示。\n* 如果不确定某些文件是否应该提交，检查是否存在 .gitignore 文件，或向用户询问澄清。\n</VERSION_CONTROL>\n\n<PULL_REQUESTS>\n* 创建拉取请求时，除非另有明确指示，每个会话/问题只创建一个。\n* 在处理现有 PR 时，用新提交更新它，而不是为同一问题创建额外的 PR。\n* 更新 PR 时，保留原始 PR 标题和目的，仅在必要时更新描述。\n</PULL_REQUESTS>\n\n<PROBLEM_SOLVING_WORKFLOW>\n1. EXPLORATION: 在提出解决方案之前，彻底探索相关文件并理解上下文\n2. ANALYSIS: 考虑多种方法并选择最有前景的一种\n3. TESTING:\n   * 对于修复漏洞：在实施修复之前创建测试以验证问题\n   * 对于新功能：在适当时考虑测试驱动开发\n   * 如果仓库缺少测试基础设施，且实现测试需要大量准备，请先与用户商量，再投入时间构建测试基础设施\n   * 如果环境未配置好以运行测试，请先与用户商量，再投入时间安装所有依赖\n4. IMPLEMENTATION: 进行有针对性的、最小化的更改来解决问题\n5. VERIFICATION: 如果环境已配置好可运行测试，请彻底测试你的实现，包括边界情况。如果环境未配置好可运行测试，请先与用户商量，再投入时间运行测试。\n</PROBLEM_SOLVING_WORKFLOW>\n\n<SECURITY>\n* 仅在用户明确请求且符合预期的方式下使用 GITHUB_TOKEN 和其他凭据。\n* 除非用户另有要求，或你的任务确实需要浏览，否则使用 API 与 GitHub 或其他平台交互。\n</SECURITY>\n\n<ENVIRONMENT_SETUP>\n* 当用户要求你运行应用程序时，如果应用未安装，不要停止。请先安装该应用，然后再次运行命令。\n* 如果遇到缺失依赖：\n  1. 先在仓库中查看是否已有依赖文件（requirements.txt、pyproject.toml、package.json、Gemfile 等）\n  2. 如果存在依赖文件，就用它们一次性安装所有依赖（例如 `pip install -r requirements.txt`、`npm install` 等）\n  3. 只有在找不到依赖文件，或者只需要特定包时，才直接安装单个包\n* 同样地，如果用户请求的关键工具缺少依赖，在可能的情况下应进行安装。\n</ENVIRONMENT_SETUP>\n\n<TROUBLESHOOTING>\n* 如果你已经多次尝试解决某个问题，但测试仍然失败，或者用户说它仍然坏着：\n  1. 后退一步，反思 5-7 个可能的问题来源\n  2. 评估每种可能原因的概率\n  3. 按概率从高到低系统地处理最可能的原因\n  4. 记录你的推理过程\n* 当你在执行用户计划时遇到任何重大问题，请不要试图直接绕过它。相反，请提出一个新计划并在继续前与用户确认。\n</TROUBLESHOOTING>[/SYSTEM_PROMPT][INST]用 Python 创建一个 Flappy Bird 游戏。你必须包含以下内容：\n1. 你必须使用 pygame。\n2. 背景颜色应随机选择，并且是浅色。以浅蓝色开始。\n3. 多次按 SPACE 会加速小鸟。\n4. 小鸟的形状应随机选择为正方形、圆形或三角形。颜色应随机选择为深色。\n5. 在底部放一些土地，颜色随机选择为深棕色或黄色。\n6. 在右上角显示分数。穿过管道且没有撞到时分数增加。\n7. 制作随机间距且间隔足够的管道。颜色随机选择为深绿色、浅棕色或深灰色。\n8. 失败时，显示最高分。文本应显示在屏幕内。按 q 或 Esc 退出游戏。重新开始则再次按 SPACE。\n最终游戏应放在一个 Python 的 markdown 区块中。检查你的代码是否有错误[/INST]"
{% hint style="danger" %} 记得移除 \，因为 Devstral 会自动添加 \！另外请使用 `--jinja` 以启用系统提示！ {% endhint %} ## :eyes:实验性视觉支持 [Xuan-Son](https://x.com/ngxson) 在 Hugging Face 上展示了他们的 [GGUF 仓库](https://huggingface.co/ngxson/Devstral-Small-Vision-2505-GGUF) 如何实际上可以将 Mistral 3.1 Instruct 的视觉编码器“嫁接”到 Devstral 2507 上。我们也上传了我们的 mmproj 文件，这样你就可以使用以下内容： ```bash ./llama.cpp/llama-mtmd-cli \ --model unsloth/Devstral-Small-2507-GGUF/Devstral-Small-2507-UD-Q4_K_XL.gguf \ --mmproj unsloth/Devstral-Small-2507-GGUF/mmproj-F16.gguf \ --threads -1 \ --ctx-size 131072 \ --cache-type-k q8_0 \ --n-gpu-layers 99 \ --seed 3407 \ --prio 2 \ --temp 0.15 ``` 例如： | 指令和输出代码 | 渲染后的代码 | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | ![](https://cdn-uploads.huggingface.co/production/uploads/63ca214abedad7e2bf1d1517/HDic53ANsCoJbiWu2eE6K.png) | ![](https://cdn-uploads.huggingface.co/production/uploads/63ca214abedad7e2bf1d1517/onV1xfJIT8gzh81RkLn8J.png) | ## 🦥 使用 Unsloth 微调 Devstral 与包括 Mistral Small 3.1 在内的标准 Mistral 模型一样，Unsloth 支持 Devstral 微调。训练速度快 2 倍，使用的 VRAM 减少 70%，并支持长 8 倍的上下文长度。Devstral 在 24GB VRAM 的 L4 GPU 上也能轻松运行。 遗憾的是，Devstral 的内存需求略微超出 16GB VRAM 的限制，因此目前无法在 Google Colab 上免费微调。不过，你 *可以* 使用我们的 [Kaggle notebook](https://www.kaggle.com/notebooks/welcome?src=https://github.com/unslothai/notebooks/blob/main/nb/Kaggle-Magistral_\(24B\)-Reasoning-Conversational.ipynb\&accelerator=nvidiaTeslaT4)免费微调该模型，它提供双 GPU 访问。只需将 notebook 中的 Magistral 模型名称改为 Devstral 模型即可。 如果你使用的是旧版 Unsloth 和/或在本地微调，请安装最新版本的 Unsloth： ```bash pip install --upgrade --force-reinstall --no-cache-dir unsloth unsloth_zoo ``` [^1]: 用于减少内存占用的 K 量化。可以是 f16、q8\_0、q4\_0 [^2]: 必须使用 --jinja 以启用系统提示 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://unsloth.ai/docs/zh/mo-xing/tutorials/devstral-how-to-run-and-fine-tune.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.