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

概述

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 示例
│   ├── self_host/                  # 自托管 Server
│   │   ├── dpo.py                  # DPO 训练客户端
│   │   ├── multi_modal.py          # 多模态训练客户端
│   │   ├── sample.py               # 推理采样客户端
│   │   ├── self_congnition.py      # 自我认知训练客户端
│   │   └── short_math_grpo.py      # GRPO 数学训练客户端
│   └── modelscope/                 # ModelScope 托管服务
│       ├── dpo.py
│       ├── multi_modal.py
│       └── self_congnition.py
└── tinker/                         # Tinker Client 示例
    ├── self_host/                  # 自托管 Server
    │   ├── dpo.py                  # DPO 训练客户端
    │   ├── lora.py                 # LoRA 训练客户端
    │   ├── multi_modal.py          # 多模态训练客户端
    │   ├── sample.py               # 推理采样客户端
    │   ├── self_cognition.py       # 自我认知训练客户端
    │   └── short_math_grpo.py      # GRPO 数学训练客户端
    └── modelscope/                 # ModelScope 托管服务
        ├── dpo.py
        ├── sample.py
        ├── self_cognition.py
        └── short_math_grpo.py

运行步骤：

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

# 2. 在另一个终端运行 Client（以 Tinker Client 为例）
python cookbook/client/tinker/self_host/self_cognition.py

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