write-kaggle-benchmarks

Kaggle ベンチマークを作成する

キーワード

Kaggle ベンチマーク、ベンチマークの作成、ベンチマークタスク、kbench、タスクのプッシュ、タスクの実行。

公式リソース

• SDK のソースと API — https://github.com/Kaggle/kaggle-benchmarks
• SDK の自動生成ドキュメント — https://deepwiki.com/Kaggle/kaggle-benchmarks
• CLI ドキュメント — https://github.com/Kaggle/kaggle-cli/blob/main/docs/benchmarks.md

コマンド階層

kaggle benchmarks (alias: kaggle b)
├── auth              — Fetch Model Proxy credentials
├── init              — Fetch credentials + setup local dev environment
└── tasks (alias: t)  — Manage benchmark tasks
    ├── push          — Upload a task from a .py file
    ├── run           — Run a task against model(s)
    ├── list          — List your benchmark tasks
    ├── status        — Show task details and per-model run status
    ├── download      — Download completed run outputs (and optionally source notebooks)
    ├── log (logs)    — Show execution logs for run(s) (streams live for RUNNING runs)
    ├── publish       — Make a task public (publishes the backing notebook by default)
    ├── models        — List available benchmark models
    └── delete        — Delete a task (not yet supported by server)

セットアップ

# Full setup: credentials + .env + example_task.py + kaggle_benchmarks_reference.md
kaggle b init -y

# Credentials only (refresh MODEL_PROXY_* in .env)
kaggle b auth -y

カスタムパス：init では --env-file <FILE> と --example-file <FILE> を指定します。

init が書き込む環境変数：

• MODEL_PROXY_URL
• MODEL_PROXY_API_KEY
• MODEL_PROXY_EXPIRY_TIME
• LLM_DEFAULT
• LLM_DEFAULT_EVAL
• LLMS_AVAILABLE

基本的なワークフロー：初期化 → 作成 → 検証 → プッシュ → 実行 → 状態確認 → ダウンロード

各ステップで確認を取る

パイプライン全体を連続して実行しないでください。 以下の各番号付きステップをチェックポイントとして扱います。

1. 現在のステップでこれから行うことを、実行する正確なコマンドを含めて一文で伝えます。
2. 実行する前にユーザーの承認を待ちます。「明らか」に見える init や list のようなステップも対象です。
3. ステップの完了後、関連する出力を表示してから停止します。次のステップに自動で進まないでください。
4. 次の手順をどう進めるか、ユーザーに確認します。ドキュメントに記載された次のステップに進むか、パラメーターを変更するか、別の作業に進むかを尋ねます。

ユーザーが「パイプライン全体」または「すべて実行」と明示的に依頼した場合は、連続して実行してもかまいません。ただし、各ステップの確認を黙って省略するのではなく、事前に実行予定の流れを要約し、全体を対象とした確認を一度求めてください。

0. 初期化（一環境につき一度。認証情報の期限が切れたら再実行）

init は Model Proxy の認証情報を取得し、.env を書き込み、同じ場所に example_task.py と kaggle_benchmarks_reference.md を配置します。以降の すべてのステップは、ここで書き込まれる MODEL_PROXY_* 変数に依存するため、 ほかの作業を行う前に実行してください。また、python task.py または kaggle b t run が認証エラーで失敗した場合は、必ず再実行してください （API キーの有効期間は短いためです）。

kaggle b init -y                      # first-time setup
kaggle b auth -y                      # creds-only refresh (no scaffolding)

1. タスクファイルを作成する

タスクファイルには、次の要件があります。

• kaggle_benchmarks as kbench をインポートする
• @kbench.task(...) でデコレートされた関数を少なくとも 1 つ定義する
• タスク関数に対して .run(kbench.llm)（または .evaluate(...)）を呼び出す。「注意点」を参照してください
• # %% のセルマーカーを使用する（jupytext の percent 形式）

最小限の例：

# %%
import kaggle_benchmarks as kbench

# %%
@kbench.task(name="my-test-task")
def my_test_task(llm):
    response = llm.prompt("What is 2 + 2?")
    kbench.assertions.assert_in("4", response, expectation="Should contain 4")

my_test_task.run(kbench.llm)

LLM の解決優先順位（高い順）：

1. コード内で明示的に指定したモデル：task.run(llm=kbench.llms["gemini-3.5-flash"])
2. コード内のデフォルト：task.run(llm=kbench.llm)（LLM_DEFAULT に解決されます）
3. .env の環境変数（LLM_DEFAULT、LLMS_AVAILABLE、MODEL_PROXY_*）

2. ローカルで検証する

プッシュする前に、タスクを最初から最後まで実行します。これにより、何もせずに成功したように見える注意点や、プロンプトの不具合を、プッシュ → 実行 → 待機 → ダウンロードの一連の流れを行う前に検出できます。

kaggle b init -y                     # ensure .env is current
python task.py                       # run the task directly
ls -1 *.run.json                     # confirm a run file was produced

python task.py が正常に終了し、*.run.json が生成された場合、タスクを安全にプッシュできます。検証に失敗した場合は、修正して再実行してからステップ 3 に進んでください。

3. プッシュ

kaggle b t push my-task -f task.py --wait
kaggle b t push my-task -f task.py -d owner/dataset1 -d owner/dataset2   # attach datasets

--wait [TIMEOUT] を指定すると、サーバー側の作成が完了するまで待機します（引数なしの場合は無期限）。--poll-interval <SECONDS> はポーリング間隔の上限を指定します（デフォルトは 60 秒です。ポーリングは 5 秒から始まり、状況に応じて間隔が延びます）。データセットごとに -d／--kaggle-dataset を繰り返し指定します（スペース区切りにしないでください。「注意点」を参照してください）。

4. 実行

# Interactive picker
kaggle b t run my-task

# Specific model
kaggle b t run my-task -m gemini-3.5-flash

# Multiple models (repeat -m, do NOT space-separate)
kaggle b t run my-task -m gemini-3.5-flash -m claude-haiku-4-5

# Wait for completion
kaggle b t run my-task -m gemini-3.5-flash --wait

利用可能なモデルを一覧表示するには、kaggle b t models を実行します。

5. 状態確認

kaggle b t status my-task
kaggle b t status my-task -m gemini-3.5-flash

タスクのメタデータ（スラッグ、バージョン、状態、作成日時、公開フラグ、タスク URL）と、モデルごとの実行状況テーブルを表示します。エラーが発生した実行では、最後の例外行が Errors: セクションの下に表示されます。

6. ダウンロード

kaggle b t download my-task                       # all terminal runs
kaggle b t download my-task -o ./results          # custom directory
kaggle b t download my-task -m gemini-3.5-flash
kaggle b t download my-task -s                    # also fetch source notebooks
kaggle b t download my-task -f                    # force re-download (overwrite)

出力先の構成：<output>/<task>/<version>/<model>/<run_id>/.... すでにダウンロード済みの実行は、--force／-f を指定しない限りスキップされます。--include-source／-s を指定すると、通常の出力とともに、各実行のディレクトリに __notebook__.ipynb と __notebook_source__.ipynb も含まれます（カーネルセッションのデバッグに便利です）。

7. ログ

kaggle b t log my-task                            # logs for every run of the task
kaggle b t log my-task -m gemini-3.5-flash # filter to one model
kaggle b t log my-task -m model-a -m model-b      # multiple models, sequential

RUNNINGの実行ではSSE経由でライブストリームを表示します。COMPLETED／ERROREDの実行では保存済みログを一度に表示します。QUEUEDの実行では(No logs available — server returned 404)を表示して続行します。

8. 公開

kaggle b t publish my-task                              # publish task + backing notebook (default)
kaggle b t publish my-task --no-publish-backing-notebook  # publish task only, keep notebook private

デフォルトではタスクと、それを支えるノートブックの両方を公開します。タスクがすでに公開されている場合、タスク自体へのコマンドは何も行いませんが、--no-publish-backing-notebookを渡さない限り、ノートブックは公開されます。

クイックレシピ

リマインダー：これらは参照用のスニペットであり、自動的に連続実行するコマンドではありません。上記の「ペース配分」セクションに従い、ユーザーが明示的に連続実行を依頼しない限り、各コマンドの間にユーザーの確認を挟んで1つずつ実行してください。

# Push → run → download (run one command at a time, confirm between)
kaggle b t push my-task -f task.py --wait
kaggle b t run my-task -m gemini-3.5-flash --wait
kaggle b t download my-task -o ./results

# List tasks, filtered
kaggle b t list --name-regex "^math" --status errored

# Debug an errored run: pull logs first, then download source notebook
kaggle b t log my-task -m gemini-3.5-flash
kaggle b t download my-task -m gemini-3.5-flash -s -f

注意点

ほとんどは、エージェントが自分では検出できないサイレントな失敗です。タスクファイルやCLIコマンドを生成する前に確認してください。

• .run()の呼び出しがないと、何も行われずに終了します。ファイルに.run()がなくてもプッシュは成功します（プッシュ時の検証では@taskデコレーターだけを確認します）。その後、タスクはサーバー上で実行されますが、.run.jsonが生成されないため、何も記録されません。すべてのタスク関数の末尾にはtask_fn.run(kbench.llm)（または.evaluate(...)）が必要です。
• MODEL_PROXY_API_KEYの有効期間は短いです。python task.pyが認証エラーで失敗した場合は、kaggle b auth -y（またはkaggle b init -y）を再実行して更新してください。
• init／authは環境変数ファイルに追記します。dotenv経由で読み込まれ、最後の値が優先されるため、再実行しても問題ありませんが、ファイルには重複したエントリーが蓄積していきます。
• タスクのスラッグは@taskデコレーターと一致させる必要があります。kaggle b t push <SLUG> -f file.pyは、<SLUG>がファイル内のいずれかの@kbench.task(name=...)（または関数名）のスラッグ化された名前と一致しない場合、失敗します。名前は正規化されます：My Task → my-task、my_task → my-task。
• モデルの正規スラッグをそのまま使用してください（例：gemini-3.5-flash、claude-haiku-4-5）。CLIはプロバイダーのプレフィックス（google/、anthropic/）を取り除き、@を-に置き換えて入力を自動的に正規化します。そのため、google/gemini-3.5-flash、anthropic/claude-haiku-4-5@20251001、claude-haiku-4-5-6@defaultはいずれも使用できます。ただし、テーブル、エラーログ、ダウンロード先ディレクトリでは常に正規形（例：claude-haiku-4-5-20251001）が表示されます。コマンド、出力、パスに一貫性を持たせるため、どこでもスラッグのみを使用してください。
• -dを指定せずに再プッシュすると、以前のデータセットが切り離されます。以前のタスクのバージョンにKaggleデータセットがアタッチされていた場合、-dフラグを繰り返さずに再プッシュすると、stderrに黄色の警告が表示され、データセットがサイレントに切り離されます。プッシュごとに-dのリストをすべて指定してください。
• ソースノートブックを後から取得する場合は、-f -sを併用してください。-sを指定せずに最初にダウンロードした場合、その後download -sを実行してもキャッシュ済みの実行はスキップされ、ヒントが表示されます。-f -sを付けて再実行すると、キャッシュ済みの実行を上書きし、ソースノートブックを取得できます。
• logは順次処理であり、ログは交互に表示されません。複数の実行が進行中の場合、CLIは最初の実行のストリームが終了するまで待機してから、次の実行に進みます。これによりログの交互表示を防げますが、一度に1つの実行の完了を待つことになります。
• サーバー側ではdeleteが実装されていません。コマンドは存在しますが、現在はDelete is not supported by the server yet.と表示されます。
• 複数の値はスペース区切りではなく、フラグを繰り返してください。複数の値を指定するフラグ（-m、-d／--kaggle-dataset）は、値ごとにフラグを指定します：-m a -m b。-m a bのようには指定できません。スペース区切りの形式はサポートされておらず、エラーになります。
• CLIの対象はタスクのみで、ベンチマークは対象外です。ベンチマークとは、厳選されたタスクの集合です。CLIでは個々のタスクを作成、プッシュ、実行できますが、ベンチマーク（コレクション）の作成や管理はKaggleのWeb UIで行う必要があります。

基本を超えるSDKの機能

以下は、タスク作成スキルにある、より効果の高いkaggle_benchmarksのパターンです。最小限の例では不十分な場合に活用し、実際のコードを使った完全な例については上流のスキルを参照してください。

タスク定義のルール

• @kbench.benchmark は @kbench.task の完全なエイリアスです。読みやすい方を使用してください。
• タスクが値を返す場合、戻り値の型注釈は必須です。 def score(llm) -> float: — -> float / -> bool / -> dict などがないと、run オブジェクトの .result の型付けが正しく機能しません。
• サブタスクには store_task=False を設定してください。 別のタスク内から @kbench.task が呼び出される場合（データセット評価で行ごとのスコアラーを使う場合など）、内側のタスクに store_task=False を設定すると、トップレベルの run として保存されるのを防げます。

Run オブジェクト

run = task_fn.run(...) の後：

• run.passed — bool。結果とすべてのアサーションが合格した場合は True です。
• run.result — 返された値（タスクの戻り値の型注釈で型付けされます）。
• run.assertion_results — list[AssertionResult]。記録されたすべてのアサーションです。

llm.prompt() の推論と温度

response = llm.prompt("Solve: 127 * 53?", reasoning="high")   # "low" | "medium" | "high"
traces   = kbench.last_reasoning_traces()                     # str | None — may be None if disabled/unsupported
response = llm.prompt("Write a creative story.", temperature=0.7)   # default 0

使用する前に、必ず last_reasoning_traces() が null でないことを確認してください。

マルチモーダル入力

from kaggle_benchmarks.content_types import images, videos, audios

# Images: from_url / from_path / from_base64
img = images.from_url("https://example.com/cat.jpg")     # llm.prompt auto-downloads + base64-encodes
img = images.from_path("local/chart.png")                # read + base64 immediately
img = images.from_base64(b64_str, format="png")          # default format="jpeg"

# Videos: YouTube URLs only (no local files, no non-YouTube URLs); select Gemini models only
video = videos.from_url("https://www.youtube.com/watch?v=...")

# Audio
audio = audios.from_path("speech.mp3")

response = llm.prompt("Describe this", image=img)

• llm.prompt(...) は画像 URL を自動的に base64 にダウンロードします（URL に対応していないモデルでも安全に使用できます）。user.send(...) は生の URL をそのまま渡します。ネイティブの URL 取得をテストする場合に使用できますが、対応していないモデルでは失敗します。
• 動画入力は YouTube のみに対応しており、特定の Gemini モデルに限定されます。ローカルファイルや YouTube 以外の URL を指定するとエラーになります。

チャット履歴の分岐と分離

• chats.fork("name") — 現在の履歴を一時的なブランチにコピーします。終了時に元のチャットは変更されません。
• contexts.enter(chat=...) — アクティブなチャットを低レベルで切り替え、エージェントの履歴を完全に分離します。ChatRoom が適さない場合（互いの情報を見てはならないエージェントなど）にのみ使用してください。

マルチエージェント：ChatRoom + Participant（パターン I.5）

ディベート／隠された役割／交渉のワークフローでは、独自に contexts.enter() を組み合わせて実装するよりも、kbench.ChatRoom を優先してください。各参加者には、それぞれの視点に投影されたトランスクリプトが表示されます。同じ kbench.llm を多くの参加者のバックエンドとして使用できます。

room = kbench.ChatRoom(system_prompt="A structured 2-turn debate.")
pro  = room.add_participant(llm, name="Pro", system_prompt="Argue FOR.")
con  = room.add_participant(llm, name="Con", system_prompt="Argue AGAINST.")
pro.reply()
con.reply()

詳しい手順については、kaggle-benchmarks リポジトリの docs/chatroom/rooms_walkthrough.md をご覧ください。

カスタムアサーション

• @assertion_handler() — 関数をカスタムアサーションとして登録するデコレーターです（AssertionResult を返すか、送出します）。不一致時に明示的に失敗させるには、@assertion_handler(raises_assertion_error=True) を使用してください。
• kbench.assertions.assert_tool_was_invoked(fn) — プロンプト中にモデルが登録済みのツールを実際に呼び出したことを検証します。