1 コマンドで Hugging Face Jobs で vLLM サーバーを実行可能に

記事一覧に戻る

• 前提条件
• サーバーの起動
• どこからでもクエリを実行
• クリーンアップ
• さらに進めて：より大きなモデル
• さらに進めて：UI でチャットする
• さらに進めて：実行中のサーバーに SSH 接続する
• さらに進めて：Pi と組み合わせてコーディングエージェントのバックエンドとして利用する
• HF Jobs か Inference Endpoints か？
• 関連資料

単一のコマンドで、Hugging Face のインフラ上でプライベートな OpenAI 互換 LLM エンドポイントを起動できます。サーバーのプロビジョニングも Kubernetes も不要で、使用した秒数に応じた従量課金です。一度起動すれば、お使いのラップトップやノートブック、あるいはどこからでもクエリを実行できます。

これはテスト、評価（evals）、またはバッチ生成のためにモデルを素早く立ち上げる最速の方法です。（管理された本番環境対応サービスをお探しの場合は、Inference Endpoints が適しています。どちらを選ぶべきかの詳細については、末尾の 「HF Jobs か Inference Endpoints か？」 をご覧ください。）

以下に、全体の流れを最初から最後まで解説します。

前提条件

• 支払い方法、または正味のプリペイド残高（Jobs はハードウェアの使用量に応じて分単位で課金されます）。
• huggingface_hub >= 1.20.0: pip install -U "huggingface_hub>=1.20.0" を実行してください。
• ローカルでログイン済み：hf auth login を実行してください。

サーバーの起動

hf jobs run は、Hugging Face インフラ向けの Docker 実行コマンドです。公式の vllm/vllm-openai イメージを使用し、--flavor オプションで GPU を要求し、--expose で vLLM のポートを公開します：

⟦CODE_0⟧

hf jobs run --flavor a10g-large --expose 8000 --timeout 2h \

vllm/vllm-openai:latest \

vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000

--expose 8000 は、コンテナのポートを Hugging Face のパブリックジョブプロキシ経由でルーティングします（完全な参照については Serve Models guide をご覧ください）。このコマンドを実行すると、サーバーに到達できる URL が表示されます:

✓ Job started

id: 6a381ca1953ed90bfb947332

url: https://huggingface.co/jobs/qgallouedec/6a381ca1953ed90bfb947332

Hint: Exposed ports are reachable at (requires an HF token with read access to the job):

https://6a381ca1953ed90bfb947332--8000.hf.jobs

6a381ca1953ed90bfb947332 はあなたのジョブ ID です。これを記録しておいてください。後ほど、このポストの残りで <job_id> をプレースホルダーとして使用します。

重みのダウンロードと起動に数分かかるので、ログに「Application startup complete」と表示されるまでお待ちください。そうすれば稼働開始です。

どこからでもクエリを実行する

vLLM は OpenAI API に準拠しており、すべてのリクエストには Hugging Face トークンをベアラートークンとして使用すれば十分です。最も簡単な方法は curl を使うことです:

curl https://<job_id>--8000.hf.jobs/v1/chat/completions \

-H "Authorization: Bearer $(hf auth token)" \

-H "Content-Type: application/json" \

-d '{

"model": "Qwen/Qwen3-4B",

"messages": [{"role": "user", "content": "Hello!"}],

"chat_template_kwargs": {"enable_thinking": false}

}'

これにより、通常の OpenAI スタイルの JSON が返されます。choices[0].message.content には「Hello! How can I assist you today? 😊」という内容が含まれています。

あるいは、Python から OpenAI クライアントを公開された URL に指し示し、トークンを API キーとして渡すこともできます:

from huggingface_hub import get_token

from openai import OpenAI

client = OpenAI(

base_url="https://<job_id>--8000.hf.jobs/v1",

api_key=get_token(),

)

resp = client.chat.completions.create(

model="Qwen/Qwen3-4B",

messages=[{"role": "user", "content": "Hello!"}],

extra_body={"chat_template_kwargs": {"enable_thinking": False}},

)

print(resp.choices[0].message.content)

Hello! How can I assist you today? 😊

開始前に簡単なヘルスチェックを実行してください：curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)" を実行すると、モデルの一覧が表示されるはずです。

🔐 エンドポイントはゲートされており、公開されていません。 すべてのリクエストには、ジョブのネームスペースに対する読み取り権限を持つ HF トークンを含める必要があります。通常のブラウザからのアクセスは拒否されます。実質的に、ジョブプロキシが API ゲートウェイとして機能しており、アクセス権限はあなた（およびあなたの組織）に限定されています。これはプライベート利用には問題ありませんが、URL については注意が必要です：公開されていると期待して URL を共有したり、信頼できない場所にトークンを貼り付けたりしないでください。より細粒度なアクセスや公開アクセスが必要な場合は、代わりに適切なゲートウェイを前面に配置してください。または、以下の HF Jobs と Inference Endpoints の比較 を参照してください。

クリーンアップ

ジョブは秒単位で課金されるため、作業が完了したらサーバーを停止してください：

hf jobs cancel <job_id>

設定した --timeout はセーフティネット（自動停止機能）ですが、明示的にキャンセルする方がコストを抑えられます。a10g-large の料金は 1.50 ドル/時間です。hf jobs ハードウェアページで完全な価格リストを確認し、モデルに適合する最も小さなフレーバーを選択してください。

さらに先へ：より大きなモデル

同じコマンドははるかに大きなモデルにもスケールします --flavor をより強力なものにし、vLLM に --tensor-parallel-size パラメータでモデルを GPU 間でシャードするように指示してください。例えば、2× H200 環境での 122B Qwen3.5 mixture-of-experts モデルの場合:

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \

vllm/vllm-openai:latest \

vllm serve Qwen/Qwen3.5-122B-A10B \

--host 0.0.0.0 --port 8000 --tensor-parallel-size 2 \

--max-model-len 32768 --max-num-seqs 256

--tensor-parallel-size はフレーバー内の GPU 数と一致させる必要があります（h200x2 → 2、h200x8 → 8）。利用可能なリソースを確認するには hf jobs hardware を実行し、より大きなモデルにはダウンロードや読み込みに時間がかかるため、より長い --timeout を設定してください。大規模モデルの場合、H200 フレーバーが通常は最もコストパフォーマンスに優れています。

--max-model-len 32768 および --max-num-seqs 256 というフラグは、このモデル固有の設定です。Qwen3.5-122B はハイブリッド Mamba/アテンションアーキテクチャであり、デフォルトのコンテキスト長が 256K トークンですが、これでは vLLM のデフォルトバッチ設定に対して十分なメモリが残っていません。コンテキスト長と同時シーケンス数を制限することで、GPU メモリ内に収まるようにしています。もしモデルがメモリ不足エラーやキャッシュブロックエラーで起動しない場合は、まずこれらの値を下げることが最初の対処法となります。それ以外の要素（公開された URL、OpenAI クライアント、トークン認証）はすべて全く同じままです。

さらに進んで：UI でチャットする

curl ではなくチャットウィンドウをお好みですか？数行の Gradio コードで、同じエンドポイントに接続できます。Qwen3 の思考プロセスを別のフィールドとして返すように（必須ではありませんが有用です）vllm serve コマンドに --reasoning-parser deepseek_r1 を追加し、このコードをローカルで実行してください（ジョブ ID が必要になります）:

import gradio as gr

from gradio import ChatMessage

from huggingface_hub import get_token

from openai import OpenAI

client = OpenAI(base_url="https://<job_id>--8000.hf.jobs/v1", api_key=get_token())

def chat(message, history):

messages = [{"role": m["role"], "content": m["content"]} for m in history if not m.get("metadata")]

messages.append({"role": "user", "content": message})

stream = client.chat.completions.create(model="Qwen/Qwen3-4B", messages=messages, stream=True)

thinking, answer = "", ""

for chunk in stream:

delta = chunk.choices[0].delta

thinking += delta.model_extra.get("reasoning", "")

answer += delta.content or ""

out = []

if thinking.strip():

status = "done" if answer.strip() else "pending"

out.append(ChatMessage(role="assistant", content=thinking, metadata={"title": "💭 Thinking", "status": status}))

if answer.strip():

out.append(ChatMessage(role="assistant", content=answer))

yield out

gr.ChatInterface(chat).launch()

実行して、http://127.0.0.1:7860 をブラウザで開き、チャットを開始してください。推論（reasoning）が折りたたみパネルにストリーミングされ、回答はその下に表示されます。

さらに踏み出す：稼働中のサーバーへの SSH 接続

起動時の失敗をデバッグしたり、GPU メモリを監視したり、ログを対話的に追跡したい場合ですか？実行中のジョブに直接シェルを開くことができます。--ssh オプションで起動し、公開鍵が huggingface.co/settings/keys に登録されていることを確認してください:

hf jobs run --flavor a10g-large --expose 8000 --timeout 2h --ssh \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000

その後、ジョブ ID を使用して接続します:

hf jobs ssh <job_id>

これでコンテナ内にいる状態になります。ここでは nvidia-smi を実行したり、プロセスを検査したり、モデルに直接アクセスしたりできます。外部からログを読むよりも、デバッグや監視がはるかに容易になります。SSH サポートには huggingface_hub >= 1.20.0 が必要です。

さらに先へ：Pi を用いたコーディングエージェントのバックエンドとして利用する

同じエンドポイントを使用して、ターミナル上のコーディングエージェントを構築することも可能です。Pi はプロバイダーに依存しないエージェントハーンです。これをジョブに指向させることで、ご自身でホストしたモデル上で動作する、読み書き・編集・Bash 実行が可能なエージェントを得ることができます。

まず設定すべき点があります：エージェントはツール呼び出しを通じてモデルを駆動しますが、vLLM はサーバー起動時にツール呼び出し機能が有効になっていない限りそれを受け付けません。したがって、--enable-auto-tool-choice を指定し、かつモデルファミリーに一致する --tool-call-parser（Qwen の場合は hermes）を指定して再実行してください。また、より強力なモデルを使用することでエージェントの性能も向上するため、ここでは大規模モデルを採用するのが適しています：

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3.5-122B-A10B \
  --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 \
  --max-model-len 32768 --max-num-seqs 256 \
  --reasoning-parser deepseek_r1 \
  --enable-auto-tool-choice --tool-call-parser hermes

次に、~/.pi/agent/models.json にジョブをカスタムプロバイダーとして追加します：

{
  "providers": {
    "hf-jobs": {
      "baseUrl": "https://<job_id>--8000.hf.jobs/v1",
      "api": "openai-completions",
      "apiKey": "!hf auth token",
      "models": [
        { "id": "Qwen/Qwen3.5-122B-A10B" }
      ]
    }
  }
}

最後に、この設定に対してエージェントを起動します：

pi

数コマンド前に起動したモデルが、今やターミナル上で対話型のコーディングエージェントを駆動しています。

HF Jobs と推論エンドポイントの比較

HF Jobs は、Hugging Face でモデルをサービス提供するための唯一の方法ではありません。Inference Endpoints は、同じ目的のための管理型製品であり、どちらが適しているかは、あなたが何を求めているかによります。

HF Jobs を利用するのは、最大限の柔軟性と制御を望む場合です。これは Hugging Face のインフラ上での単なる docker run であり、イメージ、正確な vllm serve フラグ、ハードウェアを自分で選択でき、ジョブが実行されている間のみ秒単位で課金されます。そのため、実験、ワンオフの評価、バッチ生成、あるいは何かを決める前にモデルを試す場合に非常に適しています。

Inference Endpoints を利用するのは、より本番環境向け（プロダクションレディ）なものを望む場合です。これには、長期間稼働するサービスに必要な運用上の利便性が追加されています：より細粒度のアクセス制御（エンドポイントは公開、保護、または非公開に設定可能）、スケール・トゥ・ゼロ機能（非アクティブ期間中は課金されない）。耐久性のあるエンドポイントを構築する場合やジョブを実行する場合ではなく、こちらが適したツールです。

さらに読む

この投稿は vLLM に焦点を当てていますが、ポートを公開するパターンは、OpenAI 互換サーバーであればすべてに適用可能です。llama.cpp で GGUF をサービス提供したり、代わりに SGLang を実行したい場合は、それらのバックエンドを詳しく解説している Serve Models on Jobs guide をご覧ください。

⟦CODE_0⟧