AutoDL Research Pilot

AutoDL Research Pilot 为 Codex 提供了一种实用方式来回答两个问题：这个实验现在是否应该租用 GPU，以及哪个可用 GPU 值得租用？

Enterprise Elastic 工作流从官方 AutoDL API 开始。它读取账户余额以及按地域、CUDA、CPU、RAM 和价格过滤的 GPU 库存；当令牌可以访问部署和私有镜像时，也会将它们纳入。调度器将该实时状态与特定工作负载的吞吐量证据结合，比较总完成时间和总成本，并构建一个精确的 Container 部署请求。在研究人员批准之前，该请求一直保留在本地。

较高的每小时费率并不自动意味着昂贵。如果更快的 GPU 能将 30 小时的运行缩短到 8 小时，它可能完成得更早且总成本更低。相反，顶级 GPU 可能大部分时间都在等待 DataLoader。Research Pilot 对运行进行建模，而不是对产品名称排序。

它能做什么

• 将官方 API 作为控制平面。 Enterprise 发现、规划、部署创建、列出、停止和删除都是 CLI 和 MCP 的一等操作。

• 让可用性变得可执行。 库存查询使用与部署中相同的 region、CUDA、CPU/RAM、GPU-model 和 price_to 过滤器。

• 优化整个运行过程。 运行时间、设置、传输、排队、工作负载吞吐量、不确定性和已知固定成本共同输入一次成本/时间 Pareto 比较。

• 理解研究约束。 VRAM、预算、截止时间、库存和运行就绪状态是硬过滤器。模型、数据、精度、随机种子、批次语义和评估不会为了适配更便宜的显卡而悄悄改变。

• 提供清晰的偏好。 economy 最小化保守总成本；time 在预算内最小化完成时间；balanced 选择中间点；custom 接受你自己的权重。

• 让付费操作可审查。 变更操作默认为请求预览。确认后的 Elastic 创建会在 API 调用前立即重新检查钱包容量、重复的运行名称、私有镜像的访问权限/存在性、完整候选库存和截止时间。

• 以 CLI、MCP 服务器和 Codex Skill 的形式交付。 该 Skill 还涵盖 GPU 诊断、存储、镜像、前台命令、检查点以及 Pro/Elastic 生命周期差异。

Related MCP server: Run:AI MCP Server

快速开始：Enterprise Elastic

安装

git clone https://github.com/chengxi271-commits/autodl-research-pilot.git
cd autodl-research-pilot
python -m venv .venv

Windows PowerShell：

.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[mcp]"
$env:AUTODL_TOKEN = "YOUR_TOKEN"

Linux / macOS：

source .venv/bin/activate
python -m pip install -e '.[mcp]'
export AUTODL_TOKEN='YOUR_TOKEN'

将令牌保存在进程环境中。项目绝不需要在 TOML、JSON、命令行参数或源代码管理中提供令牌。

描述本次运行

复制 Enterprise 示例，并替换镜像、命令、地域、资源边界、工作负载性能因子和价格上限：

cp examples/elastic.project.toml my-run.project.toml
cp examples/elastic.catalog.toml my-run.catalog.toml

目录刻意保持精简。它列出的是你准备使用的 GPU 配置，而不是 AutoDL 曾经提供过的每一款 GPU。账户镜像将 image_source 设为 private；AutoDL API 附录中的 UUID 则设为 public。当 dc_list 跨地域时，请在每个列出的地域准备输入和输出存储，或将列表缩小到已准备好的地域。每个 performance_factor 应来自同一工作负载或明确标注的估算值；每个 price_ceiling_cny 是你可接受的最高每小时价格，而非声称的市场报价。

发现、规划、预览

autodl-pilot discover --catalog my-run.catalog.toml --output live-context.json

autodl-pilot live-plan --project my-run.project.toml --catalog my-run.catalog.toml --profile balanced --output run.plan.json

autodl-pilot apply-live-plan --plan run.plan.json

live-plan 默认执行全新发现，因此单独的 discover 命令是可选的。当你想检查 API 返回的内容，或冻结一个只读快照用于讨论时，它很有用。

预览包含唯一的运行名称、确切的 GPU、可用地域、镜像及来源、前台命令、CPU/RAM 范围和价格上限。它不会发起任何变更调用。检查 selected.execution_ready；如果为 false，selected.needs_input 会指出缺失的账户访问权限、镜像或研究门禁。审查完一个执行就绪的请求后：

autodl-pilot apply-live-plan --plan run.plan.json --confirm

确认阶段会再次读取钱包、具有相同运行名称的活动部署、所选私有镜像以及每一个目录库存过滤器。它检查保守运行时间是否仍符合冻结的截止时间，然后调用 POST /api/v1/dev/deployment。如果所选配置消失，或之前不可用的候选出现，它会回到规划阶段，而不是依据过时的排名创建，也不会替换为未经批准的 GPU。

决策如何运作

对于 GPU 配置 g，调度器从参考运行时间开始，并估算：

compute time = reference runtime / workload performance factor
total time   = queue + setup + transfer + compute time
total cost   = fixed cost + billed time × hourly price ceiling × GPU count

置信度较低的性能证据会扩大保守时间和成本。未通过硬约束的候选永远不会进入配置评分。幸存者形成 Pareto 前沿：前沿上没有任何候选既比另一个更慢又更贵。

API 库存响应报告的是空闲显卡数量，而不是精确价格或基准速度。因此，Research Pilot 将这些事实分开处理：

1. AutoDL 库存证明价格区间内的当前可用性。

2. 目录记录 VRAM 和工作负载性能证据。

3. Elastic price_to 限制部署可能接受的最高价格；规划器使用该上限来生成保守账单。

当前的实时规划器有意创建单 GPU Container 部署。AutoDL 将库存说明为单卡查询，并警告两张空闲显卡可能位于不同主机上。多 GPU 调度应遵循同工作负载扩展测试和明确的同主机证据，而不是乐观的库存求和。

让 GPU 选择更智能

AutoDL 的官方性能表是有用的先验信息，但其运行是单卡的，使用合成的内存输入，并省略了 CPU 预处理和额外 I/O。最好使用真实模型、精度、批次语义和数据管道的一小段。

附带的 Skill 遵循简单的瓶颈规则：

• GPU 为 0%：检查设备使用情况和框架/CUDA 兼容性。

• GPU 稳定在约 90% 以上：更快的 GPU 或经过实测的单主机多 GPU 运行可能会有帮助。

• GPU 使用率低或波动：先检查 CPU、DataLoader 工作进程、存储和同步。

• CUDA OOM：在决定更大 VRAM 之前，先检查残留进程和 batch size 1。

• 进程在接近 RAM 上限时被杀：请求更多容器内存，而不是更多 VRAM。

在完成一次可比的成功运行后，将其计算时间、设置/传输开销、实际容器费率和实测瓶颈反馈到匹配的目录配置中。正是这种工作负载历史，而非通用基准表，能让后续选择不断改进。

它还将存储视为调度的一部分。热数据应放在 /root/autodl-tmp；持久化检查点和结果应在 Elastic 命令退出前放到 /root/autodl-fs 等持久存储上。有关附带来源链接的操作规则，请参阅 AutoDL 现场指南。

个人 Pro 账户

官方 Pro API 可以读取钱包、实例、状态、快照和私有镜像，并可以创建、开/关机以及释放实例。它不发布预分配市场目录或库存端点。对于新的 Pro 租用，请结合最新的控制台报价使用离线规划器：

autodl-pilot api wallet
autodl-pilot api instances
autodl-pilot api images
autodl-pilot plan --project project.toml --offers current-offers.toml --output pro.plan.json
autodl-pilot apply-plan --plan pro.plan.json

当前的 Pro 快照文档暴露了原始 payg_price 字段，但未声明其单位，因此客户端原样保留这些字段。长时间运行前，请在控制台中核实分配的价格。Pro API 创建是按量付费，支持一到四张 GPU，并提供系统磁盘扩展；API 开机支持 GPU 模式，而非控制台的无卡模式。

原始离线示例在无令牌测试调度器时仍然有用：

autodl-pilot plan --project examples/project.toml --offers examples/offers.toml --profile balanced

其价格是固定测试数据，无法通过当前报价的执行门禁。

部署运维

autodl-pilot api deployments
autodl-pilot api containers --payload '{"deployment_uuid":"DEPLOYMENT_UUID","page_index":1,"page_size":10}'
autodl-pilot api events --payload '{"deployment_uuid":"DEPLOYMENT_UUID","page_index":1,"page_size":10,"offset":0}'

autodl-pilot deployment-stop DEPLOYMENT_UUID
autodl-pilot deployment-stop DEPLOYMENT_UUID --confirm

autodl-pilot deployment-delete DEPLOYMENT_UUID
autodl-pilot deployment-delete DEPLOYMENT_UUID --confirm

Elastic 训练应在前台运行：当 cmd 退出时，容器停止。后台的 python train.py & 可能使计费和生命周期行为与研究任务脱节。停止后本地数据不会持久化：未启用复用时立即释放；复用缓存可能保留残留数据，但既不是有保障的存储，也不是可重启的容器。cmd_before_shutdown 只有五秒的时间窗口，因此检查点持久化应放在训练命令本身中。

对于通过 SSH 启动的 Pro 长时间运行，请使用 screen、tmux 或 Jupyter 终端，并将日志写入命名文件。在 release 之前检索并验证结果；停止计算和删除可恢复状态是两个独立的决策。

CLI 参考

所有正常结果和受控错误均为 JSON。运行 autodl-pilot --help 查看参数。

Codex 与 MCP

安装 mcp 附加组件，并将此仓库作为本地 Codex 插件加载。.mcp.json 面向 Windows；docs/mcp.unix.json 是 Unix 清单。MCP 提供与 CLI 相同的发现、实时规划、预览、确认、读取和生命周期操作。

Codex Skill 位于 skills/autodl-research-pilot/SKILL.md。一个有用的起始提示是：

使用 AutoDL API 检查实时 Elastic 库存，在 balanced 模式下比较我所支持的 GPU 配置，并显示确切的部署预览。在我批准之前，不要创建它。

范围

版本 0.2.0 实现了 API-first Enterprise 单 GPU Container 路径，并保留了 Pro/离线规划。API 客户端是控制面；SSH 传输、工作负载执行、指标采集和检查点检索仍是由 Skill 协调的数据面工作。Catalog 反馈由 Skill 引导，而非自动遥测。运行时成本仅在以 fixed_cost 形式提供时才包含存储。已购买的 Elastic 时长套餐余额尚未建模，因此在适用此类余额时，估算可能会高估边际现金成本。

端点和单元边界记录在 AutoDL API Boundaries 中。这是一个社区项目，与 AutoDL 无关联。

开发

python -m unittest discover -s tests -v

CI 在 Python 3.11、3.12 和 3.13 上运行测试套件。请参阅 CONTRIBUTING.md、SECURITY.md 和 问题跟踪器。

许可证

Apache-2.0