pytrio.ServiceClient

class ServiceClient:
    def __init__(
        self,
        api_key: str | None = None,
    ):

ServiceClient 是 PyTRIO API 的主要入口。它会提供以下功能：

为模型训练工作流程生成 TrainingClient 实例
生成用于文本生成和推理的 SamplingClient 实例
为 REST API 操作（例如列出权重）生成 RestClient 实例。

import pytrio as trio

client = trio.ServiceClient()

# 创建 TrainingClient 实例
training_client = client.create_lora_training_client(base_model="Qwen/Qwen3.5-4B")

# 创建 SamplingClient 实例
sampling_client = client.create_sampling_client(base_model="Qwen/Qwen3.5-4B")

# 创建 RestClient 实例
rest_client = client.create_rest_client()

参数

参数	类型	默认值	说明
`api_key`	`str \| None`	`None`	API Key；不传则读取当前进程配置，可由本地登录状态、`PYTRIO_API_KEY` 或 `pytrio.configure(api_key=...)` 提供，详见环境变量配置

初始化时，ServiceClient 会自动完成登录验证、建立 Socket 连接，并拉取可用模型列表。每个 ServiceClient 在构造开始时复制当前进程配置，之后调用 pytrio.configure(...) 不会改变已有 Client 的连接地址、超时等设置。

属性

属性	类型	说明
`user_id`	`str`	API Key 创建者的 user CUID，与 `user_cuid` 相同
`user_cuid`	`str`	Control 认证响应中的稳定 user CUID
`username`	`str`	API Key 创建者的用户名
`display_name`	`str \| None`	API Key 创建者的展示名，未设置时为 `None`
`workspace_cuid`	`str`	Control 认证响应中的 workspace CUID
`workspace_name`	`str`	Control 认证响应中的 workspace 名称
`service_session_cuid`	`str`	当前根 Client 创建的 service session CUID
`run_id`	`str`	`service_session_cuid` 的调用侧别名

方法

get_supported_models

def get_supported_models(self) -> list[str]

获取当前可用的模型列表。

返回值

list[str] — 模型名称列表，例如 ['Qwen/Qwen3.5-4B']。

示例

models = client.get_supported_models()
print(models)  # ['Qwen/Qwen3.5-4B', ...]

create_lora_training_client

def create_lora_training_client(
    self,
    base_model: str,
    rank: int = 32,
    seed: int | None = None,
    train_mlp: bool = True,
    train_attn: bool = True,
    train_unembed: bool = True,
) -> TrainingClient

创建一个用于 LoRA 微调的 TrainingClient 实例。

参数

参数	类型	默认值	说明
`base_model`	`str`	—	基础模型，例如 `'Qwen/Qwen3.5-4B'`
`rank`	`int`	`32`	LoRA rank，范围 4–64
`seed`	`int \| None`	`None`	用于初始化的随机种子
`train_mlp`	`bool`	`True`	是否训练 MLP 层
`train_attn`	`bool`	`True`	是否训练注意力层
`train_unembed`	`bool`	`True`	是否训练 `lm_head` 层

返回值

TrainingClient — 包含训练状态的客户端实例。

示例

training_client = client.create_lora_training_client(
    base_model="Qwen/Qwen3.5-4B",
    rank=16,
    train_unembed=False,
)

create_sampling_client

def create_sampling_client(
    self,
    base_model: str,
    model_path: str | None = None,
) -> SamplingClient

创建一个用于文本生成与推理的 SamplingClient 实例。

参数

参数	类型	默认值	说明
`base_model`	`str`	`""`	基础模型，例如 `'Qwen/Qwen3.5-4B'`
`model_path`	`str \| None`	`None`	LoRA 模型 checkpoint path url，传入后会在初始化时自动加载

返回值

SamplingClient — 模型采样客户端实例。

示例

# 使用基础模型
sampling_client = client.create_sampling_client(base_model="Qwen/Qwen3.5-4B")

# 加载已有 LoRA 权重
sampling_client = client.create_sampling_client(
    base_model="Qwen/Qwen3.5-4B",
    model_path="/path/to/checkpoint",
)

create_rest_client

def create_rest_client(self) -> RestClient

创建一个 RestClient 实例，用于执行 REST API 操作（例如列出权重、查询检查点信息）。

返回值

RestClient — REST 客户端实例。

示例

rest_client = client.create_rest_client()
checkpoint_list = rest_client.list_user_checkpoints().result()

create_training_client_from_state

def create_training_client_from_state(self, path: str) -> TrainingClient

从已保存的检查点恢复，创建一个 TrainingClient 实例（仅恢复模型权重，不恢复优化器状态）。

参数

参数	类型	说明
`path`	`str`	检查点路径

返回值

TrainingClient — 包含训练状态的客户端实例。

示例

training_client = client.create_training_client_from_state(
    path="/path/to/checkpoint"
)

create_training_client_from_state_with_optimizer

def create_training_client_from_state_with_optimizer(self, path: str) -> TrainingClient

从已保存的检查点恢复，创建一个 TrainingClient 实例，同时恢复优化器状态，可用于无缝续训。

参数

参数	类型	说明
`path`	`str`	检查点路径

返回值

TrainingClient — 包含训练状态与优化器状态的客户端实例。

示例

# 恢复完整训练状态（含优化器），可无缝续训
training_client = client.create_training_client_from_state_with_optimizer(
    path="/path/to/checkpoint"
)

异步方法

create_lora_training_client_async

async def create_lora_training_client_async(
    self,
    base_model: str,
    rank: int = 32,
    seed: int | None = None,
    train_mlp: bool = True,
    train_attn: bool = True,
    train_unembed: bool = True,
) -> TrainingClient

异步创建一个用于 LoRA 微调的 TrainingClient 实例。参数和返回值与 create_lora_training_client 一致。

参数

参数	类型	默认值	说明
`base_model`	`str`	—	基础模型，例如 `'Qwen/Qwen3.5-4B'`
`rank`	`int`	`32`	LoRA rank，范围 4–64
`seed`	`int \| None`	`None`	用于初始化的随机种子
`train_mlp`	`bool`	`True`	是否训练 MLP 层
`train_attn`	`bool`	`True`	是否训练注意力层
`train_unembed`	`bool`	`True`	是否训练 `lm_head` 层

返回值

TrainingClient — 包含训练状态的客户端实例。

示例

training_client = await client.create_lora_training_client_async(
    base_model="Qwen/Qwen3.5-4B",
    rank=16,
    train_unembed=False,
)

create_sampling_client_async

async def create_sampling_client_async(
    self,
    base_model: str,
    model_path: str | None = None,
) -> SamplingClient

异步创建一个用于文本生成与推理的 SamplingClient 实例。参数和返回值与 create_sampling_client 一致。

参数

参数	类型	默认值	说明
`base_model`	`str`	`""`	基础模型，例如 `'Qwen/Qwen3.5-4B'`
`model_path`	`str \| None`	`None`	LoRA 模型 checkpoint path url，传入后会在初始化时自动加载

返回值

SamplingClient — 模型采样客户端实例。

示例

# 使用基础模型
sampling_client = await client.create_sampling_client_async(base_model="Qwen/Qwen3.5-4B")

# 加载已有 LoRA 权重
sampling_client = await client.create_sampling_client_async(
    base_model="Qwen/Qwen3.5-4B",
    model_path="/path/to/checkpoint",
)

create_training_client_from_state_async

async def create_training_client_from_state_async(self, path: str) -> TrainingClient

异步从已保存的检查点恢复，创建一个 TrainingClient 实例（仅恢复模型权重，不恢复优化器状态）。参数和返回值与 create_training_client_from_state 一致。

参数

参数	类型	说明
`path`	`str`	检查点路径

返回值

TrainingClient — 包含训练状态的客户端实例。

示例

training_client = await client.create_training_client_from_state_async(
    path="/path/to/checkpoint"
)

create_training_client_from_state_with_optimizer_async

async def create_training_client_from_state_with_optimizer_async(self, path: str) -> TrainingClient

异步从已保存的检查点恢复，创建一个 TrainingClient 实例，同时恢复优化器状态，可用于无缝续训。参数和返回值与 create_training_client_from_state_with_optimizer 一致。

参数

参数	类型	说明
`path`	`str`	检查点路径

返回值

TrainingClient — 包含训练状态与优化器状态的客户端实例。

示例

# 恢复完整训练状态（含优化器），可无缝续训
training_client = await client.create_training_client_from_state_with_optimizer_async(
    path="/path/to/checkpoint"
)

本页目录