Communitygithub.com

nynuz/ml-serving-skills

機械学習モデルのAPIバックエンドからフロントエンドまで、モデル提供(サービング)のためのエージェントスキル集です。

ml-serving-skills とは?

このスキルは、Hugging Faceの`model_id`を指定するだけで、本番運用向けのFastAPIプロジェクトを自動生成します。生成されるコードは、レイヤードアーキテクチャ、起動時のモデル読み込み(リクエストごとに読み込まない)、タスクに適した推論エンドポイント、明示的な上限付きバッチ処理、入出力バリデーション、ヘルスチェック/準備態勢プローブ、構造化エラー処理、オプションの評価/ベンチマークスクリプトを含みます。テキスト分類、トークン分類(NER)、テキスト埋め込み、画像生成の4つのタスクファミリーをサポートし、それぞれに最適化されたエンドポイント形状とライブラリ(transformers、sentence-transformers、diffusers)を使用します。生成物はローカル実行専用で、Dockerやクラウドデプロイ、フロントエンドコードは含まず、認証やレート制限も設計上実装されません。ユーザーは`model_id`を提供するだけで、Hugging Face Hubの公開APIによるモデル検査、リファレンスファイルの読み取り、プロジェクトのスキャフォールディング、テスト実行までの全工程をスキルが自動化します。

対応~Claude Code~Codex CLI~Cursor
npx skills add nynuz/ml-serving-skills

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

HF Model → FastAPI Builder

このスキルの機能

Hugging Face の model_id を入力として、自己完結型のローカル本番用 FastAPI プロジェクトを生成します。レイヤードアプリ構造、起動時に一度だけ読み込まれるモデル(リクエストごとに読み込まない)、タスクに適した推論エンドポイント、明示的な上限付きバッチ処理、入出力バリデーション、ヘルスチェック/準備態勢プローブ、構造化エラー処理、オプションの評価/ベンチマークスクリプトを含みます。

以下の4つのタスクファミリーをサポートし、それぞれ異なるエンドポイント形状と基盤ライブラリを使用します。

タスクファミリーHF の概念ライブラリリファレンスファイル
テキスト分類AutoModelForSequenceClassificationtransformersreferences/text-classification.md
トークン分類(NER)AutoModelForTokenClassificationtransformersreferences/token-classification-ner.md
テキスト埋め込み文章埋め込みモデルsentence-transformersreferences/embeddings.md
画像生成拡散パイプラインdiffusersreferences/image-generation.md

適用範囲の境界 — 開始前に必読

  • ローカルのみ。 Docker、Kubernetes、クラウドデプロイ(Railway、AWS など)は含みません。出力はユーザーが uvicorn で自分のマシン上で実行するプロジェクトです。
  • バックエンドのみ。 フロントエンド/クライアントコード(React、Next.js、fetch 呼び出しなど)は絶対に生成しません。ユーザーがAPIを呼び出すUIを希望する場合は、それは別の関心事であると伝え、APIの境界で停止してください。フロントエンドの開発サーバーが後でAPIを呼び出せるように、寛容なローカルCORSを有効にすることは問題ありません。それはバックエンドの設定の関心事であり、フロントエンドコードではありません。
  • サービング(モデル提供)専用、トレーニングは対象外。 ユーザーがモデルをファインチューニングまたはトレーニングしたい場合、このスキルは適切なツールではありません。その旨を伝えてください。
  • ローカル、シングルユーザーの脅威モデル。 生成されるサービスには認証もレート制限も意図的に実装されません。これらは localhost で実行することを想定しています。ただし、入力コストの上限(バッチサイズ、文字列長、生成パラメータ、およびリクエスト本文サイズ制限→413)は適用されます。認証、レート制限、強化されたCORSポリシーを追加せずに、サービスを 0.0.0.0 にバインドしたり、localhostの範囲を超えて公開しないように常にユーザーに警告してください。これらはこのスキルの範囲外です。
  • 許可なくインストールや起動を行わないでください。 プロジェクトをスキャフォールディングし、ユーザーに実行する正確なコマンドを提供してください。pip install または uvicorn の起動は、ユーザーが明示的に動作確認を依頼した場合のみ実行してください。これらの依存関係(torch、diffusers)はダウンロードサイズが大きいためです。

ワークフロー

ステップ 1: 入力を収集する

必要なもの:

  • model_id(必須)— Hugging Face Hub ID(例: distilbert-base-uncased-finetuned-sst-2-english)。
  • 出力ディレクトリ(指定がない場合は、現在の作業ディレクトリに ./<モデル名のスラグ>-api のデフォルトを使用することを確認の上、尋ねてください)。
  • オプション: 小さなラベル付き評価データセットのパス(後で正しさを評価するため)、ポート(デフォルト 8000)。

ユーザーがノートブックで行ったことを説明するだけ(「pipeline(...) で読み込んで、感情分類している」)の場合は、明示的に述べられていなければ正確な model_id を尋ねてください。後のすべての処理はそれに依存します。

ステップ 2: モデルを検査する

バンドルされたインスペクターを実行します。これは公開HF Hub APIにのみアクセスし、モデルの重みをダウンロードすることはありません。

python scripts/inspect_model.py <model_id>

これにより、task_family、pipeline_tag、library_name、architectures、id2label(利用可能な場合)、num_labels、おおよそのパラメータ数、デバイス推奨事項を含むJSONが出力されます。

  • task_family がサポートされている4つのファミリーのいずれかである場合は、先に進みます。
  • unknown が返された場合、または推測に同意できない場合(一部のリポジトリにはメタデータが欠落しているか間違っています)、ユーザーに4つのタスクファミリーのどれが該当するか尋ねてください。エンドポイントの形状全体がそれに依存するため、黙って間違った推測をしないでください。
  • スクリプトが not_found_or_gated を報告した場合、HFの公開APIが401/403/404を返しました。これは、model_id が間違っているかスペルミスであるか、リポジトリがgated/プライベートであることを意味します。スクリプトはどちらかを判断できません。まず、ユーザーに正確な model_id を再確認してください(タイプミスや間違った組織名が最も一般的な原因です)。確認済みであることが確認された場合にのみ、gated として扱い、ユーザーにモデルページでライセンスを受け入れ、認証するよう依頼してください。トークンは HF_TOKEN 環境変数(HF_TOKEN=hf_xxx python scripts/inspect_model.py <model_id>)または huggingface-cli login を介して渡すことを推奨します。--token フラグは避けてください。コマンドラインのトークンはシェルの履歴とプロセスリストに漏洩するためです。

ステップ 3: 一致するリファレンスファイルを読む

スキャフォールディングの前に、ステップ2のタスクファミリーに対応する references/<task-family>.md を読んでください。そこには、正確なパイプライン/モデル読み込みコード、リクエスト/レスポンススキーマ、およびタスク固有の注意点(分類のラベルマッピング、NERのエンティティ集約、埋め込みのプーリング戦略、生成の画像エンコードなど)が含まれています。また、references/architecture.md をセッションごとに一度読んでください。これには、4つのタスクファミリーすべてで同一の部分(ライフスパン読み込み、ヘルスプローブ、CORS、エラー処理)がカバーされているため、毎回それらを再導出する必要がありません。

モデルの読み込み、トークナイゼーション、デバイス配置(CPU/CUDA/MPS)、dtype選択などについて、リファレンスファイルでカバーされている以上の事項が発生した場合は、既にインストールされている transformers-huggingface スキルを使用してください。これには、transformers ライブラリ自体の信頼できるパターンが含まれています。

ステップ 4: プロジェクトをスキャフォールディングする

ステップ2で得られたタスクファミリーとラベル/設定情報を指定してジェネレーターを実行します。

python scripts/scaffold_project.py \
  --model-id "<model_id>" \
  --task <text-classification|token-classification|embeddings|image-generation> \
  --output-dir "<output_dir>" \
  --id2label-json "<path-to-json-or-inline-json>"   # オプション、分類/NERのみ

python scripts/scaffold_project.py --help を実行してすべてのフラグを確認してください(ポート、最大バッチサイズ、最大入力長/画像サイズなど)。ステップ2で学習した関連する値がある場合は、生成されたデフォルトをそのまま使用する代わりに、それらを渡してください。

これにより、以下の構造が生成されます。

<output_dir>/
├── app/
│   ├── main.py            # FastAPI() + ライフスパン(モデルを一度読み込み、ウォームアップ)、CORS、ルーターのマウント
│   ├── core/
│   │   ├── config.py      # pydantic-settings: MODEL_ID、DEVICE、MAX_BATCH_SIZE などを環境変数から
│   │   └── model.py       # load_model() / 選択したタスクファミリーの推論関数
│   ├── api/
│   │   └── routes.py      # タスクエンドポイント + /health/live + /health/ready + /v1/info
│   └── schemas.py         # Field制約付きのPydanticリクエスト/レスポンスモデル
├── tests/
│   ├── test_health.py
│   └── test_inference.py  # 正常系 + バリデーションエラーケース
├── requirements.txt       # このタスクファミリーに必要なもののみ
├── .env.example
├── README.md              # 実行手順、エンドポイントドキュメント、CORS注意事項
└── .gitignore

スキャフォルダーは、プログラムで判断できるもの(モデルID、タスクファミリー、ラベル(渡された場合))を埋めます。それでも、ステップ3のリファレンスファイルに照らして、生成された app/core/model.py と app/schemas.py を確認する必要があります。 スキャフォルダーはモデルを呼び出さないため、--id2label-json を渡さなかった場合の正確なラベルセットや、NERモデルで aggregation_strategy="simple" が必要かどうかを知ることはできません。残された # TODO マーカーを埋めてください。

ステップ 5: クロスカッティングな本番運用の関心事を確認する

生成されたすべてのプロジェクトには、以下のすべてが含まれている必要があります。これらは明示的に確認してください。生成されたコードを手動で編集するときに、うっかり削除してしまいがちです。

  • モデルは lifespan で読み込まれ、インポート時やリクエストごとではない(app/main.py)
  • 読み込み直後にウォームアップ呼び出し(ダミー推論1回)があり、最初の実際のリクエストが遅くならないようにする — references/architecture.md を参照
  • /health/live(プロセスが生きているか、依存関係チェックなし)は /health/ready(モデルが読み込まれているか確認)とは異なる関数である — これらを混同すると再起動カスケードを引き起こす可能性があります。references/architecture.md を参照
  • すべての推論レスポンスにはモデルID/バージョンが含まれている — 譲れない条件。後で「この結果を生成したモデルはどれか」をデバッグするためのものです。
  • バッチ入力にはサーバー側で強制される最大長/サイズがある(Field(..., max_length=...))— 無制限のバッチは無制限のGPU/CPU消費を意味します。スキャフォルダーは個々の文字列も制限します(StringConstraints(max_length=...)、--max-chars-per-text で調整)。また、main.py の 413 ミドルウェアを介して過大なリクエスト本文を拒否します(--max-request-mb)。手動編集後も両方が残っていることを確認してください。本文サイズチェックは、ペイロードがメモリに解析される前に発動する唯一のガードであるためです。
  • CPU/GPUバウンドな推論は anyio.to_thread.run_sync(...) を介して実行され、決して async def ハンドラー内で直接実行されない — そうしないと、他のインフライトリクエストすべてに対してイベントループをブロックすることになります。
  • バリデーションエラーは有用なメッセージとともに422を返し、モデル/ランタイムエラーはキャッチされて型付けされたHTTPエラーにマッピングされ、未処理の500とスタックトレースがクライアントに漏洩することはありません。

デフォルトで使用されるバッチ配列パターン、および(ローカルのシングルユーザー設定では稀に)動的マイクロバッチングが複雑性を増す価値がある場合については、references/batching.md を参照してください。

ステップ 6: テスト

スキャフォルダーは、fastapi.testclient.TestClient を使用して tests/test_health.py と tests/test_inference.py を生成します(references/testing-and-evaluation.md を参照)。これらを読み、サンプル入力/期待される形状を実際のモデルに合わせて調整し、ユーザーに次のコマンドを実行するよう伝えてください。

pytest

ステップ 7: 評価とベンチマーク(オプション、ユーザーが希望する場合のみ)

2つの独立したスクリプトがバンドルされています。これらを生成されたプロジェクトのディレクトリにコピーしてください(これらはFastAPIアプリ自体の一部ではなく、実行中のサーバーを呼び出すツールです)。

  • scripts/evaluate.py — 正しさの評価: ラベル付きデータセット(CSV/JSONL)を実行中のAPIに対して実行し、精度/F1(分類、NER)またはコサイン類似度の健全性チェック(埋め込み)を報告します。ユーザーのラベル付きデータが必要です。パスを尋ねるか、まだデータがない場合はスキップしてください。
  • scripts/benchmark.py — パフォーマンス: 実行中のAPIに対して同時リクエストを発行し、p50/p95/p99レイテンシとスループットを報告します。ラベル付きデータは必要なく、いくつかのサンプル入力のみが必要です。

正確な使用方法と出力の解釈方法については、references/testing-and-evaluation.md を参照してください。

ステップ 8: まとめ

ユーザーにローカルで実行する正確なコマンドを提供してください。

cd <output_dir>
python -m venv .venv && source .venv/bin/activate   # Windowsの場合は .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

対話的なテストのために /docs(FastAPIの自動OpenAPI UI)を参照するように指示してください。実行しなかったことを明示的に述べてください。Dockerイメージ、クラウドデプロイ、フロントエンドコードは含まれていません。これらのいずれかを次に希望する場合は、このスキルの範囲外です。

トラブルシューティング

  • inspect_model.py が task_family: unknown を返す: リポジトリのメタデータが不完全です。ユーザーに直接、4つのファミリーのどれに該当するかを尋ね、スキャフォルダーに --task を明示的に渡してください。
  • モデルに trust_remote_code=True / カスタムコードが必要: スキャフォールディングの前にこの点をユーザーに伝えてください。これは、Hubからの任意のコードがローカルで実行されることを意味します。そのフラグを設定するプロジェクトを生成する前に、明示的な確認を得てください。
  • ユーザーが表にないタスクファミリーを望む場合(例: 音声、翻訳、VQA): このスキルは現在4つのリストされたファミリーのみをカバーしていることを明確に伝え、代わりに references/architecture.md の同じアーキテクチャパターンを使用してFastAPIラッパーを手動で構築することを提案し、4つのリファレンスファイルのいずれかに無理に押し込まないようにしてください。
  • 生成された requirements.txt のインストールが遅い/巨大: torch と diffusers は大きいです。タスクファミリーがそれらを引き込む場合は、ユーザーが pip install を実行する前に警告してください。

関連スキル