ml-easy-setup 0.7.0
一键配置机器学习/深度学习环境，解决依赖冲突和配置难题
License: MIT
Requires Python: >=3.10
Keywords: cuda, deep-learning, environment, machine-learning, pytorch, setup, training

# ML Easy Setup

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

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI Version](https://img.shields.io/pypi/v/ml-easy-setup.svg)](https://pypi.org/project/ml-easy-setup/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

## ✨ 核心特性

### 🎯 一键环境配置
- ✅ **自动检测硬件** - NVIDIA CUDA / AMD ROCm / Apple MPS
- ✅ **16+ 预配置模板** - 覆盖 NLP、CV、RL、LLM、RAG 等领域
- ✅ **容器化支持** - Docker + DevContainer 一键生成
- ✅ **现代依赖管理** - pyproject.toml + UV groups
- ✅ **分布式训练** - Accelerate / DeepSpeed / FSDP 配置生成
- ✅ **图形化界面** - Streamlit Web UI，无需命令行 ⭐ NEW

### 🔥 最新功能 (v0.6.0)

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

---

## 📦 快速开始

### 安装

```bash
pip install ml-easy-setup
```

或使用 uv（更快）：
```bash
uv pip install ml-easy-setup
```

### 基础使用

```bash
# 创建 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
```

### 🌐 Web 图形化界面 ⭐ NEW

**不熟悉命令行？** 使用 Web 图形界面，通过浏览器完成所有配置！

```bash
# 安装 Web UI 依赖
pip install ml-easy-setup[webui]

# 启动 Web UI
mlsetup webui

# 访问 http://localhost:8501
```

**Web UI 特性**：
- 🖱️ 点击式操作，无需记忆命令
- 🔍 实时硬件检测和推荐
- 👁️ 模板预览，查看依赖详情
- 📊 可视化配置步骤
- 🎨 现代化界面设计

---

## 📋 环境模板详解

### 🤖 LLM & GenAI 专用模板

#### `llm` - 大语言模型微调 ⭐ NEW
**适合场景**：LLM 微调、QLoRA、指令微调

```bash
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

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

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

---

#### `inference` - LLM 推理服务 ⭐ NEW
**适合场景**：模型部署、API 服务、高性能推理

```bash
mlsetup create my-inference --template inference --docker
```

**包含工具**：
- **vLLM** - PagedAttention 高吞吐推理
- **FastAPI** + **Uvicorn** - API 服务
- **bitsandbytes** - 量化推理
- **Prometheus** - 监控

---

### 🧠 深度学习框架

#### `pytorch` - PyTorch 深度学习
```bash
mlsetup create my-dl-project --template pytorch --cuda auto
```

#### `tensorflow` - TensorFlow 深度学习
```bash
mlsetup create tf-project --template tensorflow --cuda auto
```

---

### 🌍 传统领域

#### `nlp` - 自然语言处理
```bash
mlsetup create nlp-project --template nlp --cuda auto
```

#### `cv` - 计算机视觉
```bash
mlsetup create cv-project --template cv --cuda auto
```

#### `rl` - 强化学习
```bash
mlsetup create rl-project --template rl --cuda auto
```

---

### 🔧 高级模板

#### `model-builder` - 模型构建与超参数优化
```bash
mlsetup create model-project --template model-builder --cuda cpu
```

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

#### `mlops` - MLOps 部署
```bash
mlsetup create api-service --template mlops --docker
```

**包含**：BentoML + FastAPI + MLflow + DVC

#### `gradient-boosting` - Kaggle 竞赛
```bash
mlsetup create kaggle-project --template gradient-boosting --cuda cpu
```

---

### 📊 数据科学

#### `data-science` - 数据分析
```bash
mlsetup create data-project --template data-science --cuda cpu
```

#### `timeseries` - 时间序列
```bash
mlsetup create forecast-project --template timeseries --cuda cpu
```

#### `graph` - 图神经网络
```bash
mlsetup create graph-project --template graph --cuda auto
```

---

## 🐳 容器化支持

### Docker 生成

```bash
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 支持

```bash
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 支持

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

**生成的 `pyproject.toml` 包含**：
- 现代化 build-system
- 依赖列表（按字母排序）
- 可选依赖组 (cuda, flash-attn)
- UV dependency groups
- 工具配置

**使用方式**：
```bash
# 安装核心依赖
uv sync

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

# 安装 CUDA 组
uv sync --group cuda

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

# 生成锁文件
uv lock
```

---

## 🔄 ROCm 支持 (AMD GPU)

### 自动检测

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

### 手动指定 ROCm

```bash
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)

---

## 🚀 分布式训练配置

### 一键生成分布式配置

```bash
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 |

### 启动训练

```bash
# 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
```

---

## 🔍 硬件检测

### 系统检测

```bash
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

```bash
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
```

---

## 🏥 环境健康检查

```bash
mlsetup health
```

自动修复：
```bash
mlsetup health --auto-fix
```

---

## 🎨 CLI 选项

### create 命令

```bash
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                  显示帮助信息
```

### 其他命令

```bash
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 微调

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

### 场景 2: 多卡分布式训练

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

### 场景 3: AMD GPU 训练

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

### 场景 4: 容器化部署

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

### 场景 5: 完整生产环境

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

---

## 🔮 版本路线图

### v0.6.0 (当前版本) ✅
- [x] Docker/DevContainer 支持
- [x] pyproject.toml 生成
- [x] ROCm 支持 (AMD GPU)
- [x] 分布式训练配置生成
- [x] LLM/GenAI 专用模板
- [x] Flash Attention 兼容性检测

### v0.7.0 (计划中)
- [ ] uv lock 自动生成
- [ ] Intel oneAPI 支持
- [ ] 多节点分布式配置
- [ ] TPU 支持

### v0.8.0 (规划中)
- [ ] 云端环境配置 (AWS/GCP/Azure)
- [ ] 自定义模板加载
- [ ] 图形化配置界面

---

## 📦 开发

### 从源码安装

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

### 运行测试

```bash
pytest tests/
```

### 代码质量

```bash
black src/
ruff check src/
mypy src/
```

---

## 🤝 贡献

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

---

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

---

## 🙏 致谢

本项目基于以下优秀的开源工具：
- [uv](https://github.com/astral-sh/uv) - 极速 Python 包管理器
- [click](https://click.palletsprojects.com/) - CLI 框架
- [rich](https://rich.readthedocs.io/) - 终端美化
- [PyTorch](https://pytorch.org/) - 深度学习框架
- [Hugging Face](https://huggingface.co/) - Transformers 生态

---

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

Made with ❤️ for the ML community