Lepton AI

面向 NVIDIA DGX Cloud Lepton 的 Python 库与 lep CLI

主页 •
示例 •
文档 •
CLI 参考

LeptonAI Python 库让你可以在 Python 和命令行中操作 NVIDIA DGX Cloud Lepton 平台。核心特性包括：

• 提供 lep 命令行工具，用于创建和管理端点（endpoint）、Dynamo 图部署、批处理作业（batch job）、开发 Pod（dev pod）、Ray 集群、微调作业（fine-tuning job）、存储、密钥等，并可查看受管 Slurm 集群与作业。
• 提供 Client，可以像调用本地 Python 函数一样调用已部署的端点。
• 提供 Pythonic 的配置规范，可直接下发到云端。
• 提供技能（Skills），让智能体（agent）替你操作 Lepton 平台。

快速开始

安装本库，同时也会安装 lep 命令行工具：

pip install -U leptonai

如需从 main 分支安装最新开发版本（需要 Git）：

pip install -U "git+https://github.com/leptonai/leptonai.git@main"

登录你的工作区（若未传入凭据，会打开浏览器获取）：

lep login

将容器镜像部署为一个端点，然后查看它：

lep endpoint create -n my-endpoint --container-image my-registry/my-app:latest
lep endpoint list
lep endpoint status -n my-endpoint

在启用了安全端点默认值（secure endpoint defaults）的工作区中，创建端点时若不传
--tokens，端点会自动受到保护。创建命令会打印生成的 API token，请保存该值供客户端认证使用。你也可以改为提供一个或多个可重复的 --tokens 值，或者通过
--allow-unauthenticated-access 显式选择退出认证（CLI 会显示警告）。--public 选项只控制 IP 可达性，并不会禁用 API token 认证。
lep endpoint status 会分别以 IP Access 和 API Token Authentication 报告这两个维度。

如果 SDK 调用方未指定端点认证方式，应使用
client.deployment.create_with_response(...) 并保存返回资源中的 token。旧的 create(...) 方法保持其布尔返回值约定，无法返回服务器生成的凭据，因此对于可能请求服务器生成凭据的调用，它会发出 RuntimeWarning。SDK 更新时仅发送空列表可能无法清除 api_tokens：请在同一次更新中设置 allow_unauthenticated_access=true，或将列表替换为至少一个 token。

lep endpoint get 默认会遮蔽（redact）明文 token。仅当你需要包含凭据的响应或可复用的配置导出时，才使用 --show-tokens，并将该输出视为密钥妥善处理。此前隐藏的 update --remove-tokens 选项已被拒绝；如需显式退出认证，请使用
--allow-unauthenticated-access。

认证模式的更新需要显式指定：

# 替换 token 并启用 token 认证
lep endpoint update -n my-endpoint --tokens MY_TOKEN

# 清除 token，并显式允许无需 API token 认证的请求
lep endpoint update -n my-endpoint --allow-unauthenticated-access

你也可以启动批处理作业和开发 Pod：

# 运行一个批处理作业
lep job create -n my-job --container-image my-registry/my-trainer:latest --command "python train.py"

# 启动一个交互式开发 Pod
lep pod create -n my-pod --resource-shape gpu.a10

# 通过工作区 API 在 Pod 中打开 shell（无需配置 SSH）
lep pod shell -n my-pod

# 通过启用了 Teleport SSH 的方式连接 Pod（需要本地 tsh）
lep pod ssh -n my-pod --transport teleport

lep pod shell、lep endpoint shell、lep job shell 和 lep raycluster shell
打开的交互式 shell 与仪表盘终端相同。该会话通过 HTTPS 经由工作区 API 隧道传输，因此无需 SSH 密钥、公网 IP 或 Teleport 客户端。它们遵循仪表盘的规则：Pod 必须处于 Ready 状态，并在其最新的副本中打开；拥有多个运行中副本的端点或作业需要指定 --replica；已归档的作业和平台管理的调优作业没有 shell；Ray 集群 shell 会在未停止集群的头节点上打开，除非用 --replica 选择其他节点。空闲 shell 会发送 keepalive，以免工作区入口关闭它们。

Teleport SSH 命令要求 PATH 中存在 tsh v18 或更高版本。CLI 会在读取登录配置或启动 SSO 之前检查客户端版本；客户端缺失、版本过旧或无法识别时，会给出可操作的错误。此最低版本检查并不保证与所有 Teleport 集群版本兼容。

Teleport SSH 会复用你本地的 Teleport 登录，必要时启动 SSO 登录。认证连接器（connector）会自动选择；可用
--teleport-auth <connector> 指定。Lepton API 凭据与 Teleport
登录相互独立。你的工作区
（dev_pod_teleport）、节点组和 Pod 都必须启用 Teleport，且 Pod 必须处于 Ready 状态。

Pod SSH 在服务器提供 Teleport 连接信息时会使用它。否则，如下文 Jobs 所述，它会使用当前活跃的 tsh 配置或
--teleport-proxy <host>:443，并以 root 身份连接到 Pod 的
<workspace-id>-<pod-name> 节点。若未选择配置，请提供
--teleport-proxy 以启动登录。若服务器提供了代理，则省略该选项。不指定 --transport teleport 时，lep pod ssh 使用直接 SSH。

如果你不知道应使用哪个代理，请向工作区或节点组管理员咨询 Teleport 代理（host[:port]），以及（如有需要）SSO 连接器名称。用这些值替换下面的占位符：

tsh login --proxy=<proxy>
# 如果管理员指定了 SSO 连接器：
tsh login --proxy=<proxy> --auth=<connector>

完成 tsh 显示的登录步骤后，重新运行你的 lep ... ssh 命令。
或者，向 lep pod ssh --transport teleport
或 lep job ssh 传入 --teleport-proxy <proxy> 以自动启动登录；如有需要，再加上 --teleport-auth <connector>。CLI 会替你选择 SSH 目标和 Linux 账户。该 Linux
账户（如 root）与你登录 Teleport 所用的身份是分开的。如果访问被拒绝，请让管理员核实你对相应工作负载的访问权限。

当作业所在工作区启用了 job_teleport，且其镜像/入口点会启动 Teleport 代理时，作业也可以通过 Teleport 访问：

lep job replicas --id <job-id>
lep job ssh --id <job-id> --replica <replica-id>
# 或者选择名称唯一的作业（会自动选择一个就绪副本）
lep job ssh --name <job-name>
# 在未登录时，或需要从另一个代理切换时，指定代理
lep job ssh --id <job-id> --replica <replica-id> --teleport-proxy <host>:443

Job SSH 默认使用当前活跃的 tsh 配置，因为 Job API 不发布
Teleport 连接信息。它使用标准 Lepton 代理的
<workspace-id>-<replica-id> 主机名和工作区标签来查找一个节点，然后以 root 身份连接到该节点的 Teleport 节点 ID。历史副本和未就绪副本会被排除；存在多个就绪副本时需要 --replica。作业必须处于 Running
或 Starting 状态。Job SSH 不会安装代理，也不会改变工作负载的启动命令。可使用 --teleport-auth 选择 SSO 连接器。

Slurm 计算节点也支持 Teleport SSH：

lep node list-nodes --node-group <node-group>
lep node ssh --node-group <node-group-name-or-id> --id <node-id>

Node SSH 会自动发现 Slurm 集群、Teleport 代理、机器主机名和 Linux
账户，因此从不需要 --teleport-proxy。需要时，CLI 会以拥有你的 Lepton API token 的用户身份替你运行 tsh login，因此不支持服务账户 token（Service Account Token）；该用户需要具备工作区用户或管理员权限。计算组必须启用 Teleport 并使用主机网络。对于使用 Pod 网络的集群，请改为对你自己拥有的运行中 Slurm 作业使用 lep slurm job ssh。会话会在计算容器中打开；Slurm 账户权限和作业分配策略仍然适用。可用 --teleport-auth 覆盖 SSO 连接器。

对于启用了受管 Slurm 的工作区，可查看集群和作业：

lep slurm cluster list --name prod --status Ready
lep slurm cluster shell -n production
lep slurm job list --cluster production --status Running --include-archived
lep slurm job attempts -i 12345 --steps
lep slurm job log -n my-training-job --follow
lep slurm devpod get --cluster production
lep slurm devpod ssh --cluster production

登录节点、运行中的作业和 Dev Pod 也可以通过 Teleport 访问：

lep slurm cluster ssh -n production
lep slurm job ssh -i 12345 --node <allocated-node>
lep slurm devpod ssh --cluster production --transport teleport

与 lep node ssh 类似，它们会从 Slurm 集群找到 Teleport 代理，并以拥有你的 Lepton API token 的用户身份登录 Teleport。登录节点和作业 SSH 会以你的 Slurm Linux 账户连接，该账户由集群的 LDAP 映射根据你的邮箱推导得出。登录节点 SSH 要求集群处于 Ready 状态且其登录节点已启用 Teleport；--node 可选择第一个之外的登录节点。作业 SSH 要求作业由你的 Slurm 账户拥有且正在运行；跨多个节点的作业需要 --node。Dev Pod SSH 使用 Dev Pod 报告的 Teleport 节点和 Linux 账户。如果 Teleport 访问被拒绝，请让 Slurm 集群管理员核实。

个人 Slurm Dev Pod 可在 lep slurm devpod 下使用；运行
lep slurm --help 可查看完整的命令树。devpod get 显示有效配置、身份、连接信息和仪表盘链接；devpod ssh 会运行平台报告的 bastion 命令，除非指定了
--transport teleport。Slurm 作业的提交与取消仍是通过集群上的原生 Slurm 操作（sbatch、squeue、
scancel）完成，而非 Lepton API 变更。

Dynamo 图部署（使用 vLLM、SGLang 或 TensorRT-LLM 后端的多服务 LLM 推理）有独立的命令组。每个 -svc 块配置一个服务；前端（frontend）是必需的，worker 会继承其节点组：

lep dynamo create -n my-dynamo --framework vllm \
  -svc frontend --resource-shape cpu.small --node-group my-node-group \
  -svc worker --resource-shape gpu.h100-80gb --replicas 2 -e MODEL=Qwen/Qwen3-0.6B
lep dynamo status -n my-dynamo
lep dynamo replica log -n my-dynamo -s worker --tail 200
lep dynamo update -n my-dynamo -svc worker --replicas 4

Dynamo 1.3.1 的多节点 worker 使用 --node-count 配置；--replicas 统计的是独立的 worker 组。vLLM、SGLang 和 TensorRT-LLM 均支持聚合（aggregated）与分离式（disaggregated）配置：

lep dynamo create -n my-multi --framework vllm \
  -svc frontend --resource-shape cpu.small --node-group my-node-group \
  -svc worker --resource-shape gpu.h100-80gb --node-count 2
lep dynamo create -n my-pd --framework vllm --serving-mode disaggregated \
  -svc frontend --resource-shape cpu.small --node-group my-node-group \
  -svc prefill-worker --resource-shape gpu.h100-80gb --node-count 2 \
  -svc decode-worker --resource-shape gpu.h100-80gb --node-count 2
lep dynamo create -n my-trt --framework trtllm \
  -svc frontend --resource-shape cpu.small --node-group my-node-group \
  -svc worker --resource-shape gpu.h100-80gb --node-count 2
lep dynamo update -n my-multi --dry-run -svc worker --node-count 4

请选择你的节点组中可用的资源规格（shape）。默认命令会根据所选规格推导 GPU 并行度；未知或非整数的 GPU 数量需要显式指定
--command。更新时，会将识别出的默认命令与变更后的并行度同步，并保护自定义命令。

运行 lep --help，或对任意子命令运行 lep <command> --help，可探索全部功能。完整指南见 CLI 参考。

从 Python 调用端点

端点运行后，可用 Client 从 Python 调用它。它会读取端点的 OpenAPI schema，并将每个路径暴露为一个方法：

from leptonai.client import Client, local

# 连接到工作区端点……
c = Client("my-workspace", "my-endpoint", token="MY_TOKEN")
# ……或连接到本地运行的服务：
c = Client(local(port=8080))

# 发现可用路径及其文档
print(c.paths())
print(c.run.__doc__)

# 像调用本地函数一样调用端点
print(c.run(inputs="hello world"))

查看更多示例

你可以在 示例仓库 中找到更多示例，完整指南见 文档。

技能：从 Claude Code 或 Codex 操作 Lepton

本仓库附带一个 智能体技能（agent skill），可让 Claude Code（或 Codex）替你驱动 lep CLI——用自然语言列出端点、查看作业和开发 Pod、检查工作区状态以及管理工作负载。它使用上文安装的同一个 lep CLI，因此请确保它已认证到你的工作区。

该插件位于 plugins/lepton-cli，为 Claude Code、Codex 和 Cursor 提供各自的清单（.claude-plugin/、.codex-plugin/、.cursor-plugin/），它们共享同一个技能 skills/lepton-cli。它被列入本仓库的两个市场（marketplace）：面向 Claude Code 的 .claude-plugin/marketplace.json 和面向 Codex 的 .agents/plugins/marketplace.json。

Codex — 将此仓库添加为市场，然后安装插件：

codex plugin marketplace add leptonai/leptonai
codex plugin add lepton-cli@lepton-skills

或以交互方式浏览：在 Codex CLI 中运行 /plugins（或在 Codex 应用中打开 Plugins），找到 Lepton CLI 并安装。

Claude Code — 从 Lepton 市场一行安装，无需克隆：

/plugin marketplace add leptonai/leptonai
/plugin install lepton-cli@lepton-skills

启动新会话，然后试着问 “列出我的 Lepton 工作区中的端点。” 在任何修改或删除工作负载的命令执行前，该技能都会请求明确的确认。

# Codex
cp -R plugins/lepton-cli/skills/lepton-cli "${CODEX_HOME:-$HOME/.codex}/skills/lepton-cli"
# Claude Code（个人技能）
cp -R plugins/lepton-cli/skills/lepton-cli "$HOME/.claude/skills/lepton-cli"

贡献

本仓库使用 uv 来管理其 Python 环境和依赖。安装 uv 后，在仓库根目录运行以下命令：

uv sync --locked
uv run lep --help

这会将本地源码和开发工具安装到 .venv，使用 .python-version 中的 Python 版本和 uv.lock 中的依赖。使用 uv run lep 可在不激活环境的情况下运行 CLI。

欢迎并非常感谢贡献与合作。请查看 贡献者指南 了解如何参与。

许可证

Lepton AI Python 库基于 Apache 2.0 许可证发布。

开发者说明：LeptonAI 早期开发在一个独立的单体仓库（mono-repo）中进行，因此你可能会看到来自 leptonai/lepton 仓库的提交。今后我们打算将此开源仓库作为唯一可信来源。