update cookbook

Yunnglin · Yunnglin · commit d7aee0568a28 · 2026-02-27T20:52:20.000+08:00
diff --git a/README.md b/README.md
@@ -203,7 +203,7 @@ if __name__ == '__main__':
 import os
 from tqdm import tqdm
 from tinker import types
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 from twinkle.dataloader import DataLoader
 from twinkle.dataset import Dataset, DatasetMeta
 from twinkle.preprocessor import SelfCognitionProcessor
diff --git a/README_ZH.md b/README_ZH.md
@@ -186,7 +186,7 @@ if __name__ == '__main__':
 import os
 from tqdm import tqdm
 from tinker import types
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 from twinkle.dataloader import DataLoader
 from twinkle.dataset import Dataset, DatasetMeta
 from twinkle.preprocessor import SelfCognitionProcessor
diff --git a/cookbook/client/tinker/lora.py b/cookbook/client/tinker/lora.py
@@ -8,22 +8,23 @@
 
 # Step 1: Load environment variables from a .env file (e.g., API tokens)
 import dotenv
-
 dotenv.load_dotenv('.env')
 
-import os
-
 # Step 2: Initialize Tinker client before importing ServiceClient
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 
 init_tinker_client()
 
 # Step 3: Use ServiceClient directly from tinker
 from tinker import ServiceClient
 
 service_client = ServiceClient(
-    base_url='http://www.modelscope.cn/twinkle',
-    api_key=os.environ.get('MODELSCOPE_TOKEN')
+	# BASE_URL can be a local server endpoint such as http://localhost:8000, or
+	# points to a previously deployed remote server, or
+	# modelscope server such as 'http://www.modelscope.cn/twinkle'
+    base_url='<BASE_URL>',
+	# API_KEY can be empty or a meaninful one according to sever configuration
+    api_key='<API_KEY>'
 )
 
 # Step 4: List models available on the server to verify the connection
@@ -40,10 +41,12 @@
 
 # You can resume from either:
 #   1. A twinkle path:  "twinkle://.../<run_id>/weights/<checkpoint_name>"
-#   2. A model id on hub: "<user>/<model_id>"
+#   2. A model id on ModelScope hub: "ms://<user>/<model_id>"
+#   3. A local path to a checkpoint directory
 # Example:
 # resume_path = "twinkle://20260131_170251-Qwen_Qwen2_5-0_5B-Instruct-7275126c/weights/pig-latin-lora-epoch-1"
-# resume_path = "AlexEz/20260205_163645-Qwen_Qwen2_5-7B-Instruct-385d5c17_pig-latin-lora-epoch-1"
+# resume_path = "ms://AlexEz/20260205_163645-Qwen_Qwen2_5-7B-Instruct-385d5c17_pig-latin-lora-epoch-1"
+# resume_path = "/path/to/local/checkpoint/directory"
 resume_path = ''
 
 print(f'Found {len(response.training_runs)} training runs')
@@ -85,19 +88,7 @@
     {
         'input': 'pickle jar',
         'output': 'ickle-pay ar-jay'
-    },
-    {
-        'input': 'space exploration',
-        'output': 'ace-spay exploration-way'
-    },
-    {
-        'input': 'rubber duck',
-        'output': 'ubber-ray uck-day'
-    },
-    {
-        'input': 'coding wizard',
-        'output': 'oding-cay izard-way'
-    },
+    }
 ]
 
 from modelscope import AutoTokenizer
@@ -181,6 +172,7 @@ def process_example(example: dict, tokenizer) -> types.Datum:
 
 # Step 9: Publish the final checkpoint to ModelScope Hub.
 # NOTE: Requires a valid ModelScope token set as api_key when initializing the client.
-# The published model name will be: {run_id}_{checkpoint_name}
+# The model will be published under the owner of the supplied ModelScope token,
+# with model name formatted as: {run_id}_{checkpoint_name}
 rest_client.publish_checkpoint_from_tinker_path(save_result.path).result()
 print('Published checkpoint')
diff --git a/cookbook/client/tinker/sample.py b/cookbook/client/tinker/sample.py
@@ -9,7 +9,7 @@
 
 from twinkle.data_format import Message, Trajectory
 from twinkle.template import Template
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 
 # Step 1: Initialize Tinker client
 init_tinker_client()
diff --git a/cookbook/client/tinker/self_congnition.py b/cookbook/client/tinker/self_congnition.py
@@ -9,7 +9,7 @@
 import os
 from tqdm import tqdm
 from tinker import types
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 from twinkle.data_format import Message, Trajectory
 from twinkle.template import Template
 from twinkle.dataloader import DataLoader
diff --git a/cookbook/client/tinker/short_math_grpo.py b/cookbook/client/tinker/short_math_grpo.py
@@ -24,7 +24,7 @@
 from tinker import types
 from typing import List, Tuple
 
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 from twinkle import get_logger
 from twinkle.advantage import GRPOAdvantage
 from twinkle.data_format import Message, Trajectory
diff --git a/docs/source_en/Usage Guide/Server and Client/Tinker-Compatible-Client.md b/docs/source_en/Usage Guide/Server and Client/Tinker-Compatible-Client.md
@@ -6,7 +6,7 @@ The Tinker Client is suitable for scenarios with existing Tinker training code.
 
 ```python
 # Initialize Tinker client before importing ServiceClient
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 
 init_tinker_client()
 
@@ -41,7 +41,7 @@ import dotenv
 dotenv.load_dotenv('.env')
 
 # Step 1: Initialize Tinker client before importing ServiceClient
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 init_tinker_client()
 
 from tinker import types, ServiceClient
@@ -139,7 +139,7 @@ Tinker compatible mode can also leverage Twinkle's dataset components to simplif
 ```python
 from tqdm import tqdm
 from tinker import types
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 from twinkle.dataloader import DataLoader
 from twinkle.dataset import Dataset, DatasetMeta
 from twinkle.preprocessor import SelfCognitionProcessor
@@ -216,7 +216,7 @@ You can also load saved checkpoints for inference:
 import os
 from tinker import types
 from modelscope import AutoTokenizer
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 
 # Initialize Tinker client before importing ServiceClient
 init_tinker_client()
diff --git a/docs/source_zh/使用指引/服务端和客户端/Tinker兼容客户端.md b/docs/source_zh/使用指引/服务端和客户端/Tinker兼容客户端.md
@@ -6,7 +6,7 @@ Tinker Client 适用于已有 Tinker 训练代码的场景。通过 `init_tinker
 
 ```python
 # 在导入 ServiceClient 之前，先初始化 Tinker 客户端
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 
 init_tinker_client()
 
@@ -41,7 +41,7 @@ import dotenv
 dotenv.load_dotenv('.env')
 
 # Step 1: 在导入 ServiceClient 之前，先初始化 Tinker 客户端
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 init_tinker_client()
 
 from tinker import types, ServiceClient
@@ -139,7 +139,7 @@ Tinker 兼容模式也可以利用 Twinkle 的数据集组件来简化数据准
 ```python
 from tqdm import tqdm
 from tinker import types
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 from twinkle.dataloader import DataLoader
 from twinkle.dataset import Dataset, DatasetMeta
 from twinkle.preprocessor import SelfCognitionProcessor
@@ -216,7 +216,7 @@ for i, seq in enumerate(result.sequences):
 import os
 from tinker import types
 from modelscope import AutoTokenizer
-from twinkle_client import init_tinker_client
+from twinkle import init_tinker_client
 
 # 在导入 ServiceClient 之前，先初始化 Tinker 客户端
 init_tinker_client()
diff --git a/src/twinkle/__init__.py b/src/twinkle/__init__.py
@@ -4,11 +4,11 @@
 from .utils.import_utils import _LazyModule  # noqa
 
 if TYPE_CHECKING:
+    from twinkle_client import init_tinker_client, init_twinkle_client
     from .infra import get_device_placement, initialize, is_master, remote_class, remote_function
     from .utils import (GPU, NPU, DeviceGroup, DeviceMesh, Platform, Plugin, check_unsafe, exists, find_free_port,
                         find_node_ip, framework_util, get_logger, requires, torch_util, trust_remote_code)
     from .version import __release_datetime__, __version__
-
 else:
     _import_structure = {
         'version': ['__release_datetime__', '__version__'],
@@ -21,10 +21,15 @@
 
     import sys
 
+    from twinkle_client import init_tinker_client, init_twinkle_client
+
     sys.modules[__name__] = _LazyModule(
         __name__,
         globals()['__file__'],
         _import_structure,
         module_spec=__spec__,  # noqa
-        extra_objects={},
+        extra_objects={
+            'init_tinker_client': init_tinker_client,
+            'init_twinkle_client': init_twinkle_client
+        },
     )
diff --git a/src/twinkle/model/megatron/megatron.py b/src/twinkle/model/megatron/megatron.py
@@ -880,9 +880,12 @@ def load(self, name: str, output_dir: Optional[str] = None, **kwargs):
         """
         resume = kwargs.pop('load_optimizer', False)
         if output_dir is None and not resume:
-            # Load from hub
-            token = kwargs.pop('token', None)
-            checkpoint_dir = HubOperation.download_model(name, token=token)
+            if os.path.exists(name):
+                checkpoint_dir = name
+            else:
+                # load from hub
+                token = kwargs.pop('token', None)
+                checkpoint_dir = HubOperation.download_model(name, token=token)
         else:
             if output_dir is None:
                 output_dir = 'output'
diff --git a/src/twinkle/model/transformers/transformers.py b/src/twinkle/model/transformers/transformers.py
@@ -842,9 +842,12 @@ def load(self, name: str, output_dir: Optional[str] = None, **kwargs):
         adapter_name = kwargs.pop('adapter_name', self._get_default_group())
 
         if output_dir is None:
-            # load from hub
-            token = kwargs.pop('token', None)
-            checkpoint_dir = HubOperation.download_model(name, token=token)
+            if os.path.exists(name):
+                checkpoint_dir = name
+            else:
+                # load from hub
+                token = kwargs.pop('token', None)
+                checkpoint_dir = HubOperation.download_model(name, token=token)
         else:
             checkpoint_dir = os.path.join(output_dir, name)
         model = self.strategy.unwrap_model(self.model)
diff --git a/src/twinkle/server/utils/io_utils.py b/src/twinkle/server/utils/io_utils.py
@@ -6,6 +6,8 @@
 file-based storage of training run metadata and checkpoint information.
 Both tinker and twinkle servers inherit from these classes.
 """
+import hashlib
+import hmac
 import json
 import os
 import re
@@ -25,6 +27,20 @@
 CHECKPOINT_INFO_FILENAME = 'checkpoint_metadata.json'
 TRAIN_RUN_INFO_FILENAME = 'twinkle_metadata.json'
 
+# Salt used when hashing tokens for directory isolation.
+# Override via env var TWINKLE_TOKEN_SALT to customise per-deployment.
+_TOKEN_SALT = os.environ.get('TWINKLE_TOKEN_SALT', 'twinkle-path-salt-v1').encode('utf-8')
+
+
+def _hash_token(token: str) -> str:
+    """Return a salted HMAC-SHA256 hex digest of *token*.
+
+    The digest is used as the per-user base directory name so that the raw
+    token value is never written to the filesystem.
+    """
+    return hmac.new(_TOKEN_SALT, token.encode('utf-8'), hashlib.sha256).hexdigest()
+
+
 # ----- Common Pydantic Models -----
 
 
@@ -275,13 +291,15 @@ def get_base_dir(self) -> Path:
         """
         Get base directory with token-based isolation.
 
+        The token is never written to disk in plaintext; instead a salted
+        HMAC-SHA256 digest is used as the directory name so that the real
+        token cannot be recovered by inspecting the filesystem.
+
         Returns:
             Path to token-specific base directory
         """
         base_path = Path(TWINKLE_DEFAULT_SAVE_DIR).absolute()
-        # Sanitize token to avoid filesystem issues
-        sanitized_token = re.sub(r'[^\w\-]', '_', self.token)
-        return base_path / sanitized_token
+        return base_path / _hash_token(self.token)
 
     def get_model_dir(self, model_id: str) -> Path:
         """
diff --git a/src/twinkle_client/__init__.py b/src/twinkle_client/__init__.py
@@ -1,12 +1,6 @@
 # Copyright (c) ModelScope Contributors. All rights reserved.
 from __future__ import annotations
 
-from twinkle.utils import requires
-from .http.utils import get_api_key, get_base_url, set_api_key, set_base_url
-from .manager import TwinkleClient, TwinkleClientError
-
-
-
 def init_tinker_client(**kwargs) -> None:
     """Initialize Tinker client with Twinkle-specific headers.
 
@@ -20,11 +14,13 @@ def init_tinker_client(**kwargs) -> None:
         **kwargs: Additional keyword arguments (currently unused, reserved for future)
 
     Example:
-        >>> from twinkle_client import init_tinker_client
+        >>> from twinkle import init_tinker_client
         >>> init_tinker_client()
         >>> from tinker import ServiceClient
         >>> client = ServiceClient(base_url='http://localhost:8000', api_key='your_token')
     """
+    from twinkle.utils import requires
+    
     requires('tinker')
     from twinkle_client.utils.patch_tinker import patch_tinker
 
@@ -36,6 +32,9 @@ def init_twinkle_client(base_url: str | None = None, api_key: str | None = None,
     """
     Initialize a Twinkle client and setup context variables.
     """
+    from .http.utils import get_api_key, get_base_url, set_api_key, set_base_url
+    from .manager import TwinkleClient, TwinkleClientError
+    
     if base_url is not None:
         set_base_url(base_url)
     else:
@@ -49,4 +48,4 @@ def init_twinkle_client(base_url: str | None = None, api_key: str | None = None,
     return TwinkleClient(base_url=base_url, api_key=api_key, **kwargs)
 
 
-__all__ = ['TwinkleClient', 'TwinkleClientError', 'init_tinker_client', 'init_twinkle_client']
+__all__ = ['init_tinker_client', 'init_twinkle_client']
