ServiceClient

改编自 Tinker SDK（Apache-2.0）

参考文档改编自 Tinker SDK，已为 Mint Recursive 做了调整。详见归属说明与 Apache 2.0 许可。

class mint.ServiceClient ( user_metadata=None , project_id=None , ** kwargs )¶

ServiceClient 是 Mint Recursive API 的主入口，提供以下方法：

查询服务端能力与健康状态
为模型训练流程创建 TrainingClient 实例
为文本生成与推理创建 SamplingClient 实例
为列出权重等 REST API 操作创建 RestClient 实例

# Near instant
client = ServiceClient()
# Takes a moment as we initialize the model and assign resources
training_client = client.create_lora_training_client(base_model="Qwen/Qwen3-8B")
# Near-instant
sampling_client = client.create_sampling_client(base_model="Qwen/Qwen3-8B")
# Near-instant
rest_client = client.create_rest_client()

参数：

user_metadata ( dict[str, str] | None ，默认： None ) —— 附加到所创建 session 的可选元数据。
project_id ( str | None ，默认： None ) —— 附加到所创建 session 的可选项目 ID。未提供时回退到 MINT_PROJECT_ID 环境变量。
**kwargs ( Any ) —— 传给底层 HTTP 客户端的高级选项，包括 API key、headers 和连接设置。

property holder¶

有状态的 holder。已废弃：仅为兼容直接访问 ServiceClient 内部结构的调用方而保留。

返回： InternalClientHolder

get_server_capabilities ()¶

查询服务端支持的功能与能力。

返回： GetServerCapabilitiesResponse，包含可用模型、功能和限制

capabilities = service_client.get_server_capabilities()
print(f"Supported models: {capabilities.supported_models}")
print(f"Max batch size: {capabilities.max_batch_size}")

异步变体： get_server_capabilities_async()

create_lora_training_client ( base_model , rank=32 , seed=None , train_mlp=True , train_attn=True , train_unembed=True , user_metadata=None )¶

创建用于 LoRA 微调的 TrainingClient。

参数：

base_model ( str ) —— 要微调的基座模型名称（如 "Qwen/Qwen3-8B"）
rank ( int ，默认： 32 ) —— LoRA 秩，控制适配矩阵的规模（默认 32）
seed ( int | None ，默认： None ) —— 初始化的随机种子。None 表示随机种子。
train_mlp ( bool ，默认： True ) —— 是否训练 MLP 层（默认 True）
train_attn ( bool ，默认： True ) —— 是否训练注意力层（默认 True）
train_unembed ( bool ，默认： True ) —— 是否训练 unembedding 层（默认 True）
user_metadata ( dict[str, str] | None ，默认： None ) —— 附加到训练任务的可选元数据

返回： 配置好 LoRA 训练的 TrainingClient

training_client = service_client.create_lora_training_client(
base_model="Qwen/Qwen3-8B",
rank=16,
train_mlp=True,
train_attn=True
)
# Now use training_client.forward_backward() to train

异步变体： create_lora_training_client_async()

create_training_client_from_state ( path , user_metadata=None , weights_access_token=None )¶

从已保存的模型权重创建 TrainingClient。

此方法只加载模型权重，不加载优化器状态。如需同时恢复优化器状态（如 Adam 动量），请使用 create_training_client_from_state_with_optimizer。

参数：

path ( str ) —— 已保存权重的 Mint Recursive 路径（如 "mindlab-toolkit://run-id/weights/checkpoint-001"）
user_metadata ( dict[str, str] | None ，默认： None ) —— 附加到新训练任务的可选元数据
weights_access_token ( str | None ，默认： None ) —— 用于加载其他账户下 checkpoint 的可选访问令牌。

返回： 加载了指定权重的 TrainingClient

# Resume training from a checkpoint (weights only, optimizer resets)
training_client = service_client.create_training_client_from_state(
"mindlab-toolkit://run-id/weights/checkpoint-001"
)
# Continue training from the loaded state

异步变体： create_training_client_from_state_async()

create_training_client_from_state_with_optimizer ( path , user_metadata=None , weights_access_token=None )¶

从已保存的模型权重和优化器状态创建 TrainingClient。

与 create_training_client_from_state 类似，但还会恢复优化器状态（如 Adam 动量），适合从上次中断处精确续训。

参数：

path ( str ) —— 已保存权重的 Mint Recursive 路径（如 "mindlab-toolkit://run-id/weights/checkpoint-001"）
user_metadata ( dict[str, str] | None ，默认： None ) —— 附加到新训练任务的可选元数据
weights_access_token ( str | None ，默认： None ) —— 用于加载其他账户下 checkpoint 的可选访问令牌。

返回： 加载了指定权重和优化器状态的 TrainingClient

# Resume training from a checkpoint with optimizer state
training_client = service_client.create_training_client_from_state_with_optimizer(
"mindlab-toolkit://run-id/weights/checkpoint-001"
)
# Continue training with restored optimizer momentum

异步变体： create_training_client_from_state_with_optimizer_async()

create_sampling_client ( model_path=None , base_model=None , retry_config=None )¶

创建用于文本生成的 SamplingClient。

参数：

model_path ( str | None ，默认： None ) —— 已保存模型权重的路径（如 "mindlab-toolkit://run-id/weights/checkpoint-001"）
base_model ( str | None ，默认： None ) —— 要使用的基座模型名称（如 "Qwen/Qwen3-8B"）
retry_config ( RetryConfig | None ，默认： None ) —— 失败请求的可选重试配置

返回： 配置好文本生成的 SamplingClient

# Use a base model
sampling_client = service_client.create_sampling_client(
base_model="Qwen/Qwen3-8B"
)
# Or use saved weights
sampling_client = service_client.create_sampling_client(
model_path="mindlab-toolkit://run-id/weights/checkpoint-001"
)

异步变体： create_sampling_client_async()

create_rest_client ()¶

创建用于 REST API 操作的 RestClient。

RestClient 提供多个 REST 端点的访问能力，可以查询模型信息、checkpoint、session，以及管理 checkpoint 可见性。

返回： 用于访问 REST API 端点的 RestClient

rest_client = service_client.create_rest_client()
# List checkpoints for a training run
checkpoints = rest_client.list_checkpoints("run-id").result()
# Get training run info
training_run = rest_client.get_training_run("run-id").result()
# Publish a checkpoint
rest_client.publish_checkpoint_from_tinker_path(
"mindlab-toolkit://run-id/weights/checkpoint-001"
).result()