Krauncher analyzer

Krauncher

在远程 GPU 上运行训练脚本，仅此而已。

Krauncher 是一个精简的 Python 库，面向已有可运行本地脚本、需要 GPU 而非平台的研究人员。

网站和 API 密钥：krauncher.com

---

快速入门

pip install krauncher
export CAS_API_KEY="cas_..."        # krauncher.com → Account → API Keys

需要 Python 3.11+。

import asyncio
from krauncher import KrauncherClient

client = KrauncherClient()           # reads CAS_API_KEY / CAS_BROKER_URL from env or .env

@client.task(vram_gb=1, timeout=120)
def multiply(size: int):
    import numpy as np               # imports go INSIDE the function
    a, b = np.random.rand(size, size), np.random.rand(size, size)
    return {"mean": float((a @ b).mean())}

async def main():
    handle = await multiply(size=1000)   # submit → TaskHandle
    print("task:", handle.task_id)
    result = await handle                # await the handle → TaskResult
    print("output:", result.output)
    print("gpu:", result.actual_gpu, "·", f"{result.execution_time_sec:.1f}s")

asyncio.run(main())

装饰后的函数会变为异步函数：调用它会提交任务并返回一个 TaskHandle；等待该句柄（或执行 await handle.wait(...)）会返回一个 TaskResult。

正在使用 LLM / 编码 Agent？ 请阅读 AGENTS.md——其中包含准确的 API、参数、结果字段、错误和限制说明。可运行示例请见 tutorial/。

---

无服务器 ML 平台的问题

无服务器编排平台确实是令人印象深刻的基础设施。它们负责容器构建、密钥管理、工件存储、调度、持久卷和团队仪表板。

但无论你用不用，这些功能都要收费。

如果你要微调小型模型、运行消融实验，或使用小于 2 GB 的数据集迭代研究实验，你很可能在为不需要的编排层付费。

Krauncher 有意减少功能。它会在远程 GPU 上运行你现有的 Python 函数，返回结果，然后不再干预。

---

Krauncher 适用场景（及不适用场景）

适合：

• 微调、LoRA，以及使用最大约 2 GB 训练数据集进行的小规模实验
• 已有可运行本地脚本的研究人员
• 厌倦了为适配平台抽象而重写代码的任何人
• “基础设施”仅指一个人和一张信用卡的团队

不适合：

• 需要托管的版本化工件存储
• 团队要求各次运行之间共享持久卷
• 数据集有数百 GB，且需要复杂的多节点分片
• 需要用于实验跟踪的 UI 仪表板

---

工作原理

添加一个装饰器。等待函数执行。获取结果。你现有的代码无需更改——不需要基础镜像、卷挂载或平台导入。

import asyncio
from krauncher import KrauncherClient

client = KrauncherClient()

@client.task(gpu_name="RTX4090", group_id="mistral-run", timeout=3600)
def finetune():
    from transformers import AutoModelForCausalLM, Trainer, TrainingArguments
    from datasets import load_dataset

    # Weights download to worker storage on first run (~15 GB for 7B);
    # later runs in the same group_id reuse the cached weights.
    model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
    dataset = load_dataset("tatsu-lab/alpaca", split="train[:2000]")

    # ... your training logic, unchanged from local ...

    model.save_pretrained("/tmp/output")
    # Worker storage is ephemeral — sync checkpoints out before returning.
    upload_to_s3("/tmp/output", "my-checkpoints/run-1")
    return {"status": "done", "checkpoint": "s3://my-checkpoints/run-1"}

async def main():
    result = await finetune()        # submit and wait
    print(result.output)

asyncio.run(main())

装饰后的函数是异步函数——务必在 async 上下文中调用它，并等待该句柄（这会提交任务并等待完成）。标准写法请见快速入门。

选择 GPU

装饰器参数	效果
vram_gb=24	要求至少 24 GB VRAM
gpu_name="H100"	要求特定型号（不区分大小写的子字符串匹配）
gpu_arch="Ada"	要求特定 GPU 架构
（省略 vram_gb）	自动分类：分析器会检查你的代码，并为你选择显存等级

建议默认不设置 vram_gb——Krauncher 会静态分析你的代码并自动选择合适的 GPU。

---

安全模型

Krauncher 不存储任何内容。你的 API 密钥和训练代码在离开本机前会先在本机加密，仅在临时工作器内解密。负责路由任务的中继无法读取负载——它没有密钥。

内容	Krauncher 是否可见
你的存储凭证	否
你的训练代码	否
你的模型权重/输出	否
任务时间和 GPU 类型	是

存储密钥也包括在内：任务需要的 S3 / HuggingFace 凭证（AWS_*、HF_TOKEN）会从你的环境中读取，并与代码一起封装在同一负载中，直接发送给工作器。设置 CAS_SEND_CREDENTIALS=false 可不附加任何凭证。

这不是我们添加的功能，而是不想从事数据托管业务的必然结果。端到端加密是强制要求——无法选择退出。

---

数据本地性

具有相同 group_id 的任务会路由到同一物理主机，因此你首次运行下载到本地 NVMe 的内容会保留在那里，供后续运行使用。

@client.task(gpu_name="RTX4090", group_id="my-experiment-v1")
def train_epoch(epoch: int):
    import os
    cache_path = "/tmp/dataset.bin"
    if not os.path.exists(cache_path):
        download_from_s3("my-bucket", "dataset.bin", cache_path)
        # subsequent tasks in this group skip this step
    run_training(cache_path, epoch=epoch)
    return {"epoch": epoch, "status": "complete"}

async def main():
    for epoch in range(10):
        await train_epoch(epoch=epoch)

对于较大的数据集或已注册的数据集，请使用数据桥接（data_urls= / data=），将数据下载到沙盒内的 /data——参见 tutorial/06 和 tutorial/15。

---

不止于单个函数

• 笔记本 / 编辑器单元格。 await client.run_code(code, inputs={...}, outputs=[...]) 运行代码字符串，而不是装饰后的函数：命名的本地值传入，命名变量返回（适用于 JSON，预算为 16 MB）。krauncher-jupyter 的 %%krauncher 魔法命令正是基于这一基础原语构建的。参见 tutorial/50。
• 多阶段运行。 group = await client.group(task_a, task_b) 根据任务推导出共享需求配置（VRAM 下限、GPU 固定要求、磁盘），并让这些任务在同一热工作器上运行；使用 await group.submit(task, ...) 提交。 参见 tutorial/52。
• 文件输入，文件输出。 调用任务时传入 files={"input.csv": b"..."}，并设置 artifacts=True，即可取回任务在自身目录中写入的文件（result.artifacts、result.download("received")）。两个方向的数据都通过加密负载传输——无需配置存储。参见 tutorial/54。
• 运行前估算价格。 分析和执行分为两个阶段： await client.estimate_code(code, ...) 会返回分类结果，但不提交任务；随后 run_code(code, ..., classification=...) 会执行任务，而无需再次分析。装饰后的任务也可通过 CAS_ESTIMATE_ONLY=true 实现相同操作；POST /api/estimate 会返回按 GPU 区分的预测耗时和费用。

---

检查已完成的任务

任务完成后，代理会保留一条结构化记录——Web UI 会在任务详情页呈现同一条记录。

task   = await client.get_task(task_id)         # what GET /tasks/{id} returns
report = await client.get_task_report(task_id)  # task + extended report

get_task 会返回状态、时间明细（排队 / 下载 / pip / 设置 / 执行）、分类、费用、GPU 和工作器规格，以及结果。

get_task_report 会添加扩展的 report 字段：GPU 利用率峰值/平均值、VRAM 峰值、实际 GPU 的硬件规格，以及基于工作器测得的主机能力对所有已知 GPU 进行的预计耗时/费用对比。该报告旨在为编写用户代码的大模型作者提供反馈——只有纯数据，不作解读。

---

示例

tutorial/ 中提供了按编号排列、可运行的教程：

#	文件	演示内容
01	01_remote_simple.py	最简提交与等待
02	02_remote_with_deps.py	在沙箱中使用 pip= 依赖
03	03_error_handling.py	捕获 TaskError / 远程回溯
04	04_timeout.py	执行超时行为
05	05_task_groups.py	group_id 主机亲和性
06	06_data_bridge.py	使用 data_urls= 将文件下载到 /data
09	09_streaming_logs.py	通过 wait(on_log=...) 实时查看日志
10	10_progress_bar.py	进度报告
11	11_e2e_encryption.py	端到端加密
12	12_helper_functions.py	随任务一同发送辅助函数
13	13_bert_finetune.py	实际 ML 代码 → 分析器分类
15	15_data_sources_s3.py	已注册的 S3 数据源
17	17_multiphase_training.py	在一个组中进行多阶段训练
18	18_resnet152_food101.py	在 Food-101 上运行 ResNet-152
19	19_huggingface_dataset.py	HuggingFace 数据集桥接
20	20_bert_imdb.py	在 IMDB 上微调 BERT
21	21_qwen25_7b_lora_alpaca.py	微调 Qwen2.5-7B LoRA
22	22_qwen25_7b_inference_gsm8k.py	Qwen2.5-7B 推理
23	23_gnn_node_classification_cora.py	GCN 节点分类
30+	30_…–36_…	大模型推理和批量推理
50	50_run_code_values.py	使用命名的输入/输出值运行 run_code
52	52_group_envelope.py	client.group() 多阶段封装
53	53_hf_native.py	HuggingFace 原生自动预获取
54	54_artifact_roundtrip.py	输入文件 / 输出制品
55	55_assay_ladder.py	运行前的 Assay 和每 GPU 时间阶梯

---

安装

pip install krauncher
export CAS_API_KEY="your_api_key"

需要 Python 3.11+。

---

许可证

MIT