Windows 安装 Ostris AI Toolkit

freeflydom

2026年8月5日 14:28 本文热度 41

针对 ostris/ai-toolkit，它是一个非常纯粹的命令行/脚本工具。

再次明确：它完全不需要放在 IntelliJ IDEA、PyCharm 或 VS Code 等 IDE 软件里运行。
虽然你可以用开发软件打开它查看代码，但最标准、最不容易出错的运行方式是直接在你的系统终端（Terminal / 命令行）中进行。

Github 官网地址：https://github.com/ostris/ai-toolkit#

官网提供了两种安装方式，一种是简易安装，一种是命令安装。选择简易安装的可以访问 https://github.com/Tavris1/AI-Toolkit-Easy-Install。

用命令安装 Ostris AI Toolkit

0. 官方命令解释

# 1. 从 GitHub 远程仓库克隆 ai-toolkit（FLUX/SDXL 训练工具箱）的全部源代码到本地
git clone https://github.com/ostris/ai-toolkit.git
# 2. 将命令行当前的工作路径切换到刚刚下载好的 ai-toolkit 文件夹内
cd ai-toolkit
# 3. 使用 Python 在当前目录下创建一个名为 venv 的独立虚拟环境，用于隔离该项目的依赖，防止污染全局环境
python -m venv venv
# 4. 激活刚刚创建的虚拟环境（激活后命令行开头会出现 "(venv)" 标志，后续安装都会限制在此环境中）
.\venv\Scripts\activate
# 5. 安装指定版本的 PyTorch 核心全家桶（torch 2.9.1 / torchvision 0.24.1 / torchaudio 2.9.1）
#    --no-cache-dir：下载时不使用本地缓存，防止因残余损坏文件导致安装报错，并节省 C 盘空间
#    --index-url：指定从 PyTorch 官方专为 CUDA 12.8（NVIDIA 显卡加速驱动）编译的专有源下载，以调用显卡进行高速训练
pip install --no-cache-dir torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 --index-url https://download.pytorch.org/whl/cu128
# 6. 读取项目目录下的 requirements.txt 文本文件，并自动一次性下载安装里面记录的所有辅助依赖库（如 transformers, diffusers 等）
pip install -r requirements.txt

1. 下载 ai-toolkit

可以使用 git clone 下载

git clone https://github.com/ostris/ai-toolkit.git

如果网络不好，也可以直接下载对应的 ZIP 压缩包文件，进行解压

2. ai-toolkit 环境要求

官方建议用 python 3.12 的版本。安装建议的 python 版本之后，我的本地有多个python版本。

3. 在 ai-toolkit 目录中创建虚拟环境

官方的命令是 python3 -m venv venv ，但由于我有多个 python，因此需要指定具体的 python.exe 路径，这里选择刚安装的 python 3.12.10。

C:\Soft\Python\Python312\python.exe -m venv venv

4. 激活环境

.\venv\Scripts\activate

(激活后，你的命令行开头会多出一个 (venv) 标记)

5. 安装 PyTorch（使用国内镜像源，不修改版本）

这里有一个大文件 2.9 GB 的，容易下载失败，所以用国内镜像。

pip install --no-cache-dir torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 --index-url https://mirrors.aliyun.com/pypi/simple/ --extra-index-url https://download.pytorch.org/whl/cu128 --default-timeout=1000

加入了阿里云作为辅助源，并设置了 1000 秒超时。pip 会先在国内镜像寻找，如果找不到，再通过延长的超时时间去官方 cu128 源里下载，极大降低了因为网络波动导致中断的概率。使用国内的镜像下载，可以看到速度很快。

6. 安装其余依赖

pip install -r requirements.txt

7. 运行界面

进入到 UI 目录

cd ui

运行

npm run build_and_start

如果你有多个python版本，建议直接指定对应的 python 路径

npm run build_and_start --python="C:\Soft\Python\Python312\python.exe"

这个报错是因为你的电脑上没有安装 Node.js（或者没有配置 Node.js 的环境变量）。npm（Node Package Manager）是 Node.js 的包管理工具，专门用来构建和运行网页端（Frontend）项目的。由于 ai-toolkit 的可视化界面（UI）是用网页前端技术写的，所以运行它必须先安装 Node.js。

请按照以下步骤快速解决这个问题：

下载并安装 Node.js
前往 Node.js 官网下载：
打开浏览器，访问 Node.js 官方网站 (https://nodejs.org)。
- 选择版本下载：
  推荐下载 LTS（长期支持版，通常在左边），这个版本最稳定。
- 开始安装：
  运行下载好的安装包（.msi 文件），可以自定义安装路径，剩下的，一路点击 Next（下一步）即可。
- ⚠️ 关键注意点：
  在安装过程中，确保 “Add to PATH”（添加到环境变量）这一项是勾选状态（默认就是勾选的）。
重启命令行窗口（非常重要）
安装完成后，你必须关闭当前所有的 PowerShell 或 CMD 命令行窗口，然后重新打开一个。因为新的环境变量只有在新建的窗口中才会生效。