> 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/flint.md).

# Flint：本地运行指南

使用 Unsloth Dynamic GGUFs、Unsloth Desktop 和 llama.cpp 在本地运行 Recursive Flint。

Recursive Flint 是一款 **39.8B 参数的 MoE（2.5B 激活）**，具备推理、多轮工具使用以及 **256K 上下文**。Flint 以 Apache-2.0 许可证发布，并且是 **最强的 MoE 模型** 在智能体编码基准上，参数量低于 50B。可在以下环境本地运行： [Unsloth Desktop](https://unsloth.ai/docs/zh/desktop.md) ，或使用 llama.cpp，并在 24GB RAM 上运行 Unsloth 的 3 位 GGUF。你可以在 M4 Pro MacBook Pro 上以 125+ tokens/sec 运行，在 64GB NVIDIA RTX Spark 上以 150+ tokens/sec 运行。

我们的 **3 位 UD-Q3\_K\_XL GGUF** 大小为 18.50GB，并且适配 **24GB RAM 配置** 在较短上下文下。完整的 BF16 GGUF 为 79.58GB，而 UD-Q4\_K\_XL 为 25.05GB。GGUF： [unsloth/flint-GGUF](https://huggingface.co/unsloth/flint-GGUF)

#### ⚙️ 使用指南

**表：硬件要求** （RAM + VRAM，或统一内存）。

| 2 位      | 3 位      | 4 位   | 6 位   | 8 位   |
| -------- | -------- | ----- | ----- | ----- |
| 13–15 GB | 16–20 GB | 26 GB | 38 GB | 44 GB |

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FGXYEQqEXseTna162HHNa%2Fflint%20pic.webp?alt=media&amp;token=bcddff05-8e5d-4026-a05e-02cab135af2e" alt="" width="563"><figcaption><p>在 Unsloth 中运行的 Flint。</p></figcaption></figure>

#### 推荐设置

[Recursive 推荐](https://huggingface.co/RecursiveSI/flint) 以下采样设置：

| 参数    | 设置                         |
| ----- | -------------------------- |
| 温度    | 1.0                        |
| Top-p | 0.95                       |
| Top-k | 20                         |
| 最大上下文 | 262,144 个 tokens（提示词 + 输出） |

**聊天模板：** 使用 GGUF 自带的模板。对于自定义多轮客户端，请保留返回的 `reasoning_content` 以及工具调用消息，保存在对话历史中，具体如模型卡所述。

### 运行 Flint 指南

我们将使用 **UD-Q4\_K\_XL（25.05GB）**。如果内存有限，请选择 **UD-Q3\_K\_XL（18.5GB）** 。

你也可以阅读 Recursive 官方的 [Flint 指南](#usage-guide).

#### 🦥 在 Unsloth Desktop 中运行 Flint

在 [Unsloth Desktop](https://unsloth.ai/docs/desktop) 于 **macOS、Windows 和 Linux**.

{% stepper %}
{% step %}

#### 安装 Unsloth

下载并启动最新的 [Unsloth Desktop 应用](https://unsloth.ai/download) 适用于你的设备：

* [下载 macOS 版本](https://unsloth.ai/download/mac)
* [下载 Windows 版本](https://unsloth.ai/download/windows)
* [下载 Linux 版本](https://unsloth.ai/download/linux)

如需在 macOS、Linux 或 WSL 上手动安装：

```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```

适用于 Windows PowerShell：

```powershell
irm https://unsloth.ai/install.ps1 | iex
```

{% endstep %}

{% step %}

#### 下载并运行 Flint

1. 打开 **模型中心** 或 **选择模型** 下拉菜单。
2. 搜索 `unsloth/flint-GGUF`，选择 Unsloth 仓库，并下载 `UD-Q4_K_XL` 或更小的量化版本。

Flint 接受 **文本输入**。查看我们的 [Unsloth Chat 指南](https://unsloth.ai/docs/new/studio/chat) ，了解模型加载和推理设置。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FGXYEQqEXseTna162HHNa%2Fflint%20pic.webp?alt=media&amp;token=bcddff05-8e5d-4026-a05e-02cab135af2e" alt="" width="375"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### 连接编码代理

安装 Unsloth 和你偏好的代理后，请在项目文件夹中运行此命令：

```bash
unsloth start claude \\
    --model unsloth/flint-GGUF:UD-Q4_K_XL \\
    --temp 1.0 --top-p 0.95 --top-k 20 --min-p 0.0
```

这用于代码任务的更大上下文，需要比 8K 示例更多的内存。你可以将 `claude` 替换为其他受支持的代理，例如 `opencode`。参见 [Unsloth Start](https://unsloth.ai/docs/integrations/unsloth-start) ，了解设置和受支持的集成。
{% endstep %}

{% step %}

#### 使用 Unsloth API 提供 Flint 服务

使用 `unsloth run` 来加载量化模型并在本地提供服务。 `:UD-Q4_K_XL` 后缀用于选择量化版本：

```bash
unsloth run --model unsloth/flint-GGUF:UD-Q4_K_XL \\
    --parallel 1 --alias flint \\
    --temp 1.0 --top-p 0.95 --top-k 20 --min-p 0.0 \\
    --host 127.0.0.1 --port 8001
```

使用 Unsloth 显示的端点和认证信息。若要访问 Desktop API，请在 **设置 → API** 中创建密钥，并按照我们的 [API 指南](https://unsloth.ai/docs/basics/api) 连接你的客户端。
{% endstep %}
{% endstepper %}

### 📊 量化分析

以下基准来自 [Flint GGUF README](https://huggingface.co/unsloth/flint-GGUF) ，用于比较量化质量与模型大小。 **KLD 越低越好；top-1 准确率越高越好。** 这些指标衡量每种量化与参考模型的接近程度。了解更多关于 [Unsloth Dynamic 3.0 GGUF](https://unsloth.ai/docs/basics/unsloth-dynamic-v3.0-gguf).

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FR3k6FK1PyIJuU7qBx6h8%2Fsize_vs_top1(3).png?alt=media&amp;token=1ffcb4fc-696f-4fec-92a8-68b2c160246b" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FtU9zTQiXR66yrHnGX19y%2Fsize_vs_kld(3).png?alt=media&amp;token=0d18a630-93d4-448f-b00b-df41000d61de" alt="" width="563"><figcaption></figcaption></figure></div>

### 🦙 在 llama.cpp 中运行 Flint

{% stepper %}
{% step %}

#### 构建 llama.cpp

使用 [最新的 llama.cpp](https://github.com/ggml-org/llama.cpp) 并启用 Flint 支持。下面的命令使用 macOS/Linux/WSL shell。请先安装 Git、CMake 和 C++ 编译器。对于 NVIDIA，还需要安装 CUDA 工具包。

```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone --branch iq1-narrow https://github.com/unslothai/llama.cpp
cmake llama.cpp -B llama.cpp/build \\
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
```

**Apple Silicon：** 将 `-DGGML_CUDA=ON` 替换为 `-DGGML_CUDA=OFF`；Metal 默认启用。对于仅 CPU 构建，还需在 macOS 上设置 `-DGGML_METAL=OFF` 。参见 [构建说明](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md) 以了解其他平台。
{% endstep %}

{% step %}

#### 下载 Unsloth GGUF

在同一工作目录中，下载精确的 4 位文件：

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -U huggingface_hub
hf download unsloth/flint-GGUF \\
    flint-UD-Q4_K_XL.gguf \\
    --local-dir models/flint
```

对于更小的 2 位模型，请将文件名替换为 `flint-UD-IQ2_XXS.gguf` ，并在下载和运行命令中都进行替换。如果你选择 BF16，请将三个分片都下载到同一文件夹，并让运行时指向第一个分片。
{% endstep %}

{% step %}

#### 与 Flint 聊天

```bash
./llama.cpp/llama-cli \\
    --model models/flint/flint-UD-Q4_K_XL.gguf \\
    --ctx-size 8192 --n-gpu-layers 99 \\
    --temp 1.0 --top-p 0.95 --top-k 20 --min-p 0.0 \\
    --prompt "编写一个 Python 函数，合并重叠区间，并包含测试。"
```

`--jinja` 会使用模型的聊天模板。若 VRAM 有限，请减少 `--n-gpu-layers` ，或者将其设置为 `0` 用于 CPU 推理。为卸载的层保留足够的系统 RAM。
{% endstep %}
{% endstepper %}

### 基准

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fvx89npzlDGi6Mq3sWqmJ%2Fflint_benchmarks_nvfp4.png?alt=media&amp;token=759b8b48-8c15-4ca9-a1a5-3d3aab34a522" alt=""><figcaption></figcaption></figure>

| 模型            | Terminal-Bench 2.1 | SWE-bench Pro v2† | SWE-bench Verified | LiveCodeBench v6 | IFBench | IFEval |
| ------------- | ------------------ | ----------------- | ------------------ | ---------------- | ------- | ------ |
| Flint BF16    | 54.9               | 89.7              | 74.2               | 80.3             | 89.2    | 95.1   |
| Flint NVFP4   | 53.7               | 88.5              | 74.1               | 80.8             | 88.1    | 94.6   |
| Qwen 3.5      | 38.7               | 68.6              | 69.2               | 74.6             | 70.2    | 91.9   |
| Qwen 3.6      | 44.9               | 73.8              | 73.4               | 80.4             | 67.9    | 89.6   |
| Laguna XS 2.1 | 24.7†              | 38.6              | 70.9               | 49.5†            | 34.4†   | 73.7†  |
| Qwen 3.8      | 73.0               | 94.9              | 75.6†              | 90.3             | 79.5    | 94.6†  |
| Muse Glimmer  | 51.7               | 86.0              | 76.0               | 63.5†            | 77.0    | 94.7†  |
| Gemma 4       | 43.4               | 61.7              | 66.6               | 80.0             | 76.0    | 94.6   |

图表说明：

* † = 内部测量（如原图表所示）。
* Flint BF16：总参数 40B，约 2B 激活。
* Flint NVFP4：量化后的 Flint 检查点。
* Qwen 3.5、Qwen 3.6、Laguna XS 2.1：稀疏 MoE 类别（总参数 33–35B，3B 激活）。
* Qwen 3.8、Muse Glimmer、Gemma 4：稠密类别（27–31B）。
* 所有基准面板都使用从 0 开始的刻度。


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://unsloth.ai/docs/zh/mo-xing/flint.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
