tilebox-workflow-releases

Tilebox ワークフローのリリースとデプロイ

このスキルは、ワークフロープロジェクトの初期化、ワークフローコードの変更を不変のリリースに変換する作業、およびそれらのリリースを 1 つ以上の Tilebox クラスターにデプロイする作業に使用します。タスクコードには tilebox-workflow-authoring を使用し、プロジェクトのひな形、設定、公開、デプロイ、ランナーの反復作業にはこのスキルを使用します。

エージェントのリリースループ

通常の反復作業では、安全を確保できる最小限の手順にします。

1. 新しいプロジェクトでは、以下のポリシーに従って再利用可能な機能名を選び、プロジェクトファイルを手作業で作成する前に tilebox workflow init --name "Scene QA" --json で一度だけ初期化します。現在のディレクトリに適切な機能ベースの名前が付いている場合に限り、--name を省略します。
2. ワークフローコードを編集し、変更したファイルが [build].include の対象に含まれ、除外されていないことを確認します。
3. 任意のローカル検証：tilebox workflow build-release --debug --json。
4. 公開：tilebox workflow publish-release --json。
5. 新しいリリースをデプロイします。最初の結果をすばやく得るには、ユーザーにクラスターを選んでもらう代わりに API のデフォルトクラスターを使用するため、--cluster を省略します。
6. ユーザーが実際に処理された成果物を求めている場合は、デプロイ後に tilebox-workflow-jobs を使用して代表的なジョブを送信し、検証します。デプロイだけでは成果物は作成されません。
7. 互換性のあるランナーが稼働しておらず、ローカル実行が適切な場合は、同じクラスターの動的ランナーを起動します。--cluster を省略した場合も、API のデフォルトクラスターが使用されます。

本番環境に近いターゲットには特定のリリース ID を指定してください。許容される場合に限り、開発時の反復作業では --latest を使用します。

互換性のあるタスクのバグが原因で既存のジョブが失敗した場合は、新しいジョブを最初から送信するより、修正済みリリースをデプロイして失敗したジョブを再試行することを優先します。

暗黙的な地理空間プロジェクトのデプロイ意図

tilebox ルーターが、暗黙的なプロジェクト経路を通じて実装を目的とする地球観測または地理空間関連のプロンプトを受け取った場合、ユーザーが範囲を限定しない限り、そのプロンプトはリモートワークフローの初期化、リリースの公開、および非本番環境へのデプロイを許可するものとして扱います。

次の境界を適用してください。

• 通常の最初の結果を得るには、意図が明確な既存の開発ターゲットが設定されている場合はそれを使用します。それ以外の場合は --cluster を省略し、組織の API デフォルトクラスターを使用します。小さなワークフローを実行するためだけに、新しいユーザーにクラスターの選択や作成を求めないでください。
• 一般的な成果を求めるプロンプトから本番ターゲットを推測したり選択したりしてはいけません。本番環境への明示的な意図が必要です。
• 「コードのみ」、「ローカルのプロトタイプ」、「公開しない」、「デプロイしない」などの制約を尊重します。
• ユーザーがインフラストラクチャを設定している場合、専用クラスターを展開する場合、または実行環境に大きな違いがある複数の候補から選択する場合は、クラスターの概念を説明し、ターゲット構成について確認します。
• 認証、適切なクラスター、またはランナーを利用できない場合は、可能な範囲でローカルプロジェクトを完成させて検証し、その後、運用上の具体的な阻害要因を報告します。実際には行われていない公開、デプロイ、出力の完了を主張してはいけません。
• 要求された成果が地図、アニメーション、検出結果一式、統計、またはその他の生成物である場合は、デプロイ後に tilebox-workflow-jobs を使用します。

初期化する前に、プロジェクトの状況を確認します。既存の tilebox.workflow.toml があれば再利用します。空のプロジェクトルート、または明確に意図されたプロジェクトルートを直接初期化します。無関係なリポジトリがルートを占めていて、ワークフローを独立させるべき場合は、機能ベースのサブディレクトリを使用し、生成されたワークフローファイルが無関係なプロジェクトファイルを上書きしたり混在したりしないようにします。

再利用可能なワークフロー名を選ぶ

ワークフローは再利用可能なプログラムであり、ジョブはその1つの実行です。最初のプロンプトで要求された具体的な結果ではなく、有効なすべてのジョブに共通する動作を表す名前をワークフローに付けます。単独のプロジェクトディレクトリにも同じ方針を適用します。workflow init は --name が省略された場合、そのディレクトリ名から名前を導出するためです。

初期化の前に、ルートタスクの入力とデフォルト値を確認します。ワークフロー名には、次のものを含めないでください。

• 場所、AOI、座標、日付、期間、イベント、シーン ID、シーン数などの具体的な入力値。
• seasonal、monthly、sentinel-2、ndvi、gif など、頻度、ソース、アルゴリズム／プロダクト、出力形式をジョブ入力で選択できる場合の、設定可能な選択肢を示すラベル。
• 後続のジョブで送信できる内容を制限しない、初回実行時や顧客に関するコンテキスト。

固定されたワークフローの動作、または実際の実装上の境界を表す用語だけを残します。rgb-timelapse、cloud-masked-composite、sar-change-detection のような簡潔な機能名を優先します。名前に含める語すべてに、再利用性の基準を適用します。ワークフローのコードを変えずに、別の有効な入力でこの語を変えられるでしょうか？ 変えられるなら、その語をワークフロー名とスラッグから省きます。代わりに、その詳細をルートタスクの入力に、必要であればジョブ名にも記述します。

たとえば、最初の実行でウィーン、過去3年間、季節ごとに1フレームが要求され、ルートタスクが aoi、start、end、cadence を受け取るとします。ワークフローは次のように初期化します。

mkdir rgb-timelapse
cd rgb-timelapse
tilebox workflow init --name "RGB Timelapse" --json

vienna-seasonal-timelapse は使用しないでください。vienna は AOI の値であり、seasonal は頻度の選択肢の1つです。実装が常に画像を季節ごとにグループ化し、頻度の選択肢を公開しない場合は、seasonal が固定された動作を表すため、seasonal-rgb-timelapse が適切です。

ワークフロープロジェクトを初期化する

新しい Python ワークフロープロジェクトでは、pyproject.toml、tilebox.workflow.toml、runner.py、ソースパッケージ、またはテストを作成する前に、tilebox workflow init を実行してください。初期ワークフロープロジェクトのひな形を手作業で作成しないでください。

tilebox workflow init はサーバー側のワークフローを作成し、API から返されたスラッグを tilebox.workflow.toml に書き込み、ローカルプロジェクトファイルのひな形を作成し、tilebox Python 依存関係を追加して、uv sync を実行します。これにより、プロジェクトは build-release、publish-release、deploy-release、ジョブの送信、ローカルのリリースランナーのテストに対応できる状態になります。ODC Geo、Shapely、Rasterio、async-geotiff など、タスク固有のオプションライブラリは追加されません。作成したワークフローコードでインポートするパッケージはすべて宣言し、uv sync を再実行してください。

初期化で作成される runner.py は、意図的に最小限のものです。これはひな形であり、ワークフローコードをすべて1つのファイルにまとめることを推奨するものではありません。複雑なワークフローでは、tilebox-workflow-authoring に従ってタスクと処理を一貫性のあるパッケージモジュールに移しつつ、ランナーのエントリーポイントはタスクの登録とランナーレベルの設定に限定してください。エントリーポイントを移動する場合は [workflow].runner を更新し、[build].include にパッケージツリー全体が含まれていることを確認してください。

ワークフローの初期化、リリースのビルド／公開の検証、tilebox runner start には、PATH 上に uv が必要です。uv が見つからない場合は、まず uv のインストールを修正してから、tilebox workflow init を再実行してください。最初に uv が利用できないという理由だけで、手動でのひな形作成に切り替えないでください。

tilebox workflow init --json

ディレクトリ名がエージェントやユーザーに表示したい名前と異なる場合は、再利用可能な機能名を明示してください。

tilebox workflow init --name "Scene QA" --json

CLI の実装における初期化の仕様：

• 現在のディレクトリのみを初期化します。
• tilebox.workflow.toml、pyproject.toml、runner.py、uv.lock のいずれかがすでに存在する場合は中止します。
• PATH 上に uv が必要です。
• --name が指定されている場合はそこから、指定されていない場合は現在のディレクトリ名からローカルプロジェクトのスラッグを決定します。
• プロジェクト名をスラッグ化し、可能な場合は単語の区切りを優先して、最大40文字に切り詰めます。
• リモートの Tilebox ワークフローを作成し、API から返されたワークフローのスラッグを tilebox.workflow.toml に書き込みます。
• tilebox.workflow.toml、pyproject.toml、runner.py のひな形を作成します。
• pyproject.toml の依存関係に tilebox を追加します。
• uv sync を実行して、uv.lock とローカル環境を作成します。

自動化で出力フィールドを利用する前に、次のコマンドでスキーマを更新してください。

tilebox agent-context workflow init --output-schema

既存または手動のワークフロープロジェクトを紐付ける

次のいずれかに該当する場合に限り、この方法を使用してください。

• ディレクトリが既存のワークフロー／コードベースであり、正常に初期化できない場合
• ユーザーから、既存の Tilebox ワークフローのスラッグを紐付けるよう明示的に依頼された場合
• tilebox workflow init を実行して失敗し、原因を特定したうえで、手動での紐付けが最も安全で簡潔な復旧方法である場合

新しいプロジェクトで最初の手順として tilebox workflow create を使用しないでください。新しいプロジェクトでは tilebox workflow init を使用し、生成されたファイルを発展させてください。

既存または手動のワークフロープロジェクトでは、まずサーバー側でワークフローを手動作成し、その後、プロジェクトのルートに tilebox.workflow.toml を作成または更新してください。CLI は現在のディレクトリから上方向に検索し、最も近い設定ファイルを使用するため、サブディレクトリからでもコマンドを実行できます。

WORKFLOW_SLUG=$(tilebox workflow create "Scene QA" \
  --description "Processes new scenes" \
  --json | jq -r '.slug')

cat > tilebox.workflow.toml <<EOF
[workflow]
slug = "$WORKFLOW_SLUG"
root = "."
runner = "scene_qa.runner:runner"

[build]
include = [
  "pyproject.toml",
  "uv.lock",
  "src/**",
]
exclude = [
  ".venv/**",
  "**/__pycache__/**",
  "**/*.pyc",
  ".pytest_cache/**",
]
use_gitignore = true

[targets.dev]
clusters = ["dev-cluster"]

[targets.production]
clusters = ["prod-a", "prod-b"]
EOF

CLI の実装に基づく設定ルール：

• ファイル名は tilebox.workflow.toml である必要があります。
• [workflow].slug は必須です。
• [workflow].root は省略可能で、既定値は "." です。すべてのビルドパスはこのルートからの相対パスです。
• 次のいずれか一方だけを設定してください。
  • runner = "module:object" は、uv run python -m tilebox.workflows.runner module:object として実行されます。
  • command = ["uv", "run", "python", "-m", "my_workflow.worker"] は、カスタムのワーカープロセスコマンドです。
• [build].include は必須で、少なくとも 1 つのパターンを含める必要があります。
• [build].exclude は省略可能です。生成された <workflow-slug>.tar.zst アーカイブも、アーティファクトから自動的に除外されます。
• [build].use_gitignore の既定値は true です。
• [targets.<name>].clusters は、再利用可能なクラスターのスラッグ一覧を定義します。--target と --cluster はどちらか一方のみ使用してください。
• 不明な TOML キーがあると設定の読み込みに失敗します。構造を正確に保ってください。

runner = "module:object" の場合、モジュールはインポート時に起動せずに、ランナーオブジェクトを公開する必要があります。

# scene_qa/runner.py
from tilebox.workflows import Runner
from tilebox.workflows.cache import LocalFileSystemCache

from scene_qa.tasks import SceneQA, SomeSubtask

runner = Runner(tasks=[SceneQA, SomeSubtask], cache=LocalFileSystemCache())

ビルドは任意の検証手順です

publish-release はアップロード前にビルドと検証を行うため、公開前に詳しいフィードバックを得たい場合は、任意の確認手順として build-release を実行できます。

Python ワーカーランタイムを検証または実行するワークフローのリリースコマンドでは、tilebox workflow build-release や tilebox workflow publish-release など、uv が PATH 上に必要です。uv が見つからない場合は、リリースコマンドを再試行する前に uv をインストールするか、問題を修正してください。

tilebox workflow build-release --debug --json

ビルドコマンドは次の処理を行います。

• [build].include、[build].exclude、および有効な場合は .gitignore を使用し、[workflow].root から対象ファイルを解決します。
• 決定的なローカル .tar.zst アーティファクトと SHA-256 ダイジェストを作成します。
• アーティファクトをローカルの Tilebox アーティファクトキャッシュに展開します。
• 設定されたワーカーランタイムを起動し、タスクの検出を呼び出します。
• コンテンツフィンガープリント、タスク識別子、ファイル、およびアーティファクトのダイジェスト／パスを返します。

ビルドに失敗した場合は、公開する前に設定またはランタイムを修正してください。よくある修正方法：pyproject.toml、uv.lock、および src/** や scene_qa/** などのワークフローパッケージツリー全体を含める、.venv/** を除外する、展開されたアーティファクトから runner のインポートパスを解決できることを確認する。Python のインポートエラーがあれば修正してください。

大容量のランタイムアーティファクトをリリースに含めない

ワークフローのリリースアーティファクトには、コードと小さな設定のみを含め、サイズの大きなランタイムアセットは含めないでください。モデルのチェックポイント、埋め込みの重み、参照ラスタ、大きなルックアップテーブル、生成されたキャッシュ、ダウンロードしたプロバイダーデータを [build].include に含めないでください。

プロジェクトに大容量のローカルアセットが含まれる可能性がある場合は、明示的に除外を追加してください。

[build]
exclude = [
  ".venv/**",
  ".cache/**",
  "models/**",
  "checkpoints/**",
  "data/**",
  "**/*.ckpt",
  "**/*.pt",
  "**/*.pth",
  "**/*.onnx",
]

ML のチェックポイントなど、再利用可能なランタイムアセットには、代わりにランナー内で遅延読み込みを実装してください。

• インポート時、ビルド時、公開時ではなく、初回使用時にアーティファクトを取得してください。
• 非公開のモデル重みなどのプライベートアセットは、デプロイ済みランナーがアクセスできるプライベートバケットに保存し、そのバケットから遅延読み込みしてください。そのようなランナーからアクセス可能なプライベートバケットがない場合は、ワークフローを実装する前に、ユーザーに設定を依頼してください。
• ワークフローのリリース変更後も同じランナー上で保持できるよう、~/.cache/tilebox/models/<name>/<version>/... のような決定的なパスにキャッシュしてください。
• 使用前にキャッシュされたファイルを検証してください。できればチェックサムを使い、最低限、想定されるサイズを確認してください。破損または不完全なファイルは削除して、再ダウンロードしてください。
• 高コストなメモリ内の初期化は、functools.lru_cache または同等のプロセスローカルキャッシュでラップし、各ワーカープロセスでモデルを一度だけ読み込むようにしてください。
• リリースアーティファクトには、アセットの場所を特定し、取得、検証、読み込みを行うコードのみを含めてください。

実装例：

from functools import lru_cache
from pathlib import Path


@lru_cache(maxsize=1)
def load_model() -> Model:
    checkpoint = ensure_cached_file(
        url=MODEL_URL,
        path=Path.home() / ".cache/tilebox/models/clay/v1.5/model.ckpt",
        min_size_bytes=900_000_000,
    )
    return Model.load_from_checkpoint(checkpoint)

ランナー内のキャッシュは最適化として扱ってください。キャッシュが空のコールドランナーでも、ワークフローが動作する必要があります。

ランナー互換のホイール用に uv のソースを固定する

動的ランナーは、ローカル開発が異なるハードウェアやパッケージインデックスを使うマシンで行われた場合でも、Linux CPU ノード上で依存関係を解決して実行することがあります。pyproject.toml でプラットフォーム固有のホイールソースを明示し、リリースアーティファクトに uv.lock を含め、対象のランナーフリートでのサポートが保証されていない限り、CUDA/GPU ホイールへの依存を避けてください。

PyTorch などの依存関係については、必要に応じて Linux の CPU 互換ソースを固定してください。

dependencies = [
    "claymodel==1.5.0",
    "torch==2.4.0",
    "torchvision==0.19.0",
]

[tool.uv.sources]
torch = { index = "pytorch-cpu", marker = "sys_platform == 'linux'" }
torchvision = { index = "pytorch-cpu", marker = "sys_platform == 'linux'" }

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

ランナーで uv sync またはリリース検証に失敗する場合は、ロックファイルまたはソースインデックスがデプロイ先のランナープラットフォームではなく、ローカル専用のハードウェア向けに生成されたものかどうかを確認してください。

リリースを公開する

公開時にはプロジェクトを検証し、必要に応じてアーティファクトをアップロードして、変更不可のワークフローリリースを作成します。同一のリリース内容とアーティファクトダイジェストに対しては冪等であり、CLI は重複を作成せずに既存のリリースを返します。

公開するには PATH 上に uv が必要です。アップロード前に Python ワークフローのランタイムをビルドして検証するためです。

RELEASE_ID=$(tilebox workflow publish-release --debug --json | tee /tmp/workflow-release.json | jq -r '.id')
jq '{id, message, fingerprint, tasks, files}' /tmp/workflow-release.json

必要に応じて、別のプロジェクトディレクトリから公開します。

tilebox workflow publish-release ./path/to/project --json

自動化で出力フィールドを使用する前に、次のコマンドでスキーマを更新してください。

tilebox agent-context workflow publish-release --output-schema

リリースと再試行で失敗したジョブを修正する

大規模なワークフローがタスク実装のバグで失敗した場合、ジョブ全体をすぐに再送信しないでください。Tilebox のジョブ再試行キューは失敗したタスクを再度キューに入れ、失敗した時点から再開するため、完了済みのタスクを再実行する必要はありません。

次の手順に従ってください。

1. タスクの実装を修正します。
2. タスク識別子は変更せず、互換性のあるバージョンを使用します。後方互換性のある修正では、マイナーバージョンを上げてください。v1.5 のランナーは、v1.3 として送信されたタスクを実行できます。
3. 新しいワークフローリリースを、失敗したジョブと同じクラスターに公開してデプロイします。
4. 失敗したジョブを再試行します。

RELEASE_ID=$(tilebox workflow publish-release --json | jq -r '.id')
tilebox workflow deploy-release --release "$RELEASE_ID" --cluster "$CLUSTER" --json
tilebox job retry "$JOB_ID" --json

これは、タスクの入力パラメーターが同じか後方互換性があり、失敗したジョブが想定するワークフローの構成や依存関係グラフに大きな変更がない場合に機能します。入力または動作に互換性のない変更がある場合、古いジョブの再試行に依存しないでください。代わりにタスクのメジャーバージョンを上げ、新しいジョブを送信してください。

コマンドフラグや出力形式が自動化に影響する場合は、まずジョブ CLI のスキーマを更新してください。

tilebox agent-context job retry --output-schema

リリースをデプロイまたはデプロイ解除する

デプロイすると、ワークフローのリリースがクラスターに割り当てられます。デプロイだけではジョブは送信されません。tilebox.workflow.toml があるプロジェクト内で実行する場合は、--workflow を省略してください。CLI は [workflow].slug を使用します。

公開したばかりのリリースをデプロイします。

tilebox workflow deploy-release --release "$RELEASE_ID" --target dev --json

最新のリリースを dev/default クラスターにデプロイします。

tilebox workflow deploy-release --latest --target dev --json
tilebox workflow deploy-release --latest --cluster dev-cluster --json
tilebox workflow deploy-release --latest --json  # API default cluster

特定のリリースを複数の明示的なクラスターにデプロイします。

tilebox workflow deploy-release \
  --workflow "$WORKFLOW_SLUG" \
  --release "$RELEASE_ID" \
  --cluster cluster-a,cluster-b \
  --json

デプロイ解除では同じセレクターのルールを使用し、アクティブなリリースの割り当てを削除します。

tilebox workflow undeploy-release --latest --target dev --json
tilebox workflow undeploy-release --release "$RELEASE_ID" --cluster cluster-a --json

セレクターのルール：

• --release <uuid> または --latest のどちらか一方だけを指定します。
• --release には UUID を指定する必要があります。
• --target <name> の指定には、ローカルの tilebox.workflow.toml が必要です。また、[targets] に存在する必要があります。
• --cluster はカンマ区切りで指定し、--target と併用できません。
• --cluster と --target の両方を省略すると、API はデフォルトのクラスターを使用します。

状態を確認します。

tilebox workflow get --json
tilebox workflow get "$WORKFLOW_SLUG" --json
tilebox cluster get dev-cluster --json

ダイナミックランナーをローカルで起動する

ダイナミックランナーは、クラスターにデプロイされたリリースのタスクを実行します。クラスターのデプロイ状態をポーリングし、不足しているアーティファクトをダウンロードして展開し、リリースのタスク登録を検証して、Python ワーカーランタイムを起動し、実行を継続します。ログは標準エラーに出力され、JSON 出力は生成されません。

tilebox runner start でワークフローのリリースアーティファクトから Python ワーカーランタイムを起動するには、PATH 上に uv が必要です。uv が見つからない場合は、ランナーを起動する前に uv をインストールするか、設定を修正してください。

ターミナル 1：

tilebox runner start --cluster dev-cluster --debug

--cluster を省略すると、API のデフォルトクラスターが使用されます。

tilebox runner start --debug

Tilebox のログをエクスポートしながら、コンソールログを抑制します。

tilebox runner start --cluster dev-cluster --quiet

ターミナル 2 で、同じクラスターにリリースをデプロイした後、ルートタスクを送信します。

tilebox job submit \
  --name scene-qa-test \
  --task tilebox.com/example/SceneQA \
  --version v1.0 \
  --cluster dev-cluster \
  --input '{"scene_id":"S2A_001"}' \
  --wait \
  --json

デバッグ時のランナーに関する注意事項：

• デプロイ済みのワークフローがない場合、ランナーはローカルで待機し、警告をログに記録します。
• デプロイの変更はポーリングで検出されます。間隔はおよそ 10 秒にジッターが加わります。
• 無効なデプロイ済みリリースはスキップされ、有効なリリースは実行可能なままです。
• デプロイ済みの 2 つのリリースでタスク識別子が競合する場合、ランナーは曖昧なリリースを通知しません。
• ランナーは割り込みを処理します。最初の割り込みでは、新しいタスクの取得を停止して正常なシャットダウンを試みます。2 回目の割り込みでは、すばやく終了します。

安全な自動化パターン

ユーザーから現在のプロジェクトの公開とデプロイを依頼された場合は、エージェント実行スクリプトで次のようなシェル構成を使用します。

set -euo pipefail

release_json=$(tilebox workflow publish-release --json)
release_id=$(jq -r '.id' <<<"$release_json")
test -n "$release_id" && test "$release_id" != "null"

tilebox workflow deploy-release --release "$release_id" --target dev --json

設定済みのターゲットがない場合は、明示的なクラスターを使用します。

tilebox workflow deploy-release --release "$release_id" --cluster dev-cluster-a,dev-cluster-b --json