内容
# colab-fleet
> 将繁重的 CPU/ML 工作卸载到 **免费的 Google Colab**，通过 Claude Code（或任何 MCP 客户端）- 具有免费层锁定、自动关闭、作业队列和检查点恢复。
将繁重的运算（ML 训练、超参数搜索、回测）从您的 PC 移到 **免费的 Google Colab 运行时**，并仅接收结果。该工具允许 **MCP 客户端（如 Claude Code）只需调用一次** (`gpu_submit(...)`)，即可发送作业并在完成后自动检索结果。
您的计算机上不需要沉重的库或 GPU。**一个 Colab 账户（免费）** 就足够了。
---
## 与官方 `colab` CLI 有何不同（简要）
一句话：**Google 的 `colab` CLI 是“手动工具”**，而 **colab-fleet 是“AI 自动调用的工具”**。虽然我们使用相同的官方 CLI 作为引擎，但我们在其上添加了安全措施和自动化功能。
> Google **没有创建官方的 MCP 服务器**。他们只提供了命令行 CLI。因此，我们创建了这个项目，以便 AI 可以直接使用 MCP 与其交互。
| 项目 | 官方 `colab` CLI（原生） | colab-fleet（此包装器） |
|------|------------------------|------------------------|
| **谁在使用** | 人直接在终端中使用 | AI 在对话中调用 `gpu_submit(...)` |
| **成本控制** | A100、TPU 等付费加速器直接连接（需付费） | **仅允许免费（cpu/t4），拒绝付费硬件** → 保证 0 成本 |
| **超时** | 默认 30 秒 - ML 训练可能会中断 | 每个作业超时时间更长（默认 1 小时）+ 通过检查点恢复 |
| **会话清理** | 如果忘记，可能会保持开启状态 | **自动终止**，也会清理孤立会话 |
| **并发执行** | 无保护（免费账户只能有一个会话，可能会冲突） | 通过队列 **单行排队** |
| **数据** | 人工手动上传/下载 | **自动上传输入 → 执行 → 自动检索结果** |
| **凭证/隐私** | 用户自行管理 | **绝不泄露令牌或电子邮件** |
类比来说，官方 CLI = **手动变速器**，而 colab-fleet = 在其上的 **自动变速器 + 安全带 + 导航系统**。引擎（免费的 Colab 运行时）相同，但我们确保 AI 可以安全、自动地运行。
---
## 安装（3 步）
```bash
git clone https://github.com/yazzang-homelab/colab-fleet.git
cd colab-fleet
./install.sh # 创建虚拟环境 + 安装 colab CLI 和 mcp
```
`install.sh` 脚本完成后，它将指导您完成剩余的 2 个步骤：
**1）使用您的 Google 账户进行一次性身份验证** （将打开浏览器）
```bash
.venv/bin/colab sessions
```
令牌存储在 `~/.config/colab-cli/` 中，**不会通过此工具泄露**。
**2）将 colab-fleet 注册到 MCP 客户端**
- Claude Code：
```bash
claude mcp add -s user colab-fleet -- "$PWD/.venv/bin/python" "$PWD/server.py"
```
- pi / 其他（将配置添加到 mcpServers）：
```json
"colab-fleet": { "command": "/abs/path/colab-fleet/.venv/bin/python", "args": ["/abs/path/colab-fleet/server.py"] }
```
验证：从代理运行 `gpu_doctor()` → 身份验证 ✅ 即可。
> 要求：Python 3.10+，git。**不需要 GPU 或沉重的库**在您的 PC 上（所有操作都在 Colab 中执行）。
---
## 使用
```python
# 0) 健康检查
gpu_doctor()
# 1) 往返验证（依赖关系 0 → 临时运行）
gpu_submit(".../examples/selftest.py", accel="cpu", outputs="/content/selftest.json")
gpu_status(<id>); gpu_logs(<id>); gpu_fetch(<id>)
# 2) 并行超参数搜索（依赖关系 + 输出 → 受管）
gpu_submit(".../examples/sklearn_gridsearch.py", accel="cpu",
deps="scikit-learn joblib", args="--folds 5",
outputs="/content/result.json", timeout=1200)
# 3) 上传 CSV 进行训练（输入 + 依赖关系 + 输出 → 受管）
gpu_submit(".../examples/train_on_csv.py", accel="cpu",
deps="scikit-learn pandas joblib",
inputs="/path/to/data.csv", args="--csv /content/data.csv",
outputs="/content/model.pkl,/content/metrics.json", timeout=1800)
# 如果您需要真正的 DL（GPU (T4)）：
gpu_submit(".../my_torch_train.py", accel="t4", deps="torch ...", outputs="...")
```
输出将下载到 `~/.colab-fleet/jobs/job-<id>/` （可通过环境变量修改）。
### 工具列表
| 工具 | 描述 |
|------|------|
| `gpu_submit(script, accel, deps, args, inputs, outputs, ckpt, timeout, retries, label)` | 提交作业（异步），返回作业 ID |
| `gpu_status(job_id=0)` | 作业详情 / 如果 job_id 为 0，则显示最近的作业 + 活动会话 |
| `gpu_logs(job_id, lines)` | 逐步日志 tail |
| `gpu_fetch(job_id)` | 输出路径列表 |
| `gpu_sessions()` | 活动 Colab 会话 |
| `gpu_stop(name="all")` | 会话停止（保护单元） |
| `gpu_doctor()` | 健康检查、身份验证、队列状态 |
---
## 安全措施
- **免费层锁定**：仅允许 `accel ∈ {cpu, t4}`。**拒绝 A100/H100/L4/TPU**（`colabq.accel_flags`）→ 结构上保证 0 成本计算单元（付费）结算。
- **自动关闭**：所有作业都使用 try/finally 块 `colab stop`。调度程序退出时，也会回收孤立会话。
- **串行队列**：免费层只能有一个会话 → 使用 flock 实现单行排队，并对并发提交进行排队。
- **凭证/隐私保护**：工具输出中不包含令牌或电子邮件。
## 检查点-恢复（长时间作业）
如果脚本定期将检查点保存到 `ckpt` 路径，并在启动时加载并恢复，则调度程序将保留最后的检查点，并在作业跨越 12 小时/90 分钟上限时在多个会话中重试。您可以使用 `retries` 参数指定重试次数。
## 环境变量（可选）
`COLAB_FLEET_AUTH`（oauth2/adc）· `COLAB_FLEET_TIMEOUT` · `COLAB_FLEET_ARTIFACTS`（制品位置）· `COLAB_FLEET_CONFIG` · `COLAB_FLEET_DB` · `COLAB_FLEET_BIN`（强制 colab 路径）。
## 故障排除
| 症状 | 原因/解决方法 |
|------|-----------|
| `gpu_doctor` 身份验证失败 | 未完成的一次性登录 → 使用 `.venv/bin/colab sessions` 进行浏览器身份验证 |
| 401/403 | 权限不足 → 重新登录（或设置 `COLAB_FLEET_AUTH=adc` + `gcloud auth application-default login`） |
| 未分配 GPU（新建时出现 400） | 免费 T4 可用性变化 → 回退到 `accel="cpu"` |
| 作业仅排队 | 调度程序未运行 → 手动执行 `.venv/bin/python dispatch.py` |
| 上传 500/失败 | `colab upload` = Jupyter API，因此**单个输入 >80MB 时出现 500**。减小子集/压缩。调度程序将上传失败标记为作业失败（不会隐藏） |
| 已完成但无结果 | 远程脚本异常 → 未输出成功标志 → 失败处理。检查 `gpu_logs` 的 stderr 追踪信息 |
## 注意事项
- Google Colab 免费运行时有**公平使用政策**。该工具不会绕过这些政策，仅进行**正常范围内的作业卸载和自动清理**。
- 免费 CPU 运行时大约相当于 2 个 vCPU - **干净的 RAM 和与开发 PC 的隔离**更有价值。如果您需要真正的 GPU 加速，请使用 `accel="t4"`。
## 许可证
MIT。该工具使用的引擎 [`google-colab-cli`](https://pypi.org/project/google-colab-cli/) 是 Apache-2.0（独立）。
