Hub documentation
Webhookガイド: モデルとデータセットのメタデータ品質レビューの自動化セットアップ
Webhookガイド: モデルとデータセットのメタデータ品質レビューの自動化セットアップ
このガイドでは、Hub上のユーザーまたは組織のモデルやデータセットの変更を検知して、変更されたリポジトリに対して「メタデータレビュー」を作成するシステムの構築手順を説明します。
何を構築し、なぜ構築するのか
この特定のワークフローに関わる技術的な詳細に入る前に、私たちが何を作成し、なぜそれを行うのかを簡単に概要として示します。
モデルカードとデータセットカードは、機械学習モデルとデータセットを文書化するための不可欠なツールです。Hugging Face Hub は、YAMLヘッダーブロックを含むREADME.mdファイルを使用して、モデルカードとデータセットカードを生成します。このYAMLセクションは、モデルまたはデータセットに関連するメタデータを定義します。例:
---
language:
- "List of ISO 639-1 code for your language"
- lang1
- lang2
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
---このメタデータには、モデルまたはデータセットの潜在的な利用者に必要な情報が含まれています。例えば、ライセンスは、モデルやデータセットが使用できる条件を定義します。Hub のユーザーは、YAML メタデータで定義されたフィールドをフィルタとして使用して、特定の条件に合致するモデルやデータセットを特定することもできます。
このブロックで定義されるメタデータは、モデルやデータセットの利用者にとって不可欠な情報であるため、このセクションを完全に記入することが重要です。チームや組織の環境では、Hubにモデルやデータセットをプッシュするユーザーの、このYAMLメタデータブロックの重要性に対する理解の度合いが異なる場合があります。チーム内でこのメタデータのレビューを担うメンバーを置くことも可能ですが、代わりに自動化によってこの問題を解決するアプローチも考えられます。その結果、Hub上のリポジトリが変更された際に、メタデータのレビューレポートが自動的に投稿または更新されるようになります。メタデータの品質管理という観点では、このシステムはCI/CDと同様の仕組みで機能します。
例のレビューはこちらでも確認できます。
Hub Client Libraryを使用してモデルレビューカードを作成する
huggingface_hub は、Hub とのやり取りを可能にする Python ライブラリです。このライブラリを使用すると、DatasetCard.load または ModelCard.load メソッドを使って、Hub からモデルカードやデータセットカードをダウンロードできます。具体的には、これらのメソッドを使用して、モデルカードまたはデータセットカードのYAML で定義されたメタデータを含む Python の辞書を読み込みます。これらのメソッドをラップし、例外処理を行う小さな Python 関数を作成します。
from huggingface_hub import DatasetCard, ModelCard
from huggingface_hub.utils import EntryNotFoundError
def load_repo_card_metadata(repo_type, repo_name):
if repo_type == "dataset":
try:
return DatasetCard.load(repo_name).data.to_dict()
except EntryNotFoundError:
return {}
if repo_type == "model":
try:
return ModelCard.load(repo_name).data.to_dict()
except EntryNotFoundError:
return {}この関数は、リポジトリに関連付けられたメタデータを含むPythonの辞書を返します（メタデータが存在しない場合は空の辞書を返します）。
{'license': 'afl-3.0'}メタデータレビューレポートの作成
リポジトリに関連するメタデータを含む Python の辞書が手元に揃ったら、メタデータのレビュー用に「レポートカード」を作成します。ここでは、値の存在を確認したいメタデータフィールドをいくつか定義することで、メタデータをレビューします。例えば、license フィールドが常に記入されていることを確認したい場合があります。メタデータの評価として、希望するフィールドのうち実際に存在するメタデータフィールドの数を数え、値を確認したい必須メタデータフィールドの網羅率に基づいたパーセンテージスコアを返します。
メタデータを含む Python の辞書があるため、この辞書をループして、必要なキーが存在するか確認できます。必要なメタデータフィールド（辞書のキー）が欠けている場合、その値をNoneに割り当てます。
def create_metadata_key_dict(card_data, repo_type: str):
shared_keys = ["tags", "license"]
if repo_type == "model":
model_keys = ["library_name", "datasets", "metrics", "co2", "pipeline_tag"]
shared_keys.extend(model_keys)
keys = shared_keys
return {key: card_data.get(key) for key in keys}
if repo_type == "dataset":
# [...]この関数は、モデルまたはデータセットに必要なメタデータフィールドを表すキーを含む辞書を返します。辞書の値は、そのフィールドに入力されたメタデータ、またはYAMLにそのメタデータフィールドが存在しない場合はNoneになります。
{'tags': None,
'license': 'afl-3.0',
'library_name': None,
'datasets': None,
'metrics': None,
'co2': None,
'pipeline_tag': None}この辞書が用意できたら、メタデータレポートを作成できます。簡潔にするため、ここでは完全なコードは示しませんが、このWebhookのHugging Face Spaces リポジトリには完全なコードが含まれています。
メタデータカバレッジ辞書に格納されているデータを、より見栄えのよい形式で表示するためのMarkdownテーブルを生成する関数を1つ作成します。
def create_metadata_breakdown_table(desired_metadata_dictionary):
# [...]
return tabulate(
table_data, tablefmt="github", headers=("Metadata Field", "Provided Value")
)また、…というPython関数も用意されており、これは（必要なメタデータフィールドが存在する割合を表す）スコアを生成します。
def calculate_grade(desired_metadata_dictionary):
# [...]
return round(score, 2)メタデータレビュー用のMarkdownレポートを作成するPython関数です。このレポートには、スコアとメタデータテーブルの両方が含まれ、レポートの内容に関する説明も記載されています。
def create_markdown_report(
desired_metadata_dictionary, repo_name, repo_type, score, update: bool = False
):
# [...]
return reportレビューを自動的に投稿するにはどうすればよいですか？
Markdown形式のメタデータレビューレポートが作成できました。huggingface_hubライブラリを使用して、このレビューを投稿します。Hubから受信したWebhookデータを受け取り、データを解析してメタデータレポートを作成する関数を定義します。以前にレポートが作成されているかどうかに応じて、関数は新しいレポートを作成するか、既存のメタデータレビュースレッドに新しいissueを投稿します。
def create_or_update_report(data):
if parsed_post := parse_webhook_post(data):
repo_type, repo_name = parsed_post
else:
return Response("Unable to parse webhook data", status_code=400)
# [...]
return True
:=は、Python 3.8 で追加された代入式演算子の Python 構文です（一般的には walrus operator と呼ばれます）。この構文については意見が分かれています。使用しない場合、Python がコードを評価する方法は変わりません。この演算子については、この Real Python の記事 で詳しく読むことができます。
Hub での変更に応答するための Webhook の作成
これで、モデルまたはデータセットのメタデータレビューレポートを作成するコア機能が整いました。次のステップは、Webhooks を使用して変更に対して自動的に反応することです。
ユーザープロファイルでWebhookを作成します
まず、https://huggingface.co/settings/webhooks にアクセスして Webhook を作成してください。
- Webhookが監視する対象のリポジトリをいくつか入力してください（通常、自分のリポジトリや所属する組織のリポジトリに限定することをお勧めします）。
- Webhook をより安全にするためにシークレットを入力してください（この項目で何を設定すればよいか分からない場合は、パスワード生成ツールを使用して、シークレットとして十分な長さのランダムな文字列を生成することをお勧めします）。
- 現時点では、
Webhook URLパラメータにはダミーのURLを渡すことができます。
Webhookは次のようになります:
新しいBotユーザープロファイルを作成します
このガイドでは、メタデータのレビューを投稿するための別ユーザーアカウントを作成します。
Hub上で他のユーザーとやり取りするボットを作成する際は、アカウントを明確に「Bot」としてラベル付けしてください（プロフィールのスクリーンショットを参照）。
Webhookリスナーを作成する
次に、Webhookイベントを監視する方法が必要です。Webhookイベントを監視するために使用できるツールは多数あります。ZapierやIFTTTなどの既存の多くのサービスは、Webhookを使用してアクションをトリガーできます（例えば、モデルが更新されるたびにツイートを投稿する、など）。ここでは、FastAPIを使用してWebhookリスナーを実装します。
FastAPIはPythonのWebフレームワークです。Webhookリスナーの作成にFastAPIを使用します。具体的には、/webhookでPOSTリクエストを受け入れるルートを実装する必要があります。認証については、X-Webhook-Secretヘッダーを、Dockerコンテナに実行時に渡すことができるWEBHOOK_SECRETシークレットと比較します。
from fastapi import FastAPI, Request, Response
import os
KEY = os.environ.get("WEBHOOK_SECRET")
app = FastAPI()
@app.post("/webhook")
async def webhook(request: Request):
if request.method == "POST":
if request.headers.get("X-Webhook-Secret") != KEY:
return Response("Invalid secret", status_code=401)
data = await request.json()
result = create_or_update_report(data)
return "Webhook received!" if result else result上記の関数はWebhookイベントを受信し、変更されたリポジトリのメタデータレビューレポートを作成または更新します。
Spacesを使用してWebhookアプリをデプロイします
main.py ファイルには、Webhook アプリに必要なすべてのコードが含まれています。デプロイには、Space を使用します。
Spaceでは、Dockerを使用してアプリを実行します。Dockerfileは、アプリファイルをコピーし、必要な依存関係をインストールして、アプリケーションを実行します。KEY変数に値を設定するために、先ほど生成したシークレットをSpaceのWEBHOOK_SECRETシークレットとして設定します。Docker Spacesの詳細については、こちらを参照してください。
最後に、Webhook 設定の URL を、私たちの Space の URL に更新する必要があります。Space の「直接 URL」は、コンテキストメニューから取得できます。「この Space を埋め込む」をクリックし、「直接 URL」をコピーしてください。
この URL を取得したら、Webhook 設定の Webhook URL パラメータに渡すことができます。これで、監視対象のリポジトリに変更があると、ボットがレビューを投稿し始めるはずです！
結論と次のステップ
現在、自動メタデータレビューボットが利用可能になりました。このガイドを基に構築できるアイデアをいくつかご紹介します。
- ボットによるメタデータのレビューは比較的単純なものでしたが、メタデータのレビューに、より複雑なルールを追加できます。
- レビューを行うには、
README.mdファイル全体を使用できます。 - 組織にとって特に重要な「ルール」を定義し、Webhook を使用してそれらが遵守されていることを確認する必要がある場合があります。
Webhooksを使用してメタデータ品質アプリを構築する場合は、@davanstrienでタグ付けしてください。ぜひその情報をお聞かせください！
Update on GitHub