Webhook kılavuzu: Modeller ve veri kümeleri için otomatik bir meta veri kalite incelemesi yapılandırma

Bu kılavuz, Hub'daki bir kullanıcının veya kuruluşun modellerindeki veya veri setlerindeki değişikliklere tepki veren ve değiştirilen depo için bir 'metadata incelemesi' oluşturan bir sistem oluşturmanızı adım adım anlatacaktır.

Ne inşa ediyoruz ve neden?

Bu belirli iş akışının teknik detaylarına dalmadan önce, neyi oluşturduğumuzu ve nedenini kısaca özetleyelim.

Model kartları ve veri seti kartları, makine öğrenimi modellerini ve veri setlerini belgelemek için temel araçlardır. Hugging Face Hub, model ve veri seti kartlarını oluşturmak için YAML başlık bloğu içeren bir README.md dosyası kullanır. Bu YAML bölümü, modele veya veri setine ilişkin meta verileri tanımlar. Örneğin:

---
language: 
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
---

Bu meta veriler, potansiyel kullanıcılar için modeliniz veya veri setiniz hakkında temel bilgiler içerir. Örneğin, lisans, bir modelin veya veri setinin hangi koşullar altında kullanılabileceğini tanımlar. Hub kullanıcıları, belirli kriterlere uyan modelleri veya veri setlerini belirlemek için YAML meta verilerinde tanımlanan alanları filtre olarak da kullanabilir.

Bu blokta tanımlanan meta veriler, modellerimizin ve veri setlerimizin potansiyel kullanıcıları için hayati önem taşıdığından, bu bölümü tamamlamamız önemlidir. Bir ekip veya kuruluş ortamında, Hub'a model ve veri seti gönderen kullanıcıların bu YAML meta veri bloğunun önemine olan hâkimiyetleri farklılık gösterebilir. Ekipteki bir kişi bu meta verileri gözden geçirme sorumluluğunu üstlenebilir; ancak bu soruna yardımcı olmak için otomasyona da başvurabiliriz. Sonuç olarak, Hub'daki bir depo değiştiğinde otomatik olarak yayınlanan veya güncellenen bir meta veri inceleme raporu elde edeceğiz. Meta veri kalitemiz açısından bu sistem, CI/CD ile benzer şekilde çalışır.

Örnek bir incelemeyi burada da bulabilirsiniz.

Hub Client Library kullanarak bir model inceleme kartı oluşturma

huggingface_hub, Hub ile etkileşim kurmanızı sağlayan bir Python kütüphanesidir. Bu kütüphaneyi kullanarak DatasetCard.load veya ModelCard.load yöntemleriyle Hub’dan model ve veri seti kartlarını indirebiliriz. Özellikle bu yöntemleri, model veya veri seti kartımızın YAML bölümünde tanımlanan meta verileri içeren bir Python sözlüğünü yüklemek için kullanacağız. Bu yöntemleri sarmalayan ve bazı istisna işlemleri yapan küçük bir Python fonksiyonu oluşturacağız.

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 {}

Bu fonksiyon, depoya (veya metadata yoksa boş bir sözlüğe) ait metadata'yı içeren bir Python sözlüğü döndürür.

{'license': 'afl-3.0'}

Üretim verilerimizi gözden geçirme raporu oluşturma

Bir depoya ait meta verileri içeren bir Python sözlüğüne sahip olduğumuzda, meta veri incelememiz için bir ‘rapor kartı’ oluşturacağız. Bu özel durumda, değerlerini görmek istediğimiz bazı meta veri alanlarını tanımlayarak meta verilerimizi inceleyeceğiz. Örneğin, license alanının her zaman doldurulduğundan emin olmak isteyebiliriz. Meta verilerimizi puanlamak için, istediğimiz alanlar arasında hangi meta veri alanlarının mevcut olduğunu sayacak ve görmek istediğimiz zorunlu meta veri alanlarının kapsamına dayalı bir yüzde puanı döndüreceğiz.

Metadata'mızı içeren bir Python sözlüğü olduğundan, bu sözlük üzerinden dolaşarak aradığımız anahtarların var olup olmadığını kontrol edebiliriz. Aranan bir metadata alanı (sözlüğümüzdeki bir anahtar) eksikse, değeri None olarak atarız.

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

Bu fonksiyon, model veya veri setimiz için gereksinim duyduğumuz meta veri alanlarını temsil eden anahtarları içeren bir sözlük döndürür. Sözlük değerleri, o alan için girilen meta verileri veya YAML dosyasında o meta veri alanı eksikse None değerini içerir.

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

Bu sözlüğe sahip olduğumuzda, metadata raporumuzu oluşturabiliriz. Kısalık adına burada tam kodu içermeyeceğiz, ancak bu Webhook için Hugging Face Spaces deposu tam kodu içerir.

Metadata kapsam sözlüğümüzdeki verilerin daha şık bir versiyonunu üreten bir markdown tablosu oluşturan tek bir fonksiyon oluşturuyoruz.

def create_metadata_breakdown_table(desired_metadata_dictionary):
    # [...]
    return tabulate(
        table_data, tablefmt="github", headers=("Metadata Field", "Provided Value")
    )

Ayrıca, istenen metadata alanlarının mevcut yüzdesini temsil eden bir skor üreten bir Python fonksiyonumuz da var

def calculate_grade(desired_metadata_dictionary):
    # [...]
    return round(score, 2)

ve metadata incelememiz için bir markdown raporu oluşturan bir Python işlevi. Bu rapor, puan ve metadata tablosunun yanı sıra raporun içeriğine dair bazı açıklamaları da içerir.

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

Yorumu otomatik olarak göndermek için ne yapmalı?

Artık markdown biçimlendirilmiş bir metadata inceleme raporumuz var. Bu incelemeyi paylaşmak için huggingface_hub kütüphanesini kullanacağız. Hub'dan alınan Webhook verisini geri alır, verileri ayrıştırır ve metadata raporunu oluşturan bir fonksiyon tanımlıyoruz. Daha önce bir rapor oluşturulup oluşturulmadığına bağlı olarak, fonksiyon yeni bir rapor oluşturur veya mevcut bir metadata inceleme konusuna yeni bir sorun (issue) gönderir.

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 diline 3.8 sürümünde eklenen atama ifade operatörünün Python sözdizimidir (günlük dilde walrus operatörü olarak bilinir). Bu sözdizimi hakkında görüşler bölünmüş durumdadır ve bu operatörü kullanmadığınız sürece Python'un kodu nasıl değerlendirdiğini değiştirmez. Bu operatör hakkında daha fazla bilgiyi bu Real Python makalesinde bulabilirsiniz.

Hub'daki değişikliklere yanıt vermek için bir Webhook oluşturma

Artık bir model veya veri seti için metadata inceleme raporu oluşturma işlevselliğinin çekirdeğine sahibiz. Bir sonraki adım, değişikliklere otomatik olarak yanıt vermek için Webhooks kullanmaktır.

Kullanıcı profilinizde bir Webhook oluşturun

Öncelikle https://huggingface.co/settings/webhooks adresine giderek Webhook'unuzu oluşturun.

• Webhook'ünüzün dinleyeceği birkaç hedef depo girin (bu listenin yalnızca kendi depolarınıza veya ait olduğunuz organizasyonun depolarıyla sınırlı olmasını isteyeceksiniz).
• Webhook'unuzu daha güvenli hale getirmek için bir gizli anahtar girin (bunun için ne seçeceğinizi bilmiyorsanız, gizli anahtarınız için yeterince uzun rastgele bir dize oluşturmak üzere bir parola oluşturucu kullanabilirsiniz).
• Şimdilik Webhook URL parametresi için sahte bir URL geçebiliriz.

Webhook'ünüz şu şekilde görünecektir:

Yeni bir Bot kullanıcı profili oluşturun

Bu kılavuz, metadata incelemelerini paylaşacak ayrı bir kullanıcı hesabı oluşturur.

Hub'da diğer kullanıcılarla etkileşime girecek bir bot oluştururken, hesabın bir “Bot” olarak açıkça etiketlenmesini (profil ekran görüntüsüne bakın) rica ederiz.

Webhook dinleyicisi oluşturun

Artık Webhook olaylarını dinlemek için bir yola ihtiyacımız var. Webhook olaylarını dinlemek için kullanabileceğiniz birçok olası araç bulunmaktadır. Zapier ve IFTTT gibi birçok mevcut hizmet, Webhook'ları eylemleri tetiklemek için kullanabilir (örneğin, bir model her güncellendiğinde bir tweet paylaşabilirler). Bu durumda, Webhook dinleyicimizi FastAPI kullanarak uygulayacağız.

FastAPI, bir Python web çerçevesidir. Bir Webhook dinleyicisi oluşturmak için FastAPI’yi kullanacağız. Özellikle, /webhook üzerinde POST isteklerini kabul eden bir rota uygulamamız gerekiyor. Kimlik doğrulama için, X-Webhook-Secret başlığını, çalışma zamanında Docker konteynerimize iletilebilecek bir WEBHOOK_SECRET gizli anahtarıyla karşılaştıracağız.

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

Yukarıdaki fonksiyon, Webhook olaylarını alır ve değiştirilen depo için metadata inceleme raporunu oluşturur veya günceller.

Webhook uygulamamızı dağıtmak için Spaces kullanın

main.py dosyamız, Webhook uygulamamız için gereken tüm kodu içerir. Bunu dağıtmak için bir Space kullanacağız.

Uzayımızda uygulamamızı çalıştırmak için Docker kullanacağız. Dockerfile, uygulama dosyamızı kopyalar, gerekli bağımlılıkları yükler ve uygulamayı çalıştırır. KEY değişkenini doldurmak için, daha önce oluşturduğumuz gizli anahtarla Uzayımız için bir WEBHOOK_SECRET gizli anahtarı da ayarlayacağız. Docker Uzayları hakkında daha fazla bilgiyi burada okuyabilirsiniz.

Son olarak, Webhook ayarlarımızdaki URL'yi Space'imizin URL'si olarak güncellememiz gerekir. Space'imizin “direct URL” değerini bağlamsal menüden alabiliriz. “Embed this Space” seçeneğine tıklayın ve “Direct URL” değerini kopyalayın.

Bu URL'ye sahip olduğumuzda, bunu Webhook ayarlarımızdaki Webhook URL parametresine iletebiliriz. İzlenen depolar değiştiğinde botumuz artık incelemeler paylaşmaya başlamalıdır!

Sonuç ve sonraki adımlar

Artık otomatik bir meta veri inceleme botuna sahibiz! Bu kılavuzun üzerine inşa edebileceğiniz bazı fikirler:

• Botumuzun yaptığı metadata incelemesi nispeten basitti; metadata incelemesi için daha karmaşık kurallar ekleyebilirsiniz.
• İncelemeyi yapmak için tam README.md dosyasını kullanabilirsiniz.
• Örgütünüz için özellikle önemli olan ‘kuralları’ tanımlamak ve bu kuralların takip edildiğini bir webhook ile kontrol etmek isteyebilirsiniz.

Webhooks kullanarak bir metadata kalite uygulaması geliştirirseniz lütfen beni @davanstrien olarak etiketleyin; hakkında bilgi almak isterim!