使用指引 | Twinkle

训练指南

Mon, 01 Jan 0001 00:00:00 +0000

✨ Twinkle 是什么？

大模型训练组件库。基于 PyTorch，更简洁、更灵活、生产就绪。

🧩 松耦合架构 · 标准化接口
🚀 多运行模式 · torchrun / Ray / HTTP
🔌 多框架兼容 · Transformers / Megatron
👥 多租户支持 · 单基座模型部署

Twinkle 适配性

Twinkle 和都是模型训练框架，但二者的特性有很大不同，开发者可以根据自己的需求选择。

何时选择 Twinkle

如果你是大模型的初学者，希望更好地了解模型机制和模型训练方法
如果你是大模型研究者，希望定制模型或训练方法
如果你善于编写 training loop，希望定制训练过程
如果你希望提供企业级或商业化训练平台

何时选择ms-swift

如果你不关心训练过程，希望仅提供数据集便可完成训练
如果你需要更多的模型支持和数据集种类
如果你需要Embedding、Reranker、Classification等多种类型的训练
如果你需要推理、部署、量化等其他能力
如果你对新模型的训练支持敏感，Swift 会保证 day-0 的更新能力

模型训练与Twinkle

当你发现通用大模型无法满足你的需求时，训练就成为必选项：

让模型认识你：通过自我认知训练，模型可以回答"你是谁"、“你的开发者是谁"等问题，成为专属于你的 AI 助手。
让模型懂你的业务：使用私有数据微调，模型可以学会你的行业术语、业务流程、内部知识库，成为领域专家。
让模型按你的方式思考：通过强化学习（RL），你可以定义奖励规则，引导模型生成符合你期望的输出格式、推理风格或价值观。
让模型更强：蒸馏大模型的能力到小模型，或通过持续预训练注入新知识，让模型能力持续进化。

训练完成后，你可以将模型部署到自己的服务器，或发布到 ModelScope/Hugging Face 与社区分享，或者通过vLLM等部署架构部署你的服务进行使用。

现有的训练框架可以大致分为三类：

底层框架（如原生 PyTorch）：灵活性极高，但需要开发者从零搭建分布式、数据加载、checkpoint 等基础设施，开发成本高、周期长。
高层框架（如 ms-swift、transformers Trainer）：开箱即用，只需提供数据集和配置即可完成训练，但训练过程是黑盒，难以定制算法细节。
重型框架（如 Megatron-LM）：为超大规模模型设计，支持复杂的并行策略，但学习曲线陡峭，代码侵入性强。

Twinkle 的设计目标是在这三类框架之间找到平衡点：

保留 training loop 的控制权：开发者可以清晰看到并控制 forward、backward、step 的每一步，便于调试和定制算法。
提供高内聚的组件抽象：Dataset、Model、Sampler、Loss 等组件各司其职，可独立使用也可组合使用，无需整体接入。
屏蔽分布式复杂性：无论是单卡、torchrun 还是 Ray 集群，训练代码几乎相同，只需修改初始化参数。
支持生产级部署：内置多租户、HTTP 服务、权重同步等能力，可直接用于构建企业级训练平台。

使用模式

仅使用部分组件

开发者可以仅使用Twinkle的一部分组件，结合自己的已有代码来完成训练工作。例如，仅使用Dataset&DataLoader：

from twinkle.dataset import PackingDataset, DatasetMeta
from twinkle.dataloader import DataLoader
from twinkle.preprocessor import SelfCognitionProcessor

def train():
 dataset_meta = DatasetMeta(
 dataset_id='ms://swift/self-cognition',
 )

 dataset = PackingDataset(dataset_meta)
 dataset.map(SelfCognitionProcessor(model_name='Twinkle模型', model_author='ModelScope社区'))
 dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B', max_length=512)
 dataset.encode()
 dataset.pack_dataset()

 dataloader = DataLoader(dataset, batch_size=8)
 for data in dataloader:
 print(data)
 """
 {
 "input_ids": [...],
 "position_ids": [...],
 ...
 }
 """
 break

if __name__ == '__main__':
 train()

上面的代码中，使用PackingDataset加载了一个叫做swift/self-cognition的数据集。PackingDataset可以用于将数据进行装箱，保证每个batch的长度都与设置的最大长度相似。我们在循环中简单地使用了print打印了输出，在实际使用中，你可以在下面继续编写你的自定义训练代码。

Twinkle的所有组件都支持单独拆分使用，可以参考下面章节的组件列表。

单GPU

Twinkle 支持单GPU运行训练。下面是一个例子：

from peft import LoraConfig

from twinkle import get_device_placement, get_logger
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.model import TransformersModel
from twinkle.preprocessor import SelfCognitionProcessor

logger = get_logger()


def train():
 # 1000 samples
 dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(1000)))
 # Set template to prepare encoding
 dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B')
 # Preprocess the dataset to standard format
 dataset.map(SelfCognitionProcessor('twinkle大模型', 'ModelScope社区'))
 # Encode dataset
 dataset.encode()
 # Global batch size = 8, for GPUs, so 1 sample per GPU
 dataloader = DataLoader(dataset=dataset, batch_size=8)
 # Use a TransformersModel
 model = TransformersModel(model_id='ms://Qwen/Qwen3.5-4B')

 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_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)}')
 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}')
 model.save(f'last-checkpoint')


if __name__ == '__main__':
 train()

在这个训练代码中，我们构造了一个数据集并拉起了Qwen/Qwen3.5-4B模型，使用all-linear方式加载了lora，并完成了一次训练。在日志中，可以看到loss逐步收敛的过程。

提示 — 全参数训练：上面的示例使用 LoRA 以提高效率。若要切换为全参数训练，只需移除 add_adapter_to_model 调用（以及 from peft import LoraConfig 导入），其余代码完全不变。

torchrun

Twinkle 支持以 torchrun 模式运行训练。在这种场景下，不需要安装 Ray 相关的依赖。

from peft import LoraConfig

import twinkle
from twinkle import DeviceMesh, get_device_placement, get_logger
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.model import TransformersModel
from twinkle.preprocessor import SelfCognitionProcessor

# Construct a device_mesh, fsdp=4, dp=2
device_mesh = DeviceMesh.from_sizes(fsdp_size=4, dp_size=2)
# use torchrun mode
twinkle.initialize(mode='local', global_device_mesh=device_mesh)

logger = get_logger()


def train():
 # 1000 samples
 dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(1000)))
 # Set template to prepare encoding
 dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B')
 # Preprocess the dataset to standard format
 dataset.map(SelfCognitionProcessor('twinkle大模型', 'ModelScope社区'))
 # Encode dataset
 dataset.encode()
 # Global batch size = 8, for GPUs, so 1 sample per GPU
 dataloader = DataLoader(dataset=dataset, batch_size=8)
 # Use a TransformersModel
 model = TransformersModel(model_id='ms://Qwen/Qwen3.5-4B')

 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_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)}')
 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}')
 model.save(f'last-checkpoint')


if __name__ == '__main__':
 train()

上面的代码中，构造了fsdp2和dp的hybrid并行模式，并使用了八张卡进行训练。可以看到它和单卡训练的代码基本相同，只是使用了DeviceMesh来声明模型布局。

运行时，需要这样拉起训练：

CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 torchrun --nproc_per_node=8 train.py

断点续训

上面的训练循环可以扩展为支持断点续训。完整示例可直接参考 cookbook/transformers/fsdp2.py。

保存检查点

model.save(
 checkpoint_name,
 output_dir='./output/fsdp2',
 adapter_name=ADAPTER_NAME,
 save_optimizer=True, # 保存优化器状态
 consumed_train_samples=dataloader.get_state()['consumed_train_samples'], # 落盘训练进度
)

DataLoader 内部自动追踪已消费样本数，通过 dataloader.get_state() 获取。

恢复训练

from pathlib import Path

RESUME_FROM_CHECKPOINT = './output/fsdp2/last-checkpoint'
RESUME_ONLY_MODEL = False # True: 仅恢复权重，不恢复优化器/调度器等训练状态
IGNORE_DATA_SKIP = False # True: 不从 trainer_state.json 跳过已消费数据

if RESUME_FROM_CHECKPOINT:
 checkpoint_path = str(Path(RESUME_FROM_CHECKPOINT).expanduser().resolve())
 progress = model.resume_from_checkpoint(checkpoint_path, resume_only_model=RESUME_ONLY_MODEL)
 if not IGNORE_DATA_SKIP:
 dataloader.resume_from_checkpoint(progress['consumed_train_samples'])

两个开关的组合效果：

`RESUME_ONLY_MODEL`	`IGNORE_DATA_SKIP`	效果
`False`（默认）	`False`（默认）	完整续训：恢复权重 + 优化器 + 调度器 + RNG，并跳过已消费数据
`True`	`False`	仅恢复权重，但仍跳过已消费数据（适合沿用权重、重新开始优化）
`True`	`True`	仅恢复权重，从数据集开头重新训练

LoRA / adapter vs 全参训练

上述流程默认以 LoRA 为例。全参训练的恢复仅有一处不同——TransformersModel 初始化时，model_id 需要用 checkpoint 路径替代 base model ID：

# LoRA / adapter：base model 从 hub 加载，checkpoint 仅含 adapter 权重和训练状态
model = TransformersModel(model_id='ms://Qwen/Qwen3.5-4B')
progress = model.resume_from_checkpoint(resume_path)

# 全参：模型权重已整体保存到 checkpoint，直接将其作为 model_id
model = TransformersModel(model_id=resume_path)
progress = model.resume_from_checkpoint(resume_path)

二者后续的 resume_from_checkpoint 及 dataloader.resume_from_checkpoint 调用完全一致。

Ray训练

是多机模型训练和推理场景中常用的调度中间件框架。它针对多模型、多设备的执行和资源管理进行了额外优化，并支持对接kubernetes系统进行生产化。这样的特性使得它尤其适用于RL、GKD等复杂训练场景中。

Twinkle 支持使用 Ray 进行训练和采样，并且它的代码和上面的训练 API 几乎一致：

import os
from typing import List, Tuple, Dict, Any
from peft import LoraConfig
import twinkle
from twinkle import DeviceMesh, DeviceGroup, get_device_placement
from twinkle.advantage import GRPOAdvantage
from twinkle.checkpoint_engine import CheckpointEngineManager
from twinkle.data_format import SamplingParams
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.model.megatron import MegatronModel
from twinkle.metric import CompletionRewardMetric
from twinkle.preprocessor.llm import GSM8KProcessor
from twinkle.processor import InputProcessor
from twinkle.reward import GSM8KAccuracyReward, GSM8KFormatReward
from twinkle.sampler import vLLMSampler
from twinkle.template import Template

MODEL_ID = os.environ.get('MODEL_ID', 'ms://Qwen/Qwen3.5-4B')
MODEL_GPUS = int(os.environ.get('MODEL_GPUS', 4))
SAMPLER_GPUS = int(os.environ.get('SAMPLER_GPUS',4))
NUM_GPUS = MODEL_GPUS + SAMPLER_GPUS
NUM_GENERATIONS = int(os.environ.get('NUM_GENERATIONS', 8))
MAX_NEW_TOKENS = int(os.environ.get('MAX_NEW_TOKENS', 4096))
LEARNING_RATE = float(os.environ.get('LR', 1e-5))
MAX_STEPS = int(os.environ.get('MAX_STEPS', 200))
BATCH_SIZE = int(os.environ.get('BATCH_SIZE', 16)) # global prompt-level, global completion-level batch size = BATCH_SIZE * num_generations * dp_size
MINI_BATCH_SIZE = int(os.environ.get('MINI_BATCH_SIZE', 16)) # global completion-level mini-batch-size
MICRO_BATCH_SIZE = int(os.environ.get('MICRO_BATCH_SIZE', 2)) # per-device-micro-batch-size (completion-level), batch_size in forward_backward
GRADIENT_ACCUMULATION_STEPS = int(os.environ.get('GRADIENT_ACCUMULATION_STEPS', 1))
ADAPTER_NAME = 'default'

def create_gsm8k_dataset():
 dataset = Dataset(DatasetMeta('ms://modelscope/gsm8k', subset_name='main', split='train'))
 dataset.set_template('Qwen3_5Template', model_id=MODEL_ID, max_length=2048)
 dataset.map(GSM8KProcessor())
 dataset.encode(add_generation_prompt=True)
 return dataset

def compute_rewards(
 trajectories: List[Dict[str, Any]],
) -> Tuple[List[float], List[float], List[float]]:
 accuracy_reward_fn = GSM8KAccuracyReward()
 format_reward_fn = GSM8KFormatReward()
 accuracy_rewards = accuracy_reward_fn(trajectories)
 format_rewards = format_reward_fn(trajectories)
 total_rewards = [a + f for a, f in zip(accuracy_rewards, format_rewards)]
 return total_rewards, format_rewards, accuracy_rewards

def main():
 # set sampler and model separate to use different gpus
 device_groups = [
 DeviceGroup(name='model',ranks=list(range(MODEL_GPUS)),device_type='GPU'),
 DeviceGroup(name='sampler',ranks=list(range(MODEL_GPUS, NUM_GPUS)),device_type='GPU'),
 ]
 model_mesh = DeviceMesh.from_sizes(world_size=MODEL_GPUS, dp_size=MODEL_GPUS)
 sampler_mesh = DeviceMesh.from_sizes(world_size=SAMPLER_GPUS, dp_size=SAMPLER_GPUS)
 twinkle.initialize(mode='ray', nproc_per_node=NUM_GPUS, groups=device_groups, lazy_collect=False)

 lora_config = LoraConfig(target_modules='all-linear', r=32, lora_alpha=64, lora_dropout=0.05)
 model = MegatronModel(model_id=MODEL_ID, device_mesh=model_mesh, remote_group='model', mixed_precision='bf16')
 model.add_adapter_to_model(ADAPTER_NAME, lora_config, gradient_accumulation_steps=1)
 model.set_optimizer('default', lr=LEARNING_RATE)
 model.set_lr_scheduler('default', lr_decay_steps=MAX_STEPS, max_lr=LEARNING_RATE)
 model.set_loss('GRPOLoss', epsilon=0.2)
 model.set_processor(InputProcessor)
 model.set_template('Qwen3_5Template', model_id=MODEL_ID)

 sampler = vLLMSampler(
 model_id=MODEL_ID,
 engine_args={
 'gpu_memory_utilization': 0.8,
 'max_model_len': 4096,
 'max_lora_rank': 32, # save as lora_config
 'enable_lora': True,
 },
 device_mesh=sampler_mesh,
 remote_group='sampler',
 )
 sampler.set_template('Qwen3_5Template', model_id=MODEL_ID)
 ckpt_manager = CheckpointEngineManager(model=model, sampler=sampler)
 dataloader = DataLoader(
 dataset=create_gsm8k_dataset,
 batch_size=BATCH_SIZE * GRADIENT_ACCUMULATION_STEPS,
 min_batch_size=BATCH_SIZE * GRADIENT_ACCUMULATION_STEPS,
 device_mesh=model_mesh,
 remote_group='model',
 )
 advantage_fn = GRPOAdvantage()
 metrics = CompletionRewardMetric()
 sampling_params = SamplingParams(max_tokens=MAX_NEW_TOKENS, num_samples=1, logprobs=1)
 optim_step = 0
 print(get_device_placement())

 for batch in dataloader:
 if optim_step >= MAX_STEPS:
 break
 metrics.reset()
 global_prompts = batch if isinstance(batch, list) else [batch]
 ckpt_manager.sync_weights(merge_and_sync=False)
 sampler.reset_prefix_cache()
 sample_responses = sampler.sample(
 global_prompts*NUM_GENERATIONS,
 sampling_params,
 )
 all_input_data: List[Dict[str, Any]] = []
 all_old_logps: List[List[float]] = []
 all_completion_lengths: List[int] = []

 for sample_response in sample_responses:
 for sequence in sample_response.sequences:
 all_input_data.append(sequence.new_input_feature)
 all_old_logps.append([logprob[0][1] for logprob in sequence.logprobs])
 all_completion_lengths.append(len(sequence.tokens))
 total_rewards, format_rewards, accuracy_rewards = compute_rewards(
 all_input_data
 )
 metrics.accumulate(
 completion_lengths=all_completion_lengths,
 rewards={
 'total': total_rewards,
 'format': format_rewards,
 'accuracy': accuracy_rewards,
 },
 )
 advantages = advantage_fn(total_rewards, num_generations=NUM_GENERATIONS, scale='group').tolist()
 # Split completions into mini-batches and run one optim step per mini-batch.
 total_completions = len(all_input_data)
 for mb_start in range(0, total_completions, MINI_BATCH_SIZE):
 mb_end = min(mb_start + MINI_BATCH_SIZE, total_completions)
 mb_inputs = all_input_data[mb_start:mb_end]
 mb_old_logps = all_old_logps[mb_start:mb_end]
 mb_advantages = advantages[mb_start:mb_end]

 model.forward_backward(
 inputs=mb_inputs,
 old_logps=mb_old_logps,
 advantages=mb_advantages,
 micro_batch_size=MICRO_BATCH_SIZE,
 )
 model.clip_grad_and_step()
 optim_step += 1

 if optim_step >= MAX_STEPS:
 break
 log_dict = metrics.calculate()
 log_dict.update(model.calculate_metric(is_training=True))
 metrics.reset()
 print(f'[Step {optim_step}/{MAX_STEPS}] {log_dict}')

 print(f'Training completed. optim_steps={optim_step}')
 model.save('grpo-gsm8k-checkpoint')

if __name__ == '__main__':
 main()

在上面的代码中，我们给出了一个RL的训练代码。我们可以在代码中清晰看到数据如何构造、sampler/model如何声明和传参，以及advantage和loss的构造过程。这个过程没有任何显式引用 ray 的地方。我们仅在初始化时声明了 ray 模式：

twinkle.initialize(mode='ray', nproc_per_node=NUM_GPUS, groups=device_groups, lazy_collect=False)

开发者可以定制模型等组件的构造和调用方式，所有 Transformers、Megatron 的模型参数都可以在构造模型时传入。

后面所有的 ray 调用和数据分发，都是隐式进行的。运行这个脚本需要提前安装好 Ray。之后这样运行：

python train.py

远程训练

client-server 训练场景同样支持断点续训。推荐流程是调用 model.resume_from_checkpoint(resume_path) 恢复权重和优化器状态，再调用 dataloader.resume_from_checkpoint(progress['consumed_train_samples']) 跳过已消费数据。详细示例可参考和。

Twinkle 的一大特色是支持多租户用户混合训练。具体来说，多个用户可以使用一个基模进行 LoRA 训练，这样可以极大减小服务端部署成本。

假设我们使用八卡开启一个服务。首先我们需要启动ray集群：

CUDA_VISIBLE_DEVICES=0,1 ray start --head --port=6379 --num-gpus=2
CUDA_VISIBLE_DEVICES=2,3 ray start --address=127.0.0.1:6379 --num-gpus=2
CUDA_VISIBLE_DEVICES="" ray start --address=127.0.0.1:6379 --num-gpus=0

我们启动了一组包含三个 node 的 Ray 集群：

0、1 两张卡作为一个 node
2、3 两张卡作为一个 node
CPU 资源作为一个 node

如果在生产环境使用，可以启动更多 node，并部署更多 replica 以兼容更大的用户量。在这里我们仅以四卡作为例子。

下面，启动server：

twinkle-server launch -c cookbook/client/server/transformer/server_config.yaml

server_config.yaml 的编写方式详见。

服务端会启动一个包含 Sampler 集群、模型集群、工具集群的三个服务。

下面可以进行client端训练：

import dotenv
dotenv.load_dotenv('.env')
import re
from twinkle.data_format import Trajectory
from twinkle.reward.base import Reward
import gc
from peft import LoraConfig
from typing import List, Tuple

from twinkle import get_logger
from twinkle.advantage import GRPOAdvantage
from twinkle.dataset import DatasetMeta
from twinkle.metric import CompletionRewardMetric
from twinkle_client import init_twinkle_client
from twinkle_client.dataloader import DataLoader
from twinkle_client.dataset import Dataset
from twinkle_client.model import MultiLoraTransformersModel
from twinkle_client.sampler import vLLMSampler

logger = get_logger()

# ========== Configuration ==========
MODEL_ID = 'ms://Qwen/Qwen3.5-4B'
NUM_GENERATIONS = 4
MAX_NEW_TOKENS = 1024
LEARNING_RATE = 1e-5
MAX_STEPS = 10
BATCH_SIZE = 2
TEMPERATURE = 1.0
SYNC_INTERVAL = 1 # Save weights for sampler every N steps
GRADIENT_ACCUMULATION_STEPS = 4


def create_countdown_dataset():
 """Create Countdown Game dataset for GRPO training."""

 dataset = Dataset(dataset_meta=DatasetMeta('ms://zouxuhong/Countdown-Tasks-3to4', data_slice=range(500)))
 dataset.set_template('Qwen3_5Template', model_id=MODEL_ID, max_length=8192)
 dataset.map('CountdownProcessor')
 dataset.encode(add_generation_prompt=True, batched=True)
 return dataset


class CountDownAccuracy(Reward):

 @staticmethod
 def countdown_accuracy_reward(completion: str, target: int, nums: List[int]) -> float:
 """Accuracy reward: checks if equation is correct."""
 try:
 match = re.search(r'<answer>(.*?)<\/answer>', completion)
 if match is None:
 return 0.0
 equation = match.group(1).strip()
 if '=' in equation:
 equation = equation.split('=')[0]
 used_numbers = [int(n) for n in re.findall(r'\d+', equation)]
 if sorted(used_numbers) != sorted(nums):
 return 0.0
 if not re.match(r'^[\d+\-*/().\s]+$', equation):
 return 0.0
 result = eval(equation, {'__builtins__': None}, {})
 return 1.0 if abs(float(result) - float(target)) < 1e-5 else 0.0
 except Exception: # noqa
 return 0.0

 def __call__(self, trajectories: List[Trajectory], ground_truths: List[Trajectory]):
 rewards = []
 for trajectory in trajectories:
 messages = trajectory.get('messages', [])
 completion = ''
 for msg in reversed(messages):
 if msg.get('role') == 'assistant':
 completion = msg.get('content', '')
 break
 user_data = trajectory.get('user_data', [{}])
 data = user_data[0] if isinstance(user_data, list) and user_data else {}
 target = data.get('target', 0)
 nums = data.get('nums', [])
 acc_reward = self.countdown_accuracy_reward(completion, target, nums)
 rewards.append(acc_reward)
 return rewards


def compute_rewards(trajectories: List[dict], ) -> Tuple[List[float], List[float], List[float]]:
 """Compute format and accuracy rewards for Countdown game."""
 from twinkle.reward import FormatReward
 format_rewards = FormatReward()(trajectories, [])
 accuracy_rewards = CountDownAccuracy()(trajectories, [])
 total_rewards = [a + b for a, b in zip(accuracy_rewards, format_rewards)]
 return total_rewards, format_rewards, accuracy_rewards


def train():
 # Step 1: Initialize the Twinkle client
 client = init_twinkle_client(
 base_url='http://localhost:8000',
 api_key='',
 )

 # Step 2: Prepare dataset and dataloader
 dataset = create_countdown_dataset()
 dataloader = DataLoader(dataset=dataset, batch_size=BATCH_SIZE)

 # Step 3: Configure the training model
 model = MultiLoraTransformersModel(model_id=MODEL_ID)

 lora_config = LoraConfig(
 target_modules='all-linear',
 r=8,
 lora_alpha=32,
 lora_dropout=0.05,
 )
 model.add_adapter_to_model(
 'default',
 lora_config,
 gradient_accumulation_steps=GRADIENT_ACCUMULATION_STEPS,
 )

 # Set GRPO loss (the key difference from SFT training)
 model.set_loss('GRPOLoss', epsilon=0.2, beta=0.0)

 # Set optimizer and LR scheduler
 model.set_optimizer('AdamW', lr=LEARNING_RATE)
 model.set_lr_scheduler(
 'CosineWarmupScheduler',
 num_warmup_steps=500,
 num_training_steps=MAX_STEPS,
 )

 # Set processor and template for encoding inputs
 model.set_processor('InputProcessor')
 model.set_template('Qwen3_5Template', model_id=MODEL_ID)

 # Step 4: Configure the sampler
 sampler = vLLMSampler(model_id=MODEL_ID)
 sampler.set_template('Qwen3_5Template', model_id=MODEL_ID)

 # Step 5: Setup metrics and advantage function
 advantage_fn = GRPOAdvantage()
 metrics = CompletionRewardMetric()

 sampling_params = {
 'max_tokens': MAX_NEW_TOKENS,
 'temperature': TEMPERATURE,
 'top_p': 0.95,
 }

 # Track the current adapter path for sampling
 current_adapter_uri = None

 step = 0
 for batch in dataloader:
 if step >= MAX_STEPS:
 break

 metrics.reset()
 prompts = batch if isinstance(batch, list) else [batch]

 # ========== 1. Save weights and update adapter_uri ==========
 # Instead of sync_weights, save the model checkpoint and pass
 # the resulting path to the sampler as adapter_uri
 if step % SYNC_INTERVAL == 0:
 logger.info(f'Step {step}: Saving weights for sampler...')
 twinkle_path = model.save(
 name=f'grpo-sampler-step-{step}',
 save_optimizer=False,
 )
 current_adapter_uri = twinkle_path
 logger.info(f'Step {step}: Saved weights to {current_adapter_uri}')

 # ========== 2. Sample completions ==========
 sample_response = sampler.sample(
 inputs=prompts,
 sampling_params=sampling_params,
 adapter_uri=current_adapter_uri,
 num_samples=NUM_GENERATIONS,
 )

 input_features = []
 old_logps_list = []
 completion_lengths = []

 sequences = sample_response.get('sequences', [])
 for seq in sequences:
 input_features.append(seq.get('new_input_feature', seq))
 old_logps_list.append(seq.get('logprobs', []))
 completion_lengths.append(len(seq.get('tokens', [])))

 if not input_features:
 logger.warning(f'Step {step}: No valid samples, skipping')
 step += 1
 continue

 # ========== 3. Compute rewards ==========
 total_rewards, format_rewards, accuracy_rewards = compute_rewards(input_features)
 metrics.accumulate(
 None,
 None,
 completion_lengths=completion_lengths,
 rewards={
 'total': total_rewards,
 'format': format_rewards,
 'accuracy': accuracy_rewards,
 })

 # ========== 4. Compute advantages ==========
 advantages = advantage_fn(
 total_rewards,
 num_generations=NUM_GENERATIONS,
 scale='group',
 ).tolist()

 frac_zero_std = (1.0 if all(abs(a) < 1e-8 for a in advantages) else 0.0)
 if frac_zero_std == 1.0:
 logger.info(f'Step {step}: All advantages are zero, skipping training')
 step += 1
 continue

 # ========== 5. Training step (GRPO) ==========
 # forward_backward with GRPO loss: passes advantages and old_logps
 # to the server-side GRPOLoss for proper policy optimization
 model.forward_backward(
 inputs=input_features,
 advantages=advantages,
 old_logps=old_logps_list,
 )

 # Gradient clipping and optimizer step
 model.clip_grad_norm(1.0)
 model.step()
 model.zero_grad()
 model.lr_step()

 gc.collect()

 # ========== 6. Log ==========
 log_dict = metrics.calculate()
 log_dict.update(model.calculate_metric())
 log_dict['train/frac_reward_zero_std'] = frac_zero_std
 logger.info(f'Step {step}: {log_dict}')
 step += 1

 # Save final checkpoint
 twinkle_path = model.save(name='grpo-countdown-final', save_optimizer=True)
 logger.info(f'Saved final checkpoint: {twinkle_path}')


if __name__ == '__main__':
 train()

多个开发者可以并行使用这个服务的单个基模进行并行训练和采样。并且，他们进行的训练方式允许不同。例如，A 用户可以进行 SFT，B 用户可以进行 RL，C 用户可以进行采样。同样，Twinkle 也支持 Tinker-like API 进行远端训练：

from tinker import types
from tqdm import tqdm
from tinker import ServiceClient
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.preprocessor import SelfCognitionProcessor
from twinkle.server.common import input_feature_to_datum

# The base model to fine-tune / evaluate
base_model = 'Qwen/Qwen3.5-4B'


def train():
 # Step 1: Prepare the dataset

 # Load the self-cognition dataset from ModelScope (first 500 examples)
 dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(500)))

 # Apply the chat template matching the base model (max 256 tokens per sample)
 dataset.set_template('Qwen3_5Template', model_id=f'ms://{base_model}', max_length=256)

 # Replace placeholder names with custom model/author identity
 dataset.map(SelfCognitionProcessor('twinkle模型', 'twinkle团队'), load_from_cache_file=False)

 # Tokenize and encode the dataset into model-ready input features
 dataset.encode(batched=True, load_from_cache_file=False)

 # Wrap the dataset into a DataLoader that yields batches of size 8
 dataloader = DataLoader(dataset=dataset, batch_size=8)

 # Step 2: Initialize the training client
 # Connect to the Twinkle server running locally
 service_client = ServiceClient(base_url='http://localhost:8000', api_key='your-api-key')
 # Create a LoRA training client for the base model (rank=16 for the LoRA adapter)
 training_client = service_client.create_lora_training_client(base_model=base_model, rank=16)

 # Step 3: Run the training loop
 for epoch in range(3):
 print(f'Epoch {epoch}')
 for step, batch in tqdm(enumerate(dataloader)):
 # Convert each InputFeature into a Datum for the Tinker API
 input_datum = [input_feature_to_datum(input_feature) for input_feature in batch]

 # Send data to server: forward + backward pass (computes gradients)
 fwdbwd_future = training_client.forward_backward(input_datum, 'cross_entropy')

 # Optimizer step: update model weights with Adam
 optim_future = training_client.optim_step(types.AdamParams(learning_rate=1e-4))

 # Wait for both operations to complete
 fwdbwd_future.result()
 optim_result = optim_future.result()
 print(f'Training Metrics: {optim_result}')

 # Save a checkpoint after each epoch
 save_future = training_client.save_state(f'twinkle-lora-{epoch}')
 save_result = save_future.result()
 print(f'Saved checkpoint to {save_result.path}')


if __name__ == '__main__':
 train()

使用魔搭社区提供的TaaS化训练服务

在 Twinkle 框架开源的同时，我们依托ModelScope的后台服务，也提供了托管的模型训练服务(Training as a Service)，开发者可以通过这一服务，免费体验Twinkle的训练API。该服务和上面叙述的Tinker API部分代码是相同的，唯一不同的是Endpoint和Token需要使用魔搭官方的对应信息。关于如何使用官方服务，请查看的详细描述。

Twinkle提供了采样 API，该 API 可以用于更灵活地控制采样方式以验证结果，或者参与到 RL 算法的采样流程中。

完整的训练模式示例请参考目录。

使用 Hugging Face 的模型

要从 Hugging Face 加载模型而不是 ModelScope，只需切换前缀即可：

ms://Qwen/Qwen3.5-4B -> hf://Qwen/Qwen3.5-4B

所有接受 model_id 参数的组件都支持这种基于前缀的路由。

🛠️ Twinkle✨ 模块化生态系统

Dataset _{数据加载和预处理}	Template _{编码和解码}	DataLoader _{数据分发和批处理}	Preprocessor _{数据 ETL}	InputProcessor _{任务特定的输入处理}
Model _{大模型，支持多种框架}	Sampler _采样逻辑	Loss _损失函数	Metric _{训练指标收集}	Reward _奖励函数
Advantage _优势函数	CheckpointEngine _权重同步	Patch _{模型修复补丁}	Module _{组件，如优化器}	Kernel _算子
Server _{启动后端集群}	Client _{客户端代码}	Infra _{隔离 ray 和 torchrun 的差异}	Plugin _{使用 hub 组件}	Hub _{与 HF/MS 库对接}

Twinkle 的可定制组件

在 Twinkle 的设计中，torchrun、Ray、HTTP 的训练使用同样的 API，并共享相同的组件和输入输出结构。因此，其很多组件可以由开发者自定义来实现新的算法开发。

下面我们列出推荐定制的组件列表：

组件名称	基类	说明
损失	twinkle.loss.Loss	用于定义模型训练的损失函数
指标	twinkle.metric.Metric	用于定义模型训练的评价体系
Optimizer/LRScheduler	基于PyTorch	用于定义模型训练的优化器和LR衰减器
补丁	twinkle.patch.Patch	用于修复模型训练过程中的问题
预处理器	twinkle.preprocessor.Preprocessor	用于对数据进行预处理（ETL），并返回 Template 可用的标准格式
过滤器	twinkle.preprocessor.Filter	用于对原始数据进行合理性过滤
任务数据处理器	twinkle.processor.InputProcessor	用于将模型输入转换为各任务需要的数据，并添加额外字段
模型	twinkle.model.TwinkleModel	大模型本身
采样器	twinkle.sampler.Sampler	采样器，例如 vLLM
奖励	twinkle.reward.Reward	用于实现不同 RL 训练的奖励
优势	twinkle.advantage.Advantage	用于实现不同 RL 训练的优势估计
模板	twinkle.template.Template	用于处理标准输入，并转换成模型需要的 token
权重同步	twinkle.checkpoint_engine.CheckpointEngine	用于 RL 训练中的权重同步

未在上表中列出的组件，如Dataset、DataLoader等也可以实现定制，只需要跟随基类API设计即可。

DeviceGroup 和 DeviceMesh

DeviceGroup 和 DeviceMesh 是 Twinkle 架构的核心。所有的代码构建均基于这两个设计。

import twinkle
from twinkle import DeviceMesh, DeviceGroup
device_group = [
 DeviceGroup(
 name='default',
 ranks=8,
 device_type='cuda',
 )
 ]

device_mesh = DeviceMesh.from_sizes(pp_size=2, tp_size=2, dp_size=2)
twinkle.initialize(mode='ray', nproc_per_node=8, groups=device_group)

当 device_group 定义完成后，需要使用 twinkle.initialize 来初始化资源。

DeviceGroup：定义本次训练需要多少个资源组。定义后，组件可以通过选择资源组的方式将自己运行在远端：

from twinkle.model import TransformersModel
model = TransformersModel(model_id='ms://Qwen/Qwen3.5-4B', remote_group='default', device_mesh=device_mesh)
# 或者
from twinkle.model import MegatronModel
model = MegatronModel(model_id='ms://Qwen/Qwen3.5-4B', remote_group='default', device_mesh=device_mesh)

DeviceMesh 指定了模型等组件在资源组中的拓扑结构。可以理解为如何进行并行。这会影响一系列的框架决策，例如数据获取、数据消费、数据返回等。

使用样例

from peft import LoraConfig
import twinkle
from twinkle import DeviceMesh, DeviceGroup
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.model import TransformersModel
from twinkle.preprocessor import SelfCognitionProcessor

device_group = [DeviceGroup(name='default',ranks=8,device_type='cuda')]
device_mesh = DeviceMesh.from_sizes(fsdp_size=4, dp_size=2)
# local for torchrun
twinkle.initialize(mode='ray', groups=device_group, global_device_mesh=device_mesh)


def train():
 # 1000 samples
 dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(1000)))
 # Set template to prepare encoding
 dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B')
 # Preprocess the dataset to standard format
 dataset.map(SelfCognitionProcessor('twinkle大模型', 'ModelScope社区'))
 # Encode dataset
 dataset.encode()
 # Global batch size = 8, for GPUs, so 1 sample per GPU
 dataloader = DataLoader(dataset=dataset, batch_size=8, min_batch_size=8)
 # Use a TransformersModel
 model = TransformersModel(model_id='ms://Qwen/Qwen3.5-4B', remote_group='default')

 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_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))
 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)
 print(f'Current is step {step} of {len(dataloader)}, metric: {metric}')
 model.save(f'last-checkpoint')


if __name__ == '__main__':
 train()

这样启动训练：

python3 train.py

Twinkle安装

Mon, 01 Jan 0001 00:00:00 +0000

Wheel包安装

可以使用pip进行安装：

pip install 'twinkle-kit'

源代码安装

git clone https://github.com/modelscope/twinkle.git
cd twinkle
pip install -e .

Docker 镜像

你也可以使用我们的预构建 Docker 镜像：

modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:twinkle-0.3.0

客户端安装

如果你需要使用 Twinkle 的 Client 进行远程训练，可以使用我们的一键安装脚本：

# Mac or Linux
sh INSTALL_CLIENT.sh
# Windows, Open with PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\INSTALL_CLIENT.ps1

这个脚本会下载或利用 conda，创建一个叫 twinkle-client 的虚拟环境，这个环境可以直接用于远端训练。

Megatron 依赖安装

如果你需要安装 Megatron 相关依赖，可以使用如下脚本：

sh INSTALL_MEGATRON.sh

支持的硬件

硬件环境	备注
GPU A10/A100/H100/RTX系列等
GPU T4/V100等	不支持bfloat16、Flash-Attention
Ascend NPU	部分算子不支持
PPU	支持
CPU	支持dataset、dataloader等部分组件

NPU（昇腾）开箱指南

Mon, 01 Jan 0001 00:00:00 +0000

本文档介绍如何在华为昇腾 NPU 环境下安装和使用 Twinkle 框架。

环境要求

在开始之前，请确保您的系统满足以下要求：

组件	版本要求	说明
Python	>= 3.11, < 3.13	Twinkle 框架要求
昇腾固件驱动（HDK）	推荐最新版本	硬件驱动和固件
CANN 工具包	8.5.1 或更高	异构计算架构
PyTorch	2.7.1	深度学习框架
torch_npu	2.7.1	昇腾 PyTorch 适配插件

重要说明：

torch 和 torch_npu 版本必须完全一致（例如都为 2.7.1）
推荐使用 Python 3.11 以获得最佳兼容性
CANN 工具包需要约 10GB+ 磁盘空间

支持的硬件

Twinkle 当前支持以下昇腾 NPU 设备：

昇腾 910 系列
其他兼容的昇腾加速卡

安装步骤

1. 安装 NPU 环境（驱动、CANN、torch_npu）

NPU 环境的安装包括昇腾驱动、CANN 工具包、PyTorch 和 torch_npu。

📖 完整安装教程：

该文档包含：

昇腾驱动（HDK）安装步骤
CANN 工具包安装步骤
PyTorch 和 torch_npu 安装步骤
版本配套说明

推荐版本配置：

Python: 3.11
PyTorch: 2.7.1
torch_npu: 2.7.1
CANN: 8.5.1 或更高

2. 安装 Twinkle

NPU 环境配置完成后，从源码安装 Twinkle 框架：

git clone https://github.com/modelscope/twinkle.git
cd twinkle
pip install -e ".[transformers,ray]"

3. 安装 vLLM 和 vLLM-Ascend（可选）

如果需要使用 vLLMSampler 进行高效推理，可以安装 vLLM 和 vLLM-Ascend。

安装步骤：

# 第一步：安装 vLLM
pip install vllm==0.14.0

# 第二步：安装 vLLM-Ascend
pip install vllm-ascend==0.14.0rc1

注意事项：

按照上述顺序安装，忽略可能的依赖冲突提示
安装前确保已激活 CANN 环境：source /usr/local/Ascend/ascend-toolkit/set_env.sh
推荐使用的版本为 vLLM 0.14.0 和 vLLM-Ascend 0.14.0rc1

4. 验证安装

创建测试脚本 verify_npu.py：

import torch
import torch_npu

print(f"PyTorch version: {torch.__version__}")
print(f"torch_npu version: {torch_npu.__version__}")
print(f"NPU available: {torch.npu.is_available()}")
print(f"NPU device count: {torch.npu.device_count()}")

if torch.npu.is_available():
 print(f"Current NPU device: {torch.npu.current_device()}")
 print(f"NPU device name: {torch.npu.get_device_name(0)}")

 # 简单测试
 x = torch.randn(3, 3).npu()
 y = torch.randn(3, 3).npu()
 z = x + y
 print(f"NPU computation test passed: {z.shape}")

运行验证：

python verify_npu.py

如果输出显示 NPU available: True 且没有报错，说明安装成功！

注意：目前 Twinkle 暂未提供 NPU 的 Docker 镜像，建议使用手动安装方式。如需容器化部署，请参考昇腾社区的官方镜像。

5. 安装 Megatron 后端依赖

推荐组合：

Megatron-LM: v0.15.3
MindSpeed: core_r0.15.3
mcore-bridge: 主分支或当前 Twinkle 验证过的版本

安装步骤：

# 1. 获取 Megatron-LM，并切到 Twinkle 兼容版本
git clone https://github.com/NVIDIA/Megatron-LM.git
cd Megatron-LM
git checkout v0.15.3
cd ..

# 2. 获取并安装 MindSpeed
git clone https://gitcode.com/Ascend/MindSpeed.git
cd MindSpeed
git checkout core_r0.15.3
pip install -e .
cd ..

# 3. 获取并安装 mcore-bridge
git clone https://github.com/modelscope/mcore-bridge.git
cd mcore-bridge
pip install -e .
cd ..

# 4. 安装 Twinkle（如果还没有安装）
cd twinkle
pip install -e ".[transformers,ray]"

运行前环境变量：

export PYTHONPATH=$PYTHONPATH:<path/to/Megatron-LM>
export MEGATRON_LM_PATH=</path/to/Megatron-LM>
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7

验证方式：

先跑一个最小导入检查，确认 MindSpeed / Megatron-LM 可以被当前环境找到：

python -c "import mindspeed.megatron_adaptor; from twinkle.model.megatron._mindspeed_runtime import ensure_mindspeed_adaptor_patched; ensure_mindspeed_adaptor_patched(); print('✓ Megatron backend imports are ready')"

6. Qwen3.5/3.6 FLA 与 Triton-Ascend 版本配套

FLA 开启条件

Qwen3.5/3.6 在 transformers 后端使用 FLA（Flash Linear Attention）时，需要满足以下条件：

安装 triton-ascend
mindspeed 版本为 26.0.0_core_r0.12.1

Triton-Ascend 版本与 CANN 配套

triton-ascend	CANN	额外依赖
3.2.0	8.5.x	不需要安装 `triton`
3.2.1	9.0.0	需要安装 `triton`

MindSpeed 版本与代码适配

当前验证的 MindSpeed 版本为 26.0.0_core_r0.12.1。MindSpeed 代码仓地址：

如使用更高版本 MindSpeed，需注意 src/twinkle/kernel/chunk_gated_delta_rule.py 中的以下导入路径可能需要对应 MindSpeed 实际代码位置进行修改：

from mindspeed.lite.ops.triton.chunk_delta_h import chunk_gated_delta_rule_bwd_dhu, chunk_gated_delta_rule_fwd_h
from mindspeed.lite.ops.triton.chunk_o import chunk_bwd_dqkwg, chunk_bwd_dv_local, chunk_fwd_o
from mindspeed.lite.ops.triton.chunk_scaled_dot_kkt import chunk_scaled_dot_kkt_fwd
from mindspeed.lite.ops.triton.cumsum import chunk_local_cumsum
from mindspeed.lite.ops.triton.solve_tril import solve_tril
from mindspeed.lite.ops.triton.utils import autocast_custom_bwd, autocast_custom_fwd, input_guard
from mindspeed.lite.ops.triton.wy_fast import prepare_wy_repr_bwd, recompute_w_u_fwd

7. NPU Patch 环境变量配置

Twinkle 在 NPU 环境下默认启用模型层补丁，可通过以下环境变量进行细粒度控制：

环境变量	说明	默认值
`TWINKLE_NPU_PATCH`	所有 NPU 优化的总开关	`1`（启用）
`TWINKLE_NPU_FUSED_OPS`	启用融合算子（RMSNorm、RoPE、SwiGLU、SDPA）	`1`（启用）
`TWINKLE_NPU_MOE_PATCH`	启用 MoE Grouped MatMul	`1`（启用）
`TWINKLE_NPU_FLA`	启用 Qwen3.5 Flash Linear Attention；设为 `0` 强制回退到 torch 实现	`1`（启用）

使用示例：

# 关闭所有 NPU 优化，回退到 Transformers 原生实现
export TWINKLE_NPU_PATCH=0

# 仅关闭 FLA，保留其他融合算子
export TWINKLE_NPU_FLA=0

# 仅关闭 MoE 补丁
export TWINKLE_NPU_MOE_PATCH=0

快速开始

重要提示：以下示例均来自 cookbook/ 目录，已在实际 NPU 环境中验证通过。建议直接运行 cookbook 中的脚本，而不是复制粘贴代码片段。

SFT LoRA 微调

当前 NPU 文档不再提供这类 SFT cookbook 示例；这部分能力需要结合实际可用的 cookbook 示例或后续补充的 NPU 脚本来说明。

GRPO 强化学习训练

当前 NPU 文档不再提供这类 GRPO cookbook 示例；这部分能力需要结合实际可用的 cookbook 示例或后续补充的 NPU 脚本来说明。

并行策略

Twinkle 在 NPU 上目前支持以下经过验证的并行策略：

并行类型	说明	NPU 支持	验证状态
DP (Data Parallel)	数据并行	✅	暂无对应 cookbook 示例
FSDP (Fully Sharded Data Parallel)	完全分片数据并行	✅	暂无对应 cookbook 示例
TP (Tensor Parallel)	张量并行（Megatron）	✅	已验证（见 `cookbook/megatron/ascend/tp_npu.py`）
PP (Pipeline Parallel)	流水线并行（Megatron）	✅	已验证（见 `cookbook/megatron/ascend/tp_npu.py`）
CP (Context Parallel)	上下文并行	✅	已验证（见 `cookbook/megatron/ascend/tp_moe_cp_npu.py`）
EP (Expert Parallel)	专家并行（MoE）	✅	已验证（见 `cookbook/megatron/ascend/tp_moe_npu.py`）

图例说明：

✅ 已验证：有实际运行示例代码
🚧 待验证：理论上支持但暂无 NPU 验证示例
❌ 不支持：当前版本不可用

DP + FSDP 示例

当前 NPU 文档暂不提供对应的 cookbook 代码片段。

Megatron 后端说明：Twinkle 的 Megatron NPU 路径已经提供了可直接运行的 smoke 示例，安装和运行依赖请参考上面的 “Megatron 后端依赖” 小节。当前优先建议先验证 cookbook/megatron/ascend/tp_npu.py，再逐步切到 cookbook/megatron/ascend/tp_moe_npu.py 和 cookbook/megatron/ascend/tp_moe_cp_npu.py。

常见问题

1. torch_npu 版本不匹配

问题：安装 torch_npu 后出现版本不兼容警告或错误。

解决方案：

确保 torch 和 torch_npu 版本完全一致
检查 CANN 版本是否与 torch_npu 兼容

# 查看当前版本
python -c "import torch; import torch_npu; print(torch.__version__, torch_npu.__version__)"

# 重新安装匹配版本
pip uninstall torch torch_npu -y
pip install torch==2.7.1
pip install torch_npu-2.7.1-cp311-cp311-linux_aarch64.whl

2. CANN 工具包版本问题

问题：CANN 版本与 torch_npu 不兼容。

解决方案：

参考
安装对应版本的 CANN 工具包

功能支持情况

基于实际代码验证的功能支持矩阵：

功能	GPU	NPU	验证示例	说明
SFT + LoRA	✅	✅	-	暂无对应 cookbook 示例
GRPO	✅	✅	-	暂无对应 cookbook 示例
DP 并行	✅	✅	-	暂无对应 cookbook 示例
FSDP 并行	✅	✅	-	暂无对应 cookbook 示例
Ray 分布式	✅	✅	-	暂无对应 cookbook 示例
TorchSampler	✅	✅	-	暂无对应 cookbook 示例
vLLMSampler	✅	✅	-	暂无对应 cookbook 示例
全量微调	✅	✅	-	已验证可用
QLoRA	✅	❌	-	量化算子暂不支持
DPO	✅	🚧	-	理论支持，待验证
Megatron TP/PP	✅	🚧	-	待适配和验证
Flash Attention	✅	⚠️	-	部分算子不支持

图例说明：

✅ 已验证：有实际运行示例，确认可用
🚧 待验证：理论上支持但暂无 NPU 环境验证
⚠️ 部分支持：可用但有限制或性能差异
❌ 不支持：当前版本不可用

使用建议：

优先使用标记为“已验证”的功能，稳定性有保障
“待验证”功能可以尝试，但可能遇到兼容性问题
遇到问题时，参考对应的示例代码进行配置

示例代码

Twinkle 在 NPU 上已验证的示例目前聚焦 Megatron smoke 路径；SFT 和 GRPO cookbook 示例暂无对应文件。

远程训练（Tinker 协议）

服务端配置：
- 提供 HTTP API 接口
- 支持远程训练和推理
- 适用于生产环境部署

运行示例：暂无对应命令示例。

参考资源

获取帮助

如果您在使用过程中遇到问题：

查看日志：设置环境变量 ASCEND_GLOBAL_LOG_LEVEL=1 获取详细日志
提交 Issue：
社区讨论：

下一步

📖 阅读了解更多训练示例
📖 阅读了解其他平台的安装
🚀 浏览 cookbook/ 目录查看完整示例代码
💡 查看了解高级功能

ModelScope上的Twinkle训练服务

Mon, 01 Jan 0001 00:00:00 +0000

在 Twinkle 框架开源的同时，我们依托ModelScope的后台服务，也提供了托管的模型训练服务(Training as a Service），开发者可以通过这一服务，免费体验Twinkle的训练API。

目前在集群中运行的模型是。下面介绍具体的使用方法：

Step 1. 注册ModelScope用户并获取 API Key

开发者首先需要注册成为ModelScope用户。您也可以通过本地部署服务，来使用Twinkle✨。

注册地址：https://www.modelscope.cn/

注册后，在此页面获取访问的API-Key（即ModelScope平台的访问Token）：https://www.modelscope.cn/my/access/token 。

调用端点：base_url="https://www.modelscope.cn/twinkle"

Step 2. 查看 Cookbook 并二次定制开发

我们强烈推荐开发者查看我们的，并根据其中的训练代码进行二次开发。

样例代码：

import os
from tqdm import tqdm
from tinker import types
from twinkle_client import init_tinker_client
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.preprocessor import SelfCognitionProcessor
from twinkle.server.common import input_feature_to_datum

base_model = 'ms://Qwen/Qwen3.6-27B'
base_url='https://www.modelscope.cn/twinkle'
api_key=os.environ.get('MODELSCOPE_TOKEN')

# Use twinkle dataset to load the data
dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(500)))
dataset.set_template('Qwen3_5Template', model_id=base_model, max_length=256)
dataset.map(SelfCognitionProcessor('Twinkle Model', 'ModelScope Team'), load_from_cache_file=False)
dataset.encode(batched=True, load_from_cache_file=False)
dataloader = DataLoader(dataset=dataset, batch_size=8)

# Initialize Tinker client before importing ServiceClient
init_tinker_client()
from tinker import ServiceClient

service_client = ServiceClient(base_url=base_url, api_key=api_key)
training_client = service_client.create_lora_training_client(base_model=base_model[len('ms://'):], rank=16)

# Training loop: use input_feature_to_datum to transfer the input format
for epoch in range(2):
 for step, batch in tqdm(enumerate(dataloader)):
 input_datum = [input_feature_to_datum(input_feature) for input_feature in batch]

 fwdbwd_future = training_client.forward_backward(input_datum, "cross_entropy")
 optim_future = training_client.optim_step(types.AdamParams(learning_rate=1e-4))

 fwdbwd_result = fwdbwd_future.result()
 optim_result = optim_future.result()
 print(f'Training Metrics: {optim_result}')

 result = training_client.save_state(f"twinkle-lora-{epoch}").result()
 print(f'Saved checkpoint for epoch {epoch} to {result.path}')

通过上述代码，你可以训练一个原模型为Qwen/Qwen3.6-27B的自我认知lora。这个lora会改变模型的名称和制造者为训练时指定的名称。使用这个lora进行推理：

import os
from tinker import types

from twinkle.data_format import Message, Trajectory
from twinkle.template import Template
from twinkle import init_tinker_client

# Step 1: Initialize Tinker client
init_tinker_client()

from tinker import ServiceClient

base_model = 'Qwen/Qwen3.6-27B'
base_url = 'https://www.modelscope.cn/twinkle'

# Step 2: Define the base model and connect to the server
service_client = ServiceClient(
 base_url=base_url,
 api_key=os.environ.get('MODELSCOPE_TOKEN')
)

# Step 3: Create a sampling client by loading weights from a saved checkpoint.
# The model_path is a twinkle:// URI pointing to a previously saved LoRA checkpoint.
# The server will load the base model and apply the LoRA adapter weights.
sampling_client = service_client.create_sampling_client(
 model_path='twinkle://xxx-Qwen_Qwen3.6-35B-A3B-xxx/weights/twinkle-lora-1',
 base_model=base_model
)

# Step 4: Load the tokenizer locally to encode the prompt and decode the results
print(f'Using model {base_model}')

template = Template(model_id=f'ms://{base_model}')

trajectory = Trajectory(
 messages=[
 Message(role='system', content='You are a helpful assistant'),
 Message(role='user', content='Who are you?'),
 ]
)

input_feature = template.batch_encode([trajectory], add_generation_prompt=True)[0]

input_ids = input_feature['input_ids'].tolist()

# Step 5: Prepare the prompt and sampling parameters
prompt = types.ModelInput.from_ints(input_ids)
params = types.SamplingParams(
 max_tokens=128, # Maximum number of tokens to generate
 temperature=0.7,
 stop=['\n'] # Stop generation when a newline character is produced
)

# Step 6: Send the sampling request to the server.
# num_samples=1 generates 1 independent completions for the same prompt.
print('Sampling...')
future = sampling_client.sample(prompt=prompt, sampling_params=params, num_samples=1)
result = future.result()

# Step 7: Decode and print the generated responses
print('Responses:')
for i, seq in enumerate(result.sequences):
 print(f'{i}: {repr(template.decode(seq.tokens))}')

开发者也可以将这个lora和原模型合并之后，使用自己的服务进行部署，并使用OpenAI标准接口进行调用。

目前的服务兼容 Tinker Client，因此请使用 Tinker 的 cookbook 进行训练。后续我们会支持单服务器同时支持 Twinkle/Tinker 双客户端。

开发者可以定制数据集/优势函数/奖励/模板等，其中 Loss 部分由于需要在服务端执行，因此当前暂不支持定制（安全性原因）。如果需要支持您的额外 Loss，可以将该 Loss 实现上传到中，并在答疑群中或者中联系我们，将对应组件开放白名单即可使用。

附录：支持的训练方式

该模型为纯文本模型，因此暂不支持多模态任务。在纯文本任务中，你可以训练：

PT/SFT的常规训练方法，包含Agentic训练
GRPO/RLOO等自采样RL算法
GKD/On-policy等蒸馏方法，由于魔搭官方端仅支持单模型，因此另一个Teacher/Student模型需要开发者自行准备

当前官方环境仅支持LoRA训练，对LoRA的要求：

最大rank=32
不支持modules_to_save

Qwen3.5 训练最佳实践

Mon, 01 Jan 0001 00:00:00 +0000

本文以 Qwen3.5-4B 为例，演示 Twinkle 框架的核心能力：一套组件化代码，从单卡训练到Client-Server环境。

一、Twinkle 是什么

Twinkle 是一个面向生产的大模型训练框架。它的核心设计非常容易理解：训练逻辑用 Python 代码表达，运行模式通过初始化参数切换。

这意味着：

实验室里写的训练脚本，改一行代码就能多方式运行
全开放的算法定制能力
不需要维护多套代码来支持 torchrun、Ray、HTTP 等不同模式
算法工程师专注写训练逻辑，框架自动处理分布式通信

Twinkle 同时支持 Transformers 和 Megatron 后端，以及 多租户 LoRA 训练——多个用户共享一个基座模型，各自训练自己的适配器。

二、本地多卡训练

场景说明

本地 1~8 张 GPU/NPU 的训练场景。Twinkle 基于 PyTorch 原生接口，支持 FSDP2、DDP 等并行策略。

完整代码

from peft import LoraConfig
from tqdm import tqdm

import twinkle
from twinkle import DeviceMesh, get_device_placement, get_logger
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.model import TransformersModel
from twinkle.preprocessor import SelfCognitionProcessor

# 构造 device_mesh：fsdp=4, dp=2，共使用 8 张卡
device_mesh = DeviceMesh.from_sizes(fsdp_size=4, dp_size=2)
# 使用 torchrun 模式
twinkle.initialize(mode='local', global_device_mesh=device_mesh)

logger = get_logger()


def eval(model):
 # 验证集：100 条样本
 dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(100)))
 dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B')
 dataset.map(SelfCognitionProcessor('twinkle大模型', 'ModelScope社区'))
 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():
 # 训练集：1000 条样本
 dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(1000)))
 # 设置模板，准备编码
 dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B')
 # 数据预处理：替换自我认知数据中的占位符
 dataset.map(SelfCognitionProcessor('twinkle大模型', 'ModelScope社区'))
 # 编码数据集
 dataset.encode()
 # 全局 batch size = 8，8 张卡每张处理 1 条
 dataloader = DataLoader(dataset=dataset, batch_size=8)
 # 加载模型
 model = TransformersModel(model_id='ms://Qwen/Qwen3.5-4B')
 model.model._no_split_modules = {'Qwen3_5DecoderLayer'}

 lora_config = LoraConfig(r=8, lora_alpha=32, target_modules='all-linear')

 # 添加 LoRA 适配器，命名为 'default'
 # 注释掉这行即可切换到全参数训练
 model.add_adapter_to_model('default', lora_config, gradient_accumulation_steps=2)
 # 为 LoRA 配置优化器
 model.set_optimizer(optimizer_cls='AdamW', lr=1e-4)
 # 配置学习率调度器
 model.set_lr_scheduler(
 scheduler_cls='CosineWarmupScheduler', num_warmup_steps=5, num_training_steps=len(dataloader))
 logger.info(get_device_placement())
 # 打印训练配置
 logger.info(model.get_train_configs())
 logger.info(f'Total steps: {len(dataloader)}')
 loss_metric = 99.0
 # LoRA 训练：约 8G * 8 显存占用
 # 全参数训练：约 18G * 8 显存占用
 for step, batch in enumerate(dataloader):
 # 前向 + 反向传播
 model.forward_backward(inputs=batch)
 # 梯度裁剪 + 优化器步进
 model.clip_grad_and_step()
 if step % 20 == 0:
 # 打印训练指标
 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()

启动命令

CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 torchrun --nproc_per_node=8 fsdp2.py

关键设计说明

DeviceMesh 并行策略

device_mesh = DeviceMesh.from_sizes(fsdp_size=4, dp_size=2)

4 路 FSDP 分片 + 2 路数据并行的混合并行。Qwen3.5-4B 在 bf16 精度下权重占用约8GB，LoRA 模式下单卡显存占用大约 18GB，8 张 A100/H100 流畅跑。

梯度累积

model.add_adapter_to_model('default', lora_config, gradient_accumulation_steps=2)

gradient_accumulation_steps=2 每 2 个 micro-batch 更新一次参数，等效于 batch size 翻倍。显存受限但又想要较大 batch 时很实用。

算法过程外露

所有训练关键过程——前向、反向、梯度裁剪、检简点保存——都直接写在主循环里，开发者对训练过程有完整的控制权。底层的分布式通信由 Twinkle infra 负责，切换 Ray 还是 torchrun 对主循环并无影响。

对于复杂算法而言，这一点尤为关键。

RL 训练：Ray 模式下的强化学习实战

Twinkle 支持多种 RL 算法，包括 GRPO、RLOO、GSPO等。这里以 GRPO（Group Relative Policy Optimization）为例——它是 DeepSeek-R1 中使用的核心 RL 算法——展示如何在 Ray 模式下完成 RL 训练。

与 PPO 不同，GRPO 不需要单独训练一个价值模型，而是通过组内采样结果的相对奖励来估计优势函数，简化了训练流程并降低了显存开销。Twinkle 的 Ray 模式特别适合这类需要模型与采样器分离部署的 RL 算法。在下面的例子中，我们用 4 张卡跑模型训练，另外 4 张卡跑 vLLM 采样，两者通过 Ray 集群协调：

from typing import List, Dict, Any
from peft import LoraConfig
import twinkle
from twinkle import DeviceMesh, DeviceGroup, get_device_placement, get_logger
from twinkle.advantage import GRPOAdvantage
from twinkle.checkpoint_engine import CheckpointEngineManager
from twinkle.data_format import SamplingParams
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.model import TransformersModel
from twinkle.processor import InputProcessor
from twinkle.reward import GSM8KAccuracyReward, GSM8KFormatReward
from twinkle.sampler import vLLMSampler
from twinkle.template import Template
from twinkle.metric import CompletionRewardMetric
from twinkle.preprocessor.llm import GSM8KProcessor

logger = get_logger()

MODEL_ID = 'ms://Qwen/Qwen3.5-4B'
MODEL_GPUS = 4 # 模型训练用 4 张卡
SAMPLER_GPUS = 4 # vLLM 采样用 4 张卡
NUM_GPUS = MODEL_GPUS + SAMPLER_GPUS

NUM_GENERATIONS = 8 # 每组采样 8 个结果
MAX_NEW_TOKENS = 4096
LEARNING_RATE = 1e-5
MAX_STEPS = 200
BATCH_SIZE = 16
MINI_BATCH_SIZE = 16
MICRO_BATCH_SIZE = 2
ADAPTER_NAME = 'default'

def create_gsm8k_dataset():
 dataset = Dataset(DatasetMeta('ms://modelscope/gsm8k', subset_name='main', split='train'))
 dataset.set_template('Qwen3_5Template', model_id=MODEL_ID, max_length=2048)
 dataset.map(GSM8KProcessor())
 dataset.encode(add_generation_prompt=True)
 return dataset

def compute_rewards(trajectories: List[Dict[str, Any]]):
 accuracy_reward_fn = GSM8KAccuracyReward()
 format_reward_fn = GSM8KFormatReward()
 accuracy_rewards = accuracy_reward_fn(trajectories)
 format_rewards = format_reward_fn(trajectories)
 total_rewards = [a + f for a, f in zip(accuracy_rewards, format_rewards)]
 return total_rewards, format_rewards, accuracy_rewards

def main():
 # 模型和采样器分到不同的 GPU 组
 device_groups = [
 DeviceGroup(name='model', ranks=list(range(MODEL_GPUS)), device_type='GPU'),
 DeviceGroup(name='sampler', ranks=list(range(MODEL_GPUS, NUM_GPUS)), device_type='GPU'),
 ]
 model_mesh = DeviceMesh.from_sizes(world_size=MODEL_GPUS, dp_size=MODEL_GPUS)
 sampler_mesh = DeviceMesh.from_sizes(world_size=SAMPLER_GPUS, dp_size=SAMPLER_GPUS)

 # Ray 模式初始化
 twinkle.initialize(mode='ray', nproc_per_node=NUM_GPUS, groups=device_groups, lazy_collect=False)

 lora_config = LoraConfig(target_modules='all-linear', r=32, lora_alpha=64, lora_dropout=0.05)

 # 模型部署在 'model' 组
 model = TransformersModel(model_id=MODEL_ID, device_mesh=model_mesh, remote_group='model')
 model.add_adapter_to_model(ADAPTER_NAME, lora_config, gradient_accumulation_steps=1)
 model.set_optimizer('AdamW', lr=LEARNING_RATE)
 model.set_lr_scheduler('CosineAnnealingLR', T_max=MAX_STEPS, eta_min=0)
 model.set_loss('GRPOLoss', epsilon=0.2)
 model.set_processor(InputProcessor)
 model.set_template('Qwen3_5Template', model_id=MODEL_ID)

 # 采样器部署在 'sampler' 组
 sampler = vLLMSampler(
 model_id=MODEL_ID,
 engine_args={
 'gpu_memory_utilization': 0.8,
 'max_model_len': 4096,
 'max_lora_rank': 32,
 'enable_lora': False,
 },
 device_mesh=sampler_mesh,
 remote_group='sampler',
 )
 sampler.set_template('Qwen3_5Template', model_id=MODEL_ID)

 ckpt_manager = CheckpointEngineManager(model=model, sampler=sampler)

 dataloader = DataLoader(
 dataset=create_gsm8k_dataset,
 batch_size=BATCH_SIZE,
 min_batch_size=BATCH_SIZE,
 device_mesh=model_mesh,
 remote_group='model',
 )

 advantage_fn = GRPOAdvantage()
 metrics = CompletionRewardMetric()
 sampling_params = SamplingParams(max_tokens=MAX_NEW_TOKENS, num_samples=1, logprobs=1)

 optim_step = 0
 logger.info(get_device_placement())

 for batch in dataloader:
 if optim_step >= MAX_STEPS:
 break
 metrics.reset()
 global_prompts = batch if isinstance(batch, list) else [batch]

 # 同步权重到采样器
 ckpt_manager.sync_weights(merge_and_sync=True)
 sampler.reset_prefix_cache()

 # 组采样：每个 prompt 采样 NUM_GENERATIONS 个结果
 sample_responses = sampler.sample(
 global_prompts * NUM_GENERATIONS,
 sampling_params,
 )

 all_input_data = []
 all_old_logps = []
 all_completion_lengths = []

 for sample_response in sample_responses:
 for sequence in sample_response.sequences:
 all_input_data.append(sequence.new_input_feature)
 all_old_logps.append([logprob[0][1] for logprob in sequence.logprobs])
 all_completion_lengths.append(len(sequence.tokens))

 # 计算奖励
 total_rewards, format_rewards, accuracy_rewards = compute_rewards(all_input_data)
 metrics.accumulate(
 completion_lengths=all_completion_lengths,
 rewards={
 'total': total_rewards,
 'format': format_rewards,
 'accuracy': accuracy_rewards,
 },
 )

 # GRPO 优势估计：组内归一化
 advantages = advantage_fn(total_rewards, num_generations=NUM_GENERATIONS, scale='group').tolist()

 # Mini-batch 训练
 total_completions = len(all_input_data)
 for mb_start in range(0, total_completions, MINI_BATCH_SIZE):
 mb_end = min(mb_start + MINI_BATCH_SIZE, total_completions)
 mb_inputs = all_input_data[mb_start:mb_end]
 mb_old_logps = all_old_logps[mb_start:mb_end]
 mb_advantages = advantages[mb_start:mb_end]

 model.forward_backward(
 inputs=mb_inputs,
 old_logps=mb_old_logps,
 advantages=mb_advantages,
 micro_batch_size=MICRO_BATCH_SIZE,
 )
 model.clip_grad_and_step()
 optim_step += 1

 if optim_step >= MAX_STEPS:
 break
 log_dict = metrics.calculate()
 log_dict.update(model.calculate_metric(is_training=True))
 metrics.reset()
 logger.info(f'[Step {optim_step}/{MAX_STEPS}] {log_dict}')

 logger.info(f'Training completed. optim_steps={optim_step}')
 model.save('grpo-gsm8k-checkpoint')

if __name__ == '__main__':
 main()

由于是Ray集群运行，所以启动只需要：

python train.py

GRPO 训练的关键设计：

模型与采样器分离：DeviceGroup 将 8 张卡分成两组，训练和采样互不干扰，采样流程可充分利用 vLLM 的高吞吐
组采样策略：global_prompts * NUM_GENERATIONS 让每个问题采样多个结果，通过组内相对奖励估计优势——不需要单独训练价值模型
权重同步：ckpt_manager.sync_weights() 在每次采样前将训练模型权重同步到 vLLM，确保采样始终使用最新策略
算法组件外露：GRPOAdvantage 和 GRPOLoss 直接注册到模型，可替换为其他 RL 算法组件而不需修改其他任何代码

这种写法的核心价值在于：整个 RL 训练流程——采样、奖励计算、优势估计、梯度更新——都展开在可见的 Python 主循环里，没有隐藏的魔法。不同 RL 算法的差异，往往只在于替换几个组件。

三、远程训练：Client-Server 架构

当算力资源和服务消费方分离时——企业内部训推平台、云服务商的 Serverless 训练服务——就需要把训练能力以 API 形式暴露出来。

Twinkle 支持两种 Client 接入方式：

Twinkle Client：和本地训练 API 完全一致，适合需要精细控制的场景
Tinker Client：兼容生态，调用方式更简洁

服务端只维护一份基座模型，多个客户端可并行训练各自的 LoRA 适配器。

3.1 Twinkle Client：细粒度控制

Twinkle Client 提供与本地训练几乎完全一致的 API，适合需要精细控制训练流程的场景。

import dotenv
dotenv.load_dotenv('.env')

from peft import LoraConfig

from twinkle import get_logger
from twinkle.dataset import DatasetMeta
from twinkle_client import init_twinkle_client
from twinkle_client.dataloader import DataLoader
from twinkle_client.dataset import Dataset
from twinkle_client.model import MultiLoraTransformersModel

logger = get_logger()

# 初始化 Twinkle 客户端
client = init_twinkle_client(base_url='http://127.0.0.1:8000', api_key='EMPTY_TOKEN')

# 查询已有训练运行和检查点
runs = client.list_training_runs()
resume_path = None
for run in runs:
 logger.info(run.model_dump_json(indent=2))
 checkpoints = client.list_checkpoints(run.training_run_id)
 for checkpoint in checkpoints:
 logger.info(checkpoint.model_dump_json(indent=2))
 # 如需恢复训练，取消下面注释
 # resume_path = checkpoint.twinkle_path


def train():
 # 准备数据集
 dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(500)))
 dataset.set_template('Qwen3_5Template', model_id='ms://Qwen/Qwen3.5-4B', max_length=512)
 dataset.map('SelfCognitionProcessor', init_args={'model_name': 'twinkle模型', 'model_author': 'ModelScope社区'})
 dataset.encode(batched=True)
 dataloader = DataLoader(dataset=dataset, batch_size=4)

 # 配置模型
 model = MultiLoraTransformersModel(model_id='ms://Qwen/Qwen3.5-4B')

 lora_config = LoraConfig(target_modules='all-linear')
 model.add_adapter_to_model('default', lora_config, gradient_accumulation_steps=2)
 model.set_template('Qwen3_5Template')
 model.set_processor('InputProcessor', padding_side='right')
 model.set_loss('CrossEntropyLoss')
 model.set_optimizer('AdamW', lr=1e-4)
 model.set_lr_scheduler('LinearLR')

 # 恢复训练（如有检查点）
 if resume_path:
 logger.info(f'Resuming training from {resume_path}')
 model.load(resume_path, load_optimizer=True)

 logger.info(model.get_train_configs())

 for epoch in range(3):
 logger.info(f'Starting epoch {epoch}')
 for step, batch in enumerate(dataloader):
 # 前向 + 反向
 output = model.forward_backward(inputs=batch)

 if step % 2 == 0:
 logger.info(f'Current is step {step // 2}, loss: {output}')

 model.clip_grad_norm(1.0)
 model.step()
 model.zero_grad()
 model.lr_step()

 # 保存检查点
 twinkle_path = model.save(name=f'twinkle-epoch-{epoch}', save_optimizer=True)
 logger.info(f'Saved checkpoint: {twinkle_path}')


if __name__ == '__main__':
 train()

Twinkle Client 的特点：

API 与本地训练完全一致，无额外学习成本
支持断点续训、检查点管理
可动态切换 LoRA 适配器、损失函数、优化器等组件

3.2 Tinker Client：简洁即用

Tinker 是一个轻量级训练 API。Twinkle 对 Tinker 客户端提供完整支持，几行代码就能拉起训练。已有 Tinker 代码的项目可以直接迎移到 Twinkle 服务端。

import os
from tinker import types
from tqdm import tqdm

from twinkle import init_tinker_client
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.preprocessor import SelfCognitionProcessor
from twinkle.server.common import input_feature_to_datum

# 初始化 Tinker 客户端（必须在导入 ServiceClient 之前）
init_tinker_client()

from tinker import ServiceClient

# 基座模型
base_model = 'Qwen/Qwen3.5-4B'
base_url = 'http://www.modelscope.cn/twinkle'


def train():
 # 准备数据集
 dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(500)))
 dataset.set_template('Qwen3_5Template', model_id=f'ms://{base_model}', max_length=256)
 dataset.map(SelfCognitionProcessor('Twinkle模型', 'ModelScope团队'), load_from_cache_file=False)
 dataset.encode(batched=True, load_from_cache_file=False)
 dataloader = DataLoader(dataset=dataset, batch_size=8)

 # 初始化训练客户端
 service_client = ServiceClient(
 base_url=base_url,
 api_key=os.environ.get('MODELSCOPE_TOKEN')
 )
 training_client = service_client.create_lora_training_client(base_model=base_model, rank=16)

 # 训练循环
 for epoch in range(3):
 print(f'Epoch {epoch}')
 for step, batch in tqdm(enumerate(dataloader)):
 # 转换输入格式
 input_datum = [input_feature_to_datum(input_feature) for input_feature in batch]

 # 远端前向 + 反向
 fwdbwd_future = training_client.forward_backward(input_datum, 'cross_entropy')
 # 远端优化器步进
 optim_future = training_client.optim_step(types.AdamParams(learning_rate=1e-4))

 # 等待结果
 fwdbwd_result = fwdbwd_future.result()
 optim_result = optim_future.result()
 print(f'Training Metrics: {optim_result}')

 # 保存检查点
 save_future = training_client.save_state(f'twinkle-lora-{epoch}')
 save_result = save_future.result()
 print(f'Saved checkpoint to {save_result.path}')


if __name__ == '__main__':
 train()

Tinker Client 的特点：

调用方式极简，适合快速上手
完全兼容 Tinker 生态，已有代码可无缝迁移
支持魔搭官方训练环境（见下文）

3.3 魔搭官方训练环境

Twinkle 框架开源的同时，魔搭社区依托自身算力基础设施，提供了托管的模型训练服务（Training as a Service）。开发者无需准备 GPU 资源，通过 API 调用即可免费体验 Twinkle 的训练能力。

使用方式：

注册魔搭账号：
在获取 API Key
使用上面的 Tinker Client 代码，修改 endpoint：

base_url = 'https://www.modelscope.cn/twinkle'
base_model = 'Qwen/Qwen3.5-4B' # 官方环境当前部署的模型

四、如何选择适合你的训练方式

场景	推荐方案	核心优势
本地实验调试	单卡 / torchrun	代码即配置，调试效率高
大规模分布式训练	torchrun + FSDP2 / Ray	原生并行性能，生产就绪
企业内部训推平台	Twinkle Client + 自托管服务	多租户隔离，细粒度控制
快速验证想法	Tinker Client + 魔搭官方环境	零资源准备，即开即用
已有 Tinker 生态	Tinker Client	无缝迁移，生态兼容

选型建议：

如果你是算法研究员，需要频繁调整训练流程，从 torchrun 模式开始，验证完成后再考虑是否服务化
如果你是平台开发者，需要为企业内部提供训练服务，部署 Twinkle Server，根据用户习惯提供 Twinkle Client 或 Tinker Client 两种接入方式
如果你只是想快速体验 Twinkle 的能力，直接用魔搭官方环境，5 分钟跑通第一个训练任务

Twinkle 的设计哲学是不替你做决定，但给你足够的选择空间。无论是追求极致性能的大规模训练，还是追求极致便捷的 API 调用，都能找到合适的解法。

Embedding 模型训练

Mon, 01 Jan 0001 00:00:00 +0000

Twinkle 支持基于 InfoNCE 损失的对比学习 Embedding 模型训练，内置 in-batch negatives 和跨 rank 聚合。本文介绍如何使用 Twinkle 训练 Embedding 模型。

概述

Embedding 训练使用以下核心组件：

组件	职责
`InfonceLoss`	对比损失，支持 in-batch negatives
`EmbeddingMetric`	追踪正/负对相似度和损失
`TransformersModel`	可训练的 Embedding 模型（LoRA 或全参）
`InputProcessor`	将 anchor/positive 对处理为特征

数据格式

每个训练样本由 (anchor, positive) 对组成。在 Embedding 特征张量中：

embeddings: [anchor_0, positive_0, anchor_1, positive_1, ...]
labels: [ 1, 0, 1, 0, ...]

labels=1 标记新分组的起始位置（anchor）
labels=0 标记组内的 positive/negative

基础 Embedding 训练

使用 DDP 的最小化 Embedding 训练脚本：

import twinkle
from twinkle import DeviceGroup, DeviceMesh, get_logger
from twinkle.dataloader import DataLoader
from twinkle.loss import InfonceLoss
from twinkle.metric import EmbeddingMetric
from twinkle.model import TransformersModel
from twinkle.processor import InputProcessor
from twinkle.template import Qwen3_5Template

logger = get_logger()

# --- 配置 ---
MODEL_ID = 'ms://Qwen/Qwen3.5-4B'
MODEL_GPUS = 4
BATCH_SIZE = 32
LEARNING_RATE = 1e-5
TEMPERATURE = 0.07
EMB_MAX_LENGTH = 8192

# --- 初始化 ---
device_groups = [
 DeviceGroup(name='model', ranks=list(range(MODEL_GPUS)), device_type='GPU'),
]
model_mesh = DeviceMesh.from_sizes(world_size=MODEL_GPUS, dp_size=MODEL_GPUS)
twinkle.initialize(mode='ray', nproc_per_node=MODEL_GPUS, groups=device_groups)

# --- 模型 ---
model = TransformersModel(
 model_id=MODEL_ID,
 device_mesh=model_mesh,
 remote_group='model',
 ddp_config={'find_unused_parameters': True},
)
model.set_processor(InputProcessor)
model.set_loss(InfonceLoss, temperature=TEMPERATURE, use_batch=True)
model.set_optimizer(optimizer_cls='AdamW', lr=LEARNING_RATE)
model.set_lr_scheduler(
 scheduler_cls='CosineWarmupScheduler',
 num_warmup_steps=200,
 num_training_steps=total_steps,
)
model.add_metric(EmbeddingMetric, is_training=True)

# --- 模板 ---
template = Qwen3_5Template(
 model_id=MODEL_ID,
 max_length=EMB_MAX_LENGTH,
 enable_thinking=False,
)

# --- 训练循环 ---
for step, batch in enumerate(dataloader):
 # batch: 包含 anchor/positive 对的特征列表
 model.forward_backward(inputs=batch, task='embedding')
 model.clip_grad_and_step(gradient_accumulation_steps=1)

 if step % 10 == 0:
 metric = model.calculate_metric(is_training=True)
 logger.info(f'Step {step}: {metric}')

关键参数

参数	推荐值	说明
`temperature`	0.05–0.1	越低对比越尖锐；0.07 保持梯度流动直至 cosine > 0.75
`use_batch`	True	启用跨样本 in-batch negatives 提升效率
`hard_negatives`	None 或 7	固定每样本负例数量；None 使用全部 in-batch
`find_unused_parameters`	True	Embedding 模型必需（仅最后隐藏状态产生梯度）

监控指标

EmbeddingMetric 报告关键训练信号：

指标	含义
`pos_sim`	anchor-positive 平均余弦相似度（目标 > 0.8）
`neg_sim`	anchor-negative 平均相似度（目标 < 0.3）
`loss`	InfoNCE 损失值
`grad_norm`	梯度范数

健康的训练表现为 pos_sim 持续上升、neg_sim 稳定或下降。如果 pos_sim 过早饱和至 1.0 附近，应降低 temperature。

使用指引 | Twinkle

训练指南

✨ Twinkle 是什么？

Twinkle 适配性

何时选择 Twinkle

何时选择ms-swift

模型训练与Twinkle

使用模式

仅使用部分组件

单GPU

torchrun

断点续训

Ray训练

远程训练

使用魔搭社区提供的TaaS化训练服务

使用 Hugging Face 的模型

🛠️ Twinkle✨ 模块化生态系统

Twinkle 的可定制组件

DeviceGroup 和 DeviceMesh

使用样例

Twinkle安装

Wheel包安装

源代码安装

Docker 镜像

客户端安装

Megatron 依赖安装

支持的硬件

NPU（昇腾）开箱指南

环境要求

支持的硬件

安装步骤

1. 安装 NPU 环境（驱动、CANN、torch_npu）

2. 安装 Twinkle

3. 安装 vLLM 和 vLLM-Ascend（可选）

4. 验证安装

5. 安装 Megatron 后端依赖

6. Qwen3.5/3.6 FLA 与 Triton-Ascend 版本配套

7. NPU Patch 环境变量配置

快速开始

SFT LoRA 微调

GRPO 强化学习训练

更多示例

并行策略

DP + FSDP 示例

常见问题

1. torch_npu 版本不匹配

2. CANN 工具包版本问题

功能支持情况

示例代码

远程训练（Tinker 协议）

参考资源

获取帮助

下一步

ModelScope上的Twinkle训练服务

Step 1. 注册ModelScope用户并获取 API Key

Step 2. 查看 Cookbook 并二次定制开发

附录：支持的训练方式

Qwen3.5 训练最佳实践

一、Twinkle 是什么

二、本地多卡训练

场景说明

完整代码

启动命令

关键设计说明

RL 训练：Ray 模式下的强化学习实战

三、远程训练：Client-Server 架构

3.1 Twinkle Client：细粒度控制

3.2 Tinker Client：简洁即用

3.3 魔搭官方训练环境

四、如何选择适合你的训练方式

Embedding 模型训练

概述

数据格式

基础 Embedding 训练

关键参数

监控指标