Hub documentation

Вебхуки

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

Вебхуки

Webhooks являются основой для функций, связанных с MLOps. Они позволяют отслеживать новые изменения в конкретных репозиториях или во всех репозиториях, принадлежащих определённому набору пользователей/организаций (не только ваши репозитории, а любые).

Вы можете использовать их для автоматического преобразования моделей, создания ботов сообщества или настройки CI/CD для ваших моделей, наборов данных, Spaces и buckets (и многое другое!). Webhooks также могут запускать Jobs для автоматизации вычислительных задач в ответ на события в репозиториях.

Документация по Webhooks приведена ниже – вы также можете ознакомиться с нашими руководствами, в которых показаны несколько возможных сценариев использования Webhooks:

Создайте свой Webhook

Вы можете создавать новые Webhooks и редактировать существующие в настройках Webhooks settings:

Settings of an individual webhook

Webhooks могут отслеживать обновления репозиториев, Pull Requests, обсуждения и новые комментарии. Более того, можно создать Space для реакции на ваши Webhooks!

Webhook-нагрузки

После регистрации Webhook вы будете получать уведомления о новых событиях через вызов HTTP POST по указанному целевому URL. Полезная нагрузка закодирована в формате JSON.

Вы можете просмотреть историю отправленных полезных нагрузок на вкладке «Активность» страницы настроек вебхука. Также можно повторить отправку прошлых вебхуков для упрощения отладки:

В качестве примера ниже приведена полная нагрузка при открытии Pull Request:

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

Событие

Свойство верхнего уровня event всегда указывается и используется для определения типа события.

У него есть два подсвойства: event.action и event.scope.

event.scope принимает одно из следующих значений:

"repo" — глобальные события для репозиториев. Возможные значения для связанного параметра action: "create", "delete", "update", "move".
"repo.content" — события, связанные с содержимым репозитория, например новые коммиты или теги. Также срабатывает при создании новых Pull Request, так как при этом создаются новые ссылки/коммиты. Для Buckets срабатывает при добавлении или удалении файлов, а не при изменении Git-ссылок. Соответствующее action всегда равно "update".
"repo.config" — события, связанные с конфигурацией: обновление секретов Space, обновление настроек, обновление DOI, статус отключения и т. д. Соответствующее action всегда равно "update".
"discussion" — создание обсуждения или Pull Request, обновление заголовка или статуса, а также слияние. Возможные значения для связанного параметра action: "create", "delete", "update".
"discussion.comment" — создание, обновление и скрытие комментария. Возможные значения для связанного action: "create", "update".

В будущем могут быть добавлены новые области. Для обработки неизвестных событий обработчик вебхука может рассматривать любое действие в более узкой области как действие "update" в более широкой области.

Например, если в будущем будет добавлена область "repo.config.dois", любое событие с этой областью может рассматриваться вашим обработчиком вебхука как действие "update" в области "repo.config".

Репозиторий

В текущей версии вебхуков верхнеуровневое свойство repo всегда указано, поскольку события всегда могут быть связаны с репозиторием. Например, рассмотрим следующее значение:

"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 — это sha последнего коммита в ветке main репозитория. Он отправляется только тогда, когда event.scope начинается с "repo", а не для событий сообщества, таких как обсуждения и комментарии, и не для бакетов, у которых нет истории Git.

Изменения в коде

При изменениях в коде в событиях репозитория указывается верхнеуровневое свойство updatedRefs. Это массив обновлённых ссылок. Пример значения:

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

Новосозданные ссылки будут иметь значение oldSha, равное null. Удалённые ссылки будут иметь значение newSha, равное null.

Вы можете реагировать на новые коммиты в конкретных pull request, новые теги или новые ветки.

Корзины

Buckets не являются репозиториями Git: в них нет коммитов, веток или тегов. События жизненного цикла (create, delete, move и обновления конфигурации, такие как видимость) используют те же области "repo" / "repo.config", что и другие типы репозиториев.

Изменения файлов используют "repo.content", но в полезной нагрузке есть свойство updatedFiles вместо updatedRefs. Перезапись существующего файла сообщается как "add". Вот пример полезной нагрузки после добавления одного файла и удаления другого:

{
  "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 список укорачивается, а updatedFilesTruncated устанавливается в true. В этом случае перечислите содержимое бакета, чтобы получить полную картину.

В Buckets отсутствуют обсуждения и Pull Requests, поэтому вы никогда не получите события "discussion" и "discussion.comment" для них.

Если вы хотите, чтобы клиент отслеживал изменения файлов в бакете напрямую, а не через обратный вызов на ваш сервер, то бакеты также предоставляют поток живого отслеживания.

Изменения конфигурации

Если верхнеуровневое свойство event.scope равно "repo.config", указывается свойство updatedConfig. Это объект, содержащий обновлённую конфигурацию. Пример значения:

"updatedConfig": {
  "private": false
}

Если обновлённый ключ конфигурации не поддерживается вебхуком, объект будет пустым:

"updatedConfig": {}

Пока поддерживается только private. Если вам было бы полезно наличие здесь дополнительных ключей конфигурации, пожалуйста, сообщите нам об этом по адресу website@huggingface.co.

Обсуждения и Pull Requests

Свойство верхнего уровня discussion указывается для событий сообщества (обсуждений и Pull Requests). Свойство discussion.isPullRequest — это булево значение, указывающее, является ли обсуждение также Pull Request (на Hub PR представляет собой особый тип обсуждения). Пример значения:

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

Комментарий

Свойство верхнего уровня comment указывается при создании комментария (в том числе при создании обсуждения) или его обновлении. Пример значения:

"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 полезна для того, чтобы убедиться, что данные, отправляемые на URL вашего обработчика Webhook, действительно исходят от Hugging Face.

Если вы зададите секрет для вашего Webhook, он будет отправляться вместе с каждым запросом в HTTP-заголовке X-Webhook-Secret. Поддерживаются только символы ASCII.

Также можно добавить секрет непосредственно в URL обработчика. Например, задав его в качестве параметра запроса: https://example.com/webhook?secret=XXX.

Это может быть полезно, если доступ к HTTP-заголовкам запроса усложняет работу вашего обработчика Webhook.

Доставка и повторные попытки

Платформы вебхуков доставляются асинхронно, вскоре после того, как событие происходит на Hub. Порядок не гарантируется: если несколько событий происходят вблизи друг от друга, они могут прийти в неверной последовательности.

Ваш обработчик должен подтверждать доставку кодом состояния 2xx. Любой другой код состояния считается ошибкой доставки, как и ошибка соединения: доставка повторяется с задержкой (backoff). Если обработка занимает много времени, сразу отвечайте кодом 2xx и выполняйте работу асинхронно, чтобы доставка не считалась неудачной.

Каждая доставка имеет уникальный HTTP-заголовок Webhook-Id. Повторные попытки доставки после сбоя используют тот же ID, поэтому его можно использовать как ключ идемпотентности и обрабатывать каждое событие один раз.

Если доставка в Webhook постоянно завершается ошибкой, Webhook автоматически приостанавливается, а его владелец получает уведомление по электронной почте. Вы можете устранить проблему и повторно активировать его в настройках своих Webhooks.

Ограничение частоты запросов

Каждый Webhook ограничен 1000 срабатываниями в течение 24 часов. Вы можете просмотреть свои данные об использовании на странице настроек Webhook во вкладке «Activity».

Если вам нужно увеличить количество срабатываний для вашего Webhook, перейдите на тариф PRO, Team или Enterprise и свяжитесь с нами по адресу website@huggingface.co.

Разработка ваших Webhooks

Если у вас нет HTTPS-эндпоинта/URL, вы можете воспользоваться общедоступными инструментами для тестирования вебхуков. Эти инструменты перехватывают все отправляемые на них запросы и возвращают код состояния 200 OK. Beeceptor — один из инструментов, с помощью которого можно создать временный HTTP-эндпоинт и просмотреть входящий payload. Другой подобный инструмент — Webhook.site.

Кроме того, во время разработки вы можете направлять реальный Webhook-пакет в код, работающий локально на вашем компьютере. Это отличный способ тестировать и отлаживать для более быстрой интеграции. Для этого нужно сделать порт вашего localhost доступным из Интернета. Чтобы пойти по этому пути, вы можете использовать ngrok или localtunnel.

Отладка вебхуков

Вы можете легко найти недавно сгенерированные события для ваших вебхуков. Откройте вкладку активности для вашего вебхука. Там вы увидите список последних событий.

Здесь можно просмотреть код состояния HTTP и полезную нагрузку сгенерированных событий. Кроме того, вы можете воспроизвести эти события, нажав кнопку Replay!

Примечание: при изменении целевого URL или секрета Webhook повторная отправка события отправит полезную нагрузку на обновленный URL.

Примечание: Повторяемое событие отправляется с тем же Webhook-Id, что и исходная доставка.

Часто задаваемые вопросы

Можно ли настроить вебхуки для моей организации, а не для моего пользовательского аккаунта?

Нет, в настоящее время это не поддерживается.

Как я могу подписаться на все события на HF (или на весь тип репозиториев, например, на все модели)?

В настоящее время эта функция не доступна конечным пользователям, но мы можем включить её для вас, если вы отправите письмо на website@huggingface.co.

Update on GitHub

←Коллекции Практическое руководство: автоматическая дообучение с Auto-Train→