skypilot

SkyPilot 技能

SkyPilot 是一个统一框架，可在任意云、Slurm 或 Kubernetes 上运行 AI 工作负载。它提供统一接口，可在 25+ 个云平台（AWS、GCP、Azure、Coreweave、Nebius、Lambda、Together AI、RunPod 等）、Kubernetes 集群和 Slurm 集群上启动集群、运行作业并提供模型服务。

何时使用 SkyPilot

在以下情况下使用 SkyPilot：

• 管理任意云、Slurm 或 Kubernetes 集群上的计算资源
• 在任意云、Kubernetes 或 Slurm 上启动 CPU/GPU/TPU（GB300、GB200、B200、H200、H100 等）
• 运行训练、微调或批量推理作业
• 通过自动扩缩和多云副本提供模型服务（SkyServe）
• 运行具有自动生命周期管理和故障恢复的长时间作业（托管作业）
• 在各云平台中寻找价格最低或可用性最高的 GPU

以下情况不要使用 SkyPilot：

• 仅在本地运行的工作负载（直接使用 Docker/conda）

功能：何时使用什么

SkyPilot 有三种核心抽象。请在工作流的各个阶段使用合适的抽象：

1. SkyPilot 集群（sky launch / sky exec）— 交互式开发和调试

• 用于初期开发、调试和实验
• 启动集群，通过 SSH 登录或连接 VSCode/Cursor（code --remote ssh-remote+CLUSTER），快速迭代
• 集群会持续运行，直到你停止/关闭它或触发自动停止
• 最适合：原型开发、调试、短期实验

2. 托管作业（sky jobs launch）— 长时间训练和批处理作业

• 用于提交应无人值守运行的长时间作业
• 管理完整生命周期：资源配置、执行、故障恢复和拆除
• 自动从抢占式实例中断、配额限制和暂时性故障中恢复
• 支持云平台、Kubernetes 和 Slurm（处理抢占和配额）
• 最适合：训练运行、微调、超参数搜索、批量推理

3. SkyServe（sky serve up）— 生产环境模型服务

• 用于通过自动扩缩大规模提供模型服务
• 先使用 sky launch + 开放端口测试服务配置，然后使用 sky serve up 扩展规模
• 提供负载均衡、自动扩缩和多云副本
• 最适合：模型服务端点、API 服务

开始之前（Agent 初始化）

进行初始化，以确认 SkyPilot 已安装、已连接到 API 服务并配置了云凭据。确认后，直接开始用户的任务。

步骤 1：检查安装情况和 API 服务连接

sky api info

输出包含	含义	下一步操作
服务版本和状态	服务正在运行且已连接	初始化完成。 跳转到用户的任务。
No SkyPilot API server is connected	未连接服务	转到下方的“启动或连接服务”。
Could not connect to SkyPilot API server	无法访问远程服务或身份验证已过期	告知用户，并建议运行 sky api login --relogin -e <endpoint> 重新连接。
command not found: sky	未安装 SkyPilot	转到下方的“安装 SkyPilot”。

安装 SkyPilot（仅在找不到 sky 命令时）：

pip install "skypilot[aws,gcp,kubernetes]"  # Pick clouds the user needs

如果不清楚用户需要哪些云平台，请询问用户，然后重新运行 sky api info。

启动或连接服务（仅在服务“未运行”时）：

询问用户：

你是否有要连接的现有 SkyPilot API 服务，还是需要我在本地启动一个？

• 连接到现有服务： sky api login -e <API_SERVER_URL> — 向用户获取 URL。
• 在本地启动： sky api start

完成任一路径后，重新运行 sky api info，确认服务可以访问。

步骤 2：检查云凭据（仅适用于全新配置 — 如果服务已在运行，则跳过）

sky check -o json

此操作会显示已启用或已禁用的云平台。如果用户目标云平台未启用，请指导用户设置凭据（参见故障排除）。

必要命令

使用 -o json 搭配状态／查询命令，可获取结构化 JSON 输出，而非表格。

集群 — 交互式开发与调试：

命令	说明
sky launch -c NAME task.yaml	启动集群或运行任务
sky exec NAME task.yaml	在现有集群上运行任务（跳过资源配置）；每次都会同步工作目录
sky exec NAME task.yaml -d	同上，但立即分离运行（不流式输出日志）
sky status -o json	显示所有集群
sky logs NAME	流式输出集群中的作业日志
sky logs NAME --no-follow	输出现有日志后立即退出
sky logs NAME --tail 50	输出最后 50 行日志后退出
sky logs NAME --status	以不同退出码表示状态：0=成功、100=失败、101=未完成、102=未找到、103=已取消
sky queue NAME -o json	列出集群上的作业及其状态（结构化 JSON）
sky stop NAME / sky start NAME	停止／重启以节省费用（保留磁盘）
sky down NAME	完全拆除集群
sky gpus list -o json	列出各云平台上可用的 GPU 类型

托管作业 — 长时间运行、无需人工值守的工作负载：

命令	说明
sky jobs launch task.yaml	启动托管作业（自动管理生命周期并恢复）
sky jobs queue -o json	显示所有托管作业及其状态
sky jobs logs JOB_ID	流式输出托管作业的日志
sky jobs cancel JOB_ID	取消托管作业

SkyServe — 支持自动扩缩容的模型服务：

命令	说明
sky serve up serve.yaml -n NAME	启动模型服务
sky serve status NAME	显示服务状态和端点 URL
sky serve update NAME new.yaml	更新正在运行的服务（滚动更新）
sky serve down NAME	拆除服务

完整的 CLI 参考请参阅 CLI 参考。

快速开始

# Launch a GPU cluster
sky launch -c mycluster --gpus H100 -- nvidia-smi

# Run a task from YAML
sky launch -c mycluster task.yaml

# SSH into cluster
ssh mycluster

# Connect VSCode or Cursor to the cluster for interactive development
code --remote ssh-remote+mycluster /home/user/sky_workdir
# or: cursor --remote ssh-remote+mycluster /home/user/sky_workdir

# Tear down
sky down mycluster

Task YAML 结构

Task YAML 是 SkyPilot 的主要接口。所有字段均为可选项。

# task.yaml
name: my-training-job

# Local directory to sync to remote ~/sky_workdir
workdir: .

# Number of nodes (for distributed training)
num_nodes: 1

resources:
  # GPU/TPU accelerators (SkyPilot auto-selects the cheapest cloud/region)
  accelerators: H200:8
  # Optional: pin to a specific cloud/region/infra
  # infra: aws  # or aws/us-east-1, k8s, ssh/my-pool
  # If infra is left out, SkyPilot automatically fails over across all
  # enabled clouds/regions to find the cheapest available option.
  # Use spot instances for cost savings
  use_spot: false
  # Disk size in GB
  disk_size: 256
  # Open ports for serving
  ports: 8080

# Environment variables (accessible in file_mounts, setup, and run)
envs:
  MODEL_NAME: my-model
  BATCH_SIZE: 32

# Setup: runs once on cluster creation, cached on reuse
setup: |
  pip install torch transformers

# Run: the main command
run: |
  python train.py --model $MODEL_NAME --batch-size $BATCH_SIZE

完整的 YAML 架构（包括文件挂载、SkyPilot 设置的环境变量和高级字段）请参阅 YAML 规范。

GPU 和云平台选择

重要：让 SkyPilot 选择云平台和区域。 不要通过解析 sky gpus list 的输出手动选择云平台／区域／实例。SkyPilot 的优化器会自动从所有已启用的云平台中选择可用的最低成本选项。只有当用户明确指定某个云平台或区域时，才设置 infra:。

默认行为（推荐）： 只需指定 GPU 类型。SkyPilot 会自动找到成本最低的云平台／区域：

resources:
  accelerators: H200:8  # SkyPilot picks the cheapest cloud/region with H200:8

如果用户未指定 GPU 类型，请询问他们需要哪种 GPU（或他们要运行哪种模型／工作负载，以便你推荐）。不要运行 sky gpus list 并替他们选择——应列出选项让用户决定，或使用 any_of 让 SkyPilot 尽可能提高可用性：

# Let SkyPilot choose from multiple acceptable GPU types (cheapest wins)
resources:
  any_of:
    - accelerators: H100:8
    - accelerators: A100-80GB:8
    - accelerators: A100:8

只有当用户有明确偏好时才使用 ordered：

# Try H100 first on AWS, fall back to GCP, then A100
resources:
  ordered:
    - infra: aws/us-east-1
      accelerators: H100:8
    - infra: gcp/us-central1
      accelerators: H100:8
    - infra: aws/us-west-2
      accelerators: A100-80GB:8

只有当用户明确提出类似“使用 AWS”或“在 GCP us-central1 上运行”的要求时，才设置 infra:：

resources:
  infra: aws             # User asked for AWS specifically
  accelerators: H100:8

集群生命周期

# Launch and run a task
sky launch -c mycluster task.yaml

# Launch with autostop at launch time (preferred: saves cost, no follow-up command needed)
sky launch -c mycluster task.yaml -i 30        # stop after 30 min idle
sky launch -c mycluster task.yaml -i 30 --down # tear down after 30 min idle

# Override or pass environment variables via CLI
sky launch -c mycluster task.yaml --env MODEL_NAME=llama3 --env BATCH_SIZE=64

# Re-run a different task on the same cluster (fast, skips provisioning)
sky exec mycluster another_task.yaml

# Run an inline command
sky exec mycluster -- python train.py --epochs 10

# Set autostop after launch (use if you forgot to set -i at launch time)
sky autostop mycluster -i 30        # stop after 30 min idle, preserving disk (can restart with sky start)
sky autostop mycluster -i 30 --down # tear down after 30 min idle (disk is deleted, cannot restart)

# Stop to save costs, restart later
sky stop mycluster
sky start mycluster

# Tear down completely
sky down mycluster

工作目录同步行为

每次执行 sky exec 前，都会通过 rsync 将 workdir: 同步到远程端的 ~/sky_workdir。rsync 采用增量同步——本地已删除的文件不会从远程端删除。 这可能导致实验使用过时的构建产物或旧配置运行。

如需确保环境干净，请先通过 SSH 清理，再执行 sky exec：

ssh mycluster "rm -rf ~/sky_workdir"
sky exec mycluster task.yaml

如果只需删除特定产物，也可以在 run: 中清理：

run: |
  find ~/sky_workdir/build -name '*.o' -delete 2>/dev/null || true
  cd ~/sky_workdir && make

托管作业

对于需要无人值守运行的长时间作业，请使用 sky jobs launch。SkyPilot 会管理完整生命周期，包括资源配置、执行、从抢占、配额限制或故障中恢复，以及资源释放：

# managed-job.yaml
name: training-job

resources:
  accelerators: A100:8

run: |
  python train.py --resume-from-checkpoint

# Launch as managed job
sky jobs launch managed-job.yaml

# Check status
sky jobs queue -o json

# Stream logs
sky jobs logs <job_id>

# Cancel
sky jobs cancel <job_id>

检查点模式：训练脚本应将检查点保存到持久化存储（云存储桶或卷），并在重启时从最新检查点恢复。SkyPilot 负责集群恢复，脚本负责状态恢复。

SkyServe：模型服务

# serve.yaml
resources:
  accelerators: A100:1
  ports: 8080

run: |
  python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3.1-8B-Instruct \
    --port 8080

service:
  readiness_probe: /v1/models
  replica_policy:
    min_replicas: 1
    max_replicas: 3
    target_qps_per_replica: 5

# Start service
sky serve up serve.yaml -n my-llm

# Check status / get endpoint
sky serve status my-llm
sky serve status my-llm --endpoint

# Update (rolling)
sky serve update my-llm new-serve.yaml

# Tear down
sky serve down my-llm

常见工作流

微调工作流

1. 编写任务 YAML，在 setup 中安装依赖项，在 run 中指定训练命令
2. 使用 file_mounts 或 workdir 同步代码
3. 使用 sky launch -c train task.yaml 启动
4. 使用 sky logs train 监控
5. 使用 sky exec train -- python eval.py 在同一集群上评估
6. 完成后运行 sky down train

超参数扫描

1. 创建包含 envs 的参数化 YAML
2. 启动多个托管作业：

   for lr in 1e-4 1e-5 1e-6; do
     sky jobs launch sweep.yaml --env LR=$lr --name sweep-lr-$lr
   done
   

3. 使用 sky jobs queue -o json 监控

模型服务部署

1. 编写包含 service: 部分的服务 YAML
2. 运行 sky serve up serve.yaml -n my-service
3. 获取端点：sky serve status my-service --endpoint
4. 更新模型：sky serve update my-service updated.yaml

并行提交实验

使用 sky exec -d 向多个 VM 提交作业而不阻塞，然后收集结果：

# Submit all experiments (detached, returns after job is queued)
for i in 1 2 3 4; do
  sky exec exp-vm-0$i task.yaml --env LR=1e-$i -d
done

# Get the latest job ID from a cluster
job_id=$(sky queue exp-vm-01 -o json \
  | python3 -c "import sys, json; jobs = json.load(sys.stdin).get('exp-vm-01', []); print(max(j['job_id'] for j in jobs) if jobs else '')")

# Wait for a specific job and fetch last 50 lines
sky logs exp-vm-01 $job_id --status && sky logs exp-vm-01 $job_id --tail 50

# Check all jobs across a cluster at once
sky queue exp-vm-01 -o json

转换 Slurm 工作负载

如果用户已有 sbatch 脚本、salloc 工作流，或询问某条 Slurm 命令如何映射到 SkyPilot，请先阅读 Migrating from Slurm，再编写任何 YAML。 映射中有一些不明显、容易出错的部分：

• --time 不会映射到 autostop —— Slurm 不支持自动停止。 请使用 config.slurm.sbatch_options.time。
• 通常应省略裸写的 srun <cmd>，而不是将其转换：run 已经会在每个节点上执行。只有 MPI/PMIx 启动器才保留 srun，并且 需要加上 --overlap 和 rank-0 守卫。
• --account / --qos / --exclusive 等其他未建模指令应通过 config.slurm.sbatch_options 传递，该配置会将它们原样传给 sbatch。
• sbatch --array 映射到 sky jobs launch --num-jobs 和 $SKYPILOT_JOB_RANK，而不是 shell 循环。

使用 sky launch --dryrun <yaml> 验证结果 —— 请注意，sky jobs launch 没有 --dryrun，因此即使最终命令是 sky jobs launch，也要通过 sky launch 执行试运行。

不要假定用户想要离开 Slurm。SkyPilot 会通过现有 Slurm 集群的登录节点提交作业；迁移到 Kubernetes 是另一个问题，其限制也有所不同。

Agent 反馈循环

以编程方式使用 SkyPilot 时，请遵循以下循环：

1. 验证：sky launch --dryrun task.yaml（检查资源可用性和成本）
2. 启动：sky launch -c mycluster task.yaml
3. 监控：sky status -o json 和 sky queue mycluster -o json
4. 等待完成：sky logs mycluster <JOB_ID>（持续输出日志，便于观察进度并处理停滞；会阻塞，直到作业结束；从 sky queue mycluster -o json 获取 JOB_ID）。对于不需要中间输出的长时间作业，请改用 sky logs mycluster <JOB_ID> --status（静默阻塞，成功时退出码为 0）。
5. 检查输出：sky logs mycluster <JOB_ID> --no-follow 或 sky logs mycluster <JOB_ID> --tail 100
6. 调试：ssh mycluster（交互式）
7. 迭代：sky exec mycluster updated_task.yaml（在现有集群上运行）
8. 清理：sky down mycluster

切勿使用 sleep + sky queue 轮询 —— 请使用 sky logs CLUSTER JOB_ID 持续输出日志，并阻塞至作业完成。如果只需要退出码，请使用 --status；如果要在作业完成后获取最近的输出，请使用 --tail N。

调查托管作业

当用户询问“我的作业正在做什么”或“为什么它处于等待/失败状态”时，按顺序运行以下命令，并在问题得到解答后立即停止：

1. sky jobs queue -v -o json — 查看 status、details、failure_reason（-v 会添加 details）。对于尚未启动的作业，details 就是答案：它会说明集群正在等待什么，例如 Slurm 的 QOSGrpGRES 或 Dependency 原因，以及作业排队所在的分区
2. sky jobs logs JOB_ID --tail 100 --no-follow — 查看近期任务输出；使用 --controller 查看配置/恢复日志

如何解读 details 和 Slurm 等待原因，请参阅作业调查。

Agent 常见错误

错误	错误原因	应改为
根据 sky gpus list 的输出手动选择云或区域	SkyPilot 优化器会自动完成，而且做得更好	只需设置 accelerators:，让 SkyPilot 选择
使用 sky launch 运行长期无人值守作业	被抢占或中断后无法恢复	使用 sky jobs launch 运行无人值守作业
工作完成后忘记运行 sky down 或设置 autostop	空闲集群会造成费用浪费	始终清理，或在启动时使用 -i <minutes> --down
用户未要求时硬编码 infra: aws	限制可用性并增加成本	仅在用户明确指定云服务时设置 infra:
没有使用 envs: 设置可配置的值	难以复用或通过 CLI 覆盖	在 YAML 中使用 envs:，并通过 --env KEY=VAL 设置参数
运行 sky launch 时未使用 -c <name>	会创建随机命名的集群，难以引用	始终使用 -c 为集群命名
解析状态命令的表格输出	表格格式面向人类，解析起来不可靠	使用 -o json 获取结构化输出
使用已弃用的 cloud:/region:/zone: 字段	这些字段已弃用，应使用 infra:	改用 infra: aws/us-east-1
使用 sleep + sky queue 轮询作业状态	浪费令牌、容易引入时序错误，且不可靠	使用 sky logs CLUSTER JOB_ID --status 阻塞等待作业完成
认为工作目录同步会删除远程文件	rsync 只会添加文件；旧的远程文件会在多次 sky exec 调用之间保留	通过 SSH 手动清理 ~/sky_workdir，或在 run: 脚本中清理
只关心最后的输出时未使用 --tail	长作业流式传输完整日志会浪费令牌	使用 sky logs CLUSTER JOB_ID --tail 50 查看最后 N 行

常见问题速查

问题	解决方案
GPU 不可用	使用 any_of 设置回退选项，或尝试其他区域/云服务
设置耗时过长	SkyPilot 会缓存设置；重新运行时使用 sky exec 跳过设置
任务静默失败	检查 sky logs <cluster> 或 ssh <cluster> 进行调试
集群卡在 INIT	运行 sky down <cluster> 后重新启动
抢占/配额问题	使用 sky jobs launch 自动恢复并管理生命周期
端口无法访问	确保在资源中设置了 ports:，且安全组允许流量通过
文件同步缓慢	对于大型数据集，使用云存储桶挂载，而不是 workdir
凭据错误	运行 sky check -o json，检查哪些云服务已禁用

参考资料

如需详细的参考文档：

• CLI 参考 — 所有命令和标志
• YAML 规范 — 完整的任务 YAML 架构、文件挂载、环境变量
• Python SDK — 编程 API 和 SDK 用法
• 高级模式 — 多云、分布式训练、生产环境模式
• 从 Slurm 迁移 — 将 sbatch 脚本转换为任务 YAML、Slurm 命令/环境变量映射、Slurm 专属限制
• 作业排查 — 哪个命令可以回答“我的作业正在做什么，为什么”；读取 details、事件、Slurm 等待原因
• 故障排除 — 错误诊断和解决方案
• 示例 — 可直接复制粘贴的任务 YAML 示例