twinkle-kit 0.0.1__tar.gz

twinkle_kit-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

twinkle_kit-0.0.1/PKG-INFO

@@ -0,0 +1,411 @@
+Metadata-Version: 2.4
+Name: twinkle-kit
+Version: 0.0.1
+Summary: Training API for large language models with efficient data handling and advanced optimization techniques.
+Author-email: ModelScope <contact@modelscope.cn>
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: datasets<4.0,>=3.0
+Requires-Dist: numpy!=2.4.0,<3.0.0,>=2.0.0
+Requires-Dist: omegaconf<3.0.0,>=2.3.0
+Requires-Dist: fastapi
+Requires-Dist: modelscope[framework]>=1.34.0
+Requires-Dist: safetensors
+Requires-Dist: peft<=0.19.0,>=0.11.0
+Requires-Dist: transformers
+Provides-Extra: transformers
+Requires-Dist: accelerate; extra == "transformers"
+Requires-Dist: torch<3.0.0,>=2.6.0; extra == "transformers"
+Requires-Dist: torchvision; extra == "transformers"
+Provides-Extra: kernels
+Requires-Dist: kernels; extra == "kernels"
+Provides-Extra: megatron
+Requires-Dist: megatron-core>=0.12.0; extra == "megatron"
+Requires-Dist: transformer-engine[pytorch]; extra == "megatron"
+Provides-Extra: vllm
+Requires-Dist: vllm>=0.11; extra == "vllm"
+Provides-Extra: ray
+Requires-Dist: ray[serve]; extra == "ray"
+Provides-Extra: docs
+Requires-Dist: sphinx<6.0.0,>=5.3.0; extra == "docs"
+Requires-Dist: docutils<0.17.0,>=0.16.0; extra == "docs"
+Requires-Dist: myst_parser; extra == "docs"
+Requires-Dist: recommonmark; extra == "docs"
+Requires-Dist: sphinx-book-theme; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx_markdown_tables; extra == "docs"
+Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
+Dynamic: license-file
+
+<h1 align="center">Twinkle: Training workbench to make your model glow</h1>
+
+<p align="center">
+    <img src="assets/slogan.png" width="200"/>
+<p>
+<p align="center">
+by <a href="https://modelscope.cn/home">ModelScope</a>
+<br>
+        English&nbsp ｜ &nbsp<a href="README_ZH.md">中文</a>&nbsp
+</p>
+
+<p align="center">
+<img src="https://img.shields.io/badge/python-3.11-5be.svg">
+<img src="https://img.shields.io/badge/pytorch-%E2%89%A52.0-orange.svg">
+<a href="https://pypi.org/project/twinkle/"><img src="https://badge.fury.io/py/twinkle.svg"></a>
+<a href="https://github.com/modelscope/twinkle/blob/main/LICENSE"><img src="https://img.shields.io/github/license/modelscope/twinkle"></a>
+<a href="https://pepy.tech/project/twinkle-kit"><img src="https://pepy.tech/badge/twinkle-kit"></a>
+<a href="https://github.com/modelscope/twinkle/pulls"><img src="https://img.shields.io/badge/PR-welcome-55EB99.svg"></a>
+</p>
+
+<p align="center">
+        <a href="https://twinkle-kit.readthedocs.io/en/latest/">English Documentation</a> &nbsp ｜ &nbsp <a href="https://twinkle-kit.readthedocs.io/zh-cn/latest/">中文文档</a> &nbsp
+</p>
+
+## ✨ What is Twinkle?
+
+Twinkle✨ is a lightweight, client-server training framework engineered
+with modular, high-cohesion interfaces. Whether you are executing locally
+with `torchrun`, or scaling training across Ray clusters,
+Twinkle✨ eliminates infrastructure friction by encapsulating
+training logic into standardized APIs. Beyond simple
+abstraction, Twinkle✨ serves as a robust backend and gateway to enable serverless Training-as-a-Service (TaaS).
+It offers interfaces that constitute a _superset_ of  [Tinker](https://thinkingmachines.ai/tinker/) APIs,
+thereby making it possible to access a Twinkle✨ training service via Tinker client or native Twinkle✨ client
+which offers more functionalities.
+
+🧩 <b>Decoupled Architecture</b>: Standardized Interfaces, backward compatible with Tinker APIs.<br>
+🚀 <b>Multiple Runtime Modes</b>: torchrun / Ray / HTTP.<br>
+🔌 <b>Versatile Backends</b>: Transformers / Megatron.<br>
+👥 <b>Multi-Tenancy Training Service</b>: Train multiple LoRAs that share one base model deployment.<br>
+
+Note: Twinkle✨is built by the team behind [ms-swift](https://github.com/modelscope/ms-swift), and
+we expect the two projects to evolve together. We expect some fundamental components in Twinkle✨will likely
+be reused in [ms-swift](https://github.com/modelscope/ms-swift).
+
+|                  Twinkle Wechat Group                  |
+|:------------------------------------------------------:|
+| <img src="assets/wechat.jpg" width="200" height="200"> |
+
+## Installation
+
+### Install with package:
+
+```shell
+pip install 'twinkle-kit'
+```
+
+### Install from Source:
+
+```shell
+git clone https://github.com/modelscope/twinkle.git
+cd twinkle
+pip install -e .
+```
+
+## Tutorials
+
+| Training Type                     | Model Framework | Cookbook Path                                     |
+| --------------------------------- | --------------- | ------------------------------------------------- |
+| FSDP finetuning                   | transformers    | [Script](cookbook/transformers/fsdp2.py)             |
+| FSDP MoE finetuning               | transformers    | [Script](cookbook/transformers/fsdp2_moe.py)         |
+| ep FSDP MoE finetuning            | transformers    | [Script](cookbook/transformers/ep_fsdp_qwen3_moe.py) |
+| sp FSDP finetuning                | transformers    | [Script](cookbook/transformers/sp_fsdp_dense.py)     |
+| EP MoE finetuning                 | transformers    | [Script](cookbook/transformers/ep_fsdp_qwen3_moe.py) |
+| pp/tp/cp finetuning               | megatron        | [Script](cookbook/megatron/tp.py)                    |
+| pp/tp/cp MoE finetuning           | megatron        | [Script](cookbook/megatron/tp_moe.py)                |
+| tinker client finetuning          | megatron        | [Script](cookbook/client/tinker/megatron)            |
+| tinker client finetuning/sampling | transformers    | [Script](cookbook/client/tinker/transformer)         |
+| twinkle client finetuning         | megatron        | [Script](cookbook/client/twinkle/megatron)           |
+| twinkle client finetuning         | transformer     | [Script](cookbook/client/twinkle/transformer)        |
+
+## Changelog
+
+- 🎉2026-02-13 Initial version of Twinkle✨ released, including SFT/PT/RL support for text models and serverless training capabilities on [ModelScope](https://modelscope.cn).
+
+## Training as a Service on ModelScope
+
+We are rolling out training service built atop Twinkle✨ on ModelScope. It is currently in _Beta_. You may
+sign up for free access by joining the [Twinkle-Explorers](https://modelscope.cn/organization/twinkle-explorers) organization, and
+train via API endpoint  `base_url=https://www.modelscope.cn/twinkle`. For more details, please refer to
+our [documentation](docs/source_en/Usage%20Guide/Train-as-a-Service.md).
+
+## Supported Hardware
+
+| Hardware Environment | Notes                                                            |
+| -------------------- | ---------------------------------------------------------------- |
+| Nvidia GPUs          | ✅ Support for BF16/Flash-Attn may be incomplete in earlier GPUs |
+| Ascend NPU           | ✅ Some operators may not supported                              |
+| PPU                  | ✅                                                               |
+| CPU                  | Supports partial components like dataset, dataloader             |
+
+## Supported Models
+
+We will be adding support for more models as new models are released. The following table lists current models
+supported on Twinkle✨ framework.
+
+>[!Note]
+> For serverless training service accessed via `base_url=https://www.modelscope.cn/twinkle`, it currently supports
+> one training base at a time, and currently it is [Qwen3-30B-A3B-Instruct-2507](https://modelscope.cn/models/Qwen/Qwen3-30B-A3B-Instruct-2507).
+
+
+| Model Type          | Model ID on [ModelScope](https://modelscope.cn)                                                                          | Requires             | Megatron Support | HF Model ID                                                                                                |
+| ------------------- |--------------------------------------------------------------------------------------------------------------------------| -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
+| qwen3 series        | [Qwen/Qwen3-0.6B-Base](https://modelscope.cn/models/Qwen/Qwen3-0.6B-Base)~32B                                            | transformers>=4.51   | ✅               | [Qwen/Qwen3-0.6B-Base](https://huggingface.co/Qwen/Qwen3-0.6B-Base)                                           |
+| qwen3_moe series    | [Qwen/Qwen3-30B-A3B-Base](https://modelscope.cn/models/Qwen/Qwen3-30B-A3B-Base)                                          | transformers>=4.51   | ✅               | [Qwen/Qwen3-30B-A3B-Base](https://huggingface.co/Qwen/Qwen3-30B-A3B-Base)                                     |
+|                     | [Qwen/Qwen3-30B-A3B](https://modelscope.cn/models/Qwen/Qwen3-30B-A3B)~235B                                               | transformers>=4.51   | ✅               | [Qwen/Qwen3-30B-A3B](https://huggingface.co/Qwen/Qwen3-30B-A3B)                                               |
+| qwen2 series        | [Qwen/Qwen2-0.5B-Instruct](https://modelscope.cn/models/Qwen/Qwen2-0.5B-Instruct) ~72B                                   | transformers>=4.37   | ✅               | [Qwen/Qwen2-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2-0.5B-Instruct)                                   |
+|                     | [Qwen/Qwen2.5-0.5B-Instruct](https://modelscope.cn/models/Qwen/Qwen2.5-0.5B-Instruct)~72B                                | transformers>=4.37   | ✅               | [Qwen/Qwen2.5-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct)                               |
+|                     | [Qwen/Qwen2.5-0.5B](https://modelscope.cn/models/Qwen/Qwen2.5-0.5B)~72B                                                  | transformers>=4.37   | ✅               | [Qwen/Qwen2.5-0.5B](https://huggingface.co/Qwen/Qwen2.5-0.5B)                                                 |
+| qwen2_moe series    | [Qwen/Qwen1.5-MoE-A2.7B-Chat](https://modelscope.cn/models/Qwen/Qwen1.5-MoE-A2.7B-Chat)                                  | transformers>=4.40   | ✅               | [Qwen/Qwen1.5-MoE-A2.7B-Chat](https://huggingface.co/Qwen/Qwen1.5-MoE-A2.7B-Chat)                             |
+| chatglm4 series     | [ZhipuAI/glm-4-9b-chat](https://modelscope.cn/models/ZhipuAI/glm-4-9b-chat)                                              | transformers>=4.42   | ✘               | [zai-org/glm-4-9b-chat](https://huggingface.co/zai-org/glm-4-9b-chat)                                         |
+|                     | [ZhipuAI/LongWriter-glm4-9b](https://modelscope.cn/models/ZhipuAI/LongWriter-glm4-9b)                                    | transformers>=4.42   | ✘               | [zai-org/LongWriter-glm4-9b](https://huggingface.co/zai-org/LongWriter-glm4-9b)                               |
+| glm_edge series     | [ZhipuAI/glm-edge-1.5b-chat](https://modelscope.cn/models/ZhipuAI/glm-edge-1.5b-chat)                                    | transformers>=4.46   | ✘               | [zai-org/glm-edge-1.5b-chat](https://huggingface.co/zai-org/glm-edge-1.5b-chat)                               |
+|                     | [ZhipuAI/glm-edge-4b-chat](https://modelscope.cn/models/ZhipuAI/glm-edge-4b-chat)                                        | transformers>=4.46   | ✘               | [zai-org/glm-edge-4b-chat](https://huggingface.co/zai-org/glm-edge-4b-chat)                                   |
+| internlm2 series    | [Shanghai_AI_Laboratory/internlm2-1_8b](https://modelscope.cn/models/Shanghai_AI_Laboratory/internlm2-1_8b)              | transformers>=4.38   | ✘               | [internlm/internlm2-1_8b](https://huggingface.co/internlm/internlm2-1_8b)                                     |
+|                     | [Shanghai_AI_Laboratory/internlm2-chat-7b](https://modelscope.cn/models/Shanghai_AI_Laboratory/internlm2-chat-7b)        | transformers>=4.38   | ✘               | [internlm/internlm2-chat-7b](https://huggingface.co/internlm/internlm2-chat-7b)                               |
+| deepseek_v1         | [deepseek-ai/deepseek-vl-7b-chat](https://modelscope.cn/models/deepseek-ai/deepseek-vl-7b-chat)                          | transformers>=4.39.4 | ✅               | ——                                                                                                       |
+|                     | [deepseek-ai/DeepSeek-V2-Lite](https://modelscope.cn/models/deepseek-ai/DeepSeek-V2-Lite)                                | transformers>=4.39.3 | ✅               | [deepseek-ai/DeepSeek-V2-Lite](https://huggingface.co/deepseek-ai/DeepSeek-V2-Lite)                           |
+|                     | [deepseek-ai/DeepSeek-V2.5](https://modelscope.cn/models/deepseek-ai/DeepSeek-V2.5)                                      | transformers>=4.39.3 | ✅               | [deepseek-ai/DeepSeek-V2.5](https://huggingface.co/deepseek-ai/DeepSeek-V2.5)                                 |
+|                     | [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-1.5B](https://modelscope.cn/models/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B) ~32B | transformers>=4.37   | ✅               | [deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B) |
+
+For more detailed model support list 👉  [Quick Start](docs/source_en/Usage%20Guide/Quick-Start.md)
+
+## Sample Code
+
+### Train with Ray
+
+```python
+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():
+    # to load model from Hugging Face, use 'hf://...'
+    base_model = 'ms://Qwen/Qwen2.5-7B-Instruct'
+    # 1000 samples
+    dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(1000)))
+    # Set template to prepare encoding
+    dataset.set_template('Template', model_id=base_model)
+    # Preprocess the dataset to standard format
+    dataset.map(SelfCognitionProcessor('twinkle LLM', 'ModelScope Community'))
+    # 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=base_model, 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()
+```
+
+### Using Tinker-Like API
+
+```python
+import os
+from tqdm import tqdm
+from tinker import types
+from twinkle_client import init_tinker_compat_client
+from twinkle.dataloader import DataLoader
+from twinkle.dataset import Dataset, DatasetMeta
+from twinkle.preprocessor import SelfCognitionProcessor
+from twinkle.server.tinker.common import input_feature_to_datum
+
+base_model = 'ms://Qwen/Qwen3-30B-A3B-Instruct-2507'
+base_url='http://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('Template', model_id=base_model, max_length=256)
+dataset.map(SelfCognitionProcessor('twinkle Model', 'twinkle 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
+service_client = init_tinker_compat_client(base_url, 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(3):
+    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()
+
+    training_client.save_state(f"twinkle-lora-{epoch}").result()
+```
+
+## Architecture Design
+
+<img src="assets/framework.jpg" style="max-width: 500px; width: 100%;" />
+
+ **Twinkle✨** features a decoupled **Client-Server architecture** designed for maximum flexibility.
+ The client-side provides two distinct integration paths:
+
+* **Twinkle✨ Native:** A conforming API that mirrors the server-side interface for seamless end-to-end integration.
+* **Tinker Compatibility:** Full support for the native Tinker API, enabling developers to leverage Twinkle✨’s backend using Tinker client.
+
+This dual-path design ensures access to Twinkle✨’s training services using Tinker API, with a simple modification of the Tinker base URL.
+
+## Multi-Tenancy
+
+**Twinkle✨** supports simultaneous multi-tenant training on a shared base model. Leveraging a **LoRA Pool + Tenant Application** architecture, Twinkle enables up to **N tenants** to train in parallel with complete isolation. This design offers unprecedented flexibility: from the model's perspective, each tenant's session is distinct, supporting heterogeneous configurations including unique **data padding strategies, optimizers, and loss functions**—all running concurrently on the same base model.
+
+*Note: This feature is currently optimized for [LoRA](https://github.com/huggingface/peft).*
+
+<img src="assets/multi_lora.png" style="max-width: 500px; width: 100%;" />
+
+For example:
+
+- Tenant A: Load local private dataset locally, LoRA rank=8, using base model for SFT
+- Tenant B: Load open-source dataset from Hub remotely, LoRA rank=32, using base model for PT
+- Tenant C: Use base model for GRPO loss calculation, using Sampler for sampling
+- Tenant D: Use base model for logps inference
+
+These processes are executed concurrently on a single base model because the **Model and Sampler**
+are integrated as **task-agnostic components** within the Twinkle✨ ecosystem.
+Upon completion, checkpoints are automatically pushed to **ModelScope** or **HuggingFace**  repositories
+(private by default). On the server side, Twinkle✨  provides a robust multi-tenant suite
+featuring **automated cluster management** and **dynamic scaling**, making it the
+foundation for building customizable, enterprise-grade training services.
+
+> As a modular framework, Twinkle✨ also supports remote temporary exclusive training, i.e., training in full-parameter mode.
+
+## 🛠️ Twinkle✨ Modular Ecosystem
+
+<div align="center">
+  <table style="width: 100%; border-collapse: separate; border-spacing: 8px;">
+    <tr>
+      <td width="20%" bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Dataset</b><br><sub>Data loading and preprocessing</sub></p>
+      </td>
+      <td width="20%" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Template</b><br><sub>Encoding and decoding</sub></p>
+      </td>
+      <td width="20%" bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>DataLoader</b><br><sub>Data distribution and batching</sub></p>
+      </td>
+      <td width="20%" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Preprocessor</b><br><sub>Data ETL</sub></p>
+      </td>
+      <td width="20%" bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>InputProcessor</b><br><sub>Task-specific input processing</sub></p>
+      </td>
+    </tr>
+    <tr>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Model</b><br><sub>Large models, supports multiple frameworks</sub></p>
+      </td>
+      <td style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Sampler</b><br><sub>Sampler logic</sub></p>
+      </td>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Loss</b><br><sub>Loss functions</sub></p>
+      </td>
+      <td style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Metric</b><br><sub>Training metrics collection</sub></p>
+      </td>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Reward</b><br><sub>Reward function</sub></p>
+      </td>
+    </tr>
+    <tr>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Advantage</b><br><sub>Advantage function</sub></p>
+      </td>
+      <td style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>CheckpointEngine</b><br><sub>Weight synchronization</sub></p>
+      </td>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Patch</b><br><sub>Patches for model fixes</sub></p>
+      </td>
+      <td style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Module</b><br><sub>Components, e.g., Optimizer</sub></p>
+      </td>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Kernel</b><br><sub>Operators</sub></p>
+      </td>
+    </tr>
+    <tr>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Server</b><br><sub>Start backend cluster</sub></p>
+      </td>
+      <td style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Client</b><br><sub>Client code</sub></p>
+      </td>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Infra</b><br><sub>Isolate ray and torchrun differences</sub></p>
+      </td>
+      <td style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Plugin</b><br><sub>Use hub components</sub></p>
+      </td>
+      <td bgcolor="#f6f8fa" style="border: 1px solid #d0d7de; border-radius: 8px; padding: 12px;">
+        <p align="center"><b>Hub</b><br><sub>Interface with HF/MS libraries</sub></p>
+      </td>
+    </tr>
+  </table>
+</div>
+
+## Community Components
+
+| Component Type | Component Link                                                                                           | Component Function                                                                      | Author              |
+| -------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------- |
+| Patch          | [qwen3_moe_transformers4_patch](https://www.modelscope.cn/models/twinkle-kit/qwen3_moe_transformers4_patch) | Fixes Qwen3 MoE model hang issue during FSDP2 training, effective for transformers==4.x | ModelScope Official |
+
+## Contributions
+
+Twinkle✨ is a collaborative initiative put together by ModelScope in partnership
+with the open-source community, with key contributions from strategic stakeholders
+including China Merchants Bank Tech Team.
+
+We are grateful to the open-source community, particularly the projects that inspired us,
+including [Transformers](https://github.com/huggingface/transformers),
+[MS-SWIFT](https://github.com/modelscope/swift),
+[veRL](https://github.com/verl-project/verl), [Tinker](https://github.com/thinking-machines-lab/tinker), and many others.
+
+We welcome
+open contributions via [issues](https://github.com/modelscope/twinkle/issues) and [pull-requests](https://github.com/modelscope/twinkle/pulls).