ジョブでモデルをサーブする

公開ポートを使用すると、Jobは一時的な推論サーバーとして機能します。GPUフレーバーでvLLMを起動し、OpenAI互換のクライアントをJobのURLに向ければ、使用が完了したらJobをキャンセルするだけです。Jobが実行されている間、1分単位で課金され、Jobが終了するとエンドポイントも消去されます。

エンドポイントが最終的な成果物ではなく、あくまで手段として機能する場合に、このアプローチは適しています。具体的には、評価の実行、データラベリングのセッション、ホットモデルに対するプロンプトの反復改善、あるいは午後だけのデモなどです。

より永続的なエンドポイント、つまり消滅しないものが必要な場合は、オートスケーリング、モニタリング、安定したURLを備えたマネージドインフラストラクチャを提供するInference Endpointsが適しています。

vLLMサーバーを開始する

vllm/vllm-openaiイメージにはすべてが事前インストールされています。1つのコマンドでOpenAI互換のサーバーを起動できます:

>>> hf jobs run --detach --expose 8000 --flavor a10g-small -s HF_TOKEN \
...   vllm/vllm-openai \
...   vllm serve LiquidAI/LFM2.5-8B-A1B --max-model-len 8192
✓ Job started
  id: 6a2b137a59bbdade52d4a58c
  url: https://huggingface.co/jobs/davanstrien/6a2b137a59bbdade52d4a58c
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a2b137a59bbdade52d4a58c--8000.hf.jobs

-s HF_TOKEN は、Hugging Face トークンをジョブにシークレットとして転送します。これによりモデルのダウンロードが認証されます。ゲート付きモデルやプライベートモデルには必須であり、それ以外のモデルでもレート制限が緩和され、ダウンロードが高速化されます。

Jobs は指定したコマンドを直接実行します。docker run のようにイメージの entrypoint に引数を渡すわけではありません。したがって、--model ... のみではなく、vllm serve ... のように完全なコマンドを明示的に記述してください。

サーバーの準備が整うまで数分かかります（イメージのプル、モデルのダウンロード、モデルのロード）。hf jobs logs -f <job_id> を実行して進捗を追跡してください。ログにApplication startup complete と表示された時点で、サーバーの準備が完了しています。

クライアントを接続する

公開ポートには、ジョブのネームスペースに対するreadアクセス権限を持つ HF トークンを、Bearer トークンとして渡す必要があります。OpenAI 互換サーバーの場合、このトークンはクライアントの API キーとしてそのまま使用でき、ベース URL は公開ポートの URL に/v1を付加したものです:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://6a2b137a59bbdade52d4a58c--8000.hf.jobs/v1",
    api_key=os.environ["HF_TOKEN"],  # any token with read access to the job's namespace
)

response = client.chat.completions.create(
    model="LiquidAI/LFM2.5-8B-A1B",
    messages=[{"role": "user", "content": "Write a haiku about ephemeral compute."}],
)
print(response.choices[0].message.content)

LFM2.5は推論モデルであるため、最終的な回答の前に<think>タグ内にその推論過程が含まれます。

またはcurlを使用します:

>>> curl https://6a2b137a59bbdade52d4a58c--8000.hf.jobs/v1/chat/completions \
...   -H "Authorization: Bearer $HF_TOKEN" \
...   -H "Content-Type: application/json" \
...   -d '{"model": "LiquidAI/LFM2.5-8B-A1B", "messages": [{"role": "user", "content": "Hello!"}]}'

トークンはAuthorizationヘッダー内で送信されるため、これらの URL はスクリプト、ノートブック、エージェントなど、OpenAI 互換 API を使用するあらゆる場所で機能します。ブラウザで直接開くことはできません。HF トークンなしでポートを公開するには、--expose-publicを使用してください。Expose Portsを参照してください。

llama.cppでGGUFモデルをサーブする

このパターンは、HTTPを扱うサーバーであればすべてで機能します。llama.cppのllama serveは-hfフラグを指定することで、GGUFファイルをHubから直接取得し、同じOpenAI互換APIを提供します。例えば、Gemma 4 E4BをGemmaの推奨サンプリング設定でサーブするには:

>>> hf jobs run --detach --expose 8080 --flavor a10g-small -s HF_TOKEN \
...   ghcr.io/ggml-org/llama.cpp:server-cuda -- \
...   /app/llama serve -hf ggml-org/gemma-4-E4B-it-GGUF \
...   --host 0.0.0.0 --port 8080 -ngl 99 \
...   --temp 1.0 --top-p 0.95 --top-k 64

-- は、ジョブのコマンドと hf jobs run 自身のオプションを区切るために使用されます。ここでは、llama serve のフラグが CLI 自体によって解析されてしまうのを防ぐために必要です。

モデルリポジトリを読み取り専用ボリュームとしてマウントし、サーバーを直接ファイルに指向することで、モデルのダウンロードを完全にスキップできます。

コピーしました

>>> hf jobs run --detach --expose 8080 --flavor a10g-small -s HF_TOKEN \
...   -v hf://ggml-org/gemma-4-E4B-it-GGUF:/model:ro \
...   ghcr.io/ggml-org/llama.cpp:server-cuda -- \
...   /app/llama serve --model /model/gemma-4-E4B-it-Q4_K_M.gguf \
...   --host 0.0.0.0 --port 8080 -ngl 99

ダウンロードするものが何もないため、サーバーははるかに高速に起動します。モデルはマウントされたリポジトリから、読み込み中にストリーミングされます。

サーバーは0.0.0.0でリッスンする必要があります。llama serveはデフォルトで127.0.0.1にバインドされるため、ジョブのプロキシから到達できません。明示的に--host 0.0.0.0を指定してください。

他のOpenAI互換サーバー（SGLang、…）にも同じことが当てはまります。公開されたポートでサーバーを起動し、0.0.0.0でリッスンし、HFトークンをAPIキーとして使用して接続します。

サーバーを停止する

ジョブ（およびその課金）は、キャンセルした場合またはタイムアウトに達した場合（デフォルトは30分。長時間のセッションには--timeoutを明示的に設定してください）に停止します：

>>> hf jobs cancel <job_id>

公開ポートにはhuggingface_hub >= 1.19.0 が必要であり、ジョブのハードウェア料金に上乗せして課金されます — Jobs pricingを参照してください。