# 🎯 Hydra ML Config Template

<div align="center">

**优雅的Python配置管理解决方案 | 告别杂乱的硬编码**

[快速开始](#快速开始) • [使用场景](#使用场景) • [最佳实践](#最佳实践) • [常见问题](#常见问题)

</div>

---

## 📖 项目简介

这是一个基于 [Hydra](https://hydra.cc/) 的Python配置管理模板仓库,专为机器学习和数据科学项目设计。通过分层配置、动态组合、命令行覆盖等特性,让你的项目配置管理变得简单优雅。

### ✨ 核心特性

- 🔧 **分层配置** - 模块化管理,配置文件清晰有序
- 🎨 **动态组合** - 灵活切换不同配置组合
- 🚀 **命令行覆盖** - 无需修改代码即可调整参数
- 📊 **自动实验管理** - 每次运行自动创建独立输出目录
- 🔄 **多任务运行** - 一次性运行多组超参数实验
- 💾 **配置版本化** - 完整保存每次实验的配置

---

## 🚀 快速开始

### 环境安装

本项目使用 [uv](https://github.com/astral-sh/uv) 进行依赖管理,这是一个极速的Python包管理工具。

#### 1. 安装 uv

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 pip
pip install uv
```

#### 2. 克隆仓库

```bash
git clone <your-gitea-url>/hydra-ml-config-template.git
cd hydra-ml-config-template
```

#### 3. 创建虚拟环境并安装依赖

```bash
# 使用 uv 创建虚拟环境
uv venv

# 激活虚拟环境
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 安装依赖
uv pip install -e .
```

#### 4. 运行示例

```bash
# 基础示例
python examples/01_basic/train.py

# 使用不同配置
python examples/02_ml_training/train.py model=transformer optimizer=sgd

# 多任务运行
python examples/02_ml_training/train.py -m learning_rate=0.001,0.01,0.1
```

---

## 🎯 使用场景

### 场景1: 基础配置管理

```bash
cd examples/01_basic
python train.py learning_rate=0.01
```

### 场景2: 机器学习训练配置

```bash
cd examples/02_ml_training
python train.py model=transformer optimizer=sgd
python train.py learning_rate=0.01 batch_size=64
```

### 场景3: 多环境配置

```bash
cd examples/04_multi_env
python app.py env=dev    # 开发环境
python app.py env=prod   # 生产环境
```

---

## 📚 学习资源

- [Hydra官方文档](https://hydra.cc/)
- [项目结构说明](PROJECT_STRUCTURE.md)
- [最佳实践](docs/best_practices.md)

---

## 🤝 贡献

欢迎提交Issue和Pull Request!

---

## 📄 许可证

MIT License

---

<div align="center">

**如果这个模板对你有帮助,请给个 ⭐️ Star!**

Made with ❤️ for ML Engineers

</div>