> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YAML 配置

> 使用配置文件进行训练

# YAML 配置文件

配置文件使复杂的训练设置可重现且可共享。

## 基本用法

```bash theme={null}
aitraining --config training.yaml
```

## 配置文件结构

YAML 配置具有特定的嵌套结构：

```yaml theme={null}
# training.yaml
task: llm-sft                        # Task with trainer suffix
backend: local                       # Required: local, spaces-*, etc.

# Model settings
base_model: google/gemma-3-270m      # Note: "base_model", not "model"
project_name: my-gemma-model

# Data settings (nested under "data:")
data:
  path: ./data/conversations.jsonl   # Note: nested under data
  train_split: train
  valid_split: null
  chat_template: tokenizer           # For LLM: tokenizer, chatml, zephyr, none
  column_mapping:                    # Column names
    text_column: text

# Logging
log: wandb

# Hub settings (optional)
hub:
  username: ${HF_USERNAME}
  token: ${HF_TOKEN}
  push_to_hub: false

# All other training parameters go under "params:"
params:
  epochs: 3
  batch_size: 4
  lr: 3e-5
  mixed_precision: bf16
  peft: true
  lora_r: 16
  lora_alpha: 32
  lora_dropout: 0.05
```

<Warning>
  **重要结构说明：**

  * 使用 `base_model`，而不是 `model`
  * 数据路径是 `data.path`，而不是 `data_path`
  * 列映射位于 `data.column_mapping` 下
  * 训练参数位于 `params:` 下
  * `backend` 字段是**必需的**
</Warning>

## 任务类型

任务字段包括训练器类型：

```yaml theme={null}
# LLM tasks (trainer in task name)
task: llm-sft                # SFT training
task: llm-dpo                # DPO training
task: llm-orpo               # ORPO training
task: llm-reward             # Reward model training
task: llm-generic            # Default/pretraining

# Other tasks
task: text-classification    # Text classification
task: image-classification   # Image classification
task: token-classification   # NER
task: seq2seq                # Sequence to sequence
task: tabular                # Tabular data
task: vlm:vqa                # Vision-language (VQA)
task: vlm:captioning         # Vision-language (captioning)
task: sentence-transformers:pair_score  # Sentence transformers
```

## LLM 训练配置

### SFT 训练

```yaml theme={null}
task: llm-sft
backend: local
base_model: meta-llama/Llama-3.2-1B
project_name: llama-sft

data:
  path: ./conversations.jsonl
  train_split: train
  valid_split: null
  chat_template: tokenizer
  column_mapping:
    text_column: text

log: wandb

hub:
  push_to_hub: false

params:
  epochs: 3
  batch_size: 2
  lr: 3e-5
  peft: true
  lora_r: 16
  lora_alpha: 32
```

### DPO 训练

```yaml theme={null}
task: llm-dpo
backend: local
base_model: meta-llama/Llama-3.2-1B
project_name: llama-dpo

data:
  path: ./preferences.jsonl
  train_split: train
  valid_split: null
  chat_template: tokenizer
  column_mapping:
    prompt_text_column: prompt
    text_column: chosen
    rejected_text_column: rejected

log: wandb

params:
  dpo_beta: 0.1
  max_prompt_length: 128
  max_completion_length: null
  epochs: 1
  batch_size: 2
  peft: true
  lora_r: 16
```

### 知识蒸馏

```yaml theme={null}
task: llm-sft
backend: local
base_model: google/gemma-3-270m
project_name: distilled-model

data:
  path: ./prompts.jsonl
  train_split: train
  valid_split: null
  chat_template: tokenizer
  column_mapping:
    text_column: text

log: wandb

params:
  use_distillation: true
  teacher_model: google/gemma-2-2b
  distill_temperature: 3.0
  distill_alpha: 0.7
  epochs: 3
```

## 文本分类配置

```yaml theme={null}
task: text-classification
backend: local
base_model: bert-base-uncased
project_name: sentiment-classifier

data:
  path: ./reviews.csv
  train_split: train
  valid_split: null
  column_mapping:
    text_column: text
    target_column: target

log: wandb

params:
  epochs: 5
  batch_size: 16
  lr: 5e-5
```

## 配置文件中的环境变量

使用 `${VAR_NAME}` 引用环境变量：

```yaml theme={null}
hub:
  token: ${HF_TOKEN}
  username: ${HF_USERNAME}
```

在运行之前设置它们：

```bash theme={null}
export HF_TOKEN="hf_..."
export HF_USERNAME="my-username"
aitraining --config training.yaml
```

## 完整功能配置示例

```yaml theme={null}
task: llm-sft
backend: local
base_model: meta-llama/Llama-3.2-1B
project_name: production-model

data:
  path: ./conversations.jsonl
  train_split: train
  valid_split: validation
  chat_template: tokenizer
  column_mapping:
    text_column: text

log: wandb

hub:
  push_to_hub: true
  username: ${HF_USERNAME}
  token: ${HF_TOKEN}

params:
  # Training
  epochs: 3
  batch_size: 4
  gradient_accumulation: 4
  lr: 3e-5
  warmup_ratio: 0.1
  mixed_precision: bf16

  # LoRA
  peft: true
  lora_r: 32
  lora_alpha: 64
  lora_dropout: 0.05
  target_modules: all-linear

  # Distribution (for multi-GPU)
  distributed_backend: null        # null for auto (DDP), or "deepspeed"

  # Optimization
  use_flash_attention_2: true
  packing: true
  auto_find_batch_size: true

  # Checkpointing
  logging_steps: 10
  save_strategy: steps
  save_steps: 100
  save_total_limit: 1
```

## 最小配置

必需的最小字段：

```yaml theme={null}
task: llm-sft
backend: local
base_model: google/gemma-3-270m
project_name: my-model

data:
  path: ./data.jsonl
  train_split: train
  valid_split: null
  chat_template: tokenizer
  column_mapping:
    text_column: text

log: wandb
```

## 下一步

<CardGroup cols={2}>
  <Card title="LLM 训练" href="/cli/llm-training">
    LLM 参数参考
  </Card>

  <Card title="配置模板" href="/cli/config-templates">
    即用模板
  </Card>
</CardGroup>