ByteNoteByteNote
字

字节笔记本

2026年2月22日

Lepton AI Python SDK 完全指南

#产品文档

Lepton AI Python SDK 是一个功能强大的开发工具包，让开发者能够轻松构建、调试和部署 AI 模型。本文详细介绍 SDK 的安装、认证流程以及核心 API 的使用方法。

安装与认证

安装 SDK

使用 pip 安装 Lepton AI Python SDK：

bash
pip3 install -U leptonai

登录认证

安装完成后，使用 CLI 进行认证：

bash
lep login

在 GUI 环境中，系统会自动打开浏览器；在终端环境中，会显示一个 URL 供手动访问。登录后，在 Dashboard → Settings → Tokens 中创建工作区 token，格式为 xxxxxx:**************************。

验证安装是否成功：

bash
lep workspace list

SDK 基本流程

使用 Lepton AI Python SDK 的基本流程包含三个步骤：

  1. 初始化客户端 - 创建 APIClient 实例
  2. 定义任务 - 配置需要执行的任务参数
  3. 执行任务 - 调用相应 API 完成任务

初始化客户端

python
from leptonai.api.v2.client import APIClient

client = APIClient()

核心 API 资源

Lepton AI Python SDK 提供以下核心 API 资源：

资源说明
Batch Jobs批量任务的管理和监控
Dev Pods开发环境管理
Endpoints模型部署端点
Events系统事件查询
Health Checks健康状态检查
Ingress网络入口配置
Logs日志检索
Monitoring指标和监控
Node Groups计算节点组管理
Queue任务队列管理
Readiness就绪探针
Replicas副本管理
Secrets密钥管理
Templates任务模板
Workspaces工作空间管理

关键数据类型

SDK 使用以下核心类型：

  • 批量任务: leptonai.api.v1.types.job.LeptonJob 配合 LeptonJobUserSpec
  • 端点/部署: leptonai.api.v1.types.deployment.LeptonDeployment
  • 开发 Pod: 与部署使用相同类型

完整的 API 类型定义可在 GitHub 仓库查看：https://github.com/leptonai/leptonai/tree/main/leptonai/api/v1/types

资源规格配置

使用 CLI v0.26.4+ 查看可用的资源规格：

bash
lep node resource-shape

在配置中使用 Shapes 列的值作为 resource_shape 字段。

共享存储挂载

配置共享存储挂载：

python
mount = {
    "path": "/",  # 存储中的源目录
    "mount_path": "/my-mount",  # 容器中的目标路径（不能是 "/"）
    "from": "node-nfs:lepton-shared-fs"  # storage_type:storage_name
}

将挂载配置添加到任务规格：

python
job_spec = LeptonJobUserSpec(
    # ... 其他字段 ...
    mounts=[mount]
)

私有镜像仓库认证

在 UI 的 Settings > Registries 中创建密钥，然后在任务中使用：

python
job_spec = LeptonJobUserSpec(
    # ... 其他字段 ...
    image_pull_secrets=["my-registry-secret"]
)

节点预留配置

python
job_spec = LeptonJobUserSpec(
    # ... 其他字段 ...
    node_reservation="my-reservation-name"
)

完整示例代码

以下是一个完整的批量训练任务示例：

python
from leptonai.api.v2.client import APIClient
from leptonai.api.v1.types.job import LeptonJob, LeptonJobUserSpec
from leptonai.api.v1.types.affinity import LeptonResourceAffinity

# 初始化客户端
client = APIClient()

# 获取节点组和节点 ID
node_groups = client.node_group.list()
node_group_id = next(
    ng.id for ng in node_groups
    if ng.name == "my-node-group"
)
nodes = client.node.list(node_group_id)
node_ids = [node.id for node in nodes]

# 定义任务规格
job_spec = LeptonJobUserSpec(
    resource_shape="A100-80GB-SXM",
    container_image="nvcr.io/nvidia/pytorch:23.10-py3",
    command=["python", "train.py"],
    num_workers=2,
    affinity=LeptonResourceAffinity(
        allowed_nodes=node_ids
    )
)

# 创建并启动任务
job = LeptonJob(
    spec=job_spec,
    metadata={"name": "my-training-job"}
)
client.job.create(job)

运行脚本：

bash
python run.py

常用 CLI 命令

bash
# 列出运行中的部署
lep deployment list

# 查看部署状态
lep deployment status --name <name>

# 查看可用资源规格
lep node resource-shape

总结

Lepton AI Python SDK 提供了简洁而强大的 API，让开发者能够：

  • 使用原生 Python 构建模型，无需容器或 Kubernetes 知识
  • 在本地调试和测试模型
  • 使用单条命令部署到云端
  • 灵活选择硬件配置（CPU/GPU）
  • 水平扩展应用以处理大规模工作负载

更多详细信息请参考 NVIDIA DGX Cloud Lepton 官方文档。

产品文档
上一篇

OpenCode 配置教程：通过 PackyAPI 使用 Claude、Codex、Gemini 模型

下一篇

Lepton AI Python SDK 完全指南

分享: