ml-easy-setup 0.6.0

一键配置机器学习/深度学习环境，解决依赖冲突和配置难题

ML Easy Setup

🚀 一键配置现代化机器学习/深度学习环境 - 支持容器化、分布式训练、LLM 微调

✨ 核心特性

🎯 一键环境配置

• ✅ 自动检测硬件 - NVIDIA CUDA / AMD ROCm / Apple MPS
• ✅ 16+ 预配置模板 - 覆盖 NLP、CV、RL、LLM、RAG 等领域
• ✅ 容器化支持 - Docker + DevContainer 一键生成
• ✅ 现代依赖管理 - pyproject.toml + UV groups
• ✅ 分布式训练 - Accelerate / DeepSpeed / FSDP 配置生成

🔥 最新功能 (v0.6.0)

功能	说明
🐳 Docker 支持	多阶段构建 Dockerfile，支持 CUDA/ROCm
📦 DevContainer	VS Code 远程开发环境配置
🤖 LLM 模板	大模型微调、RAG、推理服务专用模板
⚡ pyproject.toml	现代Python打包标准，UV dependency groups
🔄 ROCm 支持	AMD GPU 完整支持
🚀 分布式配置	自动生成多卡训练配置

---

📦 快速开始

安装

pip install ml-easy-setup

或使用 uv（更快）：

uv pip install ml-easy-setup

基础使用

# 创建 PyTorch 项目（自动检测 CUDA）
mlsetup create my-project --template pytorch --cuda auto

# 创建 LLM 微调项目
mlsetup create my-llm --template llm --cuda 12.1

# 创建带容器的项目
mlsetup create my-project --template pytorch --docker --devcontainer

# 完整配置：LLM + Docker + 分布式
mlsetup create production-llm --template llm --cuda 12.1 --docker --distributed --pyproject

---

📋 环境模板详解

🤖 LLM & GenAI 专用模板

llm - 大语言模型微调 ⭐ NEW

适合场景：LLM 微调、QLoRA、指令微调

mlsetup create my-llm --template llm --cuda 12.1 --distributed

包含工具：

• Transformers - HuggingFace 生态
• PEFT - 参数高效微调 (LoRA/QLoRA)
• bitsandbytes - 4/8-bit 量化
• DeepSpeed - 分布式训练
• Flash Attention - 加速（需兼容 GPU）
• TRL - RLHF 训练
• W&B - 实验跟踪

硬件要求：推荐 GPU ≥ 24GB VRAM

---

rag - 检索增强生成 ⭐ NEW

适合场景：知识库问答、文档分析、企业级 RAG

mlsetup create my-rag --template rag --cuda auto

包含工具：

• LangChain + LlamaIndex - 双 RAG 框架
• ChromaDB / FAISS / Qdrant - 向量数据库
• sentence-transformers - 文本嵌入
• 文档处理 - PDF、DOCX、HTML 解析

---

inference - LLM 推理服务 ⭐ NEW

适合场景：模型部署、API 服务、高性能推理

mlsetup create my-inference --template inference --docker

包含工具：

• vLLM - PagedAttention 高吞吐推理
• FastAPI + Uvicorn - API 服务
• bitsandbytes - 量化推理
• Prometheus - 监控

---

🧠 深度学习框架

pytorch - PyTorch 深度学习

mlsetup create my-dl-project --template pytorch --cuda auto

tensorflow - TensorFlow 深度学习

mlsetup create tf-project --template tensorflow --cuda auto

---

🌍 传统领域

nlp - 自然语言处理

mlsetup create nlp-project --template nlp --cuda auto

cv - 计算机视觉

mlsetup create cv-project --template cv --cuda auto

rl - 强化学习

mlsetup create rl-project --template rl --cuda auto

---

🔧 高级模板

model-builder - 模型构建与超参数优化

mlsetup create model-project --template model-builder --cuda cpu

包含：XGBoost/LightGBM/CatBoost + Optuna + MLflow + W&B

mlops - MLOps 部署

mlsetup create api-service --template mlops --docker

包含：BentoML + FastAPI + MLflow + DVC

gradient-boosting - Kaggle 竞赛

mlsetup create kaggle-project --template gradient-boosting --cuda cpu

---

📊 数据科学

data-science - 数据分析

mlsetup create data-project --template data-science --cuda cpu

timeseries - 时间序列

mlsetup create forecast-project --template timeseries --cuda cpu

graph - 图神经网络

mlsetup create graph-project --template graph --cuda auto

---

🐳 容器化支持

Docker 生成

mlsetup create my-project --template pytorch --cuda 12.1 --docker

生成的文件：

• Dockerfile - 多阶段构建，优化镜像大小
• .dockerignore - 减小构建上下文
• README_CONTAINER.md - 容器化部署指南

特性：

• CUDA 基础镜像自动选择
• PyTorch wheel URL 自动配置
• 标准端口暴露 (8888/Jupyter, 6006/TensorBoard, 8000/API)

DevContainer 支持

mlsetup create my-project --template pytorch --devcontainer

生成的文件：

• .devcontainer/devcontainer.json - VS Code 配置
• .devcontainer/docker-compose.yml - 多容器编排
• 预装 VS Code 扩展 (Python, Pylance, Jupyter, Black, Ruff)

---

📦 现代依赖管理

pyproject.toml 支持

mlsetup create my-project --template llm --pyproject

生成的 pyproject.toml 包含：

• 现代化 build-system
• 依赖列表（按字母排序）
• 可选依赖组 (cuda, flash-attn)
• UV dependency groups
• 工具配置

使用方式：

# 安装核心依赖
uv sync

# 安装开发依赖
uv sync --group dev

# 安装 CUDA 组
uv sync --group cuda

# 安装 Flash Attention
uv sync --group flash-attn

# 生成锁文件
uv lock

---

🔄 ROCm 支持 (AMD GPU)

自动检测

# 自动检测 AMD GPU 并使用 ROCm
mlsetup create my-project --template pytorch --cuda auto

手动指定 ROCm

mlsetup create my-project --template llm --rocm --rocm-version 5.7

支持的 ROCm 版本：5.4, 5.5, 5.6, 5.7

支持的 GPU：

• RX 6000/7000 系列 (gfx1030+)
• MI 系列 (计算卡)
• Vega 系列 (gfx900)

---

🚀 分布式训练配置

一键生成分布式配置

mlsetup create my-project --template llm --distributed

自动检测：

• GPU 数量 (NVIDIA/AMD)
• GPU 类型
• 计算能力

生成的配置文件：

文件	功能
accelerate_config.yaml	Accelerate 分布式配置
ds_config.json	DeepSpeed ZeRO (根据卡数自动优化)
fsdp_config.json	FSDP 配置
scripts/train_distributed.sh	训练启动脚本
launch_config.json	启动配置
src/train_distributed.py	训练示例

DeepSpeed ZeRO 自动优化

GPU 数量	ZeRO Stage	梯度累积
1	1 + CPU Offload	8
2-3	2	4
4-7	2	2
8+	3	1

启动训练

# Accelerate
accelerate launch --config_file accelerate_config.yaml src/train.py

# DeepSpeed
deepspeed --num_gpus=8 src/train.py --deepspeed ds_config.json

# torchrun
torchrun --nproc_per_node=8 src/train.py

# 使用生成的脚本
bash scripts/train_distributed.sh

---

🔍 硬件检测

系统检测

mlsetup detect

输出示例：

╭───────────── ML Easy Setup ─────────────╮
│ 系统环境检测                             │
├──────────────────────────────────────────┤
│ 项目          检测结果                    │
├──────────────────────────────────────────┤
│ 操作系统      Linux                      │
│ Python 版本   3.11.5                     │
│ 架构          x86_64                     │
│ CUDA          12.1                       │
│ GPU           NVIDIA A100 (4 cards)      │
│ UV            0.1.20                     │
╰──────────────────────────────────────────╯

LLM 硬件兼容性检查 ⭐ NEW

mlsetup llm-check

输出示例：

🔍 LLM 硬件兼容性检查

GPU 信息:
  GPU: NVIDIA GeForce RTX 3090
  Compute Capability: 8.6

CUDA 版本:
  12.1

Flash Attention:
  ✓ 兼容 - GPU NVIDIA GeForce RTX 3090 (Compute Capability 8.6) 支持 Flash Attention

  安装命令:
    pip install flash-attn --no-build-isolation

推荐训练设置:
  use_flash_attention: True
  use_bitsandbytes: True
  use_deepspeed: True
  gradient_checkpointing: True

---

🏥 环境健康检查

mlsetup health

自动修复：

mlsetup health --auto-fix

---

🎨 CLI 选项

create 命令

mlsetup create [OPTIONS] NAME

选项:
  -t, --template TEXT      预配置环境模板
  -c, --cuda TEXT          CUDA 版本 (auto/cpu/11.8/12.1/12.4/none)
  -p, --python TEXT        Python 版本 (默认: 3.10)
  -d, --path PATH          项目路径
  --docker                生成 Dockerfile 和容器配置
  --devcontainer          生成 VS Code DevContainer 配置
  --pyproject             使用 pyproject.toml (现代 Python 打包)
  --rocm                  使用 ROCm (AMD GPU)
  --rocm-version TEXT     ROCm 版本 (5.4/5.5/5.6/5.7)
  --distributed           生成分布式训练配置
  --help                  显示帮助信息

其他命令

mlsetup list-templates     # 列出所有模板
mlsetup detect             # 系统硬件检测
mlsetup llm-check          # LLM 硬件兼容性检查
mlsetup add <packages>     # 添加额外的包
mlsetup health             # 环境健康检查

---

📊 技术架构

ml-easy-setup/
├── CLI层 (cli.py)          - Click 命令接口
│   ├── create             - 创建项目
│   ├── list-templates      - 列出模板
│   ├── detect             - 硬件检测
│   ├── llm-check          - LLM 兼容性检查
│   ├── add                - 添加包
│   └── health             - 健康检查
│
├── 核心层 (core/)
│   ├── template.py        - 16+ 模板定义
│   ├── env_manager.py     - 环境创建 + pyproject.toml
│   ├── detector.py        - 硬件检测 (NVIDIA/AMD/MPS)
│   ├── container.py       - Docker/DevContainer 生成 ⭐
│   ├── distributed.py     - 分布式配置生成 ⭐
│   ├── health.py          - 健康检查
│   └── resolver.py        - 依赖冲突检测
│
└── SDK层 (sdk/)           - 简化 API (可选)
    ├── models/            - SimpleModel 一行建模
    ├── trainers/          - AutoTrainer 自动训练
    ├── magic.py           - 极简 API
    └── utils/             - 设备管理/类型工厂

---

🆚 技术对比

特性	ML Easy Setup	conda	poetry	venv
专为 ML 设计	✅	✅	❌	❌
自动 CUDA 检测	✅	❌	❌	❌
ROCm 支持	✅	❌	❌	❌
Docker 生成	✅	❌	❌	❌
DevContainer	✅	❌	❌	❌
pyproject.toml	✅	❌	✅	❌
分布式配置	✅	❌	❌	❌
LLM 模板	✅ (3种)	❌	❌	❌
安装速度	⚡⚡⚡	⚡	⚡⚡	⚡
学习曲线	低	中	高	低

---

💡 典型使用场景

场景 1: 单卡 LLM 微调

mlsetup create my-llm \
  --template llm \
  --cuda 12.1 \
  --pyproject

场景 2: 多卡分布式训练

mlsetup create my-llm \
  --template llm \
  --cuda 12.1 \
  --distributed

场景 3: AMD GPU 训练

mlsetup create my-amd-llm \
  --template llm \
  --rocm \
  --rocm-version 5.7 \
  --distributed

场景 4: 容器化部署

mlsetup create production-api \
  --template inference \
  --docker \
  --devcontainer

场景 5: 完整生产环境

mlsetup create production-llm \
  --template llm \
  --cuda 12.1 \
  --pyproject \
  --docker \
  --devcontainer \
  --distributed

---

🔮 版本路线图

v0.6.0 (当前版本) ✅

• Docker/DevContainer 支持
• pyproject.toml 生成
• ROCm 支持 (AMD GPU)
• 分布式训练配置生成
• LLM/GenAI 专用模板
• Flash Attention 兼容性检测

v0.7.0 (计划中)

• uv lock 自动生成
• Intel oneAPI 支持
• 多节点分布式配置
• TPU 支持

v0.8.0 (规划中)

• 云端环境配置 (AWS/GCP/Azure)
• 自定义模板加载
• 图形化配置界面

---

📦 开发

从源码安装

git clone https://github.com/yourusername/ml-easy-setup.git
cd ml-easy-setup
pip install -e ".[dev,sdk]"

运行测试

pytest tests/

代码质量

black src/
ruff check src/
mypy src/

---

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

---

📄 许可证

MIT License - 详见 LICENSE 文件

---

🙏 致谢

本项目基于以下优秀的开源工具：

• uv - 极速 Python 包管理器
• click - CLI 框架
• rich - 终端美化
• PyTorch - 深度学习框架
• Hugging Face - Transformers 生态

---

⭐ 如果这个项目对您有帮助，请给我们一个星标！

Made with ❤️ for the ML community