hf-model-inference

HuggingFace モデル推論サービス

概要

このスキルでは、HuggingFace モデル推論サービスをセットアップするための手順を説明します。モデルのダウンロード、キャッシュ戦略、Flask API の作成、サービスのデプロイパターンを扱います。

ワークフロー

フェーズ 1：環境のセットアップ

1. パッケージマネージャーが利用可能か確認する

   • 依存関係をインストールする前に、uv、pip、または conda が利用可能か確認します
   • 利用可能な場合は、依存関係をより速く解決できる uv を優先します

2. 必要なパッケージをインストールする

   • コア：transformers、torch（または tensorflow）
   • API：REST エンドポイント用の flask
   • 大容量パッケージのインストールでは適切なタイムアウトを設定します（300 秒以上）

3. モデルキャッシュディレクトリを作成する

   • モデルを保存する専用ディレクトリを用意します（例：/app/model_cache/model_name）
   • ダウンロードの前に、必要に応じて親ディレクトリを作成します

フェーズ 2：モデルのダウンロード

1. API の起動とは別にモデルをダウンロードする

   • 専用のダウンロードスクリプトを使用するか、サービスの起動前にインラインでダウンロードします
   • これにより、API の初期化中にタイムアウトが発生するのを防げます

2. キャッシュディレクトリを明示的に指定する

   from transformers import pipeline
   model = pipeline("task-type", model="model-name", cache_dir="/path/to/cache")
   

3. 確認手順（見落とされがちです）

   • ダウンロード後、対象ディレクトリにモデルファイルが存在することを確認します
   • ディレクトリの内容を一覧表示し、ダウンロードが正常に完了したことを確認します

フェーズ 3：API の作成

1. Flask アプリケーションの構成

   from flask import Flask, request, jsonify
   from transformers import pipeline
   
   app = Flask(__name__)
   model = None  # Load at startup
   
   @app.route('/predict', methods=['POST'])
   def predict():
       # Handle inference
       pass
   

2. 入力の検証要件

   • リクエスト JSON に必須フィールドが含まれているか確認します
   • フィールドの型（文字列、数値など）を検証します
   • 空または空白文字のみの入力を処理します
   • 適切な HTTP ステータスコードとともに、わかりやすいエラーメッセージを返します

3. エラーレスポンスの形式

   • 一貫した JSON 構造を使用します：{"error": "message"}
   • クライアントエラーには 400、サーバーエラーには 500 を返します

フェーズ 4：サービスのデプロイ

1. ホストとポートの設定

   • 外部からアクセスできるよう、0.0.0.0 にバインドします
   • 指定されたポートを使用します（一般的には 5000）
   • 例：app.run(host='0.0.0.0', port=5000)

2. バックグラウンドでの実行

   • テスト時は Flask をバックグラウンドモードで起動します
   • テストリクエストを送信する前に、起動時間として 2～3 秒待ちます

検証戦略

モデルダウンロードの検証

• ダウンロード後、キャッシュディレクトリの内容を一覧表示します
• 想定されるモデルファイル（config.json、モデルの重み、トークナイザーファイル）が存在することを確認します

API の機能テスト

以下のシナリオを順番にテストします。

1. 成功ケース：成功するはずの有効な入力

   curl -X POST http://localhost:5000/predict \
     -H "Content-Type: application/json" \
     -d '{"text": "valid input text"}'
   

2. 異なる入力のケース：さまざまなレスポンスを確認するための別の有効な入力

   curl -X POST http://localhost:5000/predict \
     -H "Content-Type: application/json" \
     -d '{"text": "different input text"}'
   

3. エラーケース：必須フィールドが欠落している場合

   curl -X POST http://localhost:5000/predict \
     -H "Content-Type: application/json" \
     -d '{}'
   

追加のエッジケース（任意）

• 空文字列の入力
• 非常に長いテキストの入力
• JSON 以外のコンテンツタイプ
• 不正な形式の JSON
• 誤ったフィールド型（文字列の代わりに数値）

よくある落とし穴

インストールに関する問題

• タイムアウトが不十分：torch などの大容量パッケージには、長めのタイムアウト（5 分以上）が必要です
• システム依存関係の不足：一部のモデルでは追加のシステムパッケージが必要です

モデル読み込みに関する問題

• コールドスタート時のタイムアウト：最初のリクエストでモデルを読み込むとタイムアウトが発生します。代わりに起動時に読み込みます
• メモリの制約：大規模モデルは利用可能な RAM を超える場合があります。モデルの要件を確認してください

API に関する問題

• 開発サーバーに関する警告：Flask の開発サーバーは本番環境には適していません。テストには使用できますが、この制限に注意してください
• 正常なシャットダウンができない：正常に終了できるよう、シグナル処理を検討してください
• ヘルスチェックエンドポイントがない：/health エンドポイントを追加すると、デバッグに役立ちます

プロセス管理

• バックグラウンドプロセスの確認：バックグラウンドで起動した後、プロセスが実行中であることを確認します
• ポートの競合：起動前に、指定されたポートがすでに使用されていないか確認します

タスク計画テンプレート

HuggingFace の推論タスクに取り組む際は、次のように作業を進めます。

1. 環境の確認（パッケージマネージャー、システム要件）
2. 適切なタイムアウトを設定して依存関係をインストール
3. キャッシュディレクトリの作成
4. 明示的なキャッシュパスを指定してモデルをダウンロード
5. モデルのダウンロードを検証
6. 検証機能付きの API スクリプトを作成
7. サービスをバックグラウンドで起動
8. 機能テスト（正常系、異常系、エラーケース）
9. エッジケースのテスト（時間に余裕がある場合）