Guia de Webhooks: Configure uma revisão automática da qualidade dos metadados para modelos e conjuntos de dados

Este guia mostrará como criar um sistema que reage a alterações nos modelos ou conjuntos de dados de um usuário ou organização no Hub e cria uma “revisão de metadados” para o repositório alterado.

O que estamos construindo e por quê?

Antes de entrarmos nos detalhes técnicos envolvidos neste fluxo de trabalho específico, vamos resumir rapidamente o que estamos criando e por quê.

Cards de modelos e cards de conjuntos de dados são ferramentas essenciais para documentar modelos e conjuntos de dados de aprendizado de máquina. O Hugging Face Hub usa um arquivo README.md contendo um bloco de cabeçalho YAML para gerar cards de modelos e conjuntos de dados. Essa seção YAML define metadados relacionados ao modelo ou conjunto de dados. Por exemplo:

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

Esses metadados contêm informações essenciais sobre seu modelo ou conjunto de dados para os usuários potenciais. A licença, por exemplo, define os termos sob os quais um modelo ou conjunto de dados pode ser usado. Os usuários do Hub também podem usar os campos definidos nos metadados YAML como filtros para identificar modelos ou conjuntos de dados que atendam a critérios específicos.

Como os metadados definidos neste bloco são essenciais para os potenciais usuários de nossos modelos e conjuntos de dados, é importante que preenchamos esta seção. Em um ambiente de equipe ou organização, os usuários que enviam modelos e conjuntos de dados para o Hub podem ter diferentes níveis de familiaridade com a importância deste bloco de metadados YAML. Embora alguém na equipe possa assumir a responsabilidade de revisar esses metadados, podemos, em vez disso, implementar alguma automação para nos ajudar com esse problema. O resultado será um relatório de revisão de metadados postado ou atualizado automaticamente quando um repositório no Hub for alterado. Para a qualidade dos nossos metadados, esse sistema funciona de maneira semelhante ao CI/CD.

Você também pode encontrar um exemplo de revisão aqui.

Usando a Biblioteca de Cliente do Hub para criar um cartão de revisão de modelo

A huggingface_hub é uma biblioteca Python que permite interagir com o Hub. Podemos usar essa biblioteca para baixar os cards de modelos e datasets do Hub usando os métodos DatasetCard.load ou ModelCard.load. Em particular, usaremos esses métodos para carregar um dicionário Python, que contém os metadados definidos no YAML do nosso card de modelo ou dataset. Criaremos uma pequena função Python para encapsular esses métodos e realizar o tratamento de exceções.

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

Esta função retornará um dicionário Python contendo os metadados associados ao repositório (ou um dicionário vazio, caso não haja metadados).

{'license': 'afl-3.0'}

Criando nosso relatório de revisão de metadados

Uma vez que tenhamos um dicionário Python contendo os metadados associados a um repositório, criaremos um “relatório de avaliação” para a revisão dos nossos metadados. Neste caso específico, revisaremos os metadados definindo alguns campos de metadados para os quais queremos valores. Por exemplo, podemos querer garantir que o campo license tenha sido sempre preenchido. Para avaliar nossos metadados, contaremos quais campos de metadados estão presentes entre os campos desejados e retornaremos uma pontuação percentual com base na cobertura dos campos de metadados obrigatórios para os quais queremos ver valores.

Como temos um dicionário Python contendo nossos metadados, podemos iterar por esse dicionário para verificar se as chaves desejadas estão presentes. Se um campo de metadados desejado (uma chave em nosso dicionário) estiver ausente, atribuiremos o valor como 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":
        # [...]

Esta função retornará um dicionário contendo chaves que representam os campos de metadados que exigimos para nosso modelo ou conjunto de dados. Os valores do dicionário incluirão os metadados inseridos para aquele campo ou None se o campo de metadados estiver ausente no YAML.

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

Uma vez que temos esse dicionário, podemos criar nosso relatório de metadados. Por brevidade, não incluiremos o código completo aqui, mas o repositório do Hugging Face Spaces para este Webhook contém o código completo.

Criamos uma função que gera uma tabela em markdown, produzindo uma versão mais bonita dos dados que temos em nosso dicionário de cobertura de metadados.

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

Também temos uma função em Python que gera uma pontuação (representando o percentual dos campos de metadados desejados presentes)

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

e uma função em Python que cria um relatório em markdown para a revisão dos nossos metadados. Este relatório contém tanto a tabela de pontuação quanto a tabela de metadados, além de uma explicação do que o relatório contém.

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

Como postar a revisão automaticamente?

Agora temos um relatório de revisão de metadados formatado em markdown. Usaremos a biblioteca huggingface_hub para publicar essa revisão. Definimos uma função que recebe os dados do Webhook obtidos do Hub, interpreta os dados e cria o relatório de metadados. Dependendo de um relatório já ter sido criado anteriormente, a função cria um novo relatório ou publica uma nova issue em um thread de revisão de metadados existente.

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

:= é a sintaxe Python para um operador de expressão de atribuição adicionado à linguagem Python na versão 3.8 (conhecido coloquialmente como operador walrus). As opiniões sobre essa sintaxe são mistas, e ela não altera a forma como o Python avalia o código caso você não a utilize. Você pode ler mais sobre esse operador neste artigo do Real Python.

Criando um Webhook para responder a alterações no Hub

Agora temos a funcionalidade central para criar um relatório de revisão de metadados para um modelo ou conjunto de dados. O próximo passo é usar Webhooks para responder automaticamente a alterações.

Crie um Webhook no seu perfil de usuário

Primeiro, crie seu Webhook acessando https://huggingface.co/settings/webhooks.

• Insira alguns repositórios de destino para os quais seu Webhook irá ouvir (provavelmente você desejará limitar isso aos seus próprios repositórios ou aos repositórios da organização à qual você pertence).
• Insira um segredo para tornar seu Webhook mais seguro (se você não souber o que escolher para isso, talvez queira usar um gerador de senhas para gerar uma string aleatória suficientemente longa para o seu segredo).
• Por enquanto, podemos passar uma URL fictícia para o parâmetro Webhook URL.

Seu Webhook ficará assim:

Crie um novo perfil de usuário Bot

Este guia cria uma conta de usuário separada que publicará as revisões de metadados.

Ao criar um bot que interagir com outros usuários no Hub, pedimos que você rotule claramente a conta como “Bot” (veja o screenshot do perfil).

Crie um listener de Webhook

Agora precisamos de alguma forma de ouvir eventos de Webhook. Existem muitas ferramentas possíveis que você pode usar para ouvir eventos de Webhook. Muitos serviços existentes, como Zapier e IFTTT, podem usar Webhooks para acionar ações (por exemplo, eles poderiam postar um tweet sempre que um modelo é atualizado). Neste caso, implementaremos nosso listener de Webhook usando FastAPI.

FastAPI é um framework web em Python. Usaremos o FastAPI para criar um listener de Webhook. Em particular, precisamos implementar uma rota que aceita requisições POST em /webhook. Para autenticação, compararemos o cabeçalho X-Webhook-Secret com um segredo WEBHOOK_SECRET que pode ser passado para o nosso container Docker em tempo de execução.

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

A função acima receberá eventos de Webhook e criará ou atualizará o relatório de revisão de metadados para o repositório alterado.

Use Spaces para implantar nosso aplicativo Webhook

Nosso arquivo main.py contém todo o código necessário para o nosso aplicativo Webhook. Para implantá-lo, usaremos um Space.

Para o nosso Space, usaremos o Docker para executar nosso aplicativo. O Dockerfile copia o arquivo do nosso aplicativo, instala as dependências necessárias e executa a aplicação. Para preencher a variável KEY, também definiremos um segredo WEBHOOK_SECRET para o nosso Space com o segredo que geramos anteriormente. Você pode ler mais sobre Spaces com Docker aqui.

Por fim, precisamos atualizar a URL em nossas configurações de Webhook para a URL do nosso Space. Podemos obter a “direct URL” do nosso Space pelo menu contextual. Clique em “Embed this Space” e copie a “Direct URL”.

Uma vez que tenhamos essa URL, podemos passá-la para o parâmetro Webhook URL nas configurações do nosso Webhook. Nosso bot deve começar a postar avaliações quando os repositórios monitorados forem alterados!

Conclusão e próximos passos

Agora temos um bot de revisão automática de metadados! Aqui estão algumas ideias de como você pode construir sobre este guia:

• A revisão de metadados realizada pelo nosso bot era relativamente simples; você pode adicionar regras mais complexas para revisar metadados.
• Você pode usar o arquivo completo README.md para fazer a revisão.
• Você pode querer definir ‘regras’ que são particularmente importantes para sua organização e usar um webhook para verificar se elas são seguidas.

Se você criar um aplicativo de qualidade de metadados usando Webhooks, por favor, me marque @davanstrien; adoraria saber sobre ele!