AutoDL 私有云弹性部署

概述

弹性部署通过 API 或网页批量调度和启动 GPU 容器，并管理容器生命周期。

• API HOST: https://private.autodl.com
• 鉴权: 在请求 Header 中添加 Authorization: <token>（控制台 → 设置 → 开发者Token）
• Token 存储: token 存放在与本 SKILL.md 同级目录的 .env 文件中，格式见 .env.example

Token 初始化流程（由 agent 执行）

使用本 skill 前，先检查同级目录下是否存在 .env 文件：

1. 若 .env 已存在，直接读取其中的 AUTODL_TOKEN 值作为后续请求的鉴权 token
2. 若 .env 不存在，向用户提问获取 token（提示用户在 AutoDL 控制台 → 设置 → 开发者Token 中获取），然后复制 .env.example 为 .env，将 your_token_here 替换为用户输入的实际 token 值

核心概念

算力调度单元

系统将主机的 CPU 和内存按 GPU 数量等比例划分为不可拆分的调度单元。例如：8卡3090、128核CPU、720GB内存 → 每个调度单元为 3090×1 + 16vCPU + 90GB。容器配置只能为该调度单元的 1~N 倍。

三种部署类型

容器生命周期

容器生命周期 = cmd 命令执行周期。cmd 结束则容器关机。

• 前台运行（推荐）: python app.py
• 后台运行: nohup python app.py & && sleep infinity（需要 sleep infinity 阻止父进程退出）
• Conda 环境: 不要用 conda activate，直接用 /root/miniconda3/envs/my-env/bin/python xxx.py

容器复用

设置 reuse_container: true 可复用已停止容器（系统保留最长7天），显著缩短镜像拉取时间。复用时不清理原容器数据。

API 速查

CUDA 版本映射

选择不低于所需 CUDA 版本的最小可选值（高版本驱动兼容低版本 CUDA）。

基本用法

查询、停止、删除等操作需在 Header 中携带 token，agent 按上述"Token 初始化流程"获取 token 后直接调用 API：

import requests

TOKEN = "<从 .env 文件中读取到的 AUTODL_TOKEN 值>"

headers = {
    "Authorization": TOKEN,
    "Content-Type": "application/json"
}

创建部署请使用 queue_submit.py（见下节），它会自动验证参数、检查资源并排队等待。

排队提交

AutoDL 平台不支持 GPU 资源不足时排队。queue_submit.py 脚本解决了这个问题：提交前自动验证配置，GPU 不足时轮询等待，资源就绪后再提交。

使用方式

1. 根据用户需求构造部署配置 JSON 文件（格式见下方）
2. 执行脚本（<SKILL_DIR> 为本 SKILL.md 所在目录的绝对路径）：

python <SKILL_DIR>/queue_submit.py <config.json> [--interval 30] [--timeout 3600]

• stdout: JSON 结果（供 agent 解析）
• stderr: 进度日志

配置文件格式

与创建部署 API 请求体一致：

{
    "name": "my-deployment",
    "deployment_type": "ReplicaSet",
    "replica_num": 2,
    "reuse_container": true,
    "container_template": {
        "gpu_name_set": ["RTX 4090"],
        "gpu_num": 1,
        "cuda_v": 118,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "cd /root && python app.py",
        "price_from": 100,
        "price_to": 9000,
        "image_uuid": "image-xxxxxxxxxx"
    }
}

成功输出

{
    "status": "success",
    "deployment_uuid": "833f1cd5a764fa3",
    "waited_seconds": 120
}

错误处理（agent 必须遵循）

脚本返回结构化 JSON 错误。收到错误时，agent 必须根据 error_type 向用户提问，引导其修正参数，而非直接重试：

错误输出示例

{
    "status": "error",
    "error_type": "gpu_type_not_found",
    "message": "请求的 GPU 型号均不存在: ['RTX 5090']",
    "details": {
        "requested": ["RTX 5090"],
        "available_gpus": ["RTX 4090", "RTX 3090", "RTX 3080 Ti"]
    }
}

最佳实践

1. 镜像: 静态环境打入镜像，避免频繁更新；变更频繁的代码/模型放网络存储
2. 启动命令: 不要后台执行（&），否则父进程退出容器即关闭
3. 路径: 先 cd 再执行，如 cd /root && python app.py
4. 复杂命令: 写成 shell 脚本放入镜像或文件存储中
5. 异常调试: 将 cmd 改为 sleep infinity 保持容器运行，SSH 登录后手动排查

⚠️ 常见陷阱

&& 与 || 组合会导致 Job 类型部署无法停止

避免使用 cmd1 && cmd2 || cmd3 模式，这会导致容器持续运行不停止。

# ❌ 避免使用
ls /data && process || echo "fallback"

# ✅ 改用分号分隔
ls /data ; process ; true

详细参考

• 完整 API 参数与响应格式，见 api-reference.md
• 常用场景代码示例，见 examples.md