# 如何使用 Unsloth 和 Docker 微调 LLM

本地训练可能因依赖地狱或环境破坏而变得复杂。Unsloth 的 [Docker 镜像](https://hub.docker.com/r/unsloth/unsloth) 可以绕过这些问题。无需设置：拉取并运行镜像即可开始训练。

* **Unsloth 官方 Docker 镜像：** [**`unsloth/unsloth`**](https://hub.docker.com/r/unsloth/unsloth)

**为什么使用 Unsloth 与 Docker？**

Unsloth 的 Docker 镜像稳定、最新，并且在 [受支持的设置](https://unsloth.ai/docs/zh/kai-shi-shi-yong/fine-tuning-for-beginners/unsloth-requirements#system-requirements) 如 Windows 上可用。

* 完全包含的依赖使系统保持清洁。无 root 也能安全运行。
* 可在本地或任何预装笔记本的平台上使用。

{% hint style="success" %}
您现在可以使用我们的主 Docker 镜像 `unsloth/unsloth` 用于 Blackwell 和 50 系列 GPU —— 无需单独镜像。
{% endhint %}

### ⚡ 逐步教程

{% stepper %}
{% step %}
**安装 Docker 和 NVIDIA Container Toolkit。**

通过以下方式安装 Docker [Linux](https://docs.docker.com/engine/install/) 或 [桌面](https://docs.docker.com/desktop/) （其他）。\
然后安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#installation):

<pre class="language-bash"><code class="lang-bash"><strong>export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
</strong>sudo apt-get update &#x26;&#x26; sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}
</code></pre>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-41cae231ed4761f844ce9836e03b17aabd7c803c%2Fnvidia%20toolkit.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**运行容器。**

[**`unsloth/unsloth`**](https://hub.docker.com/r/unsloth/unsloth) 是 Unsloth 的唯一 Docker 镜像。对于 [Blackwell](https://unsloth.ai/docs/zh/bo-ke/fine-tuning-llms-with-blackwell-rtx-50-series-and-unsloth) 和 50 系列 GPU，使用相同的镜像即可 —— 无需单独镜像。如果使用 DGX Spark，您需要遵循我们的 [DGX 指南](https://unsloth.ai/docs/zh/bo-ke/fine-tuning-llms-with-nvidia-dgx-spark-and-unsloth).

```bash
docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth
```

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-2b50d78c5d54eaf189c0a40d46c405585ea23082%2Fdocker%20run.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**访问 Jupyter Lab**

前往 [http://localhost:8888](http://localhost:8888/) 并打开 Unsloth。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-828df0a668fd94025c1193c24a7f09c1d58dcbd8%2Fjupyter.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

访问 `unsloth-notebooks` 选项卡以查看 Unsloth 笔记本。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-e7a3f620a3ec5bff335632ff9b0cb422f76528a1%2FScreenshot_from_2025-09-30_21-38-15.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-531882c33eb96dec24e2d7673471d6a3928a3951%2FScreenshot_from_2025-09-30_21-39-41.png?alt=media" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**开始使用 Unsloth 进行训练**

如果您是新手，请按照我们的逐步 [微调指南](https://unsloth.ai/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide), [强化学习指南](https://unsloth.ai/docs/zh/kai-shi-shi-yong/reinforcement-learning-rl-guide) 或只是保存/复制我们任何预制的 [笔记本](https://unsloth.ai/docs/zh/kai-shi-shi-yong/unsloth-notebooks).

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-665f900b008991ddcd8fdabb773b292de3c41e72%2FScreenshot_from_2025-09-30_21-40-29.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

#### 📂 容器结构

* `/workspace/work/` — 您挂载的工作目录
* `/workspace/unsloth-notebooks/` — 示例微调笔记本
* `/home/unsloth/` — 用户主目录

### 📖 使用示例

#### 完整示例

```bash
docker run -d -e JUPYTER_PORT=8000 \
  -e JUPYTER_PASSWORD="mypassword" \
  -e "SSH_KEY=$(cat ~/.ssh/container_key.pub)" \
  -e USER_PASSWORD="unsloth2024" \
  -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth
```

#### 设置 SSH 密钥

如果您没有 SSH 密钥对：

```bash
# 生成新的密钥对
ssh-keygen -t rsa -b 4096 -f ~/.ssh/container_key

# 在 docker run 中使用公钥
-e "SSH_KEY=$(cat ~/.ssh/container_key.pub)"

# 通过 SSH 连接
ssh -i ~/.ssh/container_key -p 2222 unsloth@localhost
```

### ⚙️ 高级设置

| 变量                 | 说明                                                        | 默认        |
| ------------------ | --------------------------------------------------------- | --------- |
| `JUPYTER_PASSWORD` | Jupyter Lab 密码                                            | `unsloth` |
| `JUPYTER_PORT`     | 容器内的 Jupyter Lab 端口                                       | `8888`    |
| `SSH_KEY`          | 用于验证的 SSH 公钥                                              | `无`       |
| `USER_PASSWORD`    | 用户的密码（sudo） `unsloth` -p \<host\_port>:\<container\_port> | `unsloth` |

```bash
Jupyter Lab：
```

* -p 8000:8888 `SSH 访问：`
* -p 2222:22 `重要`

{% hint style="warning" %}
**： 使用卷挂载以在容器运行之间保留您的工作。**-v \<local\_folder>:\<container\_folder>
{% endhint %}

```bash
🔒 安全提示
```

```bash
docker run -d -e JUPYTER_PORT=8000 \
  -e JUPYTER_PASSWORD="mypassword" \
  -e "SSH_KEY=$(cat ~/.ssh/container_key.pub)" \
  -e USER_PASSWORD="unsloth2024" \
  -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth
```

### **容器默认以非 root**

* 用户身份运行 `unsloth` 在容器内进行 sudo 操作请使用
* 以在容器内执行 sudo 操作 `USER_PASSWORD` SSH 访问需要公钥认证
* SSH 访问需要公钥认证