unsloth 部署教学2.0

此文档旨在帮助初学者在国内网络环境下完成 Unsloth 的初步部署。核心步骤涉及使用 Conda 创建环境、通过国内镜像安装 Unsloth 及其依赖，并特别处理 PyTorch 版本以确保 GPU 支持。

简明扼要的前言：

Conda 与 PyTorch： Conda 对 PyTorch 的直接支持有时不尽如人意，但仍可用于管理 PyTorch 环境。
国内网络： 直接访问官方源可能缓慢或受限。清华大学等国内镜像源是常用替代，但其提供的 PyTorch 包可能默认为 CPU 版本，无法满足训练需求。
版本兼容性： Unsloth、PyTorch 及 xformers 等库之间存在版本依赖，需谨慎选择。

硬件与环境建议：

显卡： NVIDIA 显卡，显存建议至少 8GB (示例中使用 RTX 3060 12GB)。
Python 版本： 推荐 Python 3.11 (截至编写时，较新版本可能存在兼容性问题)。
CUDA： 需要预先安装与你NVIDIA驱动兼容的CUDA Toolkit。本教程以CUDA 11.8 (cu118) 为例。

部署流程：

1. 创建 Conda 虚拟环境

首先，创建一个独立的 Conda 环境以隔离项目依赖。请确保文件夹路径不包含中文字符，以避免潜在问题。

打开你的命令行终端 (如 PowerShell 或 CMD)：

ini 复制代码

conda create -n unsloth_env python=3.11
conda activate unsloth_env

例如，如果你想将环境命名为 unslothAmr：

ini 复制代码

conda create -n unslothAmr python=3.11
conda activate unslothAmr

激活环境后，命令行提示符前应出现 (unslothAmr) 或你指定的环境名。

yaml 复制代码

(base) PS J:\Unslothdeploymenttutorial> conda create -n unslothAmr python=3.11
Retrieving notices: done
Channels:
 - defaults
Platform: win-64
Collecting package metadata (repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: D:\ProgramData\anaconda3\envs\unslothAmr

  added / updated specs:
    - python=3.11


The following packages will be downloaded:

    package                    |            build
    ---------------------------|--------------------------------
    tk-8.6.14                  |       h5e9d12e_1         3.5 MB  defaults
    ------------------------------------------------------------
                                           Total:         3.5 MB

The following NEW packages will be INSTALLED:

  bzip2              pkgs/main/win-64::bzip2-1.0.8-h2bbff1b_6 done
#
# To activate this environment, use       
#
#     $ conda activate unslothAmr
#
# To deactivate an active environment, use
#
#     $ conda deactivate

(base) PS J:\Unslothdeploymenttutorial> conda activate unslothAmr
(unslothAmr) PS J:\Unslothdeploymenttutorial>

2. 安装 Unsloth (使用清华镜像源)

接下来，使用清华镜像源安装 Unsloth。此步骤会自动安装 Unsloth 及其依赖，其中通常包含一个 CPU 版本的 PyTorch。

Bash

arduino 复制代码

pip install unsloth -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，日志会列出所有已安装的包。请留意此时安装的 torch 和 xformers 的版本 (例如，日志中可能显示 torch-2.7.0 和 xformers-0.0.30)。

3. 检查初始 PyTorch (CPU 版本)

可以创建一个简单的 Python脚本 (例如 check_torch.py) 来验证当前 PyTorch 是否能使用 CUDA：

Python

scss 复制代码

import torch

def print_cuda_info():
    try:
        print("-" * 40)
        print("PyTorch CUDA Environment Information:")
        print("-" * 40)
        if torch.cuda.is_available():
            device_count = torch.cuda.device_count()
            print(f"Number of CUDA devices: {device_count}")
            if device_count > 0:
                device_name = torch.cuda.get_device_name(0)
                print(f"0th CUDA Device Name: {device_name}")
                total_memory = torch.cuda.get_device_properties(0).total_memory
                allocated_memory = torch.cuda.memory_allocated(0)
                free_memory = total_memory - allocated_memory
                print(f"Total Memory: {total_memory / (1024 ** 3):.2f} GB")
                print(f"Allocated Memory: {allocated_memory / (1024 ** 3):.2f} GB")
                print(f"Free Memory: {free_memory / (1024 ** 3):.2f} GB")
            else:
                print("No CUDA devices found.")
        else:
            print("CUDA is not available.")
        print("-" * 40)
    except Exception as e:
        print("-" * 40)
        print(f"An error occurred: {e}")
        print("-" * 40)

if __name__ == "__main__":
    print_cuda_info()

运行脚本：

Bash

复制代码

python check_torch.py

预期输出会提示 "CUDA is not available."

markdown 复制代码

(unslothAmr) PS J:\Unslothdeploymenttutorial> python .\tryprincuda.py
----------------------------------------
CUDA is not available.
----------------------------------------
(unslothAmr) PS J:\Unslothdeploymenttutorial>

4. 卸载 CPU 版本的 PyTorch

卸载上一步中由清华源自动安装的 PyTorch 相关包：

Bash

复制代码

pip uninstall torch torchvision torchaudio -y

5. 安装 GPU 版本的 PyTorch (使用阿里云镜像或官方源)

🚸 版本选择至关重要：

Unsloth 兼容性： 检查你安装的 Unsloth 版本对 PyTorch 的最低版本要求 (例如，unsloth-2025.5.9 可能需要 torch>=2.4.0)。

xformers 兼容性： 步骤2中与 Unsloth 一同安装的 xformers 版本 (例如 xformers-0.0.30) 通常与当时一同安装的 PyTorch CPU 版本 (例如 torch-2.7.0) 兼容。

CUDA 版本： 确保选择与你的 NVIDIA 驱动和本地 CUDA Toolkit 版本匹配的 PyTorch (例如 cu118 对应 CUDA 11.8)。

建议： 尝试安装与步骤2中 Unsloth 初始依赖的 PyTorch 版本号相同，但带有正确 CUDA 后缀的 PyTorch。例如，如果初始安装了 torch-2.7.0 (CPU)，则目标是安装 torch==2.7.0 的 cu118 版本。

你可以访问 PyTorch 官方网站 (pytorch.org/get-started...)，根据你的操作系统、包管理器 (pip)、语言 (Python) 和 CUDA 版本生成安装命令。

使用阿里云 PyTorch 镜像的示例命令格式 (以 cu118 为例)：

arduino 复制代码

格式信息:
#pip install torch==<目标torch版本> torchvision==<对应版本> torchaudio==<对应版本> -f https://mirrors.aliyun.com/pytorch-wheels/cu118/torch_stable.html

例如，如果目标是 torch-2.7.0 (假设 Unsloth 需要 torch>=2.4.0，且初始 xformers 兼容 2.7.0)，你需要查找 torch-2.7.0 对应的 torchvision 和 torchaudio 版本，并确保阿里云镜像上有 cu118 的构建。一个更通用的方法是直接使用 PyTorch 官方提供的安装命令，它会自动处理版本对应关系：

perl 复制代码

# 示例：安装 PyTorch (cu118)，版本由 PyTorch 官方决定（通常是最新兼容版）
# 你可能需要根据你的目标版本调整
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# 但是前提是能访问 https://download.pytorch.org

如果坚持使用特定版本 (如 torch==2.7.0 以匹配 xformers 和满足 Unsloth 要求)： 你需要找到该特定版本 PyTorch (2.7.0) 及其对应 torchvision 和 torchaudio 的 cu118 构建。假设存在 torch==2.7.0+cu118，torchvision==0.18.0+cu118 [⬅️这里只是举例]，torchaudio==2.2.0+cu118 (此版本为假设，请核实)：

ini 复制代码

pip install torch==2.7.0 torchvision==0.18.0 torchaudio==2.2.0 --index-url https://download.pytorch.org/whl/cu118
# 或通过阿里云 (如果版本存在)
# pip install torch==2.7.0+cu118 torchvision==0.18.0+cu118 torchaudio==2.2.0+cu118 -f https://mirrors.aliyun.com/pytorch-wheels/cu118/torch_stable.html

⚠️安装过程中，pip 可能会提示依赖冲突，尤其是如果你选择的 PyTorch 版本与 Unsloth 或 xformers 的硬性要求不完全匹配。仔细阅读错误信息。如果提示 unsloth requires torch>=X.X.X, but you have torch Y.Y.Y，请确保你安装的 Y.Y.Y 至少是 X.X.X。

6. 再次验证 PyTorch GPU 支持

运行之前的 check_torch.py 脚本：

复制代码

python check_torch.py

预期输出应显示你的 NVIDIA 显卡信息及显存情况，表明 CUDA 已可用。

例如

markdown 复制代码

(unslothAmr) PS J:\Unslothdeploymenttutorial> python .\tryprincuda.py
----------------------------------------
PyTorch CUDA Environment Information:
----------------------------------------
Number of CUDA devices: 1
0th CUDA Device Name: NVIDIA GeForce RTX 3060
Total Memory: 12.00 GB
Allocated Memory: 0.00 GB
Free Memory: 12.00 GB
----------------------------------------
(unslothAmr) PS J:\Unslothdeploymenttutorial>

7. 测试 Unsloth 导入及问题排查

修改 check_torch.py 脚本，在末尾加入 Unsloth 导入语句：

Python

scss 复制代码

import torch

def print_cuda_info():
    try:
        print("-" * 40)
        print("PyTorch CUDA Environment Information:")
        print("-" * 40)
        if torch.cuda.is_available():
            device_count = torch.cuda.device_count()
            print(f"Number of CUDA devices: {device_count}")
            if device_count > 0:
                device_name = torch.cuda.get_device_name(0)
                print(f"0th CUDA Device Name: {device_name}")
                total_memory = torch.cuda.get_device_properties(0).total_memory
                allocated_memory = torch.cuda.memory_allocated(0)
                free_memory = total_memory - allocated_memory
                print(f"Total Memory: {total_memory / (1024 ** 3):.2f} GB")
                print(f"Allocated Memory: {allocated_memory / (1024 ** 3):.2f} GB")
                print(f"Free Memory: {free_memory / (1024 ** 3):.2f} GB")
            else:
                print("No CUDA devices found.")
        else:
            print("CUDA is not available.")
        print("-" * 40)
    except Exception as e:
        print("-" * 40)
        print(f"An error occurred: {e}")
        print("-" * 40)

if __name__ == "__main__":
    print_cuda_info()
    print("Attempting to import Unsloth...")
    from unsloth import FastLanguageModel
    print("Unsloth imported successfully.")

运行脚本：

Bash

复制代码

python check_torch.py

可能会遇到的问题：

NumPy 版本冲突：
arduino 复制代码
```
A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.x.x as it may crash...
```
解决方案： 降级 NumPy 版本。

Bash
复制代码
```
pip install numpy<2
```
然后再次运行 check_torch.py。
xFormers 警告：
vbnet 复制代码
```
WARNING[XFORMERS]: xFormers can't load C++/CUDA extensions. xFormers was built for:
   PyTorch X.Y.Z+cuABC with CUDA XY (you have PyTorch A.B.C+cuDEF)
  Please reinstall xformers...
  Memory-efficient attention, SwiGLU, sparse and more won't be available.
```
原因： 当前环境的 PyTorch 版本/CUDA 版本与 xformers 编译时依赖的版本不匹配。 说明： Unsloth 仍可能运行，但 xformers 提供的部分性能优化可能无法生效。 建议的尝试 (进阶)：
0. 确保你在步骤 5 中安装的 PyTorch 版本尽可能与 Unsloth 及其捆绑的 xformers 版本兼容。如果选择了与初始CPU版 PyTorch (如 2.7.0) 版本号相同的GPU版 PyTorch (如 2.7.0+cu118)，此问题可能减轻。
1. 如果问题依旧，可以尝试重装 xformers，让 pip 尝试寻找与当前 PyTorch GPU 版本更匹配的 xformers：
  
  Bash
  复制代码
```
pip uninstall xformers -y
pip install xformers
```
  注意：可能需要指定特定的 xformers 版本或使用特定索引源。

8. 最终验证

在解决上述问题后，再次运行 check_torch.py。如果能看到 CUDA 信息，并且 Unsloth 成功导入 (可能会伴随 Unsloth 自身的启动日志和 xformers 的警告)，则基本部署完成。

markdown 复制代码

(unslothAmr) PS J:\Unslothdeploymenttutorial> python .\tryprincuda.py
----------------------------------------
PyTorch CUDA Environment Information:
----------------------------------------
Number of CUDA devices: 1
0th CUDA Device Name: NVIDIA GeForce RTX 3060
Total Memory: 12.00 GB
Allocated Memory: 0.00 GB
Free Memory: 12.00 GB
----------------------------------------
🦥 Unsloth: Will patch your computer to enable 2x faster free finetuning.
WARNING[XFORMERS]: xFormers can't load C++/CUDA extensions. xFormers was built for:
    PyTorch 2.7.0+cu126 with CUDA 1206 (you have 2.3.1+cu118)
    Python  3.11.9 (you have 3.11.11)
  Please reinstall xformers (see https://github.com/facebookresearch/xformers#installing-xformers)
  Memory-efficient attention, SwiGLU, sparse and more won't be available.
  Set XFORMERS_MORE_DETAILS=1 for more details
🦥 Unsloth Zoo will now patch everything to make training faster!
(unslothAmr) PS J:\Unslothdeploymenttutorial>

🟩 即使 xformers 警告依然存在，Unsloth 通常也能运行。完全解决 xformers 警告可能需要更细致的 PyTorch 和 xformers 版本匹配，或从源码编译 xformers，这超出了本初步部署指南的范围。

至此，Unsloth 的基础 GPU 环境应已配置完毕。