Krauncher analyzer

Krauncher

トレーニングスクリプトをリモート GPU で実行します。それだけです。

Krauncher は、動作するローカルスクリプトはあるものの、必要なのはプラットフォームではなく GPU という研究者向けの、最小限の Python ライブラリです。

ウェブサイトと 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())

デコレートされた関数は async になります。呼び出すとタスクが送信され、TaskHandle が返されます。ハンドルを await する（または await handle.wait(...) を呼び出す）と、TaskResult が返されます。

LLM／コーディングエージェントを使用していますか？ AGENTS.md をお読みください。API、パラメーター、結果フィールド、エラー、制約を正確にまとめたリファレンスです。実行可能な例は tutorial/ にあります。

---

サーバーレス ML プラットフォームの問題点

サーバーレスのオーケストレーションプラットフォームは、実に見事なインフラストラクチャです。コンテナのビルド、シークレット管理、成果物のストレージ、スケジューリング、永続ボリューム、チームダッシュボードを処理します。

そのすべてに対して料金も請求されます。使うかどうかにかかわらずです。

小規模なモデルをファインチューニングしたり、アブレーションを実行したり、2 GB 未満のデータセットで研究実験を繰り返したりする場合、必要のないオーケストレーション層に料金を払っている可能性があります。

Krauncher は、意図的に機能を絞っています。既存の Python 関数をリモート GPU で実行し、結果を返したら、あとは邪魔をしません。

---

Krauncher が向いている用途（向いていない用途）

向いている用途：

• 最大約 2 GB のトレーニングデータセットを使ったファインチューニング、LoRA、小規模な実験
• すでに動作するローカルスクリプトを持つ研究者
• プラットフォームの抽象化に合わせてコードを書き直すことにうんざりしている方
• 「インフラストラクチャ」を担当するのが一人とクレジットカードだけのチーム

適していない用途：

• バージョン管理された成果物ストレージのマネージドサービスが必要な場合
• 実行間で永続的な共有ボリュームが必要なチーム
• データセットが数百 GB あり、複雑なマルチノードシャーディングが必要な場合
• 実験追跡用の UI ダッシュボードが必要な場合

---

仕組み

デコレーターを追加します。関数を await します。結果を受け取ります。既存のコードは変更不要です。ベースイメージも、ボリュームマウントも、プラットフォームのインポートも必要ありません。

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 です。必ず async コンテキストから呼び出し、ハンドルを await してください（これにより送信と待機が行われます）。標準的な書き方については、クイックスタートを参照してください。

GPU の選択

デコレーターの引数	効果
vram_gb=24	VRAM が 24 GB 以上の GPU を指定します
gpu_name="H100"	特定のモデルを指定します（大文字・小文字を区別しない部分文字列）
gpu_arch="Ada"	GPU アーキテクチャを指定します
(omit vram_gb)	自動判定：アナライザーがコードを調べ、VRAM の階層を自動的に選択します

vram_gb を未設定にするのが推奨されるデフォルトです。Krauncher がコードを静的に解析し、GPU のサイズを自動的に決定します。

---

セキュリティモデル

Krauncher は何も保存しません。API キーとトレーニングコードは、マシンから送信される前にそのマシン上で暗号化され、一時的なワーカー内でのみ復号されます。ジョブを中継するリレーはペイロードを読み取れません。復号キーを持っていないためです。

項目	Krauncher からの可視性
ストレージの認証情報	いいえ
トレーニングコード	いいえ
モデルの重み／出力	いいえ
ジョブの実行時刻と GPU の種類	はい

ストレージキーも同様です。タスクに必要な S3／HuggingFace の認証情報（AWS_*、HF_TOKEN）は環境から読み込まれ、コードと同じペイロード内に封印された状態で、そのままワーカーへ送信されます。何も付与しない場合は、CAS_SEND_CREDENTIALS=false を設定してください。

これは後から追加した機能ではありません。データ管理を担いたくないという方針の結果です。E2E 暗号化は必須であり、無効にはできません。

---

データの局所性

同じ 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 における推定時間／コストの比較が含まれます。ユーザーコードを作成する LLM へのフィードバックを目的としたもので、解釈を加えない純粋なデータです。

---

例

tutorial/ 内の、番号付きで実行可能なチュートリアルです。

#	File	Demonstrates
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	1 つのグループ内での複数フェーズのトレーニング
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_…	LLM 推論とバッチ推論
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	実行前のアッセイと GPU ごとの時間ラダー

---

インストール

pip install krauncher
export CAS_API_KEY="your_api_key"

Python 3.11 以降が必要です。

---

ライセンス

MIT