人工智能大模型微调LoRA模型优化模型量化强化学习【免费下载链接】unslothLocal UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4, MiniMax-H3, Gemma 4, FLUX and more.项目地址https://gitcode.com/GitHub_Trending/un/unsloth点击查看免费下载本篇指南围绕仓库中的 docker/DOCKERHUB-ROCM.md 展开系统讲解 Unsloth 为 AMD GPU 提供的 ROCm 官方镜像unsloth/unsloth-rocm如何构造正确的 Docker 设备透传参数、在 Linux 与 WSL2 两种宿主环境下运行、按硬件架构选择合适的标签与构建方式以及镜像内完整的训练栈、环境变量与可复现性约束。读完本文你将能在 AMD RDNA2/RDNA3/RDNA4 与 CDNA 显卡上直接跑起 LoRA/QLoRA 微调、文本到图像与文本到视频生成并学会用镜像自带的 smoke test 快速验证 GPU 是否真正可用。一、镜像定位AMD 侧的完整训练栈unsloth/unsloth-rocm是 CUDA 版unsloth/unsloth的 AMD 对应物。镜像内预装了面向 ROCm 构建的完整训练栈PyTorchROCm 7.2 版本、Unsloth、unsloth-zoo、带 ROCm 4-bit 修复的 bitsandbytes、triton-rocm、TRL、PEFT 与 diffusers目标是让 AMD 用户零配置地微调和运行 LLM。镜像的构建源头是 docker/Dockerfile.rocm其基础镜像是rocm/dev-ubuntu-24.04:7.2.4Python 3.12 位于独立的虚拟环境/opt/unsloth-venv中。值得注意的构建细节整个 Python 栈在单层内通过 uv 一次性解析锁定见 Dockerfile.rocm先从 ROCm 索引解析出 torch 版本再以torchX约束重新解析整个依赖集并在构建阶段就断言torch.version.hip非空、无任何nvidia-*CUDA wheel、triton 恰好是 torch 锁定的那个且带有amd后端——这些校验不依赖 GPU 即可在构建机上执行。CUDA 镜像通过 NVIDIA Container Toolkit 的--gpus接入 GPU而 AMD 显卡不经过任何容器工具包直接通过内核驱动的设备节点暴露给容器因此docker run的写法完全不同。二、快速开始Linux 宿主2.1 前置条件已安装 Docker无 Docker 时可用官方脚本安装curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.shLinux 宿主装有可用的 amdgpu 内核驱动Windows 宿主走 WSL2见下一节。2.2 手工构造设备透传参数AMD 设备节点是/dev/kfd内核 Fusion Driver 节点与/dev/dri渲染节点且容器内需要宿主的video、render组 id。推荐直接用仓库的 docker/run.sh 帮你推导bash docker/run.sh --rocm若想手工运行下面这几行正是run.sh构造 flags 的完整逻辑见 docker/run.sh 的amd_device_flagsGPU_FLAGS--device /dev/kfd [ -e /dev/dri ] GPU_FLAGS$GPU_FLAGS --device /dev/dri for g in video render; do gid$(getent group $g | cut -d: -f3) [ -n $gid ] GPU_FLAGS$GPU_FLAGS --group-add $gid done docker run --rm -it \ $GPU_FLAGS \ --ipchost \ -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \ unsloth/unsloth-rocm每一段都有明确理由--group-add必须传数字组 id组名是在容器内部解析的而宿主机的video/render组在镜像里并不存在传名字会加错组导致/dev/kfd不可读最小化宿主可能根本没有render组直接--group-add $(getent group render | cut -d: -f3)会展开成空参数所以先判空再拼接/dev/dri只在存在时才传Docker 不允许启动一个引用了不存在宿主设备的容器因此缺失时宁可不传让 entrypoint 去解释驱动不完整而不是在 daemon 层直接失败。--ipchost提供充足的共享内存默认 64MB 会压垮 DataLoader 多进程。Hugging Face 缓存挂载并非可选容器内HF_HOME/workspace/.cache/huggingface位于容器的可写层不挂载的话每次docker rm后所有模型都要重新下载。2.3 用 run.sh 一键启动run.sh 在 Linux 与 WSL 上都可用默认使用发布镜像unsloth/unsloth-rocm:latestcurl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/docker/run.sh -o run.sh bash run.sh --rocm # Linux UNSLOTH_IMAGEunsloth-rocm:latest bash run.sh --rocm # WSL--rocm只能作为第一个参数其后的全部参数原样传给容器命令等价地可设UNSLOTH_ROCM1。除设备节点外run.sh还会自动挂载宿主 Hugging Face 缓存、Triton 缓存、当前工作目录到/workspace/host并转发HF_TOKEN、WANDB_API_KEY、HSA_OVERRIDE_GFX_VERSION等环境变量完整清单见 docker/run.sh。三、快速开始WindowsWSL2 / DXG 桥Windows 宿主上没有/dev/kfd。WSL2 通过DXG 桥访问显卡因此参数变为/dev/dxg节点 HSA 运行时的 opt-in 变量 宿主的librocdxg动态库GPU_FLAGS--device /dev/dxg -e HSA_ENABLE_DXG_DETECTION1 \ -v /opt/rocm/lib/librocdxg.so.1:/usr/lib/x86_64-linux-gnu/librocdxg.so:ro \ -v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro -e LD_LIBRARY_PATH/usr/lib/wsl/lib docker run --rm -it \ $GPU_FLAGS \ --ipchost \ -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \ unsloth-rocm:latestWSL 路径不需要--group-addWSL 把/dev/dxg暴露给所有用户且没有render组。需要注意的三点镜像无法内置librocdxg它的构建需要 Windows SDK 的 headers任何 Linux 构建机都不具备。该库由宿主提供而宿主侧由 scripts/install_rocm_wsl_strixhalo.sh 负责安装自动检测 gfx 架构、构建 librocdxg 并写入/etc/profile.d持久化HSA_ENABLE_DXG_DETECTION1必须用 WSL 发行版内部的 Docker 引擎Docker Desktop 自带的引擎既不暴露/dev/kfd也不暴露/dev/dxg必须使用按架构构建的镜像通用镜像的 torch 捆绑了librocprofiler-sdk该库通过 KFD sysfs 拓扑枚举 GPU在 DXG 桥上找不到 agent 会直接abort()entrypoint 会在走到那一步之前就拒绝启动见 docker/entrypoint-rocm.sh 的诊断逻辑。3.1 WSL 下自行构建按架构镜像在按架构标签发布之前用 docker/build.sh 本地构建ROCM_GFXyour gfx bash docker/build.sh --rocm产物本地打标为unsloth-rocm:latest。该构建面向 Strix APU 与 RDNA4gfx1150、gfx1151、gfx1152、gfx1200、gfx1201。RDNA3 显卡gfx1100–gfx1103尚无桥接路径——因为 Dockerfile.rocm 没有把它们映射到 AMD 的gfx110X-allwheel 家族gfx1103不在已知列表中。四、启动前的 GPU 验证smoke test在任何训练开始前先用镜像自带的冒烟测试确认 GPU 可见。设置好上文 Linux 或 WSL 的GPU_FLAGS后docker run --rm $GPU_FLAGS \ -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \ unsloth/unsloth-rocm python /workspace/smoke_test_rocm.py该脚本 docker/smoke_test_rocm.py 按 fail-fast 顺序执行五步检查torch 是 ROCm 构建torch.version.hip非空且torch.cuda.is_available()为真随后在 GPU 上跑一次 fp16 矩阵乘断言数值正确依赖导入unsloth、unsloth-zoo、triton断言存在amd后端、bitsandbytes、transformers、trl、peftxformers 无 ROCm wheel缺失是预期unsloth 的FastLanguageModel可达在 Llama-3.2-1B 上跑5 步真实 LoRA 训练每步断言 loss 与梯度均有限NaN 正是旧版 bitsandbytes 4-bit ROCm bug 的表现且 5 步后 loss 必须下降、LoRA 权重必须被更新。缓存挂载的意义在此体现容器是--rm的没有挂载的话每次重试都要重新下载模型。跳过训练步骤更快、不下载模型可加--skip-train。五、镜像标签Tagstag含义latest当前main分支的构建linux/amd64sha-commit同一镜像钉死在构建时的提交nightly每周定时构建gfx1150、gfx1151、gfx1152、gfx1200、gfx1201使用 AMD 按架构 wheel 的构建发布后可用studiolatest之上叠加 Unsloth Studio 的 Web UI8000 端口与带 Unsloth notebooks 的 JupyterLab8888 端口源自 docker/Dockerfile.studio-rocm。上述每个标签都有基于同一基础镜像的-studio孪生任何可复现的场景都应钉 digest因为latest会移动。构建记录本身写入镜像cat /etc/unsloth-rocm-build可查看构建时用的 ROCm 版本、wheel 索引与架构/opt/unsloth-venv/requirements.lock.txt是解析后的完整包清单Dockerfile.rocm。六、支持的硬件与三个特殊情形镜像支持RDNA2 及以上与 CDNA除gfx1033外基于通用 ROCm 7.2 PyTorch 索引构建覆盖大多数显卡。三个情形需要特别处理Strix Halo / Strix Point APUgfx1150/gfx1151/gfx1152与 RDNA4gfx1200/gfx1201能在通用 wheel 上运行entrypoint 启动时会提示但 AMD 的按架构 wheel 携带通用索引缺失的修复——不止是调优例如gfx1151上的_grouped_mm段错误。通用镜像可能正常工作下文实测数据正是在通用镜像上测得但若在这类架构上训练崩溃用ROCM_GFXgfx1151或对应架构重建是修复手段而非提速手段Van Goghgfx1033Steam Deck被直接拒绝它是 RDNA2但在 ROCm 下前向传播看似正常、训练却发散为 NaN。entrypoint 直接退出而不是带病训练HSA_OVERRIDE_GFX_VERSION也无法解决因为它只是隐藏了硅片标识、改不了算术结果。相关测量记录在 studio/ROCM_RDNA2_APU.mdgfx1033 的 142 个 rocBLAS Tensile 文件中 76% 是fallback且三套独立 ROCm 版本包括 AMD 官方原生 gfx1033 构建训练均失败Vega 20gfx906在 ROCm 6.3 之后失去内核用ROCM_GFXgfx906与ROCM_VERSION6.3.4构建对应 Dockerfile.rocm 顶部的注释。该变体不带 bitsandbytes——没有任何预编译 wheel 携带 gfx906 内核Dockerfile.rocm。容器启动时会打印探测到的硬件信息拒绝静默降级到 CPUentrypoint 依次检查/dev/kfd存在且可读、rocm-smi 可见性、torch 为 HIP 构建且torch.cuda.is_available()为真、显卡 gfx 架构与镜像 wheel 的匹配关系见 docker/entrypoint-rocm.sh每步失败都给出可操作的修复命令。设置UNSLOTH_SKIP_GPU_CHECK1可绕过诊断仅适合离线工具链/CI绕过后结果依然不正确。七、实测数据What is measured以下数据来自 Radeon 8060Sgfx1151Strix Halo对发布版latestdigest 实测工作负载结果4-bit QLoRA5 步Llama 3.2 1Bloss 从 2.8146 降至 1.2242文生图sd-turbo4 步512px118 秒峰值显存 4.21 GB文生视频text-to-video-ms-1.7b8 帧256px279 秒峰值显存 4.77 GB扩散模型的输出与 NVIDIA B200 在相同随机种子下像素差达到小数点后三位一致说明这是数值层面的符合而不只是能跑。速度是另一回事共享系统内存的集成 APU 在这两代工作负载上大约比数据中心显卡慢 25–50 倍。独立 RDNA2、RDNA4 与 CDNA 显卡不在该测试覆盖范围内。八、镜像里有什么、没有什么包含PyTorchROCm、Unsloth、unsloth-zoo、transformers、TRL、PEFT、accelerate、bitsandbytes、triton-rocm、diffusers、timm。latest不包含与unsloth/unsloth不同Unsloth Studio 及其 Web UI、JupyterLab、预编译 llama.cpp 与 whisper.cpp、vLLM 和 xformers。latest是纯训练镜像。studio标签额外增加Unsloth Studio、带 Unsloth notebooks优先展示AMD-*系列的 JupyterLab以及用于 GGUF 聊天的 CPU 版 llama.cpp——仍然没有 whisper.cpp、vLLM 或 xformers。训练、notebooks 与 UI 走 GPUGGUF 聊天走 CPU因为 ROCm 版 llama.cpp 是按架构的打包它会将镜像钉死在单一显卡上。Studio 的数据账户、聊天、输出位于/opt/unsloth-studio务必挂载卷持久化同时设置 Linux 快速开始中的GPU_FLAGSdocker run --rm $GPU_FLAGS --ipchost -p 127.0.0.1:8000:8000 -p 127.0.0.1:8888:8888 \ -v unsloth-studio-rocm:/opt/unsloth-studio \ -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \ unsloth/unsloth-rocm:studiostudio镜像的构建细节见 docker/Dockerfile.studio-rocm它把 JupyterLab 4.6 与 notebook 运行时依赖装入基础 venvkernel 即 ROCm torch通过install.sh --local在独立 venv 安装 Studio并断言 Studio venv 的 torch 与基础 venv 同属一个rocmleafJupyter 侧还内置了 pip/uv shimdocker/unsloth_pip_shim.py 的 PATH 前置机制防止 notebook 里的安装单元破坏已烘焙的 ROCm 栈。九、环境变量一览变量作用UNSLOTH_SKIP_GPU_CHECK1跳过启动诊断见上文拒绝静默降级HSA_OVERRIDE_GFX_VERSION将不受支持的显卡伪装成受支持的架构。在带该卡原生内核的镜像上会被忽略——entrypoint 会警告并主动 unset见 docker/entrypoint-rocm.shHF_TOKEN转发用于受门控的模型UNSLOTH_STUDIO_PASSWORDstudio标签初始管理员密码仅首次启动生效一旦存储即被忽略。未设置时 Studio 自动生成并在日志中指明写入的文件JUPYTER_PASSWORD/UNSLOTH_STUDIO_PORT等studio标签的 Jupyter/Studio 配置由 docker/run.sh 转发docker/run.sh模型下载统一落在/workspace/.cache/huggingface容器可写层内不挂载就会在docker rm后全部丢失挂载后还能复用宿主已下载的模型。Studio 数据卷默认名为unsloth-studio-rocm通过UNSLOTH_STUDIO_VOLUME覆盖。十、自行构建与端到端验证10.1 用 build.sh 构建bash docker/build.sh --rocm # 默认ROCm 7.2.4 pytorch.org rocm7.2 wheels ROCM_GFXgfx1151 bash docker/build.sh --rocm # Strix Halo切到 repo.amd.com 按架构索引 torch 2.11 线 ROCM_GFXgfx1201 bash docker/build.sh --rocm # RX 9070 XTRDNA4 ROCM_VERSION6.3.4 bash docker/build.sh --rocm --gfx gfx906 # Vega 20无 bitsandbytes TAGmy-tag UNSLOTH_REFsha UNSLOTH_ZOO_REFsha bash docker/build.sh --rocm构建参数细节docker/build.shROCM_VERSION默认7.2.4这是下限rocm6.4 最高只到 torch 2.9.1低于 unsloth-zoo 的要求且 RDNA4 在 7.x 之前没有内核TORCH_INDEX_URL默认跟随基础版本7.2.4→rocm7.2索引无--gfx时用通用索引覆盖 RDNA2/RDNA3/RDNA4/CDNA--gfx gfx906走通用索引但剔除 bitsandbytesbuild.sh会把UNSLOTH_REF/UNSLOTH_ZOO_REF解析并冻结为提交 SHA避免main分支移动后 Docker 层缓存命中旧代码docker/build.sh。手工docker build也可以但要显式传冻结的 SHA见 Dockerfile.rocm 顶部的构建说明。10.2 本地端到端验证仓库提供了一键验证脚本 docker/test_locally-rocm.sh分三个模块宿主预检docker 守护进程、/dev/kfd、video 组→ 构建镜像构建机无需 GPU→ 冒烟测试与真实负载gpt-oss-20B 微调 notebookmax_steps10bash docker/test_locally-rocm.sh # 全部模块真实负载约 10 分钟需约 30GB 模型缓存空间 bash docker/test_locally-rocm.sh --skip-notebook # 只跑 1–3a约 1–2 分钟 ROCM_GFXgfx1151 TAGunsloth-rocm-strix:test bash docker/test_locally-rocm.sh10.3 构建期自检镜像构建阶段即内嵌了无 GPU 自检Dockerfile.rocm与运行时 smoke test 呼应torch.version.hip非空否则说明拿到的是 CUDA 构建TORCH_INDEX_URL指向错误七个必需包齐全nvidia-*CUDA wheel 一个都不允许存在恰好一个 triton 发行版且与 torch 的 pin 一致、带amd后端非 gfx906 构建必须能成功import bitsandbytes——把 ABI 不匹配的 wheel 挡在构建期而不是第一轮训练时。十一、许可说明镜像标签为Apache-2.0 AND AGPL-3.0-only。仓库根目录的 LICENSEApache-2.0覆盖仓库本体与训练栈AGPL-3.0 部分对应镜像随附的唯一 AGPL 文件/workspace/smoke_test_rocm.py其头部即SPDX-License-Identifier: AGPL-3.0-only版权文本见 studio/LICENSE.AGPL-3.0。Unsloth Studio 本体只在studio标签中出现。赞分享人工智能大模型微调LoRA模型优化模型量化强化学习【免费下载链接】unslothLocal UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4, MiniMax-H3, Gemma 4, FLUX and more.项目地址https://gitcode.com/GitHub_Trending/un/unsloth点击查看免费下载相关推荐Unsloth 官方 Docker 镜像实战指南零配置微调与运行 LLM 的完整部署手册Unsloth 官方 Docker 镜像实战指南零配置微调与运行 LLM 的完整部署手册 导读 Unsloth 官方 Docker 镜像 unsloth/u人工智能大模型微调LoRA模型优化模型量化强化学习eSearch 竖排文字识别教程3 个设置让古籍 OCR 真正能用eSearch 竖排文字识别教程3 个设置让古籍 OCR 真正能用 上个月朋友递来一部 96 页的清代方志全部竖排要求转成可检索的文本。按我每天 11 页桌面应用OCR屏幕录制视频处理图像处理searx Docker 部署实战指南镜像运行、配置注入与自建镜像searx Docker 部署实战指南镜像运行、配置注入与自建镜像 本篇指南围绕 searx 官方文档《Docker installation》展开系统讲解后端搜索引擎上一篇一键备份QQ空间你的青春记忆数字保险箱下一篇GetQzonehistory一键备份你的QQ空间记忆时光机创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Unsloth ROCm Docker 镜像实战指南：在 AMD GPU 上零配置微调与运行 LLM
人工智能大模型微调LoRA模型优化模型量化强化学习【免费下载链接】unslothLocal UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4, MiniMax-H3, Gemma 4, FLUX and more.项目地址https://gitcode.com/GitHub_Trending/un/unsloth点击查看免费下载本篇指南围绕仓库中的 docker/DOCKERHUB-ROCM.md 展开系统讲解 Unsloth 为 AMD GPU 提供的 ROCm 官方镜像unsloth/unsloth-rocm如何构造正确的 Docker 设备透传参数、在 Linux 与 WSL2 两种宿主环境下运行、按硬件架构选择合适的标签与构建方式以及镜像内完整的训练栈、环境变量与可复现性约束。读完本文你将能在 AMD RDNA2/RDNA3/RDNA4 与 CDNA 显卡上直接跑起 LoRA/QLoRA 微调、文本到图像与文本到视频生成并学会用镜像自带的 smoke test 快速验证 GPU 是否真正可用。一、镜像定位AMD 侧的完整训练栈unsloth/unsloth-rocm是 CUDA 版unsloth/unsloth的 AMD 对应物。镜像内预装了面向 ROCm 构建的完整训练栈PyTorchROCm 7.2 版本、Unsloth、unsloth-zoo、带 ROCm 4-bit 修复的 bitsandbytes、triton-rocm、TRL、PEFT 与 diffusers目标是让 AMD 用户零配置地微调和运行 LLM。镜像的构建源头是 docker/Dockerfile.rocm其基础镜像是rocm/dev-ubuntu-24.04:7.2.4Python 3.12 位于独立的虚拟环境/opt/unsloth-venv中。值得注意的构建细节整个 Python 栈在单层内通过 uv 一次性解析锁定见 Dockerfile.rocm先从 ROCm 索引解析出 torch 版本再以torchX约束重新解析整个依赖集并在构建阶段就断言torch.version.hip非空、无任何nvidia-*CUDA wheel、triton 恰好是 torch 锁定的那个且带有amd后端——这些校验不依赖 GPU 即可在构建机上执行。CUDA 镜像通过 NVIDIA Container Toolkit 的--gpus接入 GPU而 AMD 显卡不经过任何容器工具包直接通过内核驱动的设备节点暴露给容器因此docker run的写法完全不同。二、快速开始Linux 宿主2.1 前置条件已安装 Docker无 Docker 时可用官方脚本安装curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.shLinux 宿主装有可用的 amdgpu 内核驱动Windows 宿主走 WSL2见下一节。2.2 手工构造设备透传参数AMD 设备节点是/dev/kfd内核 Fusion Driver 节点与/dev/dri渲染节点且容器内需要宿主的video、render组 id。推荐直接用仓库的 docker/run.sh 帮你推导bash docker/run.sh --rocm若想手工运行下面这几行正是run.sh构造 flags 的完整逻辑见 docker/run.sh 的amd_device_flagsGPU_FLAGS--device /dev/kfd [ -e /dev/dri ] GPU_FLAGS$GPU_FLAGS --device /dev/dri for g in video render; do gid$(getent group $g | cut -d: -f3) [ -n $gid ] GPU_FLAGS$GPU_FLAGS --group-add $gid done docker run --rm -it \ $GPU_FLAGS \ --ipchost \ -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \ unsloth/unsloth-rocm每一段都有明确理由--group-add必须传数字组 id组名是在容器内部解析的而宿主机的video/render组在镜像里并不存在传名字会加错组导致/dev/kfd不可读最小化宿主可能根本没有render组直接--group-add $(getent group render | cut -d: -f3)会展开成空参数所以先判空再拼接/dev/dri只在存在时才传Docker 不允许启动一个引用了不存在宿主设备的容器因此缺失时宁可不传让 entrypoint 去解释驱动不完整而不是在 daemon 层直接失败。--ipchost提供充足的共享内存默认 64MB 会压垮 DataLoader 多进程。Hugging Face 缓存挂载并非可选容器内HF_HOME/workspace/.cache/huggingface位于容器的可写层不挂载的话每次docker rm后所有模型都要重新下载。2.3 用 run.sh 一键启动run.sh 在 Linux 与 WSL 上都可用默认使用发布镜像unsloth/unsloth-rocm:latestcurl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/docker/run.sh -o run.sh bash run.sh --rocm # Linux UNSLOTH_IMAGEunsloth-rocm:latest bash run.sh --rocm # WSL--rocm只能作为第一个参数其后的全部参数原样传给容器命令等价地可设UNSLOTH_ROCM1。除设备节点外run.sh还会自动挂载宿主 Hugging Face 缓存、Triton 缓存、当前工作目录到/workspace/host并转发HF_TOKEN、WANDB_API_KEY、HSA_OVERRIDE_GFX_VERSION等环境变量完整清单见 docker/run.sh。三、快速开始WindowsWSL2 / DXG 桥Windows 宿主上没有/dev/kfd。WSL2 通过DXG 桥访问显卡因此参数变为/dev/dxg节点 HSA 运行时的 opt-in 变量 宿主的librocdxg动态库GPU_FLAGS--device /dev/dxg -e HSA_ENABLE_DXG_DETECTION1 \ -v /opt/rocm/lib/librocdxg.so.1:/usr/lib/x86_64-linux-gnu/librocdxg.so:ro \ -v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro -e LD_LIBRARY_PATH/usr/lib/wsl/lib docker run --rm -it \ $GPU_FLAGS \ --ipchost \ -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \ unsloth-rocm:latestWSL 路径不需要--group-addWSL 把/dev/dxg暴露给所有用户且没有render组。需要注意的三点镜像无法内置librocdxg它的构建需要 Windows SDK 的 headers任何 Linux 构建机都不具备。该库由宿主提供而宿主侧由 scripts/install_rocm_wsl_strixhalo.sh 负责安装自动检测 gfx 架构、构建 librocdxg 并写入/etc/profile.d持久化HSA_ENABLE_DXG_DETECTION1必须用 WSL 发行版内部的 Docker 引擎Docker Desktop 自带的引擎既不暴露/dev/kfd也不暴露/dev/dxg必须使用按架构构建的镜像通用镜像的 torch 捆绑了librocprofiler-sdk该库通过 KFD sysfs 拓扑枚举 GPU在 DXG 桥上找不到 agent 会直接abort()entrypoint 会在走到那一步之前就拒绝启动见 docker/entrypoint-rocm.sh 的诊断逻辑。3.1 WSL 下自行构建按架构镜像在按架构标签发布之前用 docker/build.sh 本地构建ROCM_GFXyour gfx bash docker/build.sh --rocm产物本地打标为unsloth-rocm:latest。该构建面向 Strix APU 与 RDNA4gfx1150、gfx1151、gfx1152、gfx1200、gfx1201。RDNA3 显卡gfx1100–gfx1103尚无桥接路径——因为 Dockerfile.rocm 没有把它们映射到 AMD 的gfx110X-allwheel 家族gfx1103不在已知列表中。四、启动前的 GPU 验证smoke test在任何训练开始前先用镜像自带的冒烟测试确认 GPU 可见。设置好上文 Linux 或 WSL 的GPU_FLAGS后docker run --rm $GPU_FLAGS \ -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \ unsloth/unsloth-rocm python /workspace/smoke_test_rocm.py该脚本 docker/smoke_test_rocm.py 按 fail-fast 顺序执行五步检查torch 是 ROCm 构建torch.version.hip非空且torch.cuda.is_available()为真随后在 GPU 上跑一次 fp16 矩阵乘断言数值正确依赖导入unsloth、unsloth-zoo、triton断言存在amd后端、bitsandbytes、transformers、trl、peftxformers 无 ROCm wheel缺失是预期unsloth 的FastLanguageModel可达在 Llama-3.2-1B 上跑5 步真实 LoRA 训练每步断言 loss 与梯度均有限NaN 正是旧版 bitsandbytes 4-bit ROCm bug 的表现且 5 步后 loss 必须下降、LoRA 权重必须被更新。缓存挂载的意义在此体现容器是--rm的没有挂载的话每次重试都要重新下载模型。跳过训练步骤更快、不下载模型可加--skip-train。五、镜像标签Tagstag含义latest当前main分支的构建linux/amd64sha-commit同一镜像钉死在构建时的提交nightly每周定时构建gfx1150、gfx1151、gfx1152、gfx1200、gfx1201使用 AMD 按架构 wheel 的构建发布后可用studiolatest之上叠加 Unsloth Studio 的 Web UI8000 端口与带 Unsloth notebooks 的 JupyterLab8888 端口源自 docker/Dockerfile.studio-rocm。上述每个标签都有基于同一基础镜像的-studio孪生任何可复现的场景都应钉 digest因为latest会移动。构建记录本身写入镜像cat /etc/unsloth-rocm-build可查看构建时用的 ROCm 版本、wheel 索引与架构/opt/unsloth-venv/requirements.lock.txt是解析后的完整包清单Dockerfile.rocm。六、支持的硬件与三个特殊情形镜像支持RDNA2 及以上与 CDNA除gfx1033外基于通用 ROCm 7.2 PyTorch 索引构建覆盖大多数显卡。三个情形需要特别处理Strix Halo / Strix Point APUgfx1150/gfx1151/gfx1152与 RDNA4gfx1200/gfx1201能在通用 wheel 上运行entrypoint 启动时会提示但 AMD 的按架构 wheel 携带通用索引缺失的修复——不止是调优例如gfx1151上的_grouped_mm段错误。通用镜像可能正常工作下文实测数据正是在通用镜像上测得但若在这类架构上训练崩溃用ROCM_GFXgfx1151或对应架构重建是修复手段而非提速手段Van Goghgfx1033Steam Deck被直接拒绝它是 RDNA2但在 ROCm 下前向传播看似正常、训练却发散为 NaN。entrypoint 直接退出而不是带病训练HSA_OVERRIDE_GFX_VERSION也无法解决因为它只是隐藏了硅片标识、改不了算术结果。相关测量记录在 studio/ROCM_RDNA2_APU.mdgfx1033 的 142 个 rocBLAS Tensile 文件中 76% 是fallback且三套独立 ROCm 版本包括 AMD 官方原生 gfx1033 构建训练均失败Vega 20gfx906在 ROCm 6.3 之后失去内核用ROCM_GFXgfx906与ROCM_VERSION6.3.4构建对应 Dockerfile.rocm 顶部的注释。该变体不带 bitsandbytes——没有任何预编译 wheel 携带 gfx906 内核Dockerfile.rocm。容器启动时会打印探测到的硬件信息拒绝静默降级到 CPUentrypoint 依次检查/dev/kfd存在且可读、rocm-smi 可见性、torch 为 HIP 构建且torch.cuda.is_available()为真、显卡 gfx 架构与镜像 wheel 的匹配关系见 docker/entrypoint-rocm.sh每步失败都给出可操作的修复命令。设置UNSLOTH_SKIP_GPU_CHECK1可绕过诊断仅适合离线工具链/CI绕过后结果依然不正确。七、实测数据What is measured以下数据来自 Radeon 8060Sgfx1151Strix Halo对发布版latestdigest 实测工作负载结果4-bit QLoRA5 步Llama 3.2 1Bloss 从 2.8146 降至 1.2242文生图sd-turbo4 步512px118 秒峰值显存 4.21 GB文生视频text-to-video-ms-1.7b8 帧256px279 秒峰值显存 4.77 GB扩散模型的输出与 NVIDIA B200 在相同随机种子下像素差达到小数点后三位一致说明这是数值层面的符合而不只是能跑。速度是另一回事共享系统内存的集成 APU 在这两代工作负载上大约比数据中心显卡慢 25–50 倍。独立 RDNA2、RDNA4 与 CDNA 显卡不在该测试覆盖范围内。八、镜像里有什么、没有什么包含PyTorchROCm、Unsloth、unsloth-zoo、transformers、TRL、PEFT、accelerate、bitsandbytes、triton-rocm、diffusers、timm。latest不包含与unsloth/unsloth不同Unsloth Studio 及其 Web UI、JupyterLab、预编译 llama.cpp 与 whisper.cpp、vLLM 和 xformers。latest是纯训练镜像。studio标签额外增加Unsloth Studio、带 Unsloth notebooks优先展示AMD-*系列的 JupyterLab以及用于 GGUF 聊天的 CPU 版 llama.cpp——仍然没有 whisper.cpp、vLLM 或 xformers。训练、notebooks 与 UI 走 GPUGGUF 聊天走 CPU因为 ROCm 版 llama.cpp 是按架构的打包它会将镜像钉死在单一显卡上。Studio 的数据账户、聊天、输出位于/opt/unsloth-studio务必挂载卷持久化同时设置 Linux 快速开始中的GPU_FLAGSdocker run --rm $GPU_FLAGS --ipchost -p 127.0.0.1:8000:8000 -p 127.0.0.1:8888:8888 \ -v unsloth-studio-rocm:/opt/unsloth-studio \ -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \ unsloth/unsloth-rocm:studiostudio镜像的构建细节见 docker/Dockerfile.studio-rocm它把 JupyterLab 4.6 与 notebook 运行时依赖装入基础 venvkernel 即 ROCm torch通过install.sh --local在独立 venv 安装 Studio并断言 Studio venv 的 torch 与基础 venv 同属一个rocmleafJupyter 侧还内置了 pip/uv shimdocker/unsloth_pip_shim.py 的 PATH 前置机制防止 notebook 里的安装单元破坏已烘焙的 ROCm 栈。九、环境变量一览变量作用UNSLOTH_SKIP_GPU_CHECK1跳过启动诊断见上文拒绝静默降级HSA_OVERRIDE_GFX_VERSION将不受支持的显卡伪装成受支持的架构。在带该卡原生内核的镜像上会被忽略——entrypoint 会警告并主动 unset见 docker/entrypoint-rocm.shHF_TOKEN转发用于受门控的模型UNSLOTH_STUDIO_PASSWORDstudio标签初始管理员密码仅首次启动生效一旦存储即被忽略。未设置时 Studio 自动生成并在日志中指明写入的文件JUPYTER_PASSWORD/UNSLOTH_STUDIO_PORT等studio标签的 Jupyter/Studio 配置由 docker/run.sh 转发docker/run.sh模型下载统一落在/workspace/.cache/huggingface容器可写层内不挂载就会在docker rm后全部丢失挂载后还能复用宿主已下载的模型。Studio 数据卷默认名为unsloth-studio-rocm通过UNSLOTH_STUDIO_VOLUME覆盖。十、自行构建与端到端验证10.1 用 build.sh 构建bash docker/build.sh --rocm # 默认ROCm 7.2.4 pytorch.org rocm7.2 wheels ROCM_GFXgfx1151 bash docker/build.sh --rocm # Strix Halo切到 repo.amd.com 按架构索引 torch 2.11 线 ROCM_GFXgfx1201 bash docker/build.sh --rocm # RX 9070 XTRDNA4 ROCM_VERSION6.3.4 bash docker/build.sh --rocm --gfx gfx906 # Vega 20无 bitsandbytes TAGmy-tag UNSLOTH_REFsha UNSLOTH_ZOO_REFsha bash docker/build.sh --rocm构建参数细节docker/build.shROCM_VERSION默认7.2.4这是下限rocm6.4 最高只到 torch 2.9.1低于 unsloth-zoo 的要求且 RDNA4 在 7.x 之前没有内核TORCH_INDEX_URL默认跟随基础版本7.2.4→rocm7.2索引无--gfx时用通用索引覆盖 RDNA2/RDNA3/RDNA4/CDNA--gfx gfx906走通用索引但剔除 bitsandbytesbuild.sh会把UNSLOTH_REF/UNSLOTH_ZOO_REF解析并冻结为提交 SHA避免main分支移动后 Docker 层缓存命中旧代码docker/build.sh。手工docker build也可以但要显式传冻结的 SHA见 Dockerfile.rocm 顶部的构建说明。10.2 本地端到端验证仓库提供了一键验证脚本 docker/test_locally-rocm.sh分三个模块宿主预检docker 守护进程、/dev/kfd、video 组→ 构建镜像构建机无需 GPU→ 冒烟测试与真实负载gpt-oss-20B 微调 notebookmax_steps10bash docker/test_locally-rocm.sh # 全部模块真实负载约 10 分钟需约 30GB 模型缓存空间 bash docker/test_locally-rocm.sh --skip-notebook # 只跑 1–3a约 1–2 分钟 ROCM_GFXgfx1151 TAGunsloth-rocm-strix:test bash docker/test_locally-rocm.sh10.3 构建期自检镜像构建阶段即内嵌了无 GPU 自检Dockerfile.rocm与运行时 smoke test 呼应torch.version.hip非空否则说明拿到的是 CUDA 构建TORCH_INDEX_URL指向错误七个必需包齐全nvidia-*CUDA wheel 一个都不允许存在恰好一个 triton 发行版且与 torch 的 pin 一致、带amd后端非 gfx906 构建必须能成功import bitsandbytes——把 ABI 不匹配的 wheel 挡在构建期而不是第一轮训练时。十一、许可说明镜像标签为Apache-2.0 AND AGPL-3.0-only。仓库根目录的 LICENSEApache-2.0覆盖仓库本体与训练栈AGPL-3.0 部分对应镜像随附的唯一 AGPL 文件/workspace/smoke_test_rocm.py其头部即SPDX-License-Identifier: AGPL-3.0-only版权文本见 studio/LICENSE.AGPL-3.0。Unsloth Studio 本体只在studio标签中出现。赞分享人工智能大模型微调LoRA模型优化模型量化强化学习【免费下载链接】unslothLocal UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4, MiniMax-H3, Gemma 4, FLUX and more.项目地址https://gitcode.com/GitHub_Trending/un/unsloth点击查看免费下载相关推荐Unsloth 官方 Docker 镜像实战指南零配置微调与运行 LLM 的完整部署手册Unsloth 官方 Docker 镜像实战指南零配置微调与运行 LLM 的完整部署手册 导读 Unsloth 官方 Docker 镜像 unsloth/u人工智能大模型微调LoRA模型优化模型量化强化学习eSearch 竖排文字识别教程3 个设置让古籍 OCR 真正能用eSearch 竖排文字识别教程3 个设置让古籍 OCR 真正能用 上个月朋友递来一部 96 页的清代方志全部竖排要求转成可检索的文本。按我每天 11 页桌面应用OCR屏幕录制视频处理图像处理searx Docker 部署实战指南镜像运行、配置注入与自建镜像searx Docker 部署实战指南镜像运行、配置注入与自建镜像 本篇指南围绕 searx 官方文档《Docker installation》展开系统讲解后端搜索引擎上一篇一键备份QQ空间你的青春记忆数字保险箱下一篇GetQzonehistory一键备份你的QQ空间记忆时光机创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
