# IBM Granite 4.1 - 如何本地运行

IBM 发布了 Granite-4.1 模型，提供 3 种尺寸： **3B**, **8B** 和 **30B**。Granite-4.1 是一个长上下文的稠密模型家族，专为指令遵循、工具调用、聊天、RAG 和编程等用例而构建。这些模型在各自规模上都极具竞争力，并使用 15T tokens 进行了训练。

了解如何运行 Unsloth Granite-4.1 Dynamic GGUF，或对模型进行微调/RL。你可以使用我们的免费 notebook 为支持客服场景对 Granite-4.1 进行微调。

**Granite-4.1 模型家族：**

* **Granite-4.1-3B 稠密型：** 轻量高效，适用于本地、边缘和高吞吐量任务。非常适合快速分类、信息抽取、简单 RAG、函数调用，以及在较小 GPU 上进行微调。
* **Granite-4.1-8B 稠密型：** 一个平衡型模型，适用于本地助手、RAG、编程、多语言聊天和工具使用工作流。如果你想在保持合理内存占用的同时获得更好的质量，这是一个很好的默认选择。
* **Granite-4.1-30B 稠密型：** 最强大的 Granite-4.1 模型。最适合更高要求的企业助手、长上下文任务、复杂 RAG、编程、多语言工作流以及代理式工具调用用例。

### ⚙️ 使用指南

使用这些设置可获得确定性的、遵循指令的回复：

`temperature=0.0`, `top_p=1.0`, `top_k=0`

* Temperature of `0.0`
* Top\_K = `0`
* Top\_P = `1.0`
* 推荐最小上下文： `16,384`
* 最大上下文长度窗口： `131,072` tokens

#### Unsloth Granite-4.1 上传

* [`unsloth/granite-4.1-3b-GGUF`](https://huggingface.co/unsloth/granite-4.1-3b-GGUF)
* [`unsloth/granite-4.1-8b-GGUF`](https://huggingface.co/unsloth/granite-4.1-8b-GGUF)
* [`unsloth/granite-4.1-30b-GGUF`](https://huggingface.co/unsloth/granite-4.1-30b-GGUF)

## 运行 Granite-4.1 教程

<a href="/pages/4f11f797f5dcd74fe531721767d0972688af3a34#unsloth-studio-guide" class="button primary">在 Unsloth Studio 中运行</a><a href="/pages/4f11f797f5dcd74fe531721767d0972688af3a34#llama.cpp-run-granite-4.1-tutorial" class="button secondary">在 llama.cpp 中运行</a>

{% hint style="warning" %}
请不要使用 **CUDA 13.2** 否则你可能会得到乱码输出。NVIDIA 正在修复。
{% endhint %}

### 🦥 Unsloth Studio 指南

在本教程中，我们将使用 [Unsloth Studio](/docs/zh/xin/studio.md)，这是我们用于运行和训练 LLM 的新 Web UI。使用 Unsloth Studio，你可以在本地于 **音频**、图像和文本上运行模型，支持 **Mac、Windows**和 Linux，并且：

{% columns %}
{% column %}

* 搜索、下载、 [运行 GGUF](/docs/zh/xin/studio.md#run-models-locally) 和 safetensor 模型
* **并排** 比较 **模型**
* [**自愈式** 工具调用](/docs/zh/xin/studio.md#execute-code--heal-tool-calling) + **网页搜索**
* [**代码执行**](/docs/zh/xin/studio.md#run-models-locally) （Python、Bash）
* [自动推理](/docs/zh/xin/studio.md#model-arena) 参数调优（temp、top-p 等）
* [训练 LLM](/docs/zh/xin/studio.md#no-code-training) 速度提升 2 倍，VRAM 减少 70%
  {% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/5af4df407c8134f1ff75a4d7535569361c049e51" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% stepper %}
{% step %}

#### 安装 Unsloth

**MacOS、Linux、WSL：**

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

**Windows PowerShell：**

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

{% endstep %}

{% step %}

#### 设置 Unsloth Studio（仅需一次）

设置过程会自动安装 Node.js（通过 nvm）、构建前端、安装所有 Python 依赖，并构建带 CUDA 支持的 llama.cpp。

{% hint style="info" %}
**WSL 用户：** 系统会提示你输入 `sudo` 密码以安装构建依赖（`cmake`, `git`, `libcurl4-openssl-dev`).
{% endhint %}
{% endstep %}

{% step %}

#### 启动 Unsloth

**MacOS、Linux、WSL：**

```bash
source unsloth_studio/bin/activate
unsloth studio -H 0.0.0.0 -p 8888
```

**Windows PowerShell：**

```bash
& .\unsloth_studio\Scripts\unsloth.exe studio -H 0.0.0.0 -p 8888
```

<div data-with-frame="true"><figure><img src="/files/7fd4b2ed7fb55df6d31b4dd1ce1181d57613709b" alt="" width="375"><figcaption></figcaption></figure></div>

**然后在浏览器中打开 `http://localhost:8888` 。**
{% endstep %}

{% step %}

#### 搜索并下载 Granite 4.1

首次启动时，你需要创建一个密码来保护账户安全，并在以后重新登录。然后前往 [Studio Chat](/docs/zh/xin/studio/chat.md) 选项卡，并在搜索栏中搜索 Granite 4.1，然后下载你想要的模型和量化版本。
{% endstep %}

{% step %}

#### 运行 Granite 4.1

在使用 Unsloth Studio 时，推理参数应会自动设置，不过你仍然可以手动更改。你也可以编辑上下文长度、聊天模板和其他设置。

如需更多信息，你可以查看我们的 [Unsloth Studio 推理指南](/docs/zh/xin/studio/chat.md).
{% endstep %}
{% endstepper %}

### 🦙 Llama.cpp 教程

1. 获取最新的 `llama.cpp`。你也可以按照下面的构建说明操作。将 `-DGGML_CUDA=ON` 改为 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只想使用 CPU 推理。对于 Apple Mac / Metal 设备，请设置 `-DGGML_CUDA=OFF` 然后照常继续——Metal 支持默认已开启。

```shell
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-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
```

2. 如果你想使用 `llama.cpp` 直接加载模型，你可以使用下面的方法。 `UD-Q4_K_XL` 是量化类型。你也可以将其更改为其他量化版本，例如 `Q4_K_M`, `Q5_K_M`, `Q8_0` 或在可用时使用 BF16 全精度。

```shell
./llama.cpp/llama-cli \
    -hf unsloth/granite-4.1-30b-GGUF:UD-Q4_K_XL
```

3. 或者在安装后通过 Hugging Face 下载模型 `huggingface_hub` 和 `hf_transfer`.

```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/granite-4.1-30b-GGUF",
    local_dir = "unsloth/granite-4.1-30b-GGUF",
    allow_patterns = ["*UD-Q4_K_XL*"],
)
```

4. 运行 Unsloth 的 Flappy Bird 测试。

```shell
./llama.cpp/llama-cli \
    --model unsloth/granite-4.1-30b-GGUF/granite-4.1-30b-UD-Q4_K_XL.gguf \
    --n-gpu-layers 99 \\
    --seed 3407 \
    --prio 2 \
    --temp 0.0 \
    --top-k 0 \
    --top-p 1.0 \\
    -p "Create a single-file Python pygame implementation of Flappy Bird."
```

编辑 `--threads 32` 来设置 CPU 线程数， `--ctx-size 16384` 用于上下文长度，以及 `--n-gpu-layers 99` 用于 GPU 卸载。如果你的 GPU 内存不足，请尝试调整 GPU 层数。如果你使用的是仅 CPU 推理，请移除 `--n-gpu-layers` 。

5. 对于对话模式：

```shell
./llama.cpp/llama-cli \
    --model unsloth/granite-4.1-30b-GGUF/granite-4.1-30b-UD-Q4_K_XL.gguf \
    --conversation \\
    --n-gpu-layers 99 \\
    --seed 3407 \
    --prio 2 \
    --temp 0.0 \
    --top-k 0 \
    --top-p 1.0
```

### 在 Unsloth 中微调 Granite-4.1

Unsloth 支持包括 3B、8B 和 30B 在内的 Granite-4.1 模型进行微调。训练速度提升 2 倍，使用更少的 VRAM，并支持更长的上下文长度。Granite-4.1-3B 和 Granite-4.1-8B 是本地微调的最佳起点，而 Granite-4.1-30B 是更高精度企业工作流的最强模型。

* **Granite-4.0** [**免费微调 notebook**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Granite4.0.ipynb) **（将模型名称更改为 Granite-4.1）**

这个 notebook 会训练一个模型，使其成为能够理解客户互动的支持客服助手，并附带分析和建议。此设置可让你训练一个为支持客服人员提供实时协助的机器人。我们还展示了如何使用存储在 Google Sheet 中的数据来训练模型。

#### Granite-4.1 的 Unsloth 配置

如果你使用的是旧版 Unsloth 和/或正在本地微调，请安装最新版本的 Unsloth：

```python
!pip install --upgrade unsloth
```

```python
from unsloth import FastLanguageModel
import torch

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/granite-4.1-8b",
    max_seq_length = 2048,   # 上下文长度 - 可以更长，但会使用更多内存
    dtype = None,            # None 表示自动检测
    load_in_4bit = True,     # 4bit 占用的内存要少得多
    load_in_8bit = False,    # 准确度稍高一些，使用 2 倍内存
    full_finetuning = False, # 我们现在支持全量微调！
    # token = "hf_...",      # 如果使用受限模型，请使用一个
)
```

要强制重新安装最新的 Unsloth 和 Unsloth Zoo：

```shell
pip install --upgrade --force-reinstall --no-cache-dir unsloth unsloth_zoo
```

你可以将模型名称更改为任何 Granite-4.1 模型：

```python
model_name = "unsloth/granite-4.1-3b"
model_name = "unsloth/granite-4.1-8b"
model_name = "unsloth/granite-4.1-30b"
```

对于 30B 模型，请使用更大的 GPU 或多 GPU 配置，并在内存不足时降低 `max_seq_length` 或提高量化级别。


---

# Agent Instructions: 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/ibm-granite-4.1.md?ask=<question>
```

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.