Merge branch 'main' into release/0.1

# Conflicts:
#	pyproject.toml
#	src/twinkle/version.py

Author: tastelikefeet

README.md

@@ -135,8 +135,6 @@ supported on Twinkle✨ framework.
 |                     | [deepseek-ai/DeepSeek-R1](https://modelscope.cn/models/deepseek-ai/DeepSeek-R1)                                 |                    -                    | transformers>=4.39.3 |        ✔         |                 [deepseek-ai/DeepSeek-R1](https://huggingface.co/deepseek-ai/DeepSeek-R1)                 |
 | deepSeek-r1-distill | [deepseek-ai/DeepSeek-R1-Distill-Qwen-7B](https://modelscope.cn/models/deepseek-ai/DeepSeek-R1-Distill-Qwen-7B) |             1.5B/7B/14B/32B             | transformers>=4.37   |        ✔         | [deepseek-ai/DeepSeek-R1-Distill-Qwen-7B](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-7B) |
 
-For more detailed model support list 👉  [Quick Start](docs/source_en/Usage%20Guide/Quick-Start.md)
-
 ## Sample Code
 
 Below are some of the capabilities demonstrated in the example code. For a complete introduction to training capabilities,

README_ZH.md

@@ -116,8 +116,6 @@ Twinkle✨支持相同的算法接口运行在单GPU、torchrun多机、Ray、Cl
 |                     | [deepseek-ai/DeepSeek-R1](https://modelscope.cn/models/deepseek-ai/DeepSeek-R1)                                 |                    -                    | transformers>=4.39.3 |        ✔         |                 [deepseek-ai/DeepSeek-R1](https://huggingface.co/deepseek-ai/DeepSeek-R1)                 |
 | deepSeek-r1-distill | [deepseek-ai/DeepSeek-R1-Distill-Qwen-7B](https://modelscope.cn/models/deepseek-ai/DeepSeek-R1-Distill-Qwen-7B) |             1.5B/7B/14B/32B             | transformers>=4.37   |        ✔         | [deepseek-ai/DeepSeek-R1-Distill-Qwen-7B](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-7B) |
 
-更详细的模型支持列表 👉  [快速开始.md](docs/source_zh/使用指引/快速开始.md)
-
 ## 示例代码
 
 下面列出了示例代码的一部分能力。完整的训练能力介绍请参考[快速开始](docs/source_zh/使用指引/快速开始.md)以及[cookbook](cookbook)。

cookbook/client/tinker/custom_service/short_math_grpo.py

@@ -60,7 +60,13 @@
 
 class MathPreprocessor(Preprocessor):
 
-    def __call__(self, sample):
+    def __call__(self, rows):
+        rows = self.map_col_to_row(rows)
+        rows = [self.preprocess(row) for row in rows]
+        rows = self.map_row_to_col(rows)
+        return rows
+
+    def preprocess(self, sample):
         if sample['level'] not in ('Level 4', 'Level 5'):
             return Trajectory(messages=[], user_data=[])
 

cookbook/client/tinker/modelscope_service/short_math_grpo.py

@@ -60,7 +60,13 @@
 
 class MathPreprocessor(Preprocessor):
 
-    def __call__(self, sample):
+    def __call__(self, rows):
+        rows = self.map_col_to_row(rows)
+        rows = [self.preprocess(row) for row in rows]
+        rows = self.map_row_to_col(rows)
+        return rows
+
+    def preprocess(self, sample):
         if sample['level'] not in ('Level 4', 'Level 5'):
             return Trajectory(messages=[], user_data=[])
 

cookbook/client/twinkle/self_congnition.py

@@ -21,8 +21,7 @@
 
 logger = get_logger()
 
-# Whether to use Megatron for training
-use_megatron = True
+
 # Step 2: Initialize the Twinkle client to communicate with the remote server.
 # - base_url: the address of the running Twinkle server
 # - api_key: authentication token (loaded from environment variable)
@@ -88,8 +87,7 @@ def train():
     model.set_optimizer('Adam', lr=1e-4)
 
     # Use a linear learning rate scheduler (Do not support LR scheduler if server use megatron)
-    if not use_megatron:
-        model.set_lr_scheduler('LinearLR')
+    model.set_lr_scheduler('LinearLR')
 
     # Step 6: Optionally resume from a previous checkpoint
     if resume_path:

cookbook/mm/fsdp2.py

@@ -0,0 +1,103 @@
+from peft import LoraConfig
+from tqdm import tqdm
+
+import twinkle
+from twinkle import DeviceMesh, get_device_placement, get_logger
+from twinkle.data_format import Trajectory, Message
+from twinkle.dataloader import DataLoader
+from twinkle.dataset import LazyDataset, DatasetMeta
+from twinkle.model import TransformersModel
+from twinkle.preprocessor import Preprocessor
+
+# Construct a device_mesh, fsdp=2
+device_mesh = DeviceMesh.from_sizes(fsdp_size=2)
+# use torchrun mode
+twinkle.initialize(mode='local', global_device_mesh=device_mesh)
+
+logger = get_logger()
+
+
+class LatexOCRProcessor(Preprocessor):
+
+    def __call__(self, rows):
+        rows = self.map_col_to_row(rows)
+        rows = [self.preprocess(row) for row in rows]
+        rows = self.map_row_to_col(rows)
+        return rows
+
+    def preprocess(self, row) -> Trajectory:
+        return Trajectory(
+            messages=[
+                Message(role='user', content='<image>Using LaTeX to perform OCR on the image.', images=[row['image']]),
+                Message(role='assistant', content=row['text']),
+            ]
+        )
+
+
+def eval(model):
+    # 100 Samples
+    dataset = LazyDataset(dataset_meta=DatasetMeta('ms://AI-ModelScope/LaTeX_OCR', data_slice=range(100)))
+    dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B')
+    dataset.map(LatexOCRProcessor)
+    dataset.encode()
+    dataloader = DataLoader(dataset=dataset, batch_size=8)
+    for step, batch in tqdm(enumerate(dataloader)):
+        model.forward_only(inputs=batch)
+        model.calculate_loss()
+    metrics = model.calculate_metric(is_training=False)
+    return metrics
+
+
+def train():
+    # 2000 samples
+    dataset = LazyDataset(dataset_meta=DatasetMeta('ms://AI-ModelScope/LaTeX_OCR', data_slice=range(2000)))
+    # Set template to prepare encoding
+    dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B', max_length=1024)
+    # Preprocess the dataset to standard format
+    dataset.map(LatexOCRProcessor)
+    # Encode dataset
+    dataset.encode()
+    # Global batch size = 4, for GPUs, so 2 sample per GPU
+    dataloader = DataLoader(dataset=dataset, batch_size=4)
+    # Use a TransformersModel
+    from transformers.models.qwen3_5.modeling_qwen3_5 import Qwen3_5ForConditionalGeneration
+    model = TransformersModel(model_id='ms://Qwen/Qwen3.5-4B', model_cls=Qwen3_5ForConditionalGeneration)
+    model.model._no_split_modules = {'Qwen3_5DecoderLayer'}
+
+    lora_config = LoraConfig(r=8, lora_alpha=32, target_modules='all-linear')
+
+    # Add a lora to model, with name `default`
+    # Comment this to use full-parameter training
+    model.add_adapter_to_model('default', lora_config, gradient_accumulation_steps=2)
+    # Add Optimizer for lora `default`
+    model.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B')
+    model.set_optimizer(optimizer_cls='AdamW', lr=1e-4)
+    # Add LRScheduler for lora `default`
+    model.set_lr_scheduler(
+        scheduler_cls='CosineWarmupScheduler', num_warmup_steps=5, num_training_steps=len(dataloader))
+    logger.info(get_device_placement())
+    # Print the training config
+    logger.info(model.get_train_configs())
+    logger.info(f'Total steps: {len(dataloader)}')
+    loss_metric = 99.0
+    for step, batch in enumerate(dataloader):
+        # Do forward and backward
+        model.forward_backward(inputs=batch)
+        # Step
+        model.clip_grad_and_step()
+        if step % 20 == 0:
+            # Print metric
+            metric = model.calculate_metric(is_training=True)
+            logger.info(f'Current is step {step} of {len(dataloader)}, metric: {metric}')
+        if step > 0 and step % 40 == 0:
+            metrics = eval(model)
+            logger.info(f'Eval metric: {metrics}')
+            metrics['step'] = step
+            if loss_metric > float(metrics['loss']):
+                model.save(f'checkpoint-{step}')
+                loss_metric = float(metrics['loss'])
+    model.save(f'last-checkpoint')
+
+
+if __name__ == '__main__':
+    train()

cookbook/mm/fsdp2.sh

@@ -0,0 +1 @@
+CUDA_VISIBLE_DEVICES=0,1 torchrun --nproc_per_node=2 fsdp2.py

docs/source_en/Components/Checkpoint Engine/HCCLCheckpointEngine.md

@@ -25,4 +25,11 @@ HCCLCheckpointEngine is specifically designed for Ascend NPU environments:
 - Synchronizing model weights between NPUs
 - Large-scale NPU cluster deployment
 
+## Environment Variables
+
+- `TWINKLE_CKPT_HCCL_META_TIMEOUT_S`:
+  Controls the timeout (in seconds) for the HCCL CheckpointEngine
+  metadata handshake channel (ZMQ REQ/REP).
+  Default is `300`. This value should be an integer greater than `0`.
+
 > In Ascend NPU environments, HCCLCheckpointEngine provides performance comparable to NCCL.

docs/source_en/Components/Preprocessor and Filter/Preprocessor.md

@@ -7,11 +7,11 @@ The base class of Preprocessor:
 ```python
 class Preprocessor:
 
-    def __call__(self, row) -> Trajectory:
+    def __call__(self, rows: List[Dict]) -> List[Trajectory]:
         ...
 ```
 
-The format is to pass in a raw sample and output a `Trajectory`. If the sample cannot be used, you can directly return None.
+The format is to pass in a list of samples and output a list of `Trajectory`. If a sample cannot be used, you can directly ignore it.
 
 We provide some basic Preprocessors, such as `SelfCognitionProcessor`:
 
@@ -22,7 +22,7 @@ dataset.map('SelfCognitionProcessor', model_name='some-model', model_author='som
 Preprocessor contains the __call__ method, which means you can use a function to replace the class:
 
 ```python
-def self_cognition_preprocessor(row):
+def self_cognition_preprocessor(rows):
     ...
-    return Trajectory(...)
+    return [Trajectory(...), ...]
 ```

docs/source_en/Components/Sampler/vLLMSampler.md

@@ -69,4 +69,11 @@ sampler = vLLMSampler(
 response = sampler.sample(trajectories, sampling_params=params)
 ```
 
+## Environment Variables
+
+- `TWINKLE_VLLM_IPC_TIMEOUT_S`:
+  Controls the timeout (in seconds) for the IPC channel (ZMQ REQ/REP)
+  between `vLLMSampler` and the vLLM worker extension.
+  Default is `300`. This value must be greater than `0`.
+
 > In RLHF training, vLLMSampler is typically separated from the Actor model, using different hardware resources to avoid interference between inference and training.