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

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

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

> [!TIP]
> より永続的なエンドポイント、つまり消滅しないものが必要な場合は、オートスケーリング、モニタリング、安定したURLを備えたマネージドインフラストラクチャを提供する[Inference Endpoints](https://huggingface.co/docs/inference-endpoints)が適しています。

## vLLMサーバーを開始する

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

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

> [!NOTE]
> Jobs は指定したコマンドを直接実行します。`docker run` のようにイメージの entrypoint に引数を渡すわけではありません。必ず完全なコマンドを指定してください（`vllm serve ...` のように、`--model ...` だけでは不十分です）。

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

## クライアントを接続する

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

```python
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`を使用します:

```bash
>>> 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](./jobs-configuration#expose-ports)を参照してください。

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

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

```bash
>>> 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 自体によって解析されてしまうのを防ぐために必要です。

> [!TIP]
> モデルリポジトリを読み取り専用ボリュームとしてマウントし、サーバーを直接ファイルに指向することで、モデルのダウンロードを完全にスキップできます。
>
> ```bash
> >>> 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
> ```
>
> ダウンロードするものが何もないため、サーバーははるかに高速に起動します。モデルはマウントされたリポジトリから、読み込み中にストリーミングされます。

> [!WARNING]
> サーバーは`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`を明示的に設定してください）に停止します：

```bash
>>> hf jobs cancel <job_id>
```

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