|
| 1 | +# Twinkle Client - Transformers LoRA Training Example |
| 2 | +# |
| 3 | +# This script demonstrates how to fine-tune a language model using LoRA |
| 4 | +# (Low-Rank Adaptation) through the Twinkle client-server architecture. |
| 5 | +# The server must be running first (see server.py and server_config.yaml). |
| 6 | + |
| 7 | +# Step 1: Load environment variables from a .env file (e.g., API tokens) |
| 8 | +import dotenv |
| 9 | +import os |
| 10 | +from twinkle.data_format import Trajectory, Message |
| 11 | +from twinkle.preprocessor import Preprocessor |
| 12 | + |
| 13 | +dotenv.load_dotenv('.env') |
| 14 | +import numpy as np |
| 15 | +import torch |
| 16 | +from peft import LoraConfig |
| 17 | + |
| 18 | +from twinkle import get_logger |
| 19 | +from twinkle.dataset import DatasetMeta |
| 20 | +from twinkle_client import init_twinkle_client |
| 21 | +from twinkle.dataloader import DataLoader |
| 22 | +from twinkle.dataset import LazyDataset |
| 23 | +from twinkle_client.model import MultiLoraTransformersModel |
| 24 | + |
| 25 | +logger = get_logger() |
| 26 | + |
| 27 | +base_model = 'Qwen/Qwen3.5-4B' |
| 28 | +base_url = 'http://www.modelscope.cn/twinkle' |
| 29 | + |
| 30 | +# Step 2: Initialize the Twinkle client to communicate with the remote server. |
| 31 | +# - base_url: the address of the running Twinkle server |
| 32 | +# - api_key: authentication token (loaded from environment variable) |
| 33 | +client = init_twinkle_client(base_url=base_url, api_key=os.environ.get('MODELSCOPE_TOKEN')) |
| 34 | + |
| 35 | +# Step 3: Query the server for existing training runs and their checkpoints. |
| 36 | +# This is useful for resuming a previous training session. |
| 37 | +runs = client.list_training_runs() |
| 38 | + |
| 39 | +resume_path = None |
| 40 | +for run in runs: |
| 41 | + logger.info(run.model_dump_json(indent=2)) |
| 42 | + # List all saved checkpoints for this training run |
| 43 | + checkpoints = client.list_checkpoints(run.training_run_id) |
| 44 | + |
| 45 | + for checkpoint in checkpoints: |
| 46 | + logger.info(checkpoint.model_dump_json(indent=2)) |
| 47 | + # Uncomment the line below to resume from a specific checkpoint: |
| 48 | + # resume_path = checkpoint.twinkle_path |
| 49 | + |
| 50 | + |
| 51 | +class LatexOCRProcessor(Preprocessor): |
| 52 | + |
| 53 | + def __call__(self, rows): |
| 54 | + rows = self.map_col_to_row(rows) |
| 55 | + rows = [self.preprocess(row) for row in rows] |
| 56 | + rows = self.map_row_to_col(rows) |
| 57 | + return rows |
| 58 | + |
| 59 | + def preprocess(self, row) -> Trajectory: |
| 60 | + return Trajectory( |
| 61 | + messages=[ |
| 62 | + Message(role='user', content='<image>Using LaTeX to perform OCR on the image.', images=[row['image']]), |
| 63 | + Message(role='assistant', content=row['text']), |
| 64 | + ] |
| 65 | + ) |
| 66 | + |
| 67 | + |
| 68 | +def train(): |
| 69 | + # Step 4: Prepare the dataset |
| 70 | + |
| 71 | + # Load the latex dataset from ModelScope |
| 72 | + dataset = LazyDataset(dataset_meta=DatasetMeta('ms://AI-ModelScope/LaTeX_OCR', data_slice=range(500))) |
| 73 | + |
| 74 | + # Apply a chat template so the data matches the model's expected input format |
| 75 | + dataset.set_template('Qwen3_5Template', model_id=f'ms://{base_model}', max_length=512) |
| 76 | + |
| 77 | + # Replace placeholder names in the dataset with custom model/author names |
| 78 | + dataset.map(LatexOCRProcessor) |
| 79 | + |
| 80 | + # Tokenize and encode the dataset into model-ready input features |
| 81 | + dataset.encode(batched=True) |
| 82 | + |
| 83 | + # Wrap the dataset into a DataLoader that yields batches of size 4 |
| 84 | + dataloader = DataLoader(dataset=dataset, batch_size=4) |
| 85 | + |
| 86 | + # Step 5: Configure the model |
| 87 | + |
| 88 | + # Create a multi-LoRA Transformers model pointing to the base model on ModelScope |
| 89 | + model = MultiLoraTransformersModel(model_id=f'ms://{base_model}') |
| 90 | + |
| 91 | + # Define LoRA configuration: apply low-rank adapters to all linear layers |
| 92 | + lora_config = LoraConfig(target_modules='all-linear') |
| 93 | + |
| 94 | + # Attach the LoRA adapter named 'default' to the model. |
| 95 | + # gradient_accumulation_steps=2 means gradients are accumulated over 2 micro-batches |
| 96 | + # before an optimizer step, effectively doubling the batch size. |
| 97 | + model.add_adapter_to_model('default', lora_config, gradient_accumulation_steps=2) |
| 98 | + |
| 99 | + # Set the same chat template used during data preprocessing |
| 100 | + model.set_template('Qwen3_5Template') |
| 101 | + |
| 102 | + # Set the input processor (pads sequences on the right side) |
| 103 | + model.set_processor('InputProcessor', padding_side='right') |
| 104 | + |
| 105 | + # Use cross-entropy loss for language modeling |
| 106 | + model.set_loss('CrossEntropyLoss') |
| 107 | + |
| 108 | + # Use Adam optimizer with a learning rate of 1e-4 (Only support Adam optimizer if server use megatron) |
| 109 | + model.set_optimizer('Adam', lr=1e-4) |
| 110 | + |
| 111 | + # Use a linear learning rate scheduler (Do not support LR scheduler if server use megatron) |
| 112 | + # model.set_lr_scheduler('LinearLR') |
| 113 | + |
| 114 | + # Step 6: Optionally resume from a previous checkpoint |
| 115 | + if resume_path: |
| 116 | + logger.info(f'Resuming training from {resume_path}') |
| 117 | + model.load(resume_path, load_optimizer=True) |
| 118 | + |
| 119 | + # Step 7: Run the training loop |
| 120 | + logger.info(model.get_train_configs().model_dump()) |
| 121 | + |
| 122 | + for epoch in range(3): |
| 123 | + logger.info(f'Starting epoch {epoch}') |
| 124 | + for step, batch in enumerate(dataloader): |
| 125 | + for sample in batch: |
| 126 | + for key in sample: |
| 127 | + if isinstance(sample[key], np.ndarray): |
| 128 | + sample[key] = sample[key].tolist() |
| 129 | + elif isinstance(sample[key], torch.Tensor): |
| 130 | + sample[key] = sample[key].cpu().numpy().tolist() |
| 131 | + # Forward pass + backward pass (computes gradients) |
| 132 | + model.forward_backward(inputs=batch) |
| 133 | + |
| 134 | + # Step |
| 135 | + model.clip_grad_and_step() |
| 136 | + # Equal to the following steps: |
| 137 | + # # Clip gradients to prevent exploding gradients (max norm = 1.0) |
| 138 | + # model.clip_grad_norm(1.0) |
| 139 | + # # Perform one optimizer step (update model weights) |
| 140 | + # model.step() |
| 141 | + # # Reset gradients to zero for the next iteration |
| 142 | + # model.zero_grad() |
| 143 | + # # Advance the learning rate scheduler by one step |
| 144 | + # model.lr_step() |
| 145 | + |
| 146 | + # Log the loss every 2 steps (aligned with gradient accumulation) |
| 147 | + if step % 2 == 0: |
| 148 | + # Print metric |
| 149 | + metric = model.calculate_metric(is_training=True) |
| 150 | + logger.info(f'Current is step {step} of {len(dataloader)}, metric: {metric.result}') |
| 151 | + |
| 152 | + # Step 8: Save the trained checkpoint |
| 153 | + twinkle_path = model.save(name=f'twinkle-epoch-{epoch}', save_optimizer=True) |
| 154 | + logger.info(f'Saved checkpoint: {twinkle_path}') |
| 155 | + |
| 156 | + # Step 9: Upload the checkpoint to ModelScope Hub |
| 157 | + # YOUR_USER_NAME = "your_username" |
| 158 | + # hub_model_id = f'{YOUR_USER_NAME}/twinkle-multi-modal' |
| 159 | + # model.upload_to_hub( |
| 160 | + # checkpoint_dir=twinkle_path, |
| 161 | + # hub_model_id=hub_model_id, |
| 162 | + # async_upload=False |
| 163 | + # ) |
| 164 | + # logger.info(f"Uploaded checkpoint to hub: {hub_model_id}") |
| 165 | + |
| 166 | + |
| 167 | +if __name__ == '__main__': |
| 168 | + train() |
0 commit comments