Metadata-Version: 2.4
Name: autodl-sdk
Version: 1.0.4
Summary: AutoDL GPU 云平台 Python 自动化 SDK —— 实例管理一行搞定
License: MIT
Project-URL: Homepage, https://github.com/your-username/autodl-sdk
Project-URL: Issues, https://github.com/your-username/autodl-sdk/issues
Keywords: autodl,gpu,cloud,automation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Dynamic: license-file

# autodl-sdk

> AutoDL GPU 云平台 Python 自动化 SDK，用几行代码完成实例管理全流程。

---

## 安装

```bash
pip install autodl-sdk
```

**依赖**：`requests >= 2.28`，Python >= 3.10

---

## 功能列表

| 功能 | 方法 | 版本 |
|------|------|------|
| 查询余额 | `mgr.get_balance()` | 基础版 |
| 获取实例列表 | `mgr.list_instances()` | 基础版 |
| 查看单个实例 | `mgr.get_instance(uuid)` | 基础版 |
| 实例开机 | `mgr.power_on(uuid)` | 基础版 |
| 实例关机 | `mgr.power_off(uuid)` | 基础版 |
| 释放实例 | `mgr.release(uuid)` | 基础版 |
| 查询可用主机 | `mgr.list_machines()` | 🔒 高级版 |
| 获取我的镜像 | `mgr.list_images()` | 🔒 高级版 |
| 创建实例 | `mgr.create(...)` | 🔒 高级版 |
| SSH 执行命令 | `ssh.run_command(cmd)` | 🔒 高级版 |
| 上传文件/目录 | `ssh.upload_file/dir(...)` | 🔒 高级版 |
| 下载文件/目录 | `ssh.download_file/dir(...)` | 🔒 高级版 |

> 🔒 高级版功能请扫码自行获取 或 点击 [加入星球](https://wx.zsxq.com/group/48885115851428?secret=vuvt0n3dagznigoffixzu2unjcp9ah6f&inviter_id=212854812818141&inviter_sid=w4zkob7ne1&share_from=InviteUrl&keyword=dofWf&type=group) 获取
![img.png](img.png)
---

## 获取 Token

1. 浏览器登录 [autodl.com](https://www.autodl.com)
2. 按 **F12** 打开开发者工具 → Network 标签
3. 随便点一个页面操作（如刷新实例列表）
4. 在请求列表中找任意一个 `api/v1/` 开头的请求
5. 查看请求头（Headers），复制 **Authorization** 字段的完整值

Token 形如 `Bearer eyJhbGci...`，**复制时需要包含 `Bearer ` 前缀**。

> ⚠️ Token 包含账户权限，请勿泄露、勿提交到 Git

---

## 代码示例

### 初始化

```python
from autodl import AutoDLClient, InstanceManager

client = AutoDLClient(token="Bearer eyJhbGci...")
mgr    = InstanceManager(client)
```

### 查询余额和实例列表

```python
print(f"余额：¥{mgr.get_balance():.2f}")

for ins in mgr.list_instances():
    print(ins["uuid"], ins["status"], ins.get("gpu_name"))
```

### 按状态过滤实例

```python
# 只看运行中的实例
running = mgr.list_instances(status=["running"])

# 只看已关机的实例
stopped = mgr.list_instances(status=["shutdown"])
```

### 开机 / 关机

```python
mgr.power_on("your-instance-uuid")   # 开机，等待 running 后返回
mgr.power_off("your-instance-uuid")  # 关机，等待 shutdown 后返回
```

### 释放实例

```python
mgr.release("your-instance-uuid")              # 已关机才能释放
mgr.release("your-instance-uuid", force=True)  # 自动先关机再释放
```

### 创建实例 🔒 高级版

```python
from autodl import IMAGE_TYPE_BASE, IMAGE_TYPE_COMMUNITY, IMAGE_TYPE_PRIVATE

# 查询最便宜的可用 4090
machines = mgr.list_machines(gpu_types=["RTX 4090", "RTX 3090"], min_cuda=12.4)
machine_id = machines[0]["machine_id"]

# 方式一：基础镜像
uuid = mgr.create(
    machine_id=machine_id,
    image_type=IMAGE_TYPE_BASE,
    base_image_url="hub.kce.ksyun.com/autodl-image/torch:cuda12.4-cudnn-devel-ubuntu22.04-py312-torch2.5.1",
)

# 方式二：社区镜像
uuid = mgr.create(
    machine_id=machine_id,
    image_type=IMAGE_TYPE_COMMUNITY,
    community_uuid="your-community-image-uuid",
)

# 方式三：我的镜像
uuid = mgr.create(
    machine_id=machine_id,
    image_type=IMAGE_TYPE_PRIVATE,
    private_image_uuid="image-47c93bf9ce",
    private_image_url="hub.kce.ksyun.com/autodl-image/torch:cuda12.4-...",
)
```

### SSH 上传代码并执行 🔒 高级版

```python
from autodl import SSHManager

ins = mgr.get_instance(uuid)
ssh = SSHManager.from_instance(ins)

# 上传项目目录
ssh.upload_dir(
    local_dir="./my_project",
    remote_dir="/root/my_project",
    exclude=["__pycache__", ".git", "output"],
)

# 安装依赖
ssh.run_command("cd /root/my_project && pip install -r requirements.txt -q", timeout=300)

# 执行主程序
ssh.run_command("cd /root/my_project && python main.py", timeout=3600)

# 下载输出结果
ssh.download_dir("/root/my_project/output", "./output")
```

### 完整自动化流程 🔒 高级版

```python
from autodl import AutoDLClient, InstanceManager, SSHManager, IMAGE_TYPE_PRIVATE, Timer

client = AutoDLClient(token="Bearer ...")
mgr    = InstanceManager(client)
timer  = Timer()

balance_before = mgr.get_balance()
uuid = None

try:
    timer.begin("创建实例")
    machines = mgr.list_machines(gpu_types=["RTX 4090"], min_cuda=12.4)
    uuid = mgr.create(
        machine_id=machines[0]["machine_id"],
        image_type=IMAGE_TYPE_PRIVATE,
        private_image_uuid="image-xxx",
        private_image_url="hub.kce.ksyun.com/...",
    )
    timer.end("创建实例")

    ins = mgr.get_instance(uuid)
    ssh = SSHManager.from_instance(ins)

    timer.begin("上传 & 运行")
    ssh.upload_dir("./project", "/root/project")
    ssh.run_command("cd /root/project && python main.py")
    timer.end("上传 & 运行")

    ssh.download_dir("/root/project/output", "./output")

finally:
    if uuid:
        mgr.power_off(uuid)
        mgr.release(uuid)

    timer.summary()
    print(f"消耗：¥{balance_before - mgr.get_balance():.4f}")
```

---

## 常见问题

**Q：Token 需要加 `Bearer ` 前缀吗？**
A：需要。直接从浏览器 F12 里复制 Authorization 字段的完整值即可，通常形如 `Bearer eyJhbGci...`，前缀已经包含在内。

**Q：Token 有效期多久？**
A：AutoDL 的 Token 通常较长有效，但如果遇到 401 错误请重新抓取。

**Q：`wait=True` 等待多久超时？**
A：默认 180 秒。可调用 `wait_until_running(uuid, timeout=300)` 手动指定。

**Q：社区镜像的 UUID 怎么找？**
A：控制台 → 创建实例 → 选社区镜像 → 查看镜像详情页 URL 中的 UUID。

---

## License

MIT
