mirror of
https://github.com/hiyouga/LLaMA-Factory.git
synced 2025-12-27 09:10:35 +08:00
[assets] Add GitHub Copilot instructions for repository (#9675)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: hiyouga <16256802+hiyouga@users.noreply.github.com>
This commit is contained in:
Copilot
GitHub
180
.github/copilot-instructions.md
vendored
Normal file
180
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,180 @@
|
|||||||
|
# GitHub Copilot Instructions for LLaMA Factory
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
LLaMA Factory is an efficient fine-tuning framework for 100+ large language models (LLMs). It provides:
|
||||||
|
- Support for various models: LLaMA, LLaVA, Mistral, Qwen, DeepSeek, Yi, Gemma, ChatGLM, Phi, etc.
|
||||||
|
- Multiple training methods: pre-training, supervised fine-tuning, reward modeling, PPO, DPO, KTO, ORPO
|
||||||
|
- Scalable resources: 16-bit full-tuning, freeze-tuning, LoRA and QLoRA variants
|
||||||
|
- Advanced algorithms: GaLore, BAdam, APOLLO, Adam-mini, Muon, OFT, DoRA, etc.
|
||||||
|
- Web UI (LLaMA Board) and CLI interfaces
|
||||||
|
|
||||||
|
### Architecture Versions
|
||||||
|
|
||||||
|
LLaMA Factory has two parallel architectures that can be switched via the `USE_V1` environment variable:
|
||||||
|
|
||||||
|
**v0 (default)** - File hierarchy:
|
||||||
|
- `api`, `webui` → `chat`, `eval`, `train` → `data`, `model` → `hparams` → `extras`
|
||||||
|
|
||||||
|
**v1** - File hierarchy:
|
||||||
|
- `trainers` → `core` → `accelerator`, `plugins`, `config` → `utils`
|
||||||
|
|
||||||
|
Set `USE_V1=1` to enable v1 architecture.
|
||||||
|
|
||||||
|
## Code Structure
|
||||||
|
|
||||||
|
### v0 Architecture (Default)
|
||||||
|
|
||||||
|
- `src/llamafactory/` - Main package directory
|
||||||
|
- `api/` - OpenAI-style API implementation
|
||||||
|
- `chat/` - Chat interface implementation
|
||||||
|
- `cli.py` - Command-line interface
|
||||||
|
- `data/` - Data processing and dataset handling
|
||||||
|
- `eval/` - Model evaluation utilities
|
||||||
|
- `extras/` - Additional utilities and helpers
|
||||||
|
- `hparams/` - Hyperparameter definitions
|
||||||
|
- `model/` - Model loading, patching, and utilities
|
||||||
|
- `train/` - Training pipeline implementation
|
||||||
|
- `webui/` - Gradio-based web interface
|
||||||
|
- `src/train.py` - Training entry script (delegates to `llamafactory.train.tuner`)
|
||||||
|
- `src/webui.py` - Web UI entry script (delegates to `llamafactory.webui.interface`)
|
||||||
|
- `src/api.py` - API server entry script (delegates to `llamafactory.api.app`)
|
||||||
|
- `tests/` - Test suite
|
||||||
|
- `examples/` - Example configurations for various training scenarios
|
||||||
|
- `data/` - Dataset definitions and examples
|
||||||
|
|
||||||
|
### v1 Architecture (USE_V1=1)
|
||||||
|
|
||||||
|
- `src/llamafactory/v1/` - Version 1 package directory
|
||||||
|
- `trainers/` - Training implementations
|
||||||
|
- `core/` - Core training utilities
|
||||||
|
- `accelerator/` - Acceleration and distributed training
|
||||||
|
- `plugins/` - Pluggable components (model, data, sampler, trainer)
|
||||||
|
- `config/` - Configuration management
|
||||||
|
- `utils/` - Utility functions
|
||||||
|
|
||||||
|
## Development Practices
|
||||||
|
|
||||||
|
### Code Style
|
||||||
|
|
||||||
|
- Follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
|
||||||
|
- Use ruff for linting and formatting
|
||||||
|
- Line length: 119 characters
|
||||||
|
- Indentation: 4 spaces
|
||||||
|
- Quote style: double quotes
|
||||||
|
- Use Google-style docstrings for documentation
|
||||||
|
|
||||||
|
### Import Organization
|
||||||
|
|
||||||
|
- Known first-party: `llamafactory`
|
||||||
|
- Known third-party: `accelerate`, `datasets`, `gradio`, `numpy`, `peft`, `torch`, `transformers`, `trl`
|
||||||
|
- Use 2 blank lines after imports
|
||||||
|
|
||||||
|
### Quality Checks
|
||||||
|
|
||||||
|
Before committing code, run:
|
||||||
|
```bash
|
||||||
|
make style # Auto-fix style issues
|
||||||
|
make quality # Check code quality
|
||||||
|
make test # Run test suite
|
||||||
|
```
|
||||||
|
|
||||||
|
Or use the combined command:
|
||||||
|
```bash
|
||||||
|
make commit # Run pre-commit hooks
|
||||||
|
```
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
|
||||||
|
- Use pytest for testing
|
||||||
|
- Tests are located in `tests/` and `tests_v1/` directories
|
||||||
|
- Run tests with: `make test` (which runs `WANDB_DISABLED=true pytest -vv --import-mode=importlib tests/ tests_v1/`)
|
||||||
|
- Disable wandb during testing to avoid external dependencies
|
||||||
|
- **Note**: Training configurations require GPU machines, so training is typically not tested end-to-end. Use `make test` to validate file-level functionality.
|
||||||
|
|
||||||
|
### Building
|
||||||
|
|
||||||
|
Build the package with:
|
||||||
|
```bash
|
||||||
|
pip3 install build && python3 -m build
|
||||||
|
```
|
||||||
|
|
||||||
|
### License
|
||||||
|
|
||||||
|
- All source files must include the Apache 2.0 license header
|
||||||
|
- Check license headers with: `make license`
|
||||||
|
|
||||||
|
## Common Patterns
|
||||||
|
|
||||||
|
### Configuration Files
|
||||||
|
|
||||||
|
- Training configurations are typically YAML or JSON files in `examples/` directory
|
||||||
|
- Hyperparameters are defined using dataclasses in `src/llamafactory/hparams/`
|
||||||
|
|
||||||
|
### Model Support
|
||||||
|
|
||||||
|
- New model support is added through model patches in `src/llamafactory/model/`
|
||||||
|
- Visual models use the visual utilities in `src/llamafactory/model/model_utils/visual.py`
|
||||||
|
- Quantization support is in `src/llamafactory/model/model_utils/quantization.py`
|
||||||
|
|
||||||
|
### Data Processing
|
||||||
|
|
||||||
|
- Dataset definitions are in `data/dataset_info.json`
|
||||||
|
- Data templates and processors are in `src/llamafactory/data/`
|
||||||
|
|
||||||
|
### Training
|
||||||
|
|
||||||
|
- Training pipelines are in `src/llamafactory/train/`
|
||||||
|
- Support for different training methods: SFT, DPO, PPO, RM, PT, KTO, ORPO
|
||||||
|
|
||||||
|
## Key Dependencies
|
||||||
|
|
||||||
|
- Python >= 3.9.0
|
||||||
|
- PyTorch and transformers for model handling
|
||||||
|
- datasets for data processing
|
||||||
|
- peft for parameter-efficient fine-tuning
|
||||||
|
- accelerate for distributed training
|
||||||
|
- gradio for web UI
|
||||||
|
- trl for reinforcement learning
|
||||||
|
- Optional: vllm/sglang for inference, flash-attention-2, unsloth, liger-kernel
|
||||||
|
|
||||||
|
## Entry Points
|
||||||
|
|
||||||
|
- **CLI Training**: `llamafactory-cli train --config examples/train_lora/llama3_lora_sft.yaml`
|
||||||
|
- **Web UI**: `llamafactory-cli webui` or `python src/webui.py`
|
||||||
|
- **API Server**: `llamafactory-cli api` or `python src/api.py`
|
||||||
|
- **Chat Interface**: `llamafactory-cli chat --model_name_or_path MODEL_PATH`
|
||||||
|
|
||||||
|
## Environment Setup
|
||||||
|
|
||||||
|
For development:
|
||||||
|
```bash
|
||||||
|
pip install -e ".[dev]"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
|
||||||
|
- The project supports multiple backends: default PyTorch, vLLM, SGLang
|
||||||
|
- Megatron-core training is supported via mcore_adapter
|
||||||
|
- SwanLab and W&B are supported for experiment tracking
|
||||||
|
- Docker support is available with pre-built images
|
||||||
|
- Day-0/Day-1 support for latest cutting-edge models
|
||||||
|
- Multi-modal support for vision and audio understanding tasks
|
||||||
|
|
||||||
|
## Contribution Guidelines
|
||||||
|
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create a development branch
|
||||||
|
3. Set up development environment with `pip install -e ".[dev]"`
|
||||||
|
4. Make changes following the style guide
|
||||||
|
5. Run quality checks: `make style && make quality`
|
||||||
|
6. Run tests: `make test`
|
||||||
|
7. Submit a pull request
|
||||||
|
|
||||||
|
## Common Commands
|
||||||
|
|
||||||
|
- `make style` - Format code
|
||||||
|
- `make quality` - Run linters
|
||||||
|
- `make test` - Run tests
|
||||||
|
- `make commit` - Install and run pre-commit hooks
|
||||||
|
- `make license` - Check license headers
|
||||||
Reference in New Issue
Block a user