Webhook'lar

Webhooks, MLOps ile ilgili özelliklerin temelini oluşturur. İlgi alanınızda olan belirli kullanıcıların/organizasyonların tüm depolarında veya belirli depolardaki yeni değişiklikleri dinlemenizi sağlar. Bu kılavuzda önce webhook'ları programatik olarak nasıl yöneteceğinizi açıklayacağız. Ardından huggingface_hub kullanarak webhook'ları dinleyen bir sunucu oluşturmayı ve bunu bir Space'e dağıtmayı göreceğiz.

Bu kılavuz, Huggingface Hub'daki webhooks kavramıyla aşina olduğunuzu varsayar. Webhooks hakkında daha fazla bilgi edinmek için önce bu kılavuzu okumanız gerekir.

Webhook Yönetimi

huggingface_hub, web kancalarınızı (webhooks) programatik olarak yönetmenizi sağlar. Mevcut web kancalarınızı listeleyebilir, yeni olanlar oluşturabilir ve bunları güncelleyebilir, etkinleştirebilir, devre dışı bırakabilir veya silebilirsiniz. Bu bölüm, Hugging Face Hub API işlevlerini kullanarak bu işlemleri nasıl yapacağınızı adım adım anlatır.

Webhook Oluşturma

Yeni bir webhook oluşturmak için create_webhook() kullanın ve yüklerin gönderileceği URL'yi, izlenecek olayları ve isteğe bağlı olarak güvenlik için bir alan adı ve gizli anahtar belirleyin.

from huggingface_hub import create_webhook

# Example: Creating a webhook
webhook = create_webhook(
    url="https://webhook.site/your-custom-url",
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Bir webhook, yükü bir URL'ye göndermek yerine Hugging Face altyapısında bir Job'un çalıştırılmasını da tetikleyebilir. Bu durumda, kaynak Job'un kimliğini (ID) iletmeniz gerekir.

from huggingface_hub import create_webhook

# Example: Creating a webhook that triggers a Job
webhook = create_webhook(
    job_id=job_id,
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Webhook, ortam değişkeni WEBHOOK_PAYLOAD içindeki webhook yüküyle Job’u tetikler. Kaynak Job’ın gizli bilgileri webhoook’a kopyalanmaz. Tetiklenen Job’ın gizli bilgilere (ör. HF_TOKEN) ihtiyacı varsa, bunları secrets={"HF_TOKEN": "hf_***"} ile iletin. update_webhook() ile job_id’yi secrets ile birlikte iletmeniz gerekir. Listelenen gizli bilgiler, depolanan değerlerin yerini alır; boş bir dize bir gizli bilgiyi kaldırır ve diğer tüm gizli bilgiler korunur. Hugging Face Jobs, kullanılabilir donanımlar (CPU, GPU) ve UV betikleri hakkında daha fazla bilgi için Jobs belgelerini inceleyin.

Webhook'ları Listeleme

Yapılandırdığınız tüm webhook'ları görmek için list_webhooks() ile listeleyebilirsiniz. Bu, kimliklerini, URL'lerini ve durumlarını gözden geçirmek için kullanışlıdır.

from huggingface_hub import list_webhooks

# Example: Listing all webhooks
webhooks = list_webhooks()
for webhook in webhooks:
    print(webhook)

Webhook Güncelleme

Mevcut bir webhook'ün yapılandırmasını, örneğin URL'sini veya izlediği olayları değiştirmeniz gerekiyorsa, bunu update_webhook() kullanarak güncelleyebilirsiniz.

from huggingface_hub import update_webhook

# Example: Updating a webhook
updated_webhook = update_webhook(
    webhook_id="your-webhook-id",
    url="https://new.webhook.site/url",
    watched=[{"type": "user", "name": "new-username"}],
    domains=["repo"]
)

Webhook'ların Etkinleştirilmesi ve Devre Dışı Bırakılması

Bir webhook'ü silmeden geçici olarak devre dışı bırakmak isteyebilirsiniz. Bu, disable_webhook() kullanılarak yapılabilir ve webhook daha sonra enable_webhook() ile yeniden etkinleştirilebilir.

from huggingface_hub import enable_webhook, disable_webhook

# Example: Enabling a webhook
enabled_webhook = enable_webhook("your-webhook-id")
print("Enabled:", enabled_webhook)

# Example: Disabling a webhook
disabled_webhook = disable_webhook("your-webhook-id")
print("Disabled:", disabled_webhook)

Webhook Silme

Bir webhook artık ihtiyaç duyulmuyorsa, delete_webhook() kullanılarak kalıcı olarak silinebilir.

from huggingface_hub import delete_webhook

# Example: Deleting a webhook
delete_webhook("your-webhook-id")

CLI'den Webhook Yönetimi

Yukarıdaki tüm işlemler hf komut satırı arayüzünden de kullanılabilir. Bu, özellikle betik yazma ve ajan tabanlı iş akışları için faydalıdır.

# List all webhooks
>>> hf webhooks ls

# Get details about a specific webhook
>>> hf webhooks info <webhook_id>

# Create a webhook that pings a URL
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased --domain repo

# Create a webhook that triggers a Job
>>> hf webhooks create --job-id <job_id> --watch user:julien-c

# Create a webhook that triggers a Job with your HF token as a secret
>>> hf webhooks create --job-id <job_id> --watch bucket:my-org/my-bucket --secrets HF_TOKEN

# Update an existing webhook
>>> hf webhooks update <webhook_id> --url https://new-url.com/hook

# Enable / disable a webhook
>>> hf webhooks enable <webhook_id>
>>> hf webhooks disable <webhook_id>

# Delete a webhook (with confirmation prompt)
>>> hf webhooks delete <webhook_id>

--watch seçeneği, type'in model, dataset, space, org veya user değerlerinden biri olduğu type:name biçimini kullanır. Birden fazla öğeyi izlemek için bu seçenek tekrarlanabilir. Tüm seçeneklerin listesi için hf webhooks <command> --help komutunu çalıştırın. Daha fazla ayrıntı için CLI kılavuzuna bakın.

Webhooks Sunucusu

Bu rehber bölümünde kullanacağımız temel sınıf WebhooksServer()'dır. Bu sınıf, Huggingface Hub'dan webhook alabilen bir sunucuyu kolayca yapılandırmak için tasarlanmıştır. Sunucu, bir Gradio uygulamasına dayanmaktadır. Sizin veya kullanıcılarınızın talimatları görüntülemesi için bir arayüzü ve webhook'ları dinlemek için bir API'si vardır.

Webhook sunucusunun çalışan bir örneğini görmek için Spaces CI Bot adlı Space'e göz atın. Bu Space, bir Space üzerinde PR açıldığında geçici ortamlar başlatır.

Bu bir deneysel özelliktir. Bu, API'yi iyileştirmek için hâlâ çalıştığımız anlamına gelir. Gelecekte önceden haber verilmeden kırıcı değişiklikler getirilebilir. Gereksinimlerinizde huggingface_hub sürümünü sabitlemeyi unutmayın.

Bir uç nokta oluşturun

Bir webhook uç noktası uygulamak, bir fonksiyonu süslemek (decorator eklemek) kadar basittir. Ana kavramları açıklamak için ilk bir örneğe bakalım:

# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload) -> None:
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

Bu parçayı 'app.py' adlı bir dosyada kaydedin ve 'python app.py' ile çalıştırın. Aşağıdaki gibi bir mesaj görmelisiniz:

Webhook secret is not defined. This means your webhook endpoints will be open to everyone.
To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization:
        `app = WebhooksServer(webhook_secret='my_secret', ...)`
For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret.
Running on local URL:  http://127.0.0.1:7860
Running on public URL: https://1fadb0f52d8bf825fc.gradio.live

This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces

Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
Go to https://huggingface.co/settings/webhooks to setup your webhooks.

İyi iş! Az önce bir webhook sunucusu başlattınız! Tam olarak neler olduğunu inceleyelim:

Bir fonksiyonu webhook_endpoint() ile süsleyerek arka planda bir WebhooksServer() nesnesi oluşturulur. Gördüğünüz gibi bu sunucu, http://127.0.0.1:7860 üzerinde çalışan bir Gradio uygulamasıdır. Bu URL'yi tarayıcınızda açarsanız, kayıtlı webhooks hakkında talimatlar içeren bir karşılama sayfası görürsünüz.
Gradio uygulaması, temelde bir FastAPI sunucusudur. Bu sunucuya /webhooks/trigger_training adlı yeni bir POST rotası eklenmiştir. Bu rota, webhook'ları dinleyecek ve tetiklendiğinde trigger_training fonksiyonunu çalıştıracaktır. FastAPI, yükümlülüğü (payload) otomatik olarak ayrıştırır ve fonksiyona bir WebhookPayload nesnesi olarak iletir. Bu, webhook'u tetikleyen olaya dair tüm bilgileri içeren bir pydantic nesnesidir.
Gradio uygulaması, internetten gelen istekleri almak için bir tünel de açtı. İlginç kısım şu: https://huggingface.co/settings/webhooks adresinde, yerel makinenize işaret eden bir Webhook yapılandırabilirsiniz. Bu, webhook sunucunuzu hata ayıklamak ve onu bir Space'e dağıtmadan önce hızlıca geliştirmek için faydalıdır.
Son olarak, günlükler sunucunuzun şu anda bir gizli anahtarla korunmadığını da belirtir. Bu, yerel hata ayıklama için sorun değildir ancak ileride göz önünde bulundurulmalıdır.

Varsayılan olarak sunucu, betiğinizin sonunda başlatılır. Bir notebook'ta çalıştırıyorsanız, decorated_function.launch() çağrısını yaparak sunucuyu manuel olarak başlatabilirsiniz. Benzersiz bir sunucu kullanıldığından, birden fazla uç noktanız olsa bile sunucuyu yalnızca bir kez başlatmanız gerekir.

Webhook Yapılandır

Artık çalışan bir webhook sunucunuz var, bu nedenle mesaj almaya başlamak için bir Webhook yapılandırmak istiyorsunuz. https://huggingface.co/settings/webhooks adresine gidin, “Add a new webhook” seçeneğine tıklayın ve Webhook’unuzu yapılandırın. Gözlemlemek istediğiniz hedef depoları ve Webhook URL’sini belirleyin, burada https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training.

Ve tamam! Artık hedef depoyu güncelleyerek (ör. bir commit göndererek) bu webhook’u tetikleyebilirsiniz. Tetiklenen olayları görmek için Webhook’unuzun Activity sekmesini kontrol edin. Çalışan bir kurulumunuz olduğu için, test edebilir ve hızlıca tekrarlayabilirsiniz. Kodunuzu değiştirip sunucuyu yeniden başlatırsanız, herkese açık URL’niz değişebilir. Gerekirse Hub’daki webhook yapılandırmasını güncellemeyi unutmayın.

Bir Space'e Dağıt

Çalışan bir webhook sunucunuz olduğu için, hedef bunu bir Space'e dağıtmaktır. Bir Space oluşturmak için https://huggingface.co/new-space adresine gidin. Bir ad verin, Gradio SDK'yı seçin ve “Create Space” düğmesine tıklayın. Kodunuzu Space'e app.py adlı bir dosya olarak yükleyin. Space'iniz otomatik olarak başlayacak! Spaces hakkında daha fazla ayrıntı için bu kılavuza bakın.

Webhook sunucunuz artık herkese açık bir Space üzerinde çalışıyor. Çoğu durumda, sunucunuzu bir gizli anahtarla (secret) güvence altına almak istersiniz. Space ayarlarınıza gidin > “Repository secrets” bölümü > “Add a secret”. WEBHOOK_SECRET ortam değişkenini, seçtiğiniz değere ayarlayın. Webhooks settings sayfasına geri dönüp webhook yapılandırmasında gizli anahtarı belirleyin. Artık sunucunuz yalnızca doğru gizli anahtara sahip istekleri kabul edecektir.

Ve bu kadar! Space'iniz artık Hub'dan webhook'ları almaya hazır. Lütfen aklınızda bulundurun: Space'i ücretsiz 'cpu-basic' donanımında çalıştırırsanız, 48 saatlik hareketsizlikten sonra kapatılır. Kalıcı bir Space'e ihtiyacınız varsa, geliştirilmiş donanıma geçmeyi düşünmelisiniz.

Gelişmiş kullanım

Yukarıdaki kılavuz, WebhooksServer() kurulumunun en hızlı yolunu açıkladı. Bu bölümde, onu daha da nasıl özelleştirebileceğimizi göreceğiz.

Çoklu uç noktalar

Aynı sunucuya birden çok uç nokta kaydedebilirsiniz. Örneğin, bir eğitim işini başlatmak için bir uç nokta ve bir model değerlendirmesini başlatmak için başka bir uç nokta istemiş olabilirsiniz. Bunu birden çok @webhook_endpoint dekoratörü ekleyerek yapabilirsiniz:

# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload) -> None:
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

@webhook_endpoint
async def trigger_evaluation(payload: WebhookPayload) -> None:
    if payload.repo.type == "model" and payload.event.action == "update":
        # Trigger an evaluation job if a model is updated
        ...

Bu, iki uç nokta oluşturacaktır:

(...)
Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation

Özel sunucu

Daha fazla esneklik için WebhooksServer() nesnesini doğrudan oluşturabilirsiniz. Sunucunuzun açılış sayfasını özelleştirmek istiyorsanız bu işe yarar. Bunu, varsayılan olanın üzerine yazılacak bir Gradio UI geçirerek yapabilirsiniz. Örneğin, kullanıcılarınıza talimatlar ekleyebilir veya webhook'ları manuel olarak tetiklemek için bir form ekleyebilirsiniz. Bir WebhooksServer() oluştururken, add_webhook() dekoratörünü kullanarak yeni webhook'lar kaydedebilirsiniz.

İşte tam bir örnek:

import gradio as gr
from fastapi import Request
from huggingface_hub import WebhooksServer, WebhookPayload

# 1. Define  UI
with gr.Blocks() as ui:
    ...

# 2. Create WebhooksServer with custom UI and secret
app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")

# 3. Register webhook with explicit name
@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

# 4. Register webhook with implicit name
@app.add_webhook
async def goodbye(payload: WebhookPayload):
    return {"message": "goodbye"}

# 5. Start server (optional)
app.launch()

Gradio blokları kullanarak özel bir arayüz tanımlarız. Bu arayüz, sunucunun açılış sayfasında görüntülenecektir.
Özel bir arayüz ve bir gizli anahtar ile WebhooksServer() nesnesi oluştururuz. Gizli anahtar isteğe bağlıdır ve WEBHOOK_SECRET ortam değişkeni ile ayarlanabilir.
Açık bir adla bir webhook kaydederiz. Bu, /webhooks/say_hello adresinde bir uç nokta oluşturur.
Gizli bir adla bir webhook kaydederiz. Bu, /webhooks/goodbye adresinde bir uç nokta oluşturur.
Sunucuyu başlatırız. Bu adım isteğe bağlıdır çünkü sunucunuz, betiğin sonunda otomatik olarak başlatılır.

Update on GitHub

Hub Python Library

Webhook'lar

Webhook Yönetimi

Webhook Oluşturma

Webhook'ları Listeleme

Webhook Güncelleme

Webhook'ların Etkinleştirilmesi ve Devre Dışı Bırakılması

Webhook Silme

CLI'den Webhook Yönetimi

Webhooks Sunucusu

Bir uç nokta oluşturun

Webhook Yapılandır

Bir Space'e Dağıt

Gelişmiş kullanım

Çoklu uç noktalar

Özel sunucu