推論エンジンを足す
ECS の配備に、GPU で動く自前の推論エンジンのスタック 60-engines を足します。
GPU のインスタンスは、だれかが使っているあいだだけ存在します。Control Plane がリクエストに合わせて調達し、アイドルになると終了します。
| あなたがやること | 起きること |
|---|---|
G 系の vCPU のクォータを上げ、取得した状態に params/60-engines を置いて standup.sh を実行する |
イメージを ECR にコピーし、60-engines を空のまま構築し、サービスを 0 台にする |
| 管理の「推論エンジン」でモデルを取り込み、有効にする | モデルが S3 Bucket に置かれ、メンバーが選べるようになる |
| 何もしない | 最初のリクエストで Control Plane が GPU のインスタンスを調達してエンジンを起動し、アイドルが続くと終了する |
モードの選び方・モデルの取り込み・状態の見方は、管理画面の側のページにあります。
| 役 | エンジン | メンバーが得るもの | コールドスタート |
|---|---|---|---|
llm |
llama.cpp(llama-server) |
opencode の起動の選択肢に llamacpp/<model> |
約 527〜586 秒 |
image |
ComfyUI(comfy) |
generate_image ツールのプロバイダー comfy。生成・編集・インペイント |
インスタンスしだい(8〜88 秒) |
- それぞれ単独で選べます。
<Role>Enabled=trueがなければ、その役のサービスは作られません - 2 つの役がインスタンスを共有することはありません。 CUDA は VRAM が足りないと遅くなるのではなく落ちます。30B のモデル(20.9 GB)と SDXL(7.4 GB)は、1 枚の L4 に両方は載りません
- 動いているあいだは安くありません。g6.xlarge(NVIDIA L4、24 GB)は全部込みで $1.26/時、止めなければ月 $918 です
Fargate には GPU がないので、エンジンは EC2 のインスタンスで動きます。Control Plane が、このスタックの起動テンプレートを使って CreateFleet(type=instant) で買い、エンジンがアイドルになると終了します。タスクがなければインスタンスもない、という状態を Control Plane が保ちます。
-
G 系の vCPU のクォータを上げます。 新しいアカウントは 0 で、引き上げは自動では承認されません。サポートケースが開き、数時間から数日かかります
- 両方の役を動かすなら 16 を頼みます(
L-DB2E81BA、「Running On-Demand G and VT instances」)。8 でも g6.xlarge を 2 台起動できますが、終了したばかりのインスタンスの 4 vCPU は、停止にかかる 7〜8 分のあいだクォータに数えられたままです。16 なら 1 台分の余裕があります - クォータは上限であって予約ではないので、余裕に料金はかかりません。24 を頼んでも費用は同じで、デプロイし直すときに停止中のインスタンスが重なっても足ります
ターミナルウィンドウ aws service-quotas get-service-quota --service-code ec2 --quota-code L-DB2E81BA --query 'Quota.Value' - 両方の役を動かすなら 16 を頼みます(
-
クラスターの容量プロバイダーの関連付けを持てるのは、1 つのスタックだけです。 API はリストを足すのではなく置き換えます。計測用のハーネス(
harness/engprobe.yaml)をデプロイしているなら、先にdeploy/aws/ecs/harness/probe-managed-instances.sh downで撤去します。エンジンはそのリストに入っていませんが、配備のほかの部分のためにFARGATEとFARGATE_SPOTを持つのは60-enginesです -
サービスにリンクされたロール
AWSServiceRoleForEC2Fleetを用意します。standup.shが作ります。手で作るときは次のとおりです(2 回目以降の「has been taken」は無視します)ターミナルウィンドウ aws iam create-service-linked-role --aws-service-name ec2fleet.amazonaws.com || true# `spot` の offer を宣言する配備では、次も:aws iam create-service-linked-role --aws-service-name spot.amazonaws.com || true -
スタックを作る前に、イメージを ECR に入れます。 理由は
50-ttsと同じで、空のリポジトリを指すサービスがあると、CloudFormation があとから復旧できない状態で止まります(日本語の読み上げを足す)。standup.shは、イメージの段階でこれを行います。手でやるときは次のとおりですターミナルウィンドウ crane copy ghcr.io/ggml-org/llama.cpp:server-cuda <acct>.dkr.ecr.<region>.amazonaws.com/af-llamacpp:server-cuda# `image` の役:crane copy ghcr.io/k-k1/agent-fleet/comfyui:v0.37.0 <acct>.dkr.ecr.<region>.amazonaws.com/af-comfyui:v0.37.0- NAT 経由の GHCR は 12〜14 MB/s でした。527 秒のコールドスタートのうち 178 秒が取得だったので、ECR に置く意味があります
standup.shがimageの役のイメージをコピーするのは、ImageEnabled=trueのときだけです
イメージの中身を固定する
Section titled “イメージの中身を固定する”| オプション | 固定するもの |
|---|---|
standup.sh --llm-digest sha256:<...> |
llama.cpp のコピーの中身。server-cuda は中身が入れ替わるタグで、ツール呼び出しの解釈は llama.cpp のビルドで決まる。LlmImageTag は変えない。付けなければ、コピーは今までどおり |
standup.sh --comfy-digest sha256:<...> |
ComfyUI のコピーの中身。そのタグは comfyui-image.yml の再実行で上書きされうる |
update.sh --comfy-digest |
以前の ImageComfyImageTag の既定値からスタックを移すときに、update.sh が作るコピー |
詳細は deploy/aws/ecs/cfn/PARAMETERS-60-engines.md の LlmImageTag にあります。
standup.sh は、取得した状態に params/60-engines のファイルがあるときだけ 60-engines を構築します。
# ~/.config/agent-fleet/deploy/<profile>.<region>/params/60-engines# Every parameter has a default; standup.sh overrides NetworkStackName /# PlatformStackName / ServiceConnectNamespace from what it already knows.ServiceConnectNamespace=af.internal# Whether each role exists at all: its service, its DNS name, its row in the engine table.LlmEnabled=true# What the instance is: the ladder of GPU rungs (the first is the default), or the same list# with a `buy` column. This is the ONLY place the instance's shape is declared.LlmInstanceClasses=l4|L4 24GB|22000|g6.xlarge,g5.xlarge|4-8|15000-65536|1.17# The instance's root volume (GiB). The models land on it, so it has to hold every model the# role pulls from S3 plus the images.LlmStorageGiB=120# The image role, if you want it. Leave this out and no image service exists.ImageEnabled=true| パラメータ | 中身 |
|---|---|
<Role>Enabled |
その役があるかどうか。サービス・DNS 名・エンジン表の行がすべてこれで決まる。何を読み込むかは、ここでは決めない |
LlmInstanceClasses |
インスタンスの形。GPU の段のはしごで、最初の段が既定。buy の列を足した形でも書ける。インスタンスの形を宣言できるのはここだけで、どちらも宣言しない配備はエンジンを起動できない |
LlmStorageGiB |
ルートボリューム(既定は 120 GiB)。S3 から取るモデルとイメージがすべて収まるサイズにする |
- 「エンジンがいつまでも来ない」原因は、1 つの段に複数のタイプを書いたか、1 つの AZ で容量が足りないかのどちらかです。意図したインスタンスがいちばん安くなるようにしておきます。理由は
PARAMETERS-60-engines.mdの「The instance classes」と「The offers」にあります standup.shは、イメージを ECR にコピーし、llmのエンジンの API キーがなければ SSM に作り(/af-ws/engine-llm-key、SecureString)、読み上げのエンジンのあと・30-ingressの前に60-enginesをデプロイし、新しく作ったサービスを 0 台にして、スタックの出力EnginesSsmParamを30-ingressに渡しますimageの役には自分のキーがありません。ComfyUI には認証の仕組みがないので、セキュリティグループ(Control Plane からの 8080 だけ)がアクセス制御のすべてです
最初の構築は 1 回で、空のまま構築されます。 フェッチのサイドカーは「何も置かれていない」を成功として扱い、エンジンは待機します。空の S3 Bucket に LlmEnabled=true で構築すると、役は立ち上がって 0 台になり、最初のモデルを待ちます。あとから役を足すのも、同じ 1 行です。
モデルを手で S3 に置く
Section titled “モデルを手で S3 に置く”カタログに入れるには 2 つの段階があり、わざと分けています。
- 置く: ファイルを S3 に入れます。ふつうは管理の「推論エンジン」から取り込みます(推論エンジンにモデルを取り込む)。下の
run-taskは、Control Plane がインターネットに届かない配備のための、同じことを手でやる方法です - 有効にする: 同じ画面で行をオンにします。どの方法で置いても、行は無効の状態で届きます。「ファイルが S3 Bucket にある」と「メンバーが使ってよい」は別のことです
キーは ComfyUI の配置に合わせてあり、1 つのツリーをすべてのエンジンが使います。
| キー | 中身 |
|---|---|
llm/<name>.gguf、llm/loras/ |
llama.cpp のモデルと LoRA |
image/checkpoints/ |
1 ファイルのチェックポイント(SDXL など) |
image/loras/・image/vae/・image/text_encoders/・image/diffusion_models/ |
分かれたモデルの部品 |
インスタンスは S3 Bucket をそのままミラーします。image/checkpoints/x.safetensors は /models/image/checkpoints/x.safetensors になります。キーがそのままパスなので、別の名前を対応させて管理する必要はありません。
取り込みのタスクを動かす
Section titled “取り込みのタスクを動かす”エンジンが Hugging Face と通信することはありません。モデルは Fargate のタスクがスタックの S3 Bucket に 1 回置き、エンジンは起動時に S3 から取ります。
# sha256 は https://huggingface.co/api/models/<repo>?blobs=true の siblings[].lfs.sha256aws ecs run-task --cluster <cluster> --launch-type FARGATE \ --task-definition af-af-ecs-engines-ingest \ --network-configuration 'awsvpcConfiguration={subnets=[subnet-…],securityGroups=[sg-…],assignPublicIp=DISABLED}' \ --overrides '{"containerOverrides":[ {"name":"fetch","environment":[ {"name":"URL","value":"https://huggingface.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF/resolve/main/Qwen3-Coder-30B-A3B-Instruct-Q4_K_M.gguf"}, {"name":"SHA256","value":"<the lfs sha256>"}]}, {"name":"upload","environment":[{"name":"KEY","value":"llm/Qwen3-Coder-30B-A3B-Instruct-Q4_K_M.gguf"}]}]}'image の役も同じタスクで、URL とキーが違うだけです。SDXL の 6.94 GB は、取得と sha256 の検証に 161 秒、S3 への書き込みに 46 秒でした。
--overrides '{"containerOverrides":[ {"name":"fetch","environment":[ {"name":"URL","value":"https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors"}, {"name":"SHA256","value":"31e35c80fc4829d14f90153f4c74cd59c90b779f6afe05a74cd6120b893f7e5b"}]}, {"name":"upload","environment":[{"name":"KEY","value":"image/checkpoints/sd_xl_base_1.0.safetensors"}]}]}'2 つめのチェックポイントも、URL とキーを変えて同じように呼びます。Apache-2.0 か OpenRAIL で、ゲートがなく、量子化せずに L4 に載るものを選びます。
--overrides '{"containerOverrides":[ {"name":"fetch","environment":[ {"name":"URL","value":"https://huggingface.co/<owner>/<repo>/resolve/main/<file>.safetensors"}, {"name":"SHA256","value":"<the lfs sha256>"}]}, {"name":"upload","environment":[{"name":"KEY","value":"image/checkpoints/<file>.safetensors"}]}]}'- 分かれたモデル(FLUX.2 klein、Z-Image など、
--diffusion-model・テキストエンコーダー・VAE の組)も使えます。それぞれimage/diffusion_models/・image/text_encoders/・image/vae/に置きます - 上書きするのは、上の例のとおり
environmentだけです。 コンテナにEntryPointはなく、Commandはスクリプトそのもの(/opt/af/ingest-fetch.sh、/opt/af/ingest-upload.sh)です。commandを上書きするときは、シェルの文字列 1 つではなく argv の配列(["/opt/af/ingest-upload.sh"])で渡します - 取得の時間は読めません。sha256 も必ず渡します。 同じ NAT を通しても、Hugging Face からは 4〜236 MB/s と幅があり、ファイルにも経路にも関係なく変わりました。S3 からはどの試行でも 104〜147 MB/s でした。モデルを S3 に置くのはこのためです。途中で切れた 17 GB の GGUF も読み込めてしまい、でたらめに答えます
ゲートのあるリポジトリ(Hugging Face の API で gated: auto。FLUX.1-dev、SD3.5 など)は、運用担当者が Hugging Face でライセンスに同意し、そのアカウントのトークンを管理画面に登録しておく必要があります(推論エンジンにモデルを取り込む)。
- Control Plane はトークンを自分のデータベースに暗号化して保管し、このスタックが必ず作るシークレットに書きます。CloudFormation の操作は要りません
- トークンを読むのは取り込みのタスクだけで、エンジンのインスタンスには届きません。Control Plane も、書いた値を読み返せません(
PutSecretValueだけでGetSecretValueがありません)
メンバーから見えるもの
Section titled “メンバーから見えるもの”| 役 | 見えるもの |
|---|---|
llm |
設定は要りません。エージェントが Control Plane にエンジンを尋ね、opencode の設定にプロバイダーとして書くので、起動の選択肢に llamacpp/<model> が出ます。GPU のインスタンスが止まっているあいだも出ます。選んで最初のメッセージを送るとインスタンスが起動し、エンジンが答えるまでリクエストを保ちます。答えは再送なしで、最初の試行で届きます |
image |
既存の generate_image ツールのプロバイダーになります。ツールは既定でオフで、メンバーごとにオンにします。エンジンがあれば、generate_image は Codex の経路より先にこれを使い、編集とインペイントもできます。起動の選択肢には出ません。止まっているエンジンへの呼び出しは数分かかり、ツールは待つあいだ 10 秒ごとに進捗を通知します。これで opencode の 1 回の呼び出しの上限(60 秒)に切られません |
llama-server はルーターとして動き、有効にしたモデルがそれぞれ自分のコンテキストウィンドウで選択肢に並びます。管理者が考えることが 2 つあります。
- 有効にした GGUF はすべてインスタンスに同期されるので、合計のサイズの分だけコールドスタートが延びます(画面がモデルごとに見積もります)
LlmModelsMax(既定は 1)が、同時に持つモデルの数を決めます。上限に達しているときに別のモデルを頼むと、いまの答えが終わるのを待ってから、モデルを読み込み直します。画面に、VRAM にあるモデルと入れ替えの回数が出ます
知っておくこと
Section titled “知っておくこと”- テンプレートに
DesiredCountはわざと書いていません。50-ttsと同じ理由で、書くとスタックを更新するたびに数が戻り、答えの途中で GPU のインスタンスが止まります - 既定の容量プロバイダーの戦略は空で、空のままにします。 戦略があると、
LaunchType: FARGATEを明記していないサービスが GPU のインスタンスに載ります - 止めたエンジンは、数分のあいだ料金がかかります。
desired 0のあと、GPU のインスタンスでは 427 秒と 463 秒かかりました(CPU のインスタンスでは 93 秒)。アイドルの時間を短くしても縮むのはその時間だけで、この分は減りません - コールドスタートは秒ではなく分です。 S3 から、イメージが ECR にある状態で、待ち受けまで 527 秒でした。イメージの取得 178 秒と S3 からの取得 179 秒が並んで進み、そのあと 18.5 GB を VRAM に読み込むのに 267 秒です。Control Plane がそのあいだリクエストを保つので、利用者には最初の答えが遅いだけで、エラーにはなりません
imageの役のアイドルの時間はllmの半分(900 秒)です。 画像は、まわりに会話のない 1 回のリクエストだからです- ComfyUI は
/healthではなく/system_statsで確かめます。 認証なしですぐ答えるので、チェックポイントが読み込まれたかではなく、生きているかの確認です。comfyはリクエストごとにワークフローを組み、その中で名前を挙げたチェックポイントを使うので、読み込み済みのチェックポイントというものがありません - コントローラーが自動で行った操作は、すべて監査ログに残ります(
engine.llm.auto/engine.image.auto、実行者engine-<role>-controller)
自動の起動と停止を調整する
Section titled “自動の起動と停止を調整する”Control Plane 側のパラメータは EnginesSsmParam の 1 つだけです。30-ingress のテンプレートには余裕が少ないので、エンジンの表は SSM の /af-ws/ の下に置きます。そこは CpTaskRole がもともと読める範囲なので、権限は増えません。ほかはすべて Control Plane の環境変数で、このテンプレートはどれも設定しません。
| 環境変数 | 既定 | 中身 |
|---|---|---|
AF_ENGINE_WAKE_TIMEOUT |
900 | エンジンが立ち上がるあいだ、ストリーミングのリクエストを保つ時間。527 秒のコールドスタートに、遅い取得の余裕を足した値 |
AF_ENGINE_PLAIN_HOLD |
45 | ストリーミングでないリクエストを保つ時間。ハートビートがないので、前段のプロキシのアイドルのタイムアウトより短くします(30-ingress は ALB を 60 秒にします)。超えると 503 engine_waking と Retry-After を返し、呼び出し側がやり直します。AF_ENGINE_WAKE_TIMEOUT を超えることはありません |
AF_ENGINE_LLM_CONTROL_INTERVAL_SEC |
30 | 見に行く間隔。0 で制御を完全に止めます |
AF_ENGINE_LLM_IDLE_SEC |
スタックの LlmIdleSec(1800) |
リクエストがないまま、この時間がたつと止める。0 で止めません。起動の期限より短くはなりません |
AF_ENGINE_LLM_START_DEADLINE_SEC |
スタックの LlmStartDeadlineSec(900) |
この時間までに running にならない起動は失敗とみなす。実際のコールドスタートより長くします。300 秒では、GPU の起動がすべて失敗と記録され、クールダウンが倍々に延びます |
AF_ENGINE_LLM_FAIL_COOLDOWN_SEC |
900 | 失敗した起動が次の起動を止める時間。続けて失敗するたびに倍になります(最大 16 倍) |
AF_ENGINE_LLM_WINDOW_SEC |
300 | 需要を数える時間枠。1 回のリクエストが 1 単位です。推論ではリクエストそのものが意図で、読み上げのように Polly が代わりに読むことはありません |
AF_ENGINE_LLM_*には、同じ意味のAF_ENGINE_IMAGE_*があります。既定はimageの役のスタックのパラメータ(ImageIdleSecは 900、ImageStartDeadlineSecは 900)から取ります- 真ん中の名前はエンジンのキーです。3 つめの役ができても同じ形になります
AF_ENGINE_WAKE_TIMEOUTはすべての役で共通です
最初のリクエストを保つ
Section titled “最初のリクエストを保つ”止まっているエンジンの起動には数分かかり、opencode は 300 秒であきらめます。ただし、経過時間ではなく無音の時間で切ります。
- Control Plane は、ストリーミングのリクエストにすぐ
200 text/event-streamを返し、エンジンの最初のバイトが届くまでハートビート(SSE のコメント行を 10 秒ごと)を送ります - 300 秒は無音の上限で、待ち時間の上限ではありません。 400 秒待っても、再送なしで答えが届きました
503とRetry-Afterは、ストリーミングでないリクエストと、本当に起動に失敗したときだけに使います。503 はクライアントの限られた再試行を 1 回使ってしまい、その回数はこちらからはわかりません
ストリーミングでないリクエストは、900 秒も保てません。決めるのは Control Plane ではなく前段です。
- ALB の
idle_timeout.timeout_seconds(30-ingressでは 60 秒)は、1 分のあいだ応答のバイトが流れない接続を閉じます。止まっていたimageのエンジンへの最初のgenerate_imageは、エンジンが 165 秒かかったために503で 60 秒ちょうどに切れました - そこで、ストリーミングでないリクエストは前段より短い
AF_ENGINE_PLAIN_HOLD(45 秒)で503 engine_wakingとRetry-Afterを返します。ワークスペースのcomfyプロバイダーは自分の 16 分の範囲で尋ね続けるので、1 回のツール呼び出しで 1 枚の画像が返ります - この ALB より厳しいプロキシを前に置くときは、
AF_ENGINE_PLAIN_HOLDをそれに合わせて下げます。 Control Plane はそのタイムアウトを知る方法がありません
エージェント向け
この指示をエージェントに送ると、このページを読ませられます。
https://agent-fleet.org/docs/ja/operate/aws-ecs/engines/index.md を読んで