文档
使用指引
服务端和客户端
概述

概述

Twinkle 提供了完整的 HTTP Server/Client 架构，支持将模型部署为服务，并通过客户端远程调用完成训练、推理等任务。这种架构将**模型承载（Server 端）和训练逻辑（Client 端）**解耦，使得多个用户可以共享同一个基座模型进行训练。

核心概念

  • Server 端：基于 Ray Serve 部署，承载模型权重和推理/训练计算。Server 负责管理模型加载、前向/反向传播、权重保存、采样推理等。同一个 Server 同时支持 Twinkle Client 和 Tinker Client 连接。
  • Client 端：在本地运行，负责数据准备、训练循环编排、超参配置等。Client 通过 HTTP 与 Server 通信，发送数据和指令。

模型后端

模型加载支持三种后端：

后端backend说明
Transformerstransformers基于 HuggingFace Transformers，适用于大多数场景
Megatronmegatron基于 Megatron-LM，适用于超大规模模型训练，支持更高效的并行策略
MockmockNumpy-only 模拟后端，用于 CPU-only 开发和测试

两种 Client 模式

Client初始化方式说明
Twinkle Clientinit_twinkle_client原生客户端，将 from twinkle import 改为 from twinkle_client import 即可将本地训练代码迁移为远端调用
Tinker Clientinit_tinker_client对 Tinker SDK 进行 patch，使已有 Tinker 训练代码可直接复用

如何选择

Client 模式选择

场景推荐
已有 Twinkle 本地训练代码，希望改为远端Twinkle Client — 仅需改 import 路径
已有 Tinker 训练代码，希望复用Tinker Client — 仅需初始化 patch
全新项目Twinkle Client — API 更简洁

模型后端选择

场景推荐
7B/14B 等中小规模模型Transformers 后端（backend: transformers）
超大规模模型，需要高级并行策略Megatron 后端（backend: megatron）
快速实验和原型验证Transformers 后端（backend: transformers）
CPU-only 开发/测试Mock 后端（backend: mock）

Cookbook 参考

完整的可运行示例位于 cookbook/ 目录：

cookbook/
├── observability/                  # 可观测性（Grafana + OTLP）
│   ├── docker-compose.yaml         # 一键启动 LGTM 栈
│   └── README.md
├── client/
│   ├── server/                     # Server 启动配置
│   │   ├── transformer/            # Transformers 后端
│   │   │   ├── run.sh
│   │   │   ├── server_config.yaml
│   │   │   └── server_config_e2e.yaml
│   │   ├── megatron/               # Megatron 后端
│   │   │   ├── run.sh
│   │   │   ├── server_config.yaml
│   │   │   └── server_config_4b.yaml
│   │   └── mock/                   # Mock 后端（CPU-only 快速启动）
│   │       └── server_config.yaml
├── twinkle/                        # Twinkle Client 示例
│   ├── dpo.py                      # DPO 训练客户端
│   ├── embedding.py                # Embedding 训练客户端
│   ├── multi_modal.py              # 多模态训练客户端
│   ├── multi_turn_rollout.py       # 多轮 rollout 客户端
│   ├── sample.py                   # 推理采样客户端
│   ├── self_cognition.py           # 自我认知训练客户端
│   ├── short_math_grpo.py          # GRPO 数学训练客户端
│   └── upload_to_hub.py            # Checkpoint 上传客户端
└── tinker/                         # Tinker Client 示例
    ├── dpo.py                      # DPO 训练客户端
    ├── lora.py                     # LoRA 训练客户端
    ├── multi_modal.py              # 多模态训练客户端
    ├── sample.py                   # 推理采样客户端
    ├── self_cognition.py           # 自我认知训练客户端
    ├── short_math_grpo.py          # GRPO 数学训练客户端
    └── upload_to_hub.py            # Checkpoint 上传客户端

运行步骤：

# 1. 先启动 Server
twinkle-server launch -c cookbook/client/server/transformer/server_config.yaml

# 2. 在另一个终端配置客户端
export TWINKLE_SERVER_URL=http://localhost:8000
export TWINKLE_SERVER_TOKEN=EMPTY_TOKEN
export TWINKLE_MODEL_ID=Qwen/Qwen3.5-4B

# 3. 运行 Tinker Client 示例
python cookbook/client/tinker/self_cognition.py

# 或使用 Twinkle Client
python cookbook/client/twinkle/self_cognition.py

同一组示例也可用于 ModelScope 托管服务，只需切换环境变量：

export TWINKLE_SERVER_URL=https://www.modelscope.cn/twinkle
export TWINKLE_SERVER_TOKEN="$MODELSCOPE_TOKEN"
export TWINKLE_MODEL_ID=Qwen/Qwen3.8-27B
docs