服务端和客户端 | Twinkle

概述

Mon, 01 Jan 0001 00:00:00 +0000

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

核心概念

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

模型后端

模型加载支持三种后端：

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

两种 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 后端（`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

服务端（Server）

Mon, 01 Jan 0001 00:00:00 +0000

Ray 集群配置

在启动 Server 之前，必须先启动并配置 Ray 节点。只有正确配置了 Ray 节点后，Server 才能正确分配和占用资源（GPU、CPU 等）。

启动 Ray 节点

Ray 集群由多个节点（Node）组成，每个节点可以配置不同的资源。启动步骤如下：

1. 启动 Head 节点（第一个 GPU 节点）

# 停止已有的 Ray 集群（如果有）
ray stop

# 启动 Head 节点，使用 GPU 0-3，共 4 个 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 ray start --head --num-gpus=4 --port=6379

2. 启动 Worker 节点

# 第二个 GPU 节点，使用 GPU 4-7，共 4 个 GPU
CUDA_VISIBLE_DEVICES=4,5,6,7 ray start --address=10.28.252.9:6379 --num-gpus=4

# CPU 节点（用于运行 Processor 等 CPU 任务）
ray start --address=10.28.252.9:6379 --num-gpus=0

说明：

--head：标记此节点为 Head 节点（集群的主节点）
--port=6379：Head 节点监听端口
--address=<IP>:<PORT>：Worker 节点连接到 Head 节点的地址
--num-gpus=N：该节点可用的 GPU 数量
CUDA_VISIBLE_DEVICES：限制该节点可见的 GPU 设备

3. 完整示例：3 节点集群

# 停止旧集群并启动新集群
ray stop && \
CUDA_VISIBLE_DEVICES=0,1,2,3 ray start --head --num-gpus=4 --port=6379 && \
CUDA_VISIBLE_DEVICES=4,5,6,7 ray start --address=10.28.252.9:6379 --num-gpus=4 && \
ray start --address=10.28.252.9:6379 --num-gpus=0

此配置启动了 3 个节点：

Node 0（Head）：4 个 GPU（卡 0-3）
Node 1（Worker）：4 个 GPU（卡 4-7）
Node 2（Worker）：纯 CPU 节点

4. 设置环境变量

在启动 Server 之前，需要设置以下环境变量：

export TWINKLE_TRUST_REMOTE_CODE=0 # 是否信任远程代码（安全考虑）

YAML 配置中的 Node Rank

在 YAML 配置文件中，每个组件需要占用一个独立的 Node。

示例配置：

applications:
 # 模型服务占用 GPU 0-3（物理卡号）
 - name: models-Qwen3.5-4B
 route_prefix: /models/Qwen/Qwen3.5-4B
 import_path: model
 args:
 nproc_per_node: 4
 device_group:
 name: model
 ranks: 4 # 使用的 GPU 数量
 device_type: cuda
 device_mesh:
 device_type: cuda
 dp_size: 4 # 数据并行大小
 # tp_size: 1 # 张量并行大小（可选）
 # pp_size: 1 # 流水线并行大小（可选）
 # ep_size: 1 # 专家并行大小（可选）

 # Sampler 服务占用 GPU 4-5（物理卡号）
 - name: sampler-Qwen3.5-4B
 route_prefix: /sampler/Qwen/Qwen3.5-4B
 import_path: sampler
 args:
 nproc_per_node: 2
 device_group:
 name: sampler
 ranks: 2 # 使用的 GPU 数量
 device_type: cuda
 device_mesh:
 device_type: cuda
 dp_size: 2 # 数据并行大小

 # Processor 服务占用 CPU
 - name: processor
 route_prefix: /processors
 import_path: processor
 args:
 ncpu_proc_per_node: 4
 device_group:
 name: processor
 ranks: 0 # CPU 编号
 device_type: CPU
 device_mesh:
 device_type: CPU
 dp_size: 4 # 数据并行大小

重要提示：

ranks 配置指定为该组件分配的 GPU 数量
device_mesh 配置使用 dp_size、tp_size、pp_size、ep_size 等参数定义并行策略
不同组件会自动分配到不同的 Node 上
Ray 会根据资源需求（ray_actor_options 中的 num_gpus、num_cpus）自动调度到合适的 Node

启动方式

Server 通过 CLI 命令启动，配合 YAML 配置文件。安装 Twinkle 后会注册 twinkle-server 命令。

启动服务

twinkle-server launch --config server_config.yaml

也可以通过 Python 模块调用：

python -m twinkle.server launch --config server_config.yaml

CLI 子命令

子命令	说明
`launch`	启动 Server（阻塞直到服务关闭）
`check-config`	验证配置文件是否合法，不启动服务
`print-config`	输出经过验证和标准化的完整配置（支持 `--format yaml\|json`）
`clear persistence`	清除持久化后端中的状态数据

通用参数：

参数	说明	环境变量
`-c, --config`	YAML 配置文件路径（必须）	`TWINKLE_SERVER_CONFIG`
`--namespace`	Ray 命名空间（仅 `launch`）	`TWINKLE_RAY_NAMESPACE`

示例：

# 验证配置（CI 中可用来拦截错误配置）
twinkle-server check-config -c server_config.yaml

# 查看完整解析后的配置
twinkle-server print-config -c server_config.yaml --format json

# 清除 Redis/文件中的持久化状态
twinkle-server clear persistence -c server_config.yaml

YAML 配置详解

配置文件定义了 Server 的完整部署方案，包括 HTTP 监听、应用组件和资源分配。Server 同时支持 Twinkle 和 Tinker 两种客户端，通过统一的配置文件部署所有服务组件。

完整配置示例（Megatron 后端）

# HTTP 代理位置：EveryNode 表示每个 Ray 节点运行一个代理（多节点场景推荐）
proxy_location: EveryNode

# HTTP 监听配置
http_options:
 host: 0.0.0.0 # 监听所有网络接口
 port: 8000 # 服务端口号

# 可观测性：通过 OTLP 推送 traces/metrics/logs
telemetry:
 enabled: true
 otlp_endpoint: http://localhost:4317

# 持久化：ServerState 的存储后端（sessions、models、futures 等）
# mode: memory | file | redis
persistence:
 mode: file
 file_path: /tmp/twinkle_state.json

# 应用列表：每个条目定义一个部署在 Server 上的服务组件
applications:

 # 1. TinkerCompatServer：中央 API 服务
 # 负责处理客户端连接、训练运行跟踪、检查点管理等
 # route_prefix 使用 /api/v1，兼容 Tinker 和 Twinkle 客户端
 - name: server
 route_prefix: /api/v1
 import_path: server
 args:
 server_config:
 per_token_model_limit: 3 # 每个 token 最多可关联的模型（适配器）数量（服务器全局生效）
 supported_models:
 - Qwen/Qwen3.5-4B
 deployments:
 - name: TinkerCompatServer
 max_ongoing_requests: 50
 autoscaling_config:
 min_replicas: 1
 max_replicas: 1
 target_ongoing_requests: 128
 ray_actor_options:
 num_cpus: 0.1

 # 2. Model 服务：承载基座模型
 # 执行前向传播、反向传播等训练计算
 - name: models-Qwen3.5-4B
 route_prefix: /api/v1/model/Qwen/Qwen3.5-4B
 import_path: model
 args:
 backend: megatron  # 模型后端：transformers | megatron | mock
 model_id: "ms://Qwen/Qwen3.5-4B" # ModelScope 模型标识
 max_length: 10240
 nproc_per_node: 2 # 每节点 GPU 进程数
 device_group: # 逻辑设备组
 name: model
 ranks: 2 # 使用的 GPU 数量
 device_type: cuda
 device_mesh: # 分布式训练网格
 device_type: cuda
 dp_size: 2 # 数据并行大小
 queue_config:
 rps_limit: 100 # 最大请求速率（每秒）
 tps_limit: 10000 # 单用户最大 token 速率（每秒）
 max_input_tokens: 10000 # 每次请求最大输入 token 数
 adapter_config:
 adapter_timeout: 30 # 空闲适配器超时卸载时间（秒）
 adapter_max_lifetime: 36000 # 适配器最大生命周期（秒）
 max_loras: 1 # 每个模型最多加载的 LoRA 数量
 deployments:
 - name: ModelManagement
 autoscaling_config:
 min_replicas: 1
 max_replicas: 1
 target_ongoing_requests: 16
 ray_actor_options:
 num_cpus: 0.1
 runtime_env:
 env_vars:
 TWINKLE_TRUST_REMOTE_CODE: "0"

 # 3. Sampler 服务：推理采样
 # 使用 vLLM 引擎执行推理，支持 LoRA 适配器
 - name: sampler-Qwen3.5-4B
 route_prefix: /api/v1/sampler/Qwen/Qwen3.5-4B
 import_path: sampler
 args:
 model_id: "ms://Qwen/Qwen3.5-4B" # ModelScope 模型标识
 nproc_per_node: 2 # 每节点 GPU 进程数
 sampler_type: vllm  # 推理引擎：vllm（高性能）或 torch
 engine_args: # vLLM 引擎参数
 max_model_len: 4096 # 最大序列长度
 gpu_memory_utilization: 0.5 # GPU 显存使用比例（0.0-1.0）
 enable_lora: true # 支持推理时加载 LoRA
 logprobs_mode: processed_logprobs  # logprobs 输出模式
 device_group: # 逻辑设备组
 name: sampler
 ranks: 1 # 使用的 GPU 数量
 device_type: cuda
 device_mesh:
 device_type: cuda
 dp_size: 1
 queue_config:
 rps_limit: 100 # 最大请求速率（每秒）
 tps_limit: 100000 # 最大 token 速率（每秒）
 deployments:
 - name: SamplerManagement
 autoscaling_config:
 min_replicas: 1
 max_replicas: 1
 target_ongoing_requests: 16
 ray_actor_options:
 num_cpus: 0.1
 runtime_env:
 env_vars:
 TWINKLE_TRUST_REMOTE_CODE: "0"

 # 4. Processor 服务：数据预处理
 # 在 CPU 上执行 tokenization、模板转换等预处理任务
 - name: processor
 route_prefix: /api/v1/processor
 import_path: processor
 args:
 ncpu_proc_per_node: 2
 device_group:
 name: model
 ranks: 2
 device_type: CPU
 device_mesh:
 device_type: CPU
 dp_size: 2
 deployments:
 - name: ProcessorManagement
 autoscaling_config:
 min_replicas: 1
 max_replicas: 1
 target_ongoing_requests: 128
 ray_actor_options:
 num_cpus: 0.1

Transformers 后端

Transformers 后端与 Megatron 后端的区别仅在 Model 服务的 backend 参数：

 - name: models-Qwen3.5-4B
 route_prefix: /api/v1/model/Qwen/Qwen3.5-4B
 import_path: model
 args:
 backend: transformers  # 使用 Transformers 后端
 model_id: "ms://Qwen/Qwen3.5-4B"
 nproc_per_node: 2
 device_group:
 name: model
 ranks: 2
 device_type: cuda
 device_mesh:
 device_type: cuda
 dp_size: 2
 adapter_config:
 adapter_timeout: 1800 # 空闲适配器超时卸载时间（秒）
 adapter_max_lifetime: 36000
 deployments:
 - name: ModelManagement
 autoscaling_config:
 min_replicas: 1
 max_replicas: 1
 target_ongoing_requests: 16
 ray_actor_options:
 num_cpus: 0.1

配置项说明

顶层字段

字段	说明
`proxy_location`	HTTP 代理位置（`EveryNode` 或 `HeadOnly`）
`http_options`	HTTP 监听配置（`host`、`port`）
`telemetry`	可观测性配置（`enabled`、`otlp_endpoint`）
`persistence`	状态持久化配置（`mode`、`file_path`、`redis_url`）
`applications`	应用组件列表

配置文件启用了严格校验（extra='forbid'），任何拼写错误的字段名都会在启动前报错。可使用 twinkle-server check-config -c xxx.yaml 提前检测。

应用组件（import_path）

import_path	说明
`server`	中央管理服务，处理训练运行和检查点
`model`	模型服务，承载基座模型进行训练
`processor`	数据预处理服务，在 CPU 上执行 tokenization、模板转换等
`sampler`	推理采样服务

模型后端（backend）

backend	说明
`transformers`	基于 HuggingFace Transformers，适用于大多数场景
`megatron`	基于 Megatron-LM，适用于超大规模模型训练
`mock`	Numpy-only 模拟后端，用于 CPU-only 开发和测试

device_group 与 device_mesh

device_group：定义逻辑设备组，指定使用多少 GPU
device_mesh：定义分布式训练网格，控制并行策略

device_group:
 name: model  # 设备组名称
 ranks: 2 # 使用的 GPU 数量
 device_type: cuda  # 设备类型：cuda / CPU

device_mesh:
 device_type: cuda
 dp_size: 2 # 数据并行大小
 # tp_size: 1 # 张量并行大小（可选）
 # pp_size: 1 # 流水线并行大小（可选）
 # ep_size: 1 # 专家并行大小（可选）

重要配置参数说明：

参数	类型	说明
`ranks`	int	使用的 GPU 数量
`dp_size`	int	数据并行大小
`tp_size`	int (可选)	张量并行大小
`pp_size`	int (可选)	流水线并行大小
`ep_size`	int (可选)	专家并行大小（用于 MoE 模型）

telemetry

控制 OpenTelemetry 可观测性管线。详见。

字段	类型	默认值	说明
`enabled`	bool	`false`	是否启用遥测
`service_name`	str	`twinkle-server`	上报的服务名
`otlp_endpoint`	str	`http://localhost:4317`	OTel Collector 的 gRPC 地址
`debug`	bool	`false`	`true` 时输出到控制台而非 OTLP

persistence

ServerState（sessions、models、futures 等）的存储后端。

字段	类型	默认值	说明
`mode`	str	`memory`	`memory` / `file` / `redis`
`file_path`	str	—	`file` 模式必填，JSON 文件路径
`redis_url`	str	—	`redis` 模式必填，如 `redis://localhost:6379`
`key_prefix`	str	`""`	可选的全局 key 前缀

环境变量：

export TWINKLE_TRUST_REMOTE_CODE=0 # 是否信任远程代码

配置验证与迁移

配置文件使用严格校验模式，以下情况会在启动前报错：

拼写错误或不支持的字段名
类型不匹配（如 port 传了字符串）
跨字段约束不满足（如 persistence.mode: redis 但未设置 redis_url）

# 仅校验，不启动
twinkle-server check-config -c server_config.yaml

从旧配置迁移：

旧字段	新字段
`use_megatron: true`	`backend: megatron`
`use_megatron: false`	`backend: transformers`

此外本次重构新增了 telemetry 和 persistence 两个顶层字段（旧版本中不存在），可按需添加。

可观测化

Mon, 01 Jan 0001 00:00:00 +0000

Twinkle Server 通过 OpenTelemetry 提供完整的可观测性支持，覆盖 traces（链路追踪）、metrics（指标）和 logs（日志）三个维度。

快速开始

1. 启动观测栈

项目提供了一键式的 Docker Compose 配置，基于 grafana/otel-lgtm 镜像（内置 OTel Collector、Mimir、Tempo、Loki 和 Grafana）：

cd cookbook/observability
docker compose up -d

启动后可用服务：

服务	地址	用途
Grafana	`http://localhost:3000`	仪表盘和数据探索
OTLP gRPC	`localhost:4317`	Twinkle 的 `otlp_endpoint` 指向此处
OTLP HTTP	`localhost:4318`	同上，HTTP 替代

2. 配置 Server

在 server_config.yaml 中启用遥测：

telemetry:
 enabled: true
 otlp_endpoint: http://localhost:4317

3. 安装依赖

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

4. 启动 Server

twinkle-server launch -c server_config.yaml

5. 访问 Grafana

打开 http://localhost:3000，默认账号 admin / admin。

telemetry 配置字段

字段	类型	默认值	说明
`enabled`	bool	`false`	是否启用遥测管线
`service_name`	str	`twinkle-server`	上报的服务名称
`otlp_endpoint`	str	`http://localhost:4317`	OTel Collector 的 gRPC 地址
`debug`	bool	`false`	为 `true` 时将 spans/metrics 输出到控制台（不走 OTLP）
`export_interval_ms`	int	`30000`	指标导出间隔（毫秒）
`resource_attributes`	dict	`{}`	附加到所有遥测数据的资源属性

内置 Grafana 仪表盘

预配置的 Twinkle Server Overview 仪表盘包含以下面板：

HTTP 请求速率和 P95 延迟（按 Gateway / Model / Sampler / Processor 分组）
活跃资源数（sessions、models、sampling sessions、futures）
任务队列深度、执行 P95、等待时间 P95
限流拒绝数和任务完成状态统计

指标命名参考

Twinkle 使用点号分隔的 OpenTelemetry 指标名。Prometheus OTLP 接收端会将点号转为下划线，并为单调计数器追加 _total：

OpenTelemetry 名	Prometheus 名
`twinkle.http.requests.total`	`twinkle_http_requests_total`
`twinkle.http.request.duration_seconds`	`twinkle_http_request_duration_seconds_bucket`
`twinkle.queue.depth`	`twinkle_queue_depth`
`twinkle.task.execution_seconds`	`twinkle_task_execution_seconds_bucket`
`twinkle.task.wait_seconds`	`twinkle_task_wait_seconds_bucket`
`twinkle.rate_limit.rejections.total`	`twinkle_rate_limit_rejections_total`
`twinkle.tasks.total`	`twinkle_tasks_total`
`twinkle.sessions.active`	`twinkle_sessions_active`
`twinkle.models.active`	`twinkle_models_active`
`twinkle.sampling_sessions.active`	`twinkle_sampling_sessions_active`
`twinkle.futures.active`	`twinkle_futures_active`

*.active 资源 gauge 直接读取绝对值，不要对其使用 rate() 或 increase()。

链路追踪

Twinkle 的 spans 命名空间为 twinkle.server.<component>（Gateway / Model / Sampler / Processor）。每个请求携带 twinkle.session_id 和 trace_id 关联键，支持跨部署的全链路追踪。

在 Grafana 中切换数据源为 Tempo 即可按 service name 或 span name 搜索链路。

生产部署建议

cookbook/observability 中的 LGTM 一体化镜像仅适用于本地开发和演示。生产环境建议：

分别部署 Mimir / Tempo / Loki / Grafana，配合持久化存储和多副本
前置独立的 OTel Collector 层进行采样和路由
server_config.yaml 中的 telemetry 配置和指标名称在生产环境保持不变

常见问题

Grafana 显示 “No data”

确认 telemetry.enabled: true
确认 worker 日志中出现 Worker telemetry initialized
设置 debug: true 可先在控制台确认 spans 正常产生，再切回 debug: false

Twinkle 无法连接到 Collector

otlp_endpoint 必须从 Twinkle 进程可达。如果 Twinkle 运行在另一个容器中，使用 Docker 网络内部地址如 http://twinkle-lgtm:4317

资源 gauge 一直为 0

只有 cleanup-leader worker 推送资源计数。如果超过 export_interval_ms × 2 后仍为 0，检查日志中是否有 “became cleanup leader” 消息

清理

cd cookbook/observability
docker compose down -v # -v 同时删除数据卷

Twinkle 客户端

Mon, 01 Jan 0001 00:00:00 +0000

Twinkle Client 是原生客户端，设计理念是：将 from twinkle import 改为 from twinkle_client import，即可将本地训练代码迁移为远端调用，原有训练逻辑无需改动。

初始化

from twinkle_client import init_twinkle_client

# 初始化客户端，连接到 Twinkle Server
client = init_twinkle_client(
 base_url='http://127.0.0.1:8000', # Server 地址
 api_key='your-api-key' # 认证令牌（可通过环境变量 TWINKLE_SERVER_TOKEN 设置）
)

初始化完成后，client 对象（TwinkleClient）提供以下管理功能：

# 健康检查
client.health_check()

# 列出当前用户的训练运行
runs = client.list_training_runs(limit=20)

# 获取特定训练运行详情
run = client.get_training_run(run_id='xxx')

# 列出检查点
checkpoints = client.list_checkpoints(run_id='xxx')

# 获取检查点路径（用于恢复训练）
path = client.get_checkpoint_path(run_id='xxx', checkpoint_id='yyy')

# 获取最新检查点路径
latest_path = client.get_latest_checkpoint_path(run_id='xxx')

从本地代码迁移到远端

迁移非常简单，只需将 import 路径从 twinkle 替换为 twinkle_client：

# 本地训练代码（原始）
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset
from twinkle.model import MultiLoraTransformersModel

# 远端训练代码（迁移后）
# DataLoader 和 Dataset 使用本地 twinkle 或远端 twinkle_client 均可
from twinkle.dataloader import DataLoader # 或 from twinkle_client.dataloader import DataLoader
from twinkle.dataset import Dataset # 或 from twinkle_client.dataset import Dataset
from twinkle_client.model import MultiLoraTransformersModel

训练循环、数据处理等逻辑完全不需要修改。

完整训练示例（Transformers 后端）

import dotenv
dotenv.load_dotenv('.env')

from peft import LoraConfig
from twinkle import get_logger
from twinkle.dataset import DatasetMeta
from twinkle_client import init_twinkle_client

# DataLoader 和 Dataset 使用本地 twinkle 或远端 twinkle_client 均可
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset
from twinkle_client.model import MultiLoraTransformersModel

logger = get_logger()

base_model = 'Qwen/Qwen3.5-4B'
base_url = 'http://localhost:8000'
api_key = 'EMPTY_API_KEY'

# Step 1: 初始化客户端
client = init_twinkle_client(base_url=base_url, api_key=api_key)

# 列出服务器支持的模型
print('Available models:')
for item in client.get_server_capabilities().supported_models:
 print('- ' + item.model_name)

# Step 2: 查询已有训练运行（可选，用于恢复训练）
runs = client.list_training_runs()
resume_path = None
for run in runs:
 logger.info(run.model_dump_json(indent=2))
 checkpoints = client.list_checkpoints(run.training_run_id)
 for checkpoint in checkpoints:
 logger.info(checkpoint.model_dump_json(indent=2))
 # 取消注释以从检查点恢复：
 # resume_path = checkpoint.twinkle_path

# Step 3: 准备数据集
# data_slice 可限制加载的数据量
dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(500)))

# 设置 chat 模板，使数据匹配模型的输入格式
dataset.set_template('Qwen3_5Template', model_id=f'ms://{base_model}', max_length=512)

# 数据预处理：替换占位符为自定义名称
dataset.map('SelfCognitionProcessor',
 init_args={'model_name': 'twinkle模型', 'model_author': 'ModelScope社区'})

# 编码数据集为模型可用的 token
dataset.encode(batched=True)
# 数据量大时可用 num_proc 多进程加速：
# dataset.encode(batched=True, num_proc=8)
# 使用 twinkle_client.dataset 时，encode 是通过 HTTP 调用远端服务，
# 默认 600 秒超时，可用 timeout 参数按需调大：
# dataset.encode(batched=True, num_proc=8, timeout=3600)

# 创建 DataLoader
dataloader = DataLoader(dataset=dataset, batch_size=4)

# Step 4: 配置模型
model = MultiLoraTransformersModel(model_id=f'ms://{base_model}')

# 配置 LoRA：对所有线性层应用低秩适配器
lora_config = LoraConfig(target_modules='all-linear')
# gradient_accumulation_steps=2 表示累积 2 个 micro-batch 的梯度后再执行一次优化器更新
model.add_adapter_to_model('default', lora_config, gradient_accumulation_steps=2)

# 设置模板、处理器、损失函数
model.set_template('Qwen3_5Template')
model.set_processor('InputProcessor', padding_side='right')
model.set_loss('CrossEntropyLoss')

# 设置优化器（如果服务器使用 Megatron 后端，仅支持 Adam 优化器）
model.set_optimizer('Adam', lr=1e-4)

# 设置学习率调度器（如果服务器使用 Megatron 后端，不支持 LR 调度器）
# model.set_lr_scheduler('LinearLR')

# Step 5: 恢复训练（可选）
start_step = 0
if resume_path:
 logger.info(f'Resuming from checkpoint {resume_path}')
 progress = model.resume_from_checkpoint(resume_path)
 dataloader.resume_from_checkpoint(progress['consumed_train_samples'])
 start_step = progress['cur_step']

# Step 6: 训练循环
logger.info(model.get_train_configs().model_dump())

for epoch in range(3):
 logger.info(f'Starting epoch {epoch}')
 for cur_step, batch in enumerate(dataloader, start=start_step + 1):
 # 前向传播 + 反向传播
 model.forward_backward(inputs=batch)

 # 梯度裁剪 + 优化器更新（等价于依次调用 clip_grad_norm / step / zero_grad / lr_step）
 model.clip_grad_and_step()

 # 每 2 步打印一次指标（与 gradient_accumulation_steps 对齐）
 if cur_step % 2 == 0:
 metric = model.calculate_metric(is_training=True)
 logger.info(f'Current is step {cur_step} of {len(dataloader)}, metric: {metric.result}')

 # Step 7: 保存检查点
 twinkle_path = model.save(
 name=f'twinkle-epoch-{epoch}',
 save_optimizer=True,
 consumed_train_samples=dataloader.get_state()['consumed_train_samples'],
 )
 logger.info(f'Saved checkpoint: {twinkle_path}')

# Step 8: 上传到 ModelScope Hub（可选）
# YOUR_USER_NAME = "your_username"
# hub_model_id = f'{YOUR_USER_NAME}/twinkle-self-cognition'
# model.upload_to_hub(
# checkpoint_dir=twinkle_path,
# hub_model_id=hub_model_id,
# async_upload=False
# )

Twinkle Client 场景下，推荐的断点续训流程是：

先通过 client.list_checkpoints(...) 或 client.get_latest_checkpoint_path(...) 获取已有 checkpoint 路径。
调用 model.resume_from_checkpoint(resume_path) 恢复权重、优化器、调度器、随机数状态和训练进度元数据。
使用返回结果中的 consumed_train_samples 调用 dataloader.resume_from_checkpoint(...)，跳过已经训练过的数据。

完整示例可直接参考 cookbook/client/twinkle/self_host/self_cognition.py。

Megatron 后端的差异

使用 Megatron 后端时，客户端代码的主要差异：

# Megatron 后端不需要显式设置 loss（由 Megatron 内部计算）
# model.set_loss('CrossEntropyLoss') # 不需要

# 优化器和 LR 调度器使用 Megatron 内置默认值
model.set_optimizer('default', lr=1e-4)
model.set_lr_scheduler('default', lr_decay_steps=1000, max_lr=1e-4)

其余数据处理、训练循环、检查点保存等代码完全相同。

Tinker 客户端

Mon, 01 Jan 0001 00:00:00 +0000

Tinker Client 适用于已有 Tinker 训练代码的场景。通过 init_tinker_client 初始化后，会对 Tinker SDK 进行 patch，使其指向 Twinkle Server，其余代码可直接复用已有的 Tinker 训练代码。

初始化

# 在导入 ServiceClient 之前，先初始化 Tinker 客户端
from twinkle import init_tinker_client

init_tinker_client()

# 直接使用 tinker 中的 ServiceClient
from tinker import ServiceClient

service_client = ServiceClient(
 base_url='http://localhost:8000', # Server 地址
 api_key=os.environ.get('MODELSCOPE_TOKEN') # 建议设置为 ModelScope Token
)

# 验证连接：列出 Server 上可用的模型
for item in service_client.get_server_capabilities().supported_models:
 print("- " + item.model_name)

init_tinker_client 做了什么？

调用 init_tinker_client 时，会自动执行以下操作：

Patch Tinker SDK：绕过 Tinker 的 tinker:// 前缀校验，使其可以连接到标准 HTTP 地址
设置请求头：注入 X-Ray-Serve-Request-Id 和 Authorization 等必要的认证头

初始化之后，直接导入 from tinker import ServiceClient 即可连接到 Twinkle Server，所有已有的 Tinker 训练代码都可以直接使用，无需任何修改。

完整训练示例

注意：Tinker 兼容模式的 DataLoader 和 Dataset 只支持从本地 twinkle 导入，不支持 twinkle_client。

import os
import numpy as np
from tqdm import tqdm
from tinker import types
from twinkle import init_tinker_client
from twinkle.dataloader import DataLoader
from twinkle.dataset import Dataset, DatasetMeta
from twinkle.preprocessor import SelfCognitionProcessor
from twinkle.server.common import input_feature_to_datum

# Step 1: 在导入 ServiceClient 之前，先初始化 Tinker 客户端
init_tinker_client()

from tinker import ServiceClient

base_model = 'Qwen/Qwen3.5-4B'
base_url = 'http://localhost:8000'
api_key = 'EMPTY_API_KEY'

# Step 2: 准备数据集
dataset = Dataset(dataset_meta=DatasetMeta('ms://swift/self-cognition', data_slice=range(500)))
dataset.set_template('Qwen3_5Template', model_id=f'ms://{base_model}', max_length=256)
dataset.map(SelfCognitionProcessor('twinkle模型', 'twinkle团队'), load_from_cache_file=False)
dataset.encode(batched=True, load_from_cache_file=False)
dataloader = DataLoader(dataset=dataset, batch_size=8)

# Step 3: 初始化训练客户端
service_client = ServiceClient(base_url=base_url, api_key=api_key)

# 创建 LoRA 训练客户端（rank=16 指定 LoRA 适配器秩）
training_client = service_client.create_lora_training_client(base_model=base_model, rank=16)

# Step 4: 训练循环
for epoch in range(3):
 print(f'Epoch {epoch}')
 for step, batch in tqdm(enumerate(dataloader)):
 # 将 Twinkle 的 InputFeature 转换为 Tinker 的 Datum 格式
 input_datum = [input_feature_to_datum(input_feature) for input_feature in batch]

 # 发送数据到 Server：前向 + 反向传播
 fwdbwd_future = training_client.forward_backward(input_datum, 'cross_entropy')

 # 优化器更新：Adam 更新模型权重
 optim_future = training_client.optim_step(types.AdamParams(learning_rate=1e-4))

 # 等待两个操作完成
 fwdbwd_result = fwdbwd_future.result()
 optim_result = optim_future.result()

 # 计算每 token 加权平均 log-loss 用于监控
 logprobs = np.concatenate([output['logprobs'].tolist() for output in fwdbwd_result.loss_fn_outputs])
 weights = np.concatenate([example.loss_fn_inputs['weights'].tolist() for example in input_datum])
 print(f'Loss per token: {-np.dot(logprobs, weights) / weights.sum():.4f}')
 print(f'Training Metrics: {optim_result}')

 # 每个 epoch 保存检查点
 save_future = training_client.save_state(f'twinkle-lora-{epoch}')
 save_result = save_future.result()
 print(f'Saved checkpoint to {save_result.path}')

推理采样

Tinker 兼容模式支持推理采样功能（需要 Server 配置了 Sampler 服务）。

从训练中采样

在训练完成后，可以直接从训练客户端创建采样客户端：

# 保存当前权重并创建采样客户端
sampling_client = training_client.save_weights_and_get_sampling_client(name='my-model')

# 准备推理输入
prompt = types.ModelInput.from_ints(tokenizer.encode("English: coffee break\nPig Latin:"))
params = types.SamplingParams(
 max_tokens=20, # 最大生成 token 数
 temperature=0.0, # 贪心采样（确定性输出）
 stop=["\n"] # 遇到换行停止
)

# 生成多条补全
result = sampling_client.sample(prompt=prompt, sampling_params=params, num_samples=8).result()

for i, seq in enumerate(result.sequences):
 print(f"{i}: {tokenizer.decode(seq.tokens)}")

从检查点采样

也可以加载已保存的检查点进行推理：

import os
from tinker import types
from twinkle import init_tinker_client
from twinkle.data_format import Message, Trajectory
from twinkle.template import Template

# 在导入 ServiceClient 之前，先初始化 Tinker 客户端
init_tinker_client()

from tinker import ServiceClient

base_model = 'Qwen/Qwen3.5-4B'
base_url = 'http://localhost:8000'
api_key = 'EMPTY_API_KEY'

service_client = ServiceClient(base_url=base_url, api_key=api_key)

# 从已保存的检查点创建采样客户端
sampling_client = service_client.create_sampling_client(
 model_path='twinkle://run_id/weights/checkpoint_name', # 检查点的 twinkle:// 路径
 base_model=base_model
)

# 使用 Twinkle 的 Template 构建多轮对话输入
template = Template(model_id=f'ms://{base_model}')

trajectory = Trajectory(
 messages=[
 Message(role='system', content='You are a helpful assistant'),
 Message(role='user', content='你是谁？'),
 ]
)

input_feature = template.batch_encode([trajectory], add_generation_prompt=True)[0]
input_ids = input_feature['input_ids'].tolist()

prompt = types.ModelInput.from_ints(input_ids)
params = types.SamplingParams(
 max_tokens=50, # 最大生成 token 数
 temperature=0.2, # 低温度，更聚焦的回答
)

# 生成多条补全
print('Sampling...')
future = sampling_client.sample(prompt=prompt, sampling_params=params, num_samples=8)
result = future.result()

# 解码并打印每条响应
print('Responses:')
for i, seq in enumerate(result.sequences):
 print(f'{i}: {repr(template.decode(seq.tokens))}')

发布检查点到 ModelScope Hub

训练完成后，可以通过 REST client 将检查点发布到 ModelScope Hub：

rest_client = service_client.create_rest_client()

# 从 tinker 路径发布检查点
# 需要在初始化客户端时设置有效的 ModelScope token 作为 api_key
rest_client.publish_checkpoint_from_tinker_path(save_result.path).result()
print("Published checkpoint to ModelScope Hub")