| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 3 | 21 | 15 | 8% |
| Commands | 4 | 6 | 1 | 36% |
| Section tags | 6 | 3 | 0 | 67% |
What each file covers
Sections
3 shared · 21 only in A · 15 only in B- − GitHub Copilot Instructions for LLaMA Factory
- − Project Overview
- − Architecture Versions
- − Code Structure
- − v0 Architecture (Default)
- − v1 Architecture (USE_V1=1)
- − Development Practices
- − Import Organization
- − Quality Checks
- − Building
- − License
- − Common Patterns
- − Configuration Files
- − Model Support
- − Data Processing
- − Training
- − Key Dependencies
- − Environment Setup
- − Important Notes
- − Contribution Guidelines
- − Common Commands
- + CLAUDE.md
- + Commands
- + Code style (auto-fix)
- + Code quality check (no modifications)
- + Run all tests
- + Run a single test file
- + Run tests matching a pattern
- + License header check
- + Build package
- + Architecture
- + Training Flow (v0)
- + Configuration System
- + Key Modules
- + Adding Support for a New Model
- + Distributed Training
- Code Style
- Testing
- Entry Points
Commands
4 shared · 6 only in A · 1 only in B- − make commit
- − pip3 install build && python3 -m build
- − pip install -e ".[dev]"
- − python src/webui.py
- − python src/api.py
- − make style && make quality
- + make build
- make style
- make quality
- make test
- make license
Section tags
6 shared · 3 only in A · 0 only in B- − setup
- − git-pr
- − dependencies
- build
- test
- lint-format
- code-style
- architecture
- agent-behaviour
Line diff
hiyouga/LlamaFactory · .github/copilot-instructions.md
@@ −1 @@
1# GitHub Copilot Instructions for LLaMA Factory
2
3## Project Overview
4
5LLaMA Factory is an efficient fine-tuning framework for 100+ large language models (LLMs). It provides:
6- Support for various models: LLaMA, LLaVA, Mistral, Qwen, DeepSeek, Yi, Gemma, ChatGLM, Phi, etc.
7- Multiple training methods: pre-training, supervised fine-tuning, reward modeling, PPO, DPO, KTO, ORPO
8- Scalable resources: 16-bit full-tuning, freeze-tuning, LoRA and QLoRA variants
9- Advanced algorithms: GaLore, BAdam, APOLLO, Adam-mini, Muon, OFT, DoRA, etc.
10- Web UI (LLaMA Board) and CLI interfaces
11
12### Architecture Versions
13
14LLaMA Factory has two parallel architectures that can be switched via the `USE_V1` environment variable:
15
16**v0 (default)** - File hierarchy:
17- `api`, `webui` → `chat`, `eval`, `train` → `data`, `model` → `hparams` → `extras`
18
19**v1** - File hierarchy:
20- `trainers` → `core` → `accelerator`, `plugins`, `config` → `utils`
21
22Set `USE_V1=1` to enable v1 architecture.
23
24## Code Structure
25
26### v0 Architecture (Default)
27
28- `src/llamafactory/` - Main package directory
29 - `api/` - OpenAI-style API implementation
30 - `chat/` - Chat interface implementation
31 - `cli.py` - Command-line interface
32 - `data/` - Data processing and dataset handling
33 - `eval/` - Model evaluation utilities
34 - `extras/` - Additional utilities and helpers
35 - `hparams/` - Hyperparameter definitions
36 - `model/` - Model loading, patching, and utilities
37 - `train/` - Training pipeline implementation
38 - `webui/` - Gradio-based web interface
39- `src/train.py` - Training entry script (delegates to `llamafactory.train.tuner`)
40- `src/webui.py` - Web UI entry script (delegates to `llamafactory.webui.interface`)
41- `src/api.py` - API server entry script (delegates to `llamafactory.api.app`)
42- `tests/` - Test suite
43- `examples/` - Example configurations for various training scenarios
44- `data/` - Dataset definitions and examples
45
46### v1 Architecture (USE_V1=1)
47
48- `src/llamafactory/v1/` - Version 1 package directory
49 - `trainers/` - Training implementations
50 - `core/` - Core training utilities
51 - `accelerator/` - Acceleration and distributed training
52 - `plugins/` - Pluggable components (model, data, sampler, trainer)
53 - `config/` - Configuration management
54 - `utils/` - Utility functions
55
56## Development Practices
57
58### Code Style
59
60- Follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
61- Use ruff for linting and formatting
62- Line length: 119 characters
63- Indentation: 4 spaces
64- Quote style: double quotes
65- Use Google-style docstrings for documentation
66
67### Import Organization
68
69- Known first-party: `llamafactory`
70- Known third-party: `accelerate`, `datasets`, `gradio`, `numpy`, `peft`, `torch`, `transformers`, `trl`
71- Use 2 blank lines after imports
72
73### Quality Checks
74
75Before committing code, run:
76```bash
77make style # Auto-fix style issues
78make quality # Check code quality
79make test # Run test suite
80```
81
82Or use the combined command:
83```bash
84make commit # Run pre-commit hooks
85```
86
87### Testing
88
89- Use pytest for testing
90- Tests are located in `tests/` and `tests_v1/` directories
91- Run tests with: `make test` (which runs `WANDB_DISABLED=true pytest -vv --import-mode=importlib tests/ tests_v1/`)
92- Disable wandb during testing to avoid external dependencies
93- **Note**: Training configurations require GPU machines, so training is typically not tested end-to-end. Use `make test` to validate file-level functionality.
94
95### Building
96
97Build the package with:
98```bash
99pip3 install build && python3 -m build
100```
101
102### License
103
104- All source files must include the Apache 2.0 license header
105- Check license headers with: `make license`
106
107## Common Patterns
108
109### Configuration Files
110
111- Training configurations are typically YAML or JSON files in `examples/` directory
112- Hyperparameters are defined using dataclasses in `src/llamafactory/hparams/`
113
114### Model Support
115
116- New model support is added through model patches in `src/llamafactory/model/`
117- Visual models use the visual utilities in `src/llamafactory/model/model_utils/visual.py`
118- Quantization support is in `src/llamafactory/model/model_utils/quantization.py`
119
120### Data Processing
121
122- Dataset definitions are in `data/dataset_info.json`
123- Data templates and processors are in `src/llamafactory/data/`
124
125### Training
126
127- Training pipelines are in `src/llamafactory/train/`
128- Support for different training methods: SFT, DPO, PPO, RM, PT, KTO, ORPO
129
130## Key Dependencies
131
132- Python >= 3.9.0
133- PyTorch and transformers for model handling
134- datasets for data processing
135- peft for parameter-efficient fine-tuning
136- accelerate for distributed training
137- gradio for web UI
138- trl for reinforcement learning
139- Optional: vllm/sglang for inference, flash-attention-2, unsloth, liger-kernel
140
141## Entry Points
142
143- **CLI Training**: `llamafactory-cli train --config examples/train_lora/llama3_lora_sft.yaml`
144- **Web UI**: `llamafactory-cli webui` or `python src/webui.py`
145- **API Server**: `llamafactory-cli api` or `python src/api.py`
146- **Chat Interface**: `llamafactory-cli chat --model_name_or_path MODEL_PATH`
147
148## Environment Setup
149
150For development:
151```bash
152pip install -e ".[dev]"
153```
154
155## Important Notes
156
157- The project supports multiple backends: default PyTorch, vLLM, SGLang
158- Megatron-core training is supported via mcore_adapter
159- SwanLab and W&B are supported for experiment tracking
160- Docker support is available with pre-built images
161- Day-0/Day-1 support for latest cutting-edge models
162- Multi-modal support for vision and audio understanding tasks
163
164## Contribution Guidelines
165
1661. Fork the repository
1672. Create a development branch
1683. Set up development environment with `pip install -e ".[dev]"`
1694. Make changes following the style guide
1705. Run quality checks: `make style && make quality`
1716. Run tests: `make test`
1727. Submit a pull request
173
174## Common Commands
175
176- `make style` - Format code
177- `make quality` - Run linters
178- `make test` - Run tests
179- `make commit` - Install and run pre-commit hooks
180- `make license` - Check license headers
181
hiyouga/LlamaFactory · .ai/CLAUDE.md
@@ +1 @@
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Commands
6
7```bash
8# Code style (auto-fix)
9make style
10
11# Code quality check (no modifications)
12make quality
13
14# Run all tests
15make test
16
17# Run a single test file
18WANDB_DISABLED=true pytest -vv --import-mode=importlib tests/path/to/test_file.py
19
20# Run tests matching a pattern
21WANDB_DISABLED=true pytest -vv --import-mode=importlib tests/ -k "test_name"
22
23# License header check
24make license
25
26# Build package
27make build
28```
29
30The project uses `uv` as the preferred package manager. Commands automatically use `uv run` / `uvx` if `uv` is available.
31
32## Architecture
33
34LlamaFactory has two parallel architectures controlled by the `USE_V1` environment variable:
35
36- **v0 (default):** `api, webui > chat, eval, train > data, model > hparams > extras`
37- **v1 (experimental, `USE_V1=1`):** `trainers > core > accelerator, plugins, config > utils`
38
39Most active development happens in v0. The v1 architecture lives in `src/llamafactory/v1/`.
40
41### Entry Points
42
43CLI entry point is `llamafactory-cli` / `lmf` → `src/llamafactory/cli.py:main()`, which dispatches to `launcher.py` based on `USE_V1`.
44
45Available subcommands: `train`, `chat`, `api`, `export`, `webchat`, `webui`, `env`, `version`, `help`.
46
47### Training Flow (v0)
48
49```
50run_exp() [tuner.py]
51 → read_args() → parse YAML/JSON config
52 → get_train_args() → produces typed argument dataclasses
53 → routes to: run_sft / run_dpo / run_ppo / run_rm / run_pt / run_kto
54 → optional: export_model()
55```
56
57Training is invoked with a YAML config: `llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml`
58
59### Configuration System
60
61All training parameters are YAML/JSON config files. Argument parsing in `src/llamafactory/hparams/parser.py` produces four typed dataclasses:
62- `ModelArguments` — model/tokenizer selection, quantization
63- `DataArguments` — datasets, templates, preprocessing
64- `FinetuningArguments` — LoRA rank/target, training method (sft/dpo/ppo/rm/pt/kto)
65- `TrainingArguments` — extends HuggingFace's `TrainingArguments`
66
67### Key Modules
68
69| Module | Purpose |
70|--------|---------|
71| `src/llamafactory/model/loader.py` | Loads model + tokenizer; applies quantization, LoRA, patches |
72| `src/llamafactory/model/patcher.py` | Model-specific compatibility patches |
73| `src/llamafactory/data/template.py` | Prompt templates; `TEMPLATES` dict maps model family → format |
74| `src/llamafactory/data/mm_plugin.py` | Multi-modal (image/video/audio) data handling |
75| `src/llamafactory/data/processor/` | Per-stage data processors (supervised, pairwise, pretrain, etc.) |
76| `src/llamafactory/train/sft/` | SFT trainer; other stages follow same structure |
77| `src/llamafactory/chat/` | Inference engines: `hf_engine`, `vllm_engine`, `sglang_engine`, `kt_engine` |
78| `src/llamafactory/extras/constants.py` | Enums and constants used across the project |
79
80### Adding Support for a New Model
81
821. Add a prompt template to `src/llamafactory/data/template.py` in the `TEMPLATES` dict
832. Add any necessary model patches in `src/llamafactory/model/patcher.py`
843. Add multi-modal support in `src/llamafactory/data/mm_plugin.py` if needed
85
86### Distributed Training
87
88Multi-GPU automatically uses `torchrun`. Additional backends:
89- **Ray:** Optional Ray cluster support
90- **HyperParallel FSDP2:** `src/llamafactory/train/hyper_parallel/`
91- **Megatron-core:** `src/llamafactory/train/mca/`
92
93### Testing
94
95- `tests/` — v0 tests; `tests_v1/` — v1 tests
96- Most training tests require GPU hardware
97- pytest markers: `@pytest.mark.slow`, `@pytest.mark.runs_on(['cuda'])`
98- Always set `WANDB_DISABLED=true` when running tests
99
100### Code Style
101
102- Ruff for linting and formatting (line length 119, Google-style docstrings)
103- Python 3.11+ syntax
104- Double quotes for strings
105- All new files must include Apache 2.0 license header (checked by `make license`)
106
@@ −1 +1 @@
1−# GitHub Copilot Instructions for LLaMA Factory
1+# CLAUDE.md
22
3−## Project Overview
3+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44
5−LLaMA Factory is an efficient fine-tuning framework for 100+ large language models (LLMs). It provides:
6−- Support for various models: LLaMA, LLaVA, Mistral, Qwen, DeepSeek, Yi, Gemma, ChatGLM, Phi, etc.
7−- Multiple training methods: pre-training, supervised fine-tuning, reward modeling, PPO, DPO, KTO, ORPO
8−- Scalable resources: 16-bit full-tuning, freeze-tuning, LoRA and QLoRA variants
9−- Advanced algorithms: GaLore, BAdam, APOLLO, Adam-mini, Muon, OFT, DoRA, etc.
10−- Web UI (LLaMA Board) and CLI interfaces
5+## Commands
116
12−### Architecture Versions
7+```bash
8+# Code style (auto-fix)
9+make style
1310
14−LLaMA Factory has two parallel architectures that can be switched via the `USE_V1` environment variable:
11+# Code quality check (no modifications)
12+make quality
1513
16−**v0 (default)** - File hierarchy:
17−- `api`, `webui` → `chat`, `eval`, `train` → `data`, `model` → `hparams` → `extras`
14+# Run all tests
15+make test
1816
19−**v1** - File hierarchy:
20−- `trainers` → `core` → `accelerator`, `plugins`, `config` → `utils`
17+# Run a single test file
18+WANDB_DISABLED=true pytest -vv --import-mode=importlib tests/path/to/test_file.py
2119
22−Set `USE_V1=1` to enable v1 architecture.
20+# Run tests matching a pattern
21+WANDB_DISABLED=true pytest -vv --import-mode=importlib tests/ -k "test_name"
2322
24−## Code Structure
23+# License header check
24+make license
2525
26−### v0 Architecture (Default)
26+# Build package
27+make build
28+```
2729
28−- `src/llamafactory/` - Main package directory
29− - `api/` - OpenAI-style API implementation
30− - `chat/` - Chat interface implementation
31− - `cli.py` - Command-line interface
32− - `data/` - Data processing and dataset handling
33− - `eval/` - Model evaluation utilities
34− - `extras/` - Additional utilities and helpers
35− - `hparams/` - Hyperparameter definitions
36− - `model/` - Model loading, patching, and utilities
37− - `train/` - Training pipeline implementation
38− - `webui/` - Gradio-based web interface
39−- `src/train.py` - Training entry script (delegates to `llamafactory.train.tuner`)
40−- `src/webui.py` - Web UI entry script (delegates to `llamafactory.webui.interface`)
41−- `src/api.py` - API server entry script (delegates to `llamafactory.api.app`)
42−- `tests/` - Test suite
43−- `examples/` - Example configurations for various training scenarios
44−- `data/` - Dataset definitions and examples
30+The project uses `uv` as the preferred package manager. Commands automatically use `uv run` / `uvx` if `uv` is available.
4531
46−### v1 Architecture (USE_V1=1)
32+## Architecture
4733
48−- `src/llamafactory/v1/` - Version 1 package directory
49− - `trainers/` - Training implementations
50− - `core/` - Core training utilities
51− - `accelerator/` - Acceleration and distributed training
52− - `plugins/` - Pluggable components (model, data, sampler, trainer)
53− - `config/` - Configuration management
54− - `utils/` - Utility functions
34+LlamaFactory has two parallel architectures controlled by the `USE_V1` environment variable:
5535
56−## Development Practices
36+- **v0 (default):** `api, webui > chat, eval, train > data, model > hparams > extras`
37+- **v1 (experimental, `USE_V1=1`):** `trainers > core > accelerator, plugins, config > utils`
5738
58−### Code Style
39+Most active development happens in v0. The v1 architecture lives in `src/llamafactory/v1/`.
5940
60−- Follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
61−- Use ruff for linting and formatting
62−- Line length: 119 characters
63−- Indentation: 4 spaces
64−- Quote style: double quotes
65−- Use Google-style docstrings for documentation
41+### Entry Points
6642
67−### Import Organization
43+CLI entry point is `llamafactory-cli` / `lmf` → `src/llamafactory/cli.py:main()`, which dispatches to `launcher.py` based on `USE_V1`.
6844
69−- Known first-party: `llamafactory`
70−- Known third-party: `accelerate`, `datasets`, `gradio`, `numpy`, `peft`, `torch`, `transformers`, `trl`
71−- Use 2 blank lines after imports
45+Available subcommands: `train`, `chat`, `api`, `export`, `webchat`, `webui`, `env`, `version`, `help`.
7246
73−### Quality Checks
47+### Training Flow (v0)
7448
75−Before committing code, run:
76−```bash
77−make style # Auto-fix style issues
78−make quality # Check code quality
79−make test # Run test suite
8049 ```
81−
82−Or use the combined command:
83−```bash
84−make commit # Run pre-commit hooks
50+run_exp() [tuner.py]
51+ → read_args() → parse YAML/JSON config
52+ → get_train_args() → produces typed argument dataclasses
53+ → routes to: run_sft / run_dpo / run_ppo / run_rm / run_pt / run_kto
54+ → optional: export_model()
8555 ```
8656
87−### Testing
57+Training is invoked with a YAML config: `llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml`
8858
89−- Use pytest for testing
90−- Tests are located in `tests/` and `tests_v1/` directories
91−- Run tests with: `make test` (which runs `WANDB_DISABLED=true pytest -vv --import-mode=importlib tests/ tests_v1/`)
92−- Disable wandb during testing to avoid external dependencies
93−- **Note**: Training configurations require GPU machines, so training is typically not tested end-to-end. Use `make test` to validate file-level functionality.
59+### Configuration System
9460
95−### Building
61+All training parameters are YAML/JSON config files. Argument parsing in `src/llamafactory/hparams/parser.py` produces four typed dataclasses:
62+- `ModelArguments` — model/tokenizer selection, quantization
63+- `DataArguments` — datasets, templates, preprocessing
64+- `FinetuningArguments` — LoRA rank/target, training method (sft/dpo/ppo/rm/pt/kto)
65+- `TrainingArguments` — extends HuggingFace's `TrainingArguments`
9666
97−Build the package with:
98−```bash
99−pip3 install build && python3 -m build
100−```
67+### Key Modules
10168
102−### License
69+| Module | Purpose |
70+|--------|---------|
71+| `src/llamafactory/model/loader.py` | Loads model + tokenizer; applies quantization, LoRA, patches |
72+| `src/llamafactory/model/patcher.py` | Model-specific compatibility patches |
73+| `src/llamafactory/data/template.py` | Prompt templates; `TEMPLATES` dict maps model family → format |
74+| `src/llamafactory/data/mm_plugin.py` | Multi-modal (image/video/audio) data handling |
75+| `src/llamafactory/data/processor/` | Per-stage data processors (supervised, pairwise, pretrain, etc.) |
76+| `src/llamafactory/train/sft/` | SFT trainer; other stages follow same structure |
77+| `src/llamafactory/chat/` | Inference engines: `hf_engine`, `vllm_engine`, `sglang_engine`, `kt_engine` |
78+| `src/llamafactory/extras/constants.py` | Enums and constants used across the project |
10379
104−- All source files must include the Apache 2.0 license header
105−- Check license headers with: `make license`
80+### Adding Support for a New Model
10681
107−## Common Patterns
82+1. Add a prompt template to `src/llamafactory/data/template.py` in the `TEMPLATES` dict
83+2. Add any necessary model patches in `src/llamafactory/model/patcher.py`
84+3. Add multi-modal support in `src/llamafactory/data/mm_plugin.py` if needed
10885
109−### Configuration Files
86+### Distributed Training
11087
111−- Training configurations are typically YAML or JSON files in `examples/` directory
112−- Hyperparameters are defined using dataclasses in `src/llamafactory/hparams/`
88+Multi-GPU automatically uses `torchrun`. Additional backends:
89+- **Ray:** Optional Ray cluster support
90+- **HyperParallel FSDP2:** `src/llamafactory/train/hyper_parallel/`
91+- **Megatron-core:** `src/llamafactory/train/mca/`
11392
114−### Model Support
93+### Testing
11594
116−- New model support is added through model patches in `src/llamafactory/model/`
117−- Visual models use the visual utilities in `src/llamafactory/model/model_utils/visual.py`
118−- Quantization support is in `src/llamafactory/model/model_utils/quantization.py`
95+- `tests/` — v0 tests; `tests_v1/` — v1 tests
96+- Most training tests require GPU hardware
97+- pytest markers: `@pytest.mark.slow`, `@pytest.mark.runs_on(['cuda'])`
98+- Always set `WANDB_DISABLED=true` when running tests
11999
120−### Data Processing
100+### Code Style
121101
122−- Dataset definitions are in `data/dataset_info.json`
123−- Data templates and processors are in `src/llamafactory/data/`
124−
125−### Training
126−
127−- Training pipelines are in `src/llamafactory/train/`
128−- Support for different training methods: SFT, DPO, PPO, RM, PT, KTO, ORPO
129−
130−## Key Dependencies
131−
132−- Python >= 3.9.0
133−- PyTorch and transformers for model handling
134−- datasets for data processing
135−- peft for parameter-efficient fine-tuning
136−- accelerate for distributed training
137−- gradio for web UI
138−- trl for reinforcement learning
139−- Optional: vllm/sglang for inference, flash-attention-2, unsloth, liger-kernel
140−
141−## Entry Points
142−
143−- **CLI Training**: `llamafactory-cli train --config examples/train_lora/llama3_lora_sft.yaml`
144−- **Web UI**: `llamafactory-cli webui` or `python src/webui.py`
145−- **API Server**: `llamafactory-cli api` or `python src/api.py`
146−- **Chat Interface**: `llamafactory-cli chat --model_name_or_path MODEL_PATH`
147−
148−## Environment Setup
149−
150−For development:
151−```bash
152−pip install -e ".[dev]"
153−```
154−
155−## Important Notes
156−
157−- The project supports multiple backends: default PyTorch, vLLM, SGLang
158−- Megatron-core training is supported via mcore_adapter
159−- SwanLab and W&B are supported for experiment tracking
160−- Docker support is available with pre-built images
161−- Day-0/Day-1 support for latest cutting-edge models
162−- Multi-modal support for vision and audio understanding tasks
163−
164−## Contribution Guidelines
165−
166−1. Fork the repository
167−2. Create a development branch
168−3. Set up development environment with `pip install -e ".[dev]"`
169−4. Make changes following the style guide
170−5. Run quality checks: `make style && make quality`
171−6. Run tests: `make test`
172−7. Submit a pull request
173−
174−## Common Commands
175−
176−- `make style` - Format code
177−- `make quality` - Run linters
178−- `make test` - Run tests
179−- `make commit` - Install and run pre-commit hooks
180−- `make license` - Check license headers
102+- Ruff for linting and formatting (line length 119, Google-style docstrings)
103+- Python 3.11+ syntax
104+- Double quotes for strings
105+- All new files must include Apache 2.0 license header (checked by `make license`)
181106
