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":
        # [...]

이 함수는 모델 또는 데이터셋에 필요한 메타데이터 필드를 나타내는 키를 포함하는 사전(dictionary)을 반환합니다. 사전의 값은 해당 필드에 입력된 메타데이터를 포함하거나, YAML에 해당 메타데이터 필드가 없으면 None을 포함합니다.

{'tags': None,
 'license': 'afl-3.0',
 'library_name': None,
 'datasets': None,
 'metrics': None,
 'co2': None,
 'pipeline_tag': None}

이 사전이 준비되면 메타데이터 보고서를 생성할 수 있습니다. 간결성을 위해 여기에는 전체 코드를 포함하지 않지만, 이 Webhook의 Hugging Face Spaces 저장소에는 전체 코드가 포함되어 있습니다.

metadata coverage 사전에 있는 데이터를 더 보기 좋게 표시하는 마크다운 표를 생성하는 함수를 하나 만듭니다.

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)

그리고 메타데이터 검토를 위한 마크다운 보고서를 생성하는 Python 함수입니다. 이 보고서에는 점수와 메타데이터 테이블, 그리고 보고서에 포함된 내용에 대한 설명이 함께 포함되어 있습니다.

def create_markdown_report(
    desired_metadata_dictionary, repo_name, repo_type, score, update: bool = False
):
    # [...]
    return report

리뷰를 자동으로 게시하는 방법

이제 markdown 형식의 메타데이터 검토 리포트가 준비되었습니다. huggingface_hub 라이브러리를 사용해 이 검토 결과를 게시합니다. Hub에서 받은 Webhook 데이터를 다시 받아 데이터를 파싱하고 메타데이터 리포트를 생성하는 함수를 정의합니다. 이전에 리포트가 생성되었는지에 따라, 함수는 새로운 리포트를 생성하거나 기존 메타데이터 검토 스레드에 새로운 이슈를 게시합니다.

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을 더 안전하게 만들기 위해 시크릿을 입력하세요(이 항목에 무엇을 선택할지 모르겠다면, password generator를 사용하여 시크릿에 사용할 충분히 긴 랜덤 문자열을 생성하는 것이 좋습니다).
• Webhook URL 파라미터에는 당분간 더미 URL을 전달할 수 있습니다.

Webhook은 다음과 같은 형태를 가집니다:

새로운 Bot 사용자 프로필을 만듭니다

이 가이드는 메타데이터 리뷰를 게시할 별도의 사용자 계정을 생성합니다.

Hub에서 다른 사용자와 상호작용하는 봇을 만들 때, 프로필에 “Bot”으로 명확히 표시해 주시기를 요청드립니다(프로필 스크린샷 참조).

Webhook 리스너 생성

이제 Webhook 이벤트를 수신할 수 있는 방법이 필요합니다. Webhook 이벤트를 수신하는 데 사용할 수 있는 도구는 다양합니다. Zapier와 IFTTT와 같은 기존 서비스들은 Webhook을 사용하여 작업을 트리거할 수 있습니다(예: 모델이 업데이트될 때마다 트윗을 게시하는 것). 이 경우, FastAPI를 사용하여 Webhook 리스너를 구현하겠습니다.

FastAPI는 Python 웹 프레임워크입니다. 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의 “direct URL”은 컨텍스트 메뉴에서 가져올 수 있습니다. “Embed this Space”를 클릭하고 “Direct URL”을 복사하세요.

이 URL을 얻으면 Webhook 설정의 Webhook URL 매개변수에 전달할 수 있습니다. 이제 모니터링 중인 저장소가 변경되면 봇이 리뷰를 게시하기 시작해야 합니다!

결론 및 다음 단계

이제 자동 메타데이터 검토 봇이 있습니다! 이 가이드를 기반으로 구축할 수 있는 몇 가지 아이디어를 소개합니다:

• 봇이 수행한 메타데이터 검토는 비교적 단순했습니다. 메타데이터 검토를 위해 더 복잡한 규칙을 추가할 수 있습니다.
• 리뷰를 수행하려면 전체 README.md 파일을 사용할 수 있습니다.
• 조직에 특히 중요한 ‘규칙’을 정의하고, 웹훅을 사용하여 이러한 규칙이 준수되는지 확인하는 것이 좋습니다.

Webhooks를 사용하여 메타데이터 품질 앱을 구축하신 경우, @davanstrien으로 태그를 달아 주세요. 해당 앱에 대해 듣고 싶습니다!