> 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/how-to-run-llms-with-docker.md).

# 如何使用 Docker 在本地运行 LLM：分步指南

了解如何在本地设备上使用 Docker 和 Unsloth 运行大型语言模型（LLM）。

你现在可以运行任何模型，包括 Unsloth [动态 GGUFs](/docs/zh/ji-chu-zhi-shi/dynamic-3.0-ggufs.md)，在 Mac、Windows 或 Linux 上，只需一行代码，或者 **无需代码** 完全不需要。我们与 Docker 合作简化模型部署，而 Unsloth 现在为 Docker 上大多数 GGUF 模型提供支持。

在开始之前，请务必查看 [硬件要求](#hardware-info--performance) 和 [我们的提示](#hardware-info--performance) 以优化在你的设备上运行 LLM 时的性能。

<a href="/docs/zh/mo-xing/tutorials/how-to-run-llms-with-docker.md#method-1-docker-terminal" class="button primary">Docker 终端教程</a><a href="#method-2-docker-desktop-no-code" class="button primary">Docker 无代码教程</a>

要开始，请运行 OpenAI [gpt-oss](/docs/zh/mo-xing/gpt-oss-how-to-run-and-fine-tune.md) ，只需一条命令：

```bash
docker model run ai/gpt-oss:20B
```

或者要运行特定的 [Unsloth 模型](/docs/zh/kuai-su-kai-shi/unsloth-model-catalog.md)  / Hugging Face 上的量化版本：

```bash
docker model run hf.co/unsloth/gpt-oss-20b-GGUF:F16
```

{% hint style="success" %}
你不需要 Docker Desktop，Docker CE 就足以运行模型。
{% endhint %}

#### **为什么选择 Unsloth + Docker？**

我们与 Google Gemma 等模型实验室合作，修复模型 bug 并提高准确率。我们的 Dynamic GGUF 一贯优于其他量化方法，为你提供高精度、高效率的推理。

如果你使用 Docker，就可以零配置立即运行模型。Docker 使用 [Docker Model Runner](https://github.com/docker/model-runner) （DMR），让你像运行容器一样轻松运行 LLM，且不会有依赖问题。DMR 使用 Unsloth 模型和 `llama.cpp` 在幕后提供快速、高效、最新的推理。

## :gear: 硬件信息 + 性能

为了获得最佳性能，建议你的 VRAM + RAM 总和至少等于你下载的量化模型大小。如果更少，模型仍然可以运行，但会明显更慢。

确保你的设备也有足够的磁盘空间来存储模型。如果模型只是勉强装进内存，预计速度大约为 \~5 tokens/s，具体取决于模型大小。

可用的额外 RAM/VRAM 会提升推理速度，而更多的 VRAM 将带来最大的性能提升（前提是整个模型能够装下）

{% hint style="info" %}
**示例：** 如果你下载的是 gpt-oss-20b（F16），且模型大小为 13.8 GB，请确保你的磁盘空间以及 RAM + VRAM > 13.8 GB。
{% endhint %}

**量化建议：**

* 对于参数少于 30B 的模型，至少使用 4-bit（Q4）。
* 对于参数为 70B 或更大的模型，至少使用 2-bit 量化（例如，UD\_Q2\_K\_XL）。

## ⚡ 分步教程

下面有 **两种方式** 使用 Docker 运行模型：一种使用 [终端](#method-1-docker-terminal)，另一种使用 [Docker Desktop](#method-2-docker-desktop-no-code) ，无需代码：

### 方法 #1：Docker 终端

{% stepper %}
{% step %}

#### 安装 Docker

Docker Model Runner 已经可在 **两者** [Docker Desktop](https://docs.docker.com/ai/model-runner/get-started/#docker-desktop) 和 [**Docker CE**](https://docs.docker.com/ai/model-runner/get-started/#docker-engine)**.**
{% endstep %}

{% step %}

#### 运行模型

先决定要运行的模型，然后通过终端运行命令。

* 浏览 [Docker Hub](https://hub.docker.com/r/ai) 或 [Unsloth 的 Hugging Face](https://huggingface.co/unsloth) 页面。
* 前往终端执行命令。要验证你是否已安装 `docker` ，你可以输入 'docker' 并按回车。
* Docker Hub 默认运行 Unsloth Dynamic 4-bit，不过你可以选择自己的量化级别（见第 #3 步）。

例如，要运行 OpenAI `gpt-oss-20b` ，只需一条命令：

```bash
docker model run ai/gpt-oss:20B
```

或者要运行特定的 [Unsloth](/docs/zh/kuai-su-kai-shi/unsloth-model-catalog.md) gpt-oss 的 Hugging Face 量化版本：

```bash
docker model run hf.co/unsloth/gpt-oss-20b-GGUF:UD-Q8_K_XL
```

**通过 CLI 运行 gpt-oss-20b 应该如下所示：**

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FNQQGqQfLuX2a40i07Es1%2Funknown.png?alt=media&amp;token=6006e370-a298-4e5f-af9f-5c4e8c4a0fc8" alt="" width="563"><figcaption><p>来自 Docker Hub 的 gpt-oss-20b</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FFtzowkLonKo4N2LzEnhe%2Fgptoss%20ud8kxl.png?alt=media&amp;token=08eb6244-0626-4ad8-adbe-f5c4e5aa6d72" alt="" width="563"><figcaption><p>使用 Unsloth 的 UD-Q8_K_XL 量化的 gpt-oss-20b</p></figcaption></figure></div>
{% endstep %}

{% step %}

#### 要运行特定量化级别：

如果你想运行某个模型的特定量化版本，请在后面追加 `:` 以及量化名称到模型名后（例如， `Q4` 用于 Docker，或者 `UD-Q4_K_XL`）。你可以在每个模型的 Docker Hub 页面查看所有可用量化版本。例如，查看 gpt-oss 的列出量化版本 [这里](https://hub.docker.com/r/ai/gpt-oss#gptoss).

同样适用于 Hugging Face 上的 Unsloth 量化版本：访问 [模型的 HF 页面](https://huggingface.co/unsloth/gpt-oss-20b-GGUF?show_file_info=gpt-oss-20b-Q2_K_L.gguf)，选择一个量化版本，然后运行类似下面的命令： `docker model run hf.co/unsloth/gpt-oss-20b-GGUF:Q2_K_L`

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FI7MrphUugkU8eZ1f7lJz%2FScreenshot%202025-11-16%20at%2010.52.25%E2%80%AFPM.png?alt=media&amp;token=ae777fdb-258e-46d0-b06e-b68434f7fa58" alt="" width="563"><figcaption><p>gpt-oss 的量化级别，位于 <a href="https://hub.docker.com/r/ai/gpt-oss#gptoss">Docker Hub</a></p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F73UWIs9VAZ6Iz1omgZSm%2FScreenshot%202025-11-16%20at%2010.54.53%E2%80%AFPM.png?alt=media&amp;token=e8dee7f3-1b8b-4dda-a455-26df58102d16" alt="" width="563"><figcaption><p>Unsloth gpt-oss 的量化级别，位于<a href="https://huggingface.co/unsloth/gpt-oss-20b-GGUF"> Hugging Face</a></p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 方法 #2：Docker Desktop（无代码）

{% stepper %}
{% step %}

#### 安装 Docker Desktop

Docker Model Runner 已经可在 [Docker Desktop](https://docs.docker.com/ai/model-runner/get-started/#docker-desktop).

1. 先决定要运行的模型，打开 Docker Desktop，然后点击模型选项卡。
2. 点击“Add models +”或 Docker Hub。搜索该模型。

浏览可用的已验证模型目录，位于 [Docker Hub](https://hub.docker.com/r/ai).

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F6R8uxbedMklVHsriLgpZ%2FScreenshot%202025-11-16%20at%206.36.49%E2%80%AFAM.png?alt=media&amp;token=0fb849f5-bc72-4883-9b25-1a756334ab4b" alt=""><figcaption><p>#1. 点击“Models”选项卡，然后点击“Add models +”</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fj7I69xgxDeHXkvVbjemq%2FScreenshot%202025-11-16%20at%206.46.47%E2%80%AFAM.png?alt=media&amp;token=3e25d495-f34b-47d6-9185-f145610eed10" alt=""><figcaption><p>#2. 搜索你想要的模型。</p></figcaption></figure></div>
{% endstep %}

{% step %}

#### 拉取模型

点击你想运行的模型以查看可用的量化版本。

* 量化范围为 1–16 bit。对于参数少于 30B 的模型，至少使用 4-bit（`Q4`).
* 选择适合你硬件的大小：理想情况下，你的统一内存、RAM 或 VRAM 总和应等于或大于模型大小。例如，一个 11GB 的模型在 12GB 统一内存上运行良好。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FdQnwVwsMhYtWTzAGFih3%2FScreenshot%202025-11-16%20at%206.47.26%E2%80%AFAM.png?alt=media&amp;token=b1f0e29a-b3de-4d96-b79a-931441744565" alt=""><figcaption><p>#3. 选择你要拉取的量化版本。</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FFGMZEXgQjBdVqP0vFTX3%2FScreenshot%202025-11-16%20at%206.54.09%E2%80%AFAM.png?alt=media&amp;token=b7f0c0d8-ebef-4e7e-99a9-c44c4c5f0844" alt=""><figcaption><p>#4. 等待模型下载完成，然后运行它。</p></figcaption></figure></div>
{% endstep %}

{% step %}

#### 运行模型

在“Ask a question”框中输入任意提示词，然后像使用 ChatGPT 一样使用 LLM。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F9nVjWcVsYK9CeT8gk3nQ%2FScreenshot%202025-11-16%20at%206.54.50%E2%80%AFAM.png?alt=media&amp;token=d7e5b63d-9c3e-42b0-882c-de046bbcfc9a" alt="" width="563"><figcaption><p>运行 Qwen3-4B 的示例 <code>UD-Q8_K_XL</code></p></figcaption></figure>
{% endstep %}
{% endstepper %}

#### **要运行最新模型：**

只要受支持，你就可以在 Docker 上运行任何新模型， `llama.cpp` 或 `vllm` 并且可在 Docker Hub 上获取。

### 什么是 Docker Model Runner？

Docker Model Runner（DMR）是一个开源工具，让你像运行容器一样轻松拉取并运行 AI 模型。GitHub： <https://github.com/docker/model-runner>

它为模型提供一致的运行时，就像 Docker 标准化了应用部署一样。在幕后，它使用优化的后端（例如 `llama.cpp`）在你的机器上实现流畅、硬件高效的推理。

无论你是研究人员、开发者还是爱好者，现在你都可以：

* 在几秒内在本地运行开源模型。
* 避免依赖地狱，所有事情都由 Docker 处理。
* 轻松分享和复现模型配置。


---

# 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/tutorials/how-to-run-llms-with-docker.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.