canifinetune 部署 比想象中简单：核心估算功能不需要 PyTorch、不需要下载模型权重，一条pip install命令即可在 Windows、Linux 或 WSL 上跑起来。本文给出 canifinetune 0.4.1 的完整依赖版本清单、三个平台的分步安装命令，以及一份"已验证 / 未验证"平台兼容清单，帮你在动手微调前先把显存账算清楚，避开 OOM 踩坑。

🧭 canifinetune 是什么：先算显存，再跑微调

一句话概括：你有一张消费级 NVIDIA 显卡和一个想微调的 Hugging Face 模型，canifinetune 会先回答"训练要吃多少显存、序列长度/batch/LoRA rank 该选多少"，再给你一份可直接运行的训练配方，最后还能本地实测并与估算值对比。

整条链路只有一份配置契约贯穿：估算、配方生成、基准测试共用同一套 dtype、attention、量化等参数，避免"估算一套、训练另一套"的错位。

• 核心估算：canifinetune estimate/recommend，纯 Python 计算，不加载权重
• 交互式演示：canifinetune demo，在浏览器中复用同一估算引擎
• 训练执行：canifinetune recipe生成配方后本地真实训练

CLI 入口定义在 src/canifinetune/cli.py，估算核心在 src/canifinetune/estimator/。

📦 依赖版本清单：核心、训练、报表三层分开装

canifinetune 把依赖拆成三层，按需安装（来源：pyproject.toml）：

核心层的依赖很轻：typer、rich、pydantic、pyyaml、huggingface-hub、jinja2等，所以 Windows/Linux/WSL 上几乎无门槛。

训练层则必须用经过资格验证的版本组合，官方提供了最小和推荐两档约束文件：

• 最小组合：constraints/train-min.txt
• 推荐组合：constraints/train-recommended.txt

⚠️ 注意：bitsandbytes仅在非 macOS 平台生效；Torch 的 CPU / CUDA wheel 需要按平台单独先装好，再安装约束文件锁定的其余包，不要无上限升级。

💻 Windows 原生部署：PowerShell 分步命令

Windows 是官方原生验证过的平台（实测 RTX 4080 环境）。在 PowerShell 中依次执行：

# 1. 创建并激活 3.12 虚拟环境（训练资格验证基于 Python 3.12） py -3.12 -m venv .venv .\.venv\Scripts\Activate.ps1 # 2. 强制 UTF-8，避免控制台中文/特殊符号乱码 $env:PYTHONUTF8 = "1" # 3. 安装核心（无需 torch、不下载权重） python -m pip install canifinetune==0.4.1 # 4. 跑第一个估算：1.5B QLoRA，16 GiB 显存预算 canifinetune estimate --model Qwen/Qwen2.5-1.5B-Instruct --method qlora --gpu-vram-gb 16 --seq-len 2048 --offline # 5. 启动本地交互式 demo canifinetune demo

第 4 步会输出8.420 GiB 规划预算、对 16 GiB 判定 YES（启发式置信度 medium）。注意这是规划预算，不代表长训练一定不会 OOM。

🖥️ 本地 demo：浏览器里复用同一套估算引擎

canifinetune demo会在本机127.0.0.1:8765起一个纯本地页面：选择模型、训练配置与显存预算后，查看显存分解（静态权重、梯度、优化器、激活、logits/loss、安全余量各占多少），并一键复制对应的 CLI 命令。它不训练、不联网查询、不上传数据。

🐧 Linux / WSL 部署：bash 分步命令

Linux 与 WSL 的 shell 步骤基本一致：

# 1. 创建并激活 3.12 虚拟环境 python3.12 -m venv .venv source .venv/bin/activate # 2. 强制 UTF-8 export PYTHONUTF8=1 # 3. 安装核心并估算 python -m pip install canifinetune==0.4.1 canifinetune estimate --model Qwen/Qwen2.5-1.5B-Instruct --method qlora --gpu-vram-gb 16 --offline

不想下载 Hub 权重？可以用离线 CPU 冒烟路径：本地随机生成一个 tiny 模型，完成完整的更新/保存/重载流程（CPU 路径需显式--device cpu --base-dtype fp32 --optimizer adamw_torch，QLoRA 和 8-bit 优化器需要 CUDA）。先装好 CPU 版 torch 2.6.0 wheel，再用约束文件安装训练依赖，完整命令见 docs/quickstart.md。

🧩 训练依赖安装：用 constraints 文件锁版本

需要真实训练时，建议先 clone 源码以获得官方约束文件：

git clone https://gitcode.com/gh_mirrors/ca/can-i-finetune-this cd can-i-finetune-this

然后按顺序安装（Windows PowerShell 与 bash 相同）：

# 1. 先单独安装平台对应的 torch 2.6.0 wheel # - Windows 验证组合：CUDA 12.4 wheel # - Linux：CPU 或 CUDA wheel 二选一 # （精确的 wheel 安装索引地址见 docs/quickstart.md，避免装错源） python -m pip install torch==2.6.0 # 2. 用推荐约束文件安装训练依赖 python -m pip install -c constraints/train-recommended.txt "canifinetune[train]==0.4.1" # 3. 生成配方并训练（以 0.5B QLoRA 为例） canifinetune recipe --model Qwen/Qwen2.5-0.5B-Instruct --revision 7ae557604adf67be50417f59c2c2f167def9a775 --method qlora --seq-len 256 --max-steps 2 --grad-accum 1 --output my-recipe python my-recipe/train.py --config my-recipe/config.yaml python my-recipe/eval_smoke.py --output-dir my-recipe/output --max-new-tokens 8

要点：

• 首次训练约下载 988 MB 权重；输出目录必须为空，重复运行请换新目录
• 检查output/run.json：status: success且更新次数符合预期；LoRA/QLoRA 保存adapter
• 完整训练不支持 FP16 权重；CPU 只能用 fp32

✅ 平台兼容清单：哪些已验证、哪些没有

部署前务必对照这张清单，来源 docs/compatibility.md：

尚未资格验证（不要假设可用）：WSL GPU、其他 GPU 硬件、macOS 训练、Flash Attention、Liger 内核。Liger 配方仍属实验性，估算置信度低。

🔍 部署自检：doctor 命令与高频报错

装完环境后，先跑一次体检：

canifinetune doctor

它会探测 Python 版本、CUDA 可用性、torch/transformers/peft 等已装库并列出问题项，实现见 src/canifinetune/doctor.py。高频问题速查：

更多细节见 docs/troubleshooting.md 与 docs/quickstart.md。

📌 写在最后

canifinetune 的部署逻辑可以浓缩为三步：装核心（任意 Python 3.10+）→ 估算显存 → 需要训练时再按 3.12 + 约束文件加装训练栈。核心层轻量、平台宽容，训练层版本严格但已给出最小/推荐两档现成清单。按本文的 Windows / Linux / WSL 步骤操作，并对照兼容清单确认自己的硬件在已验证范围内，就能在加载权重之前先把"能不能微调、怎么配"这两个问题想清楚。

📄 延伸阅读：CHANGELOG.md（版本演进）· docs/compatibility.md（迁移指南）· examples/（可运行的 Qwen / tiny-GPT2 配方示例）