Hub documentation

Webhook'lar

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Webhook'lar

Webhooks, MLOps ile ilgili özelliklerin temelini oluşturur. Belirli depolardaki yeni değişiklikleri dinlemenize veya belirli bir kullanıcı/organizasyon grubuna ait tüm depolardaki değişiklikleri izlemenize olanak tanır (yalnızca kendi depolarınız değil, herhangi bir depo).

Bunları modelleri otomatik olarak dönüştürmek, topluluk botları oluşturmak veya modelleriniz, veri setleriniz, Spaces ve bucket'larınız için CI/CD oluşturmak (ve çok daha fazlası) için kullanabilirsiniz. Webhooks, depo olaylarına yanıt olarak hesaplama görevlerini otomatikleştirmek için Jobs tetikleyebilir.

Webhooks belgeleri aşağıdadır – ayrıca Webhooks'un birkaç olası kullanım senaryosünü gösteren kılavuzlarımıza da göz atabilirsiniz:

Webhook'unuzu oluşturun

Webhooks ayarlarınızda yeni Webhook'lar oluşturabilir ve mevcut olanları düzenleyebilirsiniz:

Settings of an individual webhook

Webhooks, depo güncellemelerini, Pull Request'leri, tartışmaları ve yeni yorumları izleyebilir. Webhook'larınıza tepki vermek için bir Space bile oluşturabilirsiniz!

Webhook Yükleri

Bir Webhook kaydettikten sonra, belirtilen hedef URL üzerinde bir HTTP POST çağrısı ile yeni olaylardan haberdar edilirsiniz. Yük, JSON olarak kodlanır.

Webhook ayarları sayfasındaki aktivite sekmesinde gönderilen yüklerin geçmişini görüntüleyebilir, ayrıca hata ayıklamayı kolaylaştırmak için geçmiş webhook'ları yeniden oynatabilirsiniz:

Örnek olarak, bir Pull Request açıldığında tam yük aşağıdaki gibidir:

{
  "event": {
    "action": "create",
    "scope": "discussion"
  },
  "repo": {
    "type": "model",
    "name": "openai-community/gpt2",
    "id": "621ffdc036468d709f17434d",
    "private": false,
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2",
      "api": "https://huggingface.co/api/models/openai-community/gpt2"
    },
    "owner": {
      "id": "628b753283ef59b5be89e937"
    }
  },
  "discussion": {
    "id": "6399f58518721fdd27fc9ca9",
    "title": "Update co2 emissions",
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19",
      "api": "https://huggingface.co/api/models/openai-community/gpt2/discussions/19"
    },
    "status": "open",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "num": 19,
    "isPullRequest": true,
    "changes": {
      "base": "refs/heads/main"
    }
  },
  "comment": {
    "id": "6399f58518721fdd27fc9caa",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "content": "Add co2 emissions information to the model card",
    "hidden": false,
    // Note: when `hidden` is `true`, `content` will be undefined
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19#6399f58518721fdd27fc9caa"
    }
  },
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

Olay

Üst düzey özellik event her zaman belirtilir ve olayın niteliğini belirlemek için kullanılır.

İki alt özelliği vardır: event.action ve event.scope.

event.scope aşağıdaki değerlerden biri olacaktır:

"repo" - Depolardaki genel olaylar. İlişkili action için olası değerler: "create", "delete", "update", "move".
"repo.content" - Deponun içeriğindeki olaylar, örneğin yeni commit'ler veya etiketler. Yeni oluşturulan referans/commit nedeniyle yeni Pull Request'lerde de tetiklenir. Buckets için, Git referansları yerine dosyaların eklenmesi veya silinmesi durumunda tetiklenir. İlişkili action her zaman "update"'dir.
"repo.config" - Yapılandırma olayları: Space gizli bilgilerini güncelleme, ayarları güncelleme, DOI'leri güncelleme, devre dışı bırakılma durumu vb. İlişkili action her zaman "update"'dir.
"discussion" - Bir tartışma veya Pull Request oluşturma, başlığı veya durumu güncelleme ve birleştirme. İlgili action için olası değerler: "create", "delete", "update".
"discussion.comment" - Bir yorumun oluşturulması, güncellenmesi ve gizlenmesi. İlgili action için olası değerler: "create", "update".

Gelecekte daha fazla kapsam eklenebilir. Bilinmeyen olayları işlemek için webhook işleyiciniz, daraltılmış bir kapsamda herhangi bir eylemi, daha geniş kapsamda bir "update" eylemi olarak değerlendirebilir.

Örneğin, gelecekte "repo.config.dois" kapsamı eklenirse, bu kapsama sahip herhangi bir olay, webhook işleyiciniz tarafından "repo.config" kapsamındaki bir "update" işlemi olarak değerlendirilebilir.

Depo

Webhooks'ün mevcut sürümünde, olaylar her zaman bir repoya ilişkilendirilebildiği için üst düzey repo özelliği her zaman belirtilir. Örneğin, aşağıdaki değeri ele alalım:

"repo": {
	"type": "model",
	"name": "some-user/some-repo",
	"id": "6366c000a2abcdf2fd69a080",
	"private": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo",
		"api": "https://huggingface.co/api/models/some-user/some-repo"
	},
	"headSha": "c379e821c9c95d613899e8c4343e4bfee2b0c600",
	"owner": {
		"id": "61d2000c3c2083e1c08af22d"
	}
}

repo.headSha, repodaki main dalındaki en son commit'in sha değeridir. Bu değer yalnızca event.scope "repo" ile başlıyorsa gönderilir; tartışmalar ve yorumlar gibi topluluk etkinliklerinde ve Git geçmişi olmayan varillerde gönderilmez.

Kod değişiklikleri

Kod değişikliklerinde, üst düzey özellik updatedRefs depo olaylarında belirtilir. Güncellenmiş referansların bir dizisidir. İşte örnek bir değer:

"updatedRefs": [
  {
    "ref": "refs/heads/main",
    "oldSha": "ce9a4674fa833a68d5a73ec355f0ea95eedd60b7",
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  },
  {
    "ref": "refs/tags/test",
    "oldSha": null,
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  }
]

Yeni oluşturulan referanslarda oldSha değeri null olarak ayarlanır. Silinen referanslarda newSha değeri null olarak ayarlanır.

Belirli çekme isteklerindeki yeni commit'lere, yeni etiketlere veya yeni dallara tepki verebilirsiniz.

Kovalar

Buckets Git depoları değildir: commit, branch veya tag içermezler. Yaşam döngüsü olayları (create, delete, move ve görünürlük gibi yapılandırma güncellemeleri) diğer depo türlerinde olduğu gibi aynı "repo" / "repo.config" kapsamlarını kullanır.

Dosya değişiklikleri "repo.content" kullanır, ancak yükte updatedRefs yerine updatedFiles özelliği bulunur. Mevcut bir dosyanın üzerine yazılması bir "add" olarak raporlanır. Bir dosya eklendikten ve başka bir dosya silindikten sonra bir örnek yük aşağıdadır:

{
  "event": {
    "action": "update",
    "scope": "repo.content"
  },
  "repo": {
    "type": "bucket",
    "name": "some-user/some-bucket",
    "id": "6366c000a2abcdf2fd69a080",
    "private": false,
    "url": {
      "web": "https://huggingface.co/buckets/some-user/some-bucket",
      "api": "https://huggingface.co/api/buckets/some-user/some-bucket"
    },
    "owner": {
      "id": "61d2000c3c2083e1c08af22d"
    }
  },
  "updatedFiles": [
    {
      "path": "data/train.txt",
      "action": "add",
      "xetHash": "55faef2f2f80cd1a087c35b729f228960739441d38073cd5aa4320751e137166",
      "size": 20
    },
    {
      "path": "data/old.txt",
      "action": "delete"
    },
    ...
  ],
  "updatedFilesTruncated": true,
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

10.000 girdinin üzerinde liste kısaltılır ve updatedFilesTruncated true olarak ayarlanır. Bu durumda, tam resmi görmek için bucket'ı listeleyin.

Buckets'ta tartışma veya Pull Request bulunmadığından, bunlar için asla "discussion" ve "discussion.comment" olayları almazsınız.

Bir istemcinin, kendi sunucunuza bir geri çağrı (callback) üzerinden değil de doğrudan bir varlığın (bucket) dosya değişikliklerini izlemesini istiyorsanız, varlıklar ayrıca bir canlı takip akışı da sunar.

Yapılandırma değişiklikleri

Üst düzey özellik event.scope "repo.config" olduğunda, updatedConfig özelliği belirtilir. Bu, güncellenmiş yapılandırmayı içeren bir nesnedir. İşte bir örnek değer:

"updatedConfig": {
  "private": false
}

Güncellenen yapılandırma anahtarı webhook tarafından desteklenmiyorsa, nesne boş olacaktır:

"updatedConfig": {}

Şimdilik yalnızca private desteklenmektedir. Burada daha fazla yapılandırma anahtarının bulunmasından faydalanacaksanız, lütfen website@huggingface.co adresinden bize bildirin.

Tartışmalar ve Çekme İstekleri

Üst düzey özellik discussion, topluluk etkinliklerinde (tartışmalarda ve Pull Request'lerde) tanımlanır. discussion.isPullRequest özelliği, tartışmanın aynı zamanda bir Pull Request olup olmadığını gösteren bir booleandır (Hub'da bir PR, tartışmanın özel bir türüdür). İşte bir örnek değer:

"discussion": {
	"id": "639885d811ae2bad2b7ba461",
	"title": "Hello!",
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/3",
		"api": "https://huggingface.co/api/models/some-user/some-repo/discussions/3"
	},
	"status": "open",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"isPullRequest": true,
	"changes": {
		"base": "refs/heads/main"
	}
	"num": 3
}

Yorum

Üst düzey özellik comment, bir yorum oluşturulduğunda (tartışma oluşturulması dahil) veya güncellendiğinde belirtilir. İşte bir örnek değer:

"comment": {
	"id": "6398872887bfcfb93a306f18",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"content": "This adds an env key",
	"hidden": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/4#6398872887bfcfb93a306f18"
	}
}

Webhook gizli anahtarı

Bir Webhook gizli anahtarı (secret) ayarlamak, Webhook işleyici URL'nize gönderilen yüklerin (payload) gerçekten Hugging Face'ten geldiğinden emin olmak için faydalıdır.

Webhook için bir gizli anahtar (secret) tanımlarsanız, bu anahtar her istekle birlikte X-Webhook-Secret HTTP başlığı olarak gönderilir. Yalnızca ASCII karakterleri desteklenir.

Gizli anahtarın doğrudan işleyici URL'sine eklenmesi de mümkündür. Örneğin, bir sorgu parametresi olarak ayarlayabilirsiniz: https://example.com/webhook?secret=XXX.

Webhook işleyiciniz için istek HTTP başlıklarına erişim karmaşık ise bu durum işinize yarayabilir.

Teslimat ve yeniden denemeler

Webhook yükleri, Hub'da olay gerçekleşmesinden kısa bir süre sonra asenkron olarak iletilir. Sıra garantisi verilmez: birden fazla olay yakın zamanlarda gerçekleşirse, sıralama dışında varabilirler.

İşleyiciniz, bir teslimatı 2xx durum koduyla onaylamalıdır. Başka herhangi bir durum kodu, bağlantı hatası gibi başarısız bir teslimat sayılır ve geri çekilme (backoff) ile yeniden denenir. İşlemeniz yavaşsa, teslimatın başarısız sayılmaması için hemen 2xx yanıtı verin ve işi asenkron olarak yapın.

Her teslimatın benzersiz bir Webhook-Id HTTP başlığı vardır. Başarısız bir teslimatın yeniden denemeleri aynı kimliği yeniden kullanır; bu nedenle bu kimliği bir idempotency anahtarı olarak ele alabilir ve her olayı yalnızca bir kez işleyebilirsiniz.

Bir Webhook'a yapılan iletimler sürekli başarısız olduğunda, Webhook otomatik olarak askıya alınır ve sahibi e-posta ile bilgilendirilir. Sorunu giderip Webhook'larınızı ayarlar bölümünden yeniden etkinleştirebilirsiniz.

Hız sınırlama

Her Webhook, 24 saatte 1.000 tetiklemeye kadar sınırlıdır. Kullanımınızı Webhook ayarları sayfasındaki “Activity” sekmesinde görüntüleyebilirsiniz.

Webhook'unuz için tetikleyici sayısını artırmak gerekiyorsa PRO, Team veya Enterprise planına yükseltin ve website@huggingface.co adresinden bizimle iletişime geçin.

Webhook'lerinizi Geliştirme

HTTPS uç noktası/URL'si yoksa, webhook testleri için halka açık araçları deneyebilirsiniz. Bu araçlar, kendilerine gönderilen tüm istekleri yakalar (catch-all) ve 200 OK durum kodunu döndürür. Beeceptor, geçici bir HTTP uç noktası oluşturmak ve gelen yükü (payload) incelemek için kullanabileceğiniz araçlardan biridir. Benzer bir diğer araç da Webhook.site'tir.

Ayrıca, geliştirme sırasında makinenizde yerel olarak çalışan koda gerçek bir Webhook yüklemesi yönlendirebilirsiniz. Bu, daha hızlı entegrasyonlar için test ve hata ayıklama yapmak için harika bir yoldur. Bunu, yerel ana bilgisayarınızın (localhost) portunu İnternet'e açarak yapabilirsiniz. Bu yolu izleyebilmek için ngrok veya localtunnel kullanabilirsiniz.

Webhook'ları Hata Ayıklama

Webhook'larınız için son oluşturulan olayları kolayca bulabilirsiniz. Webhook'unuz için aktivite sekmesini açın. Burada son olayların listesini göreceksiniz.

Burada, oluşturulan olayların HTTP durum kodunu ve yükünü inceleyebilirsiniz. Ayrıca, Replay düğmesine tıklayarak bu olayları yeniden oynatabilirsiniz!

Not: Bir Webhook'un hedef URL'si veya gizli anahtarı değiştirildiğinde, bir olayın yeniden oynatılması, yükü güncellenmiş URL'ye gönderir.

Not: Tekrar oynatılan olay, orijinal teslimatla aynı Webhook-Id ile gönderilir.

SSS

Webhook'ları kullanıcı hesabımda mı yoksa organizasyonumda mı tanımlayabilirim?

Hayır, bu şu anda desteklenmemektedir.

HF'deki (veya tüm modeller gibi bir depo türündeki) tüm olaylara nasıl abone olabilirim?

Bu özellik şu anda son kullanıcılara sunulmamaktadır ancak website@huggingface.co adresine e-posta gönderirseniz sizin için etkinleştirebiliriz.

Update on GitHub

←Koleksiyonlar Nasıl yapılır: Auto-Train ile otomatik ince ayar→