> 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/xin/studio/chat.md).

# 如何使用 Unsloth 运行模型

使用 Unsloth Studio 在本地运行 AI 模型、LLM 和 GGUF。

[Unsloth Studio](https://unsloth.ai/docs/zh/xin/studio.md) 而 Unsloth Desktop 可让你在电脑上 100% 离线运行 AI 模型。你可以运行 GGUF、safetensors 等格式的模型，这些模型可从 Hugging Face 获取，也可以使用本地文件。

* **适用于所有 MacOS、CPU、Windows、Linux 和 WSL 环境！无需 GPU**
* [**自动修复工具调用**](#auto-healing-tool-calling)**,** 高级 [**网页搜索**](#advanced-web-search), [**代码执行**](#code-execution)
* 将 Unsloth 用作兼容 OpenAI 的推理 [**API 端点**](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/api.md) 或连接 [提供商](https://unsloth.ai/docs/zh/ji-cheng/connections.md)
* 搜索 + 下载 + 运行 + [比较](#model-arena) 任意模型，例如 GGUF、LoRA 适配器、safetensors 等。
* [**自动推理参数**](#auto-parameter-tuning) 调优（temp、top-p 等）并编辑聊天模板
* 上传图片、音频、PDF、代码、DOCX 等多种文件，与模型聊天。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FVrjsMhR9uLeIlqzD2jAL%2Fqwen37b.gif?alt=media&amp;token=f1bb11b4-d4fa-4765-83b7-bbba563082c9" alt="" width="563"><figcaption></figcaption></figure>

### 使用 Unsloth Studio Chat

{% hint style="success" %}
Unsloth Studio Chat 可自动适配 **多 GPU 环境** 进行推理。
{% endhint %}

{% columns %}
{% column %}

#### 代码执行

Unsloth Studio 让 LLM 能运行 Bash 和 Python，而不只是 JavaScript。它还会像 Claude Artifacts 那样将程序放在沙盒中运行，让模型可以测试代码、生成文件，并通过实际计算验证答案。

这让模型的回答更加可靠、准确。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fel6jjv4rUTRCRwcRpIr7%2Flong%20code%20exec.png?alt=media&amp;token=9d3d5930-0fdc-4d97-941c-983e5629296d" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### 自动修复工具调用

Unsloth Studio 不仅支持 [工具调用](#id-50-tool-calling-accuracy)，还会自动修复格式错误或无法正常工作的工具调用，修复率提升 50%。

这意味着你将始终获得 **不会出现** 工具调用故障的推理输出。&#x20;

例如，Qwen3.5-4B 搜索了 20 多个网站并引用了来源，而且网页搜索是在其思维过程内部完成的。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FXPQGEEr1YoKofrTatAKK%2Ftoolcallingif.gif?alt=media&amp;token=25d68698-fb13-4c46-99b2-d39fb025df08" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### 高级网页搜索

Unsloth 提供不限量且安全的网页搜索，会直接访问网页以收集相关信息和数据，而不仅仅是浏览网站摘要。因此，输出的信息和上下文更加准确、深入。搜索使用 DuckDuckGo 的私密安全 API。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FVrjsMhR9uLeIlqzD2jAL%2Fqwen37b.gif?alt=media&amp;token=f1bb11b4-d4fa-4765-83b7-bbba563082c9" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### 将 Unsloth 用作 API 端点

现在，你可以通过连接到 Unsloth 的 [Claude Code](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/claude-code.md) 和 [Codex](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/codex.md) 等工具，使用本地 LLM。 [API 端点](#use-unsloth-as-an-api-endpoint)。这样，你就能在这些工具中直接运行 Qwen 和 Gemma 模型，并使用 Unsloth 的推理功能，包括自动修复工具调用、网页搜索等。
{% endcolumn %}

{% column %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F1s98Id9xclzwMfxjXw2O%2Funsloth%20api%20cropped.png?alt=media&amp;token=64fac263-ca5b-4447-a740-41f58ec94904" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### 自动推理设置

推理参数，例如 **temperature**, **top-p**, **top-k**, [**MTP**](https://unsloth.ai/docs/zh/mo-xing/qwen3.6.md#mtp-guide) 会针对 Qwen3.5 等新模型自动预设，让你无需操心设置也能获得最佳输出。你也可以手动调整参数并编辑系统提示词。

借助 llama.cpp 的智能自动上下文功能，不再需要手动调整上下文长度；它只使用所需的上下文，不会加载多余内容。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FAQKsjtynvCXKtadvKhq1%2FRecording%202026-03-13%20114257.gif?alt=media&amp;token=b5bfff0c-8189-4358-9344-08d0ae17782a" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### 连接服务提供商

[Unsloth 可连接](https://unsloth.ai/docs/zh/ji-cheng/connections.md) OpenAI、Anthropic、Ollama、llama.cpp、vLLM 等服务。

添加 API 密钥或模型服务器 URL，即可在与本地模型和云端模型相同的聊天界面中使用外部模型。支持 [提示缓存](https://unsloth.ai/docs/zh/ji-cheng/connections.md#prompt-caching)、工具调用、思考，以及 OpenAI 的 [网页搜索](#web-search-and-thinking) 和 [代码执行](#code-execution).
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FAQKsjtynvCXKtadvKhq1%2FRecording%202026-03-13%20114257.gif?alt=media&amp;token=b5bfff0c-8189-4358-9344-08d0ae17782a" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### 搜索并运行模型

你可以通过 Hugging Face 搜索并下载任意模型，也可以使用本地文件。

Unsloth 支持多种模型类型，包括 **GGUF**、视觉语言模型和文本转语音模型。运行最新模型，例如 [Qwen3.5](https://unsloth.ai/docs/zh/mo-xing/qwen3.5.md) 或 NVIDIA [Nemotron 3](https://unsloth.ai/docs/zh/mo-xing/nemotron-3.md).

上传图片、音频、PDF、代码、DOCX 等多种文件，与模型聊天。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FBf3UDywdNSlvCBhUuVsp%2FScreenshot%202026-03-17%20at%2012.34.23%E2%80%AFAM.png?alt=media&amp;token=b6127cbf-76f7-48da-b869-3760ed5e9b42" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### 聊天工作区

输入提示词，附加文档、图片（webp、png）、代码文件、txt 文件或音频作为补充上下文，并实时查看模型的回复。

开启或关闭：思考 + 网页搜索。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FHlOKWnSB6slhE1EXgAeZ%2Fimage.png?alt=media&amp;token=b5bdfe4e-fe0e-4a2a-9eba-b04b15a79018" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

### **工具调用准确率提升 50%**

Unsloth 提供多项独特功能，可提升工具调用效果，包括：

* 在 Unsloth 中，所有模型的工具调用 **准确率均提高 30% 至 80%**.
* 网页搜索会检索实际网页内容，而不只是摘要。
* 允许的工具调用次数上限 **超过 25 次。**
* 工具调用能更可靠地终止，从而减少循环和重复调用。
* 改进后的工具调用修复与去重逻辑有助于防止 XML 泄漏到输出中。

查看以下模型的测试结果： `unsloth/Qwen3.5-4B-GGUF (UD-Q4_K_XL)` 已启用网页搜索、代码执行和思考：

| 指标           | 常规工具调用 | Unsloth 工具调用 |
| ------------ | ------ | ------------ |
| 回复中出现 XML 泄漏 | 10/10  | 0/10         |
| 使用的 URL 获取次数 | 0      | 10 次运行中有 4 次 |
| 歌曲名称正确的运行次数  | 0/10   | 2/10         |
| 平均工具调用次数     | 5.5    | 3.8          |
| 平均响应时间       | 12.3 秒 | 9.8 秒        |

### 模型竞技场

Unsloth Chat 可使用相同提示词并排比较任意两个模型。例如，比较基础模型和 LoRA 适配器。推理会先加载一个模型，再加载另一个模型（并行推理功能正在开发中）。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FC3xjqlunbpUr7nx6sQ4j%2Fimage.png?alt=media&amp;token=65501d63-1346-4a1e-b055-c94294a24305" alt="" width="563"><figcaption></figcaption></figure></div>

{% columns %}
{% column %}
训练后，你可以使用相同提示词并排比较基础模型和微调后的模型，查看发生了哪些变化，以及结果是否有所改善。

通过这一工作流程，你可以轻松了解微调如何改变模型的回复，以及它是否改善了针对你使用场景的结果。
{% endcolumn %}

{% column %}

<div align="center" data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FVgnE7eMPQk2vaFboJ4BU%2Fmodel%20arena%20closeup.png?alt=media&amp;token=8b0a910b-440c-4859-a846-0060e61e157b" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
Unsloth Studio Chat 可自动适配 **多 GPU 配置** 进行推理。
{% endhint %}

### 使用旧版 / 已有的 GGUF 模型

{% columns %}
{% column %}
**4 月 1 日更新：** 现在可以选择一个已有文件夹，让 Unsloth 从中检测模型。

**3 月 27 日更新：** Unsloth Studio 现在 **会自动检测较旧 / 预先存在的模型** 这些模型从 Hugging Face、LM Studio 等平台下载而来。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FBn3Fs1cchFchl328wSOs%2FScreenshot%202026-04-05%20at%205.43.57%E2%80%AFAM.png?alt=media&amp;token=cc57ec6e-653a-4824-8e8d-a6bfbcd27493" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

**手动操作说明：** Unsloth Studio 会检测下载到 Hugging Face Hub 缓存中的模型 `(C:\Users{your_username}.cache\huggingface\hub)`。如果你通过 LM Studio 下载了 GGUF 模型，请注意，这些模型存储在 `C:\Users\{your_username}.cache\lm-studio\models` ***或*** `C:\Users{your_username}\lm-studio\models` 中，默认情况下 llama.cpp 无法访问这些模型。你需要将这些 .gguf 文件移动或复制到 Hugging Face Hub 缓存目录（或 llama.cpp 可访问的其他路径），Unsloth Studio 才能加载它们。

在 Unsloth 中微调模型或适配器后，你可以将其导出为 GGUF，并使用 **llama.cpp** 直接在 Unsloth Chat 中运行本地推理。Unsloth Studio 基于 llama.cpp 和 Hugging Face 构建。

### 添加文件作为上下文

Unsloth Chat 支持在对话中直接使用多模态输入。你可以附加文档、图像或音频，为提示提供额外上下文。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FSitddQpGkOwUvirMem5P%2Fimage.png?alt=media&amp;token=43b7af91-ea86-4279-a787-b4b444640d82" alt="" width="563"><figcaption></figcaption></figure></div>

这样就能轻松测试模型如何处理 PDF、屏幕截图或参考资料等真实输入。文件会在本地处理，并作为上下文提供给模型。

### 项目来源和关联文件夹

使用 **添加来源** 添加单个文件，或使用 **添加文件夹** 来关联一个文件夹。Unsloth 每 30 秒检查一次关联文件夹中的新增、变更和删除文件，不会修改原始文件。

这三个索引计数器分别表示不同的内容：

| 计数器                            | 含义                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------ |
| **来源文件夹**: `750 of 7692 files` | 本次同步处理的文件数（新增、更新、移除或处理失败），占找到的所有受支持文件的数量。此前已编入索引的文件会跳过，因此恢复同步后，处理完成时的数量可能少于总数。 |
| **文件夹标签**: `1342 files`        | 此文件夹中已纳入项目索引的文件数。转圈指示器中的百分比表示已完成索引的比例。                                         |
| **项目来源**: `Indexing 2 of 1342` | 当前正在读取并生成嵌入的文件数，占文件夹标签所示文件总数的比例。 **这不代表整体进度。**                                 |

索引完成后， **来源文件夹** 旁的转圈指示器会停止，且该行会显示 `N files indexed`。跳过的文件会列在文件夹下方，包括： `与 .gitignore` 规则匹配的文件、构建文件夹、超大型数据文件，以及超出 10,000 个文件上限的文件。

文件夹菜单提供 **同步变更**, **重建索引**，以及在保留或不保留已索引文件的情况下取消链接。

### **删除模型文件**

你可以通过模型搜索中的垃圾桶图标删除旧模型文件，也可以从默认的 Hugging Face 缓存目录中移除相应的缓存模型文件夹。默认情况下，Hugging Face 使用 `~/.cache/huggingface/hub/` （适用于 macOS/Linux/WSL），以及 `C:\Users\<username>\.cache\huggingface\hub\` （适用于 Windows）。

* **macOS、Linux、WSL：** `~/.cache/huggingface/hub/`
* **Windows：** `%USERPROFILE%\.cache\huggingface\hub\`

如果 `HF_HUB_CACHE` 或 `HF_HOME` 已设置，请改用该位置。在 Linux 和 WSL 上， `XDG_CACHE_HOME` 也可以更改默认缓存根目录。

### **Unsloth 未检测到或未使用我的 GPU**

如果模型没有使用你的 GPU（尤其是在 Docker 中），请尝试：

手动拉取最新镜像：

```bash
 docker pull unsloth/unsloth:latest
```

* 启动容器并启用 GPU 访问：
  * `docker run`: `--gpus all`
  * Docker Compose： `capabilities: [gpu]`
* 在 Linux 上，请确保已安装 NVIDIA Container Toolkit。
* 在 Windows 上：
  * 检查 `nvcc --version` 显示的 CUDA 版本是否与 `nvidia-smi`
  * 请参阅： <https://docs.docker.com/desktop/features/gpu/>


---

# 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/xin/studio/chat.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.
