# 概述

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

## 核心概念

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

### 两种模型后端

模型加载支持两种后端：

| 后端 | use_megatron | 说明 |
|------|-------------|------|
| **Transformers** | `false` | 基于 HuggingFace Transformers，适用于大多数场景 |
| **Megatron** | `true` | 基于 Megatron-LM，适用于超大规模模型训练，支持更高效的并行策略 |

### 两种 Client 模式

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

## 如何选择

### Client 模式选择

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

### 模型后端选择

| 场景 | 推荐 |
|------|------|
| 7B/14B 等中小规模模型 | Transformers 后端 (`use_megatron: false`) |
| 超大规模模型，需要高级并行策略 | Megatron 后端 (`use_megatron: true`) |
| 快速实验和原型验证 | Transformers 后端 (`use_megatron: false`) |

## Cookbook 参考

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

```
cookbook/client/
├── server/                         # Server 启动配置
│   ├── transformer/                # Transformers 后端
│   │   ├── run.sh                  # 启动脚本
│   │   ├── server.py               # Server 入口
│   │   └── server_config.yaml      # 配置文件
│   └── megatron/                   # Megatron 后端
│       ├── run.sh
│       ├── server.py
│       ├── server_config.yaml
│       └── server_config_4b.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
```

运行步骤：

```bash
# 1. 先启动 Server
python cookbook/client/server/megatron/server.py

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

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