エラーメッセージ本番環境でボットやスクリプトを実行しているときに、突然ログが次のような特定の例外で埋め尽くされた場面を想像してみてください。
huggingface_hub.utils._errors.HfHubHTTPError: 503 Server Error: Service Unavailable for url: https://api-inference.huggingface.co/models/... {"error":"Model is currently loading","estimated_time":20.0}
これは、無料または共有のInference APIを使用する際によくある障害です。永続的な失敗ではありません。しかし、HuggingFaceのインフラ管理方法に対応していないスクリプトは、これでクラッシュしてしまいます。
原因：コールドスタートHuggingFaceは50万以上のモデルをホストしています。共有サーバー上で、すべてのモデルを24時間365日GPUメモリにロードしたままにすることは不可能です。数時間呼び出しがないモデルは、より人気のあるモデルのためのスペースを確保するために「スワップアウト（退避）」されます。
休止状態のモデルをリクエストすると、HuggingFaceは「コールドスタート」をトリガーします。503エラーは、「現在モデルを起動中ですが、まだ準備ができていません。約20秒後に再試行してください」という通知です。
ステップ 1：迅速な修正（huggingface_hubライブラリ）公式の huggingface_hub Pythonライブラリを使用している場合は、パラメータを1つ追加するだけで解決できます。開発者はすでに、自動的に待機を処理する仕組みを組み込んでいます。
from huggingface_hub import InferenceClient
client = InferenceClient(model="bigscience/bloomz-560m")
# 'wait_for_model=True' は、モデルがメモリに完全にロードされるまで
# クライアントにブロックと再試行を行うよう指示します。
try:
response = client.text_generation(
"How do I fix a 503 error?",
wait_for_model=True
)
print(response)
except Exception as e:
print(f"Request failed: {e}")
これを True に設定すると、クライアントはエラーから estimated_time（推定時間）を読み取り、モデルが稼働するまでスクリプトを一時停止します。
ステップ 2：カスタム再試行ロジック（Requests/Raw API）requests や fetch を介してAPIを呼び出す場合は、再試行ロジックを自分で実装する必要があります。最初の503エラーでクラッシュしてしまうと、単にモデルが眠っていただけで失敗する脆弱なアプリケーションになってしまいます。
以下は、待機処理を行う堅牢なPythonのループ処理です。
import requests
import time
API_URL = "https://api-inference.huggingface.co/models/YOUR_MODEL_ID"
headers = {"Authorization": "Bearer YOUR_HF_TOKEN"}
def query_with_retry(payload, max_retries=3):
for i in range(max_retries):
response = requests.post(API_URL, headers=headers, json=payload)
output = response.json()
# モデルがまだロード中かどうかを確認
if response.status_code == 503 and "loading" in str(output):
# estimated_time がない場合はデフォルトで20秒に設定
wait_time = output.get("estimated_time", 20)
print(f"Model loading. Waiting {wait_time}s (Attempt {i+1}/{max_retries})...")
time.sleep(wait_time)
continue
return output
raise Exception("Model failed to load within the retry limit.")
data = query_with_retry({"inputs": "The cat sat on the mat."})
print(data)
ステップ 3：モデルのプリウォーミング（事前準備）初回のユーザーに対して20秒の遅延を許容できない場合は、モデルを「プリウォーミング」することができます。これは、アプリケーションの起動フェーズやスケジュールされたタスクを通じて、ダミーのリクエストを送信することを意味します。
- Startup Warmup（起動時のウォームアップ）: サーバーの起動時に、
wait_for_model=Trueを指定してモデルを一度呼び出します。これにより、最初の実際のユーザーが来る前にモデルが準備完了状態になります。- Keep-alive Cron（生存確認の定期実行）: あまり使用されないモデルの場合、15分ごとに小さなリクエストをAPIに送信します。これにより、HuggingFaceのキャッシュ内でモデルを「ホット（稼働状態）」に保つことができます。## ステップ 4：タイムアウト設定の確認wait_for_modelを有効にすると、HTTPリクエストが最大60秒間開いたままになる可能性があります。Nginx、Gunicorn、Cloudflareなどの独自のインフラが、待機中に接続を切断しないように確認する必要があります。requestsやhttpxの場合は、クライアント側のタイムアウトを少なくとも120秒に増やしてください。
# モデルがロードされるまで十分な時間を与える
response = requests.post(API_URL, headers=headers, json=payload, timeout=120)