本番では Go API が Modal worker の起動を依頼します。デプロイには mise run modal-deploy-push を使います。
- Go API と PostgreSQL が部室サーバーで起動している。
- Modal から API の公開 HTTPS URL に接続できる。
- API と worker が同じ R2 バケットを使う。
worker の環境変数は deploy/modal/.env に設定し、Modal Secret に登録します。
deploy/modal/.env がない場合だけ .env.example をコピーしてください。
API_BASE_URL:API の公開 URL を設定します。- R2 のバケット・認証情報:Go API と同じ値を設定します。
INTERNAL_API_KEY:Go API と同じ値を設定します。
WORKER_API_MODE=url
API_BASE_URL=https://embeddings.mumumu6.networker は WORKER_API_MODE で API の接続先を切り替えます。
- Docker Compose: compose.yaml が
WORKER_API_MODE=hostを指定し、API_HOST/API_PORTを使う。 - Modal: Secret の
WORKER_API_MODE=urlによりAPI_BASE_URLを使う。
Docker Compose 用の .env と Modal 用の deploy/modal/.env は分けて管理してください。
次のコマンドで Secret を登録・更新します。
mise run modal-secretmise run modal-runmise run modal-deploy-push は、Go API が起動依頼を送る HTTP エンドポイント run_batch を公開します。
deploy/modal/.envに Go API と同じINTERNAL_API_KEY、MODAL_GPU=T4、OCR_ENABLED=trueを設定します。mise run modal-secretで Secret を更新します。mise run modal-deploy-pushでデプロイします。- 表示された
run_batchの URL を Go API のMODAL_TRIGGER_URLに設定します。 - Go API 側で
MODAL_ENABLE=true、MODAL_BATCH_THRESHOLD=10、Modal と同じINTERNAL_API_KEYを設定します。 mise run deploy-apiで Go API 側の設定を反映します。
Go API は未処理の画像ジョブが MODAL_BATCH_THRESHOLD(既定10)以上になると、run_batch に POST します。認証ヘッダーは Authorization: Bearer <INTERNAL_API_KEY> です。
件数はサービス全体の未処理の画像ジョブで数えます。複数画像を送った1回の POST も1ジョブです。
10件待ちの理由は 画像 worker の起動条件、通知と結果取得は Webhook の流れ を参照してください。
認証キーは用途ごとに分けます。
API_KEY: クライアント → Go(公開 API)INTERNAL_API_KEY: worker/Modal → Go(/internal/...)、Go → Modalrun_batch
Modal worker はキューが空になると終了します。
Modal worker の設定は deploy/modal/.env で管理します。
| 変数・設定例 | 動作 |
|---|---|
MODAL_GPU=T4 |
GPU の種類。既定は T4 |
MODAL_MAX_CONTAINERS=1 |
同時に起動する worker コンテナの上限 |
MODAL_MAX_JOBS_PER_RUN=0 |
1回の起動で処理するジョブ数の上限。0はキューが空になるまで処理 |
MODAL_WORKER_RUN_SECONDS=0 |
worker が次のジョブを取得し続ける時間の上限。0はこの制限なし |
MODAL_FUNCTION_TIMEOUT_SECONDS=10800 |
process_queue の実行時間の上限。既定は3時間 |
MODAL_SCALEDOWN_WINDOW_SECONDS=30 |
処理後に GPU コンテナを保持する秒数 |
EMBEDDING_BATCH_SIZE=4 |
1回の推論にまとめるジョブ数。コードの既定は1、常駐 worker も1 |
EMBEDDING_MAX_PIXELS |
推論用画像のリサイズ上限 |
OCR_ENABLED=true |
yomitoku による文字認識を有効化 |
MODEL_MAX_MEMORY_CUDA / QUANTIZATION |
モデルの GPU メモリ上限・量子化方式 |
MODAL_WORKER_RUN_SECONDS=0 でも、関数の実行時間には MODAL_FUNCTION_TIMEOUT_SECONDS の上限が適用されます。推論バッチや画像のリサイズ上限を増やす場合は、VRAM 使用量を実測してください。
GPU の種類・関数タイムアウト・コンテナ上限などは再デプロイで反映します。mise run modal-deploy-push はローカルの deploy/modal/.env を読み込みます。OCR などの worker 設定は Secret も更新してください。
Go API は processing の画像ジョブがある間、Modal の追加起動を見送ります。
MODAL_RECLAIM_TTL=30m は Go API 側の設定です。最終更新から30分を超えた processing のジョブを pending に戻します。
Modal がタイムアウトして処理中のジョブが残った場合も、回収の対象です。回収後に画像ジョブ数と起動間隔を確認し、起動条件を満たした場合に依頼します。
起動後の worker は、起動条件の10件を下回ってもキューが空になるまで処理します。復旧時のログ確認と手動実行は 開発者向けガイド を参照してください。