服务端（Server）
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 两个顶层字段（旧版本中不存在），可按需添加。