Documentar conjuntos de dados e modelos: fichas técnicas, declarações de dados e cartões de modelo

Uma referência sobre os três frameworks padrão de documentação para dados anotados e os modelos construídos a partir deles: o que cada um cobre, quando usar qual e como o relato de reprodutibilidade os conecta.

Três padrões de documentação tornaram-se a norma para dados de aprendizado de máquina: as declarações de dados e as fichas técnicas para o conjunto de dados, e os cartões de modelo para o que você treina com ele. Eles se sobrepõem bastante e nenhum é opcional se você quer que os dados sejam considerados confiáveis e reutilizados. Este guia é uma referência sobre o que cada um cobre e quando recorrer a ele. Para um percurso narrado sobre como redigir um deles, veja a publicação complementar sobre como documentar seu conjunto de dados de anotação; esta página é a comparação dos padrões.

Por que documentação estruturada e não um README

Um conjunto de dados anotado sem documentação envelhece mal. Seis meses depois, ninguém consegue dizer como ele foi amostrado, quem o rotulou ou o que um rótulo deveria significar, de modo que os dados se tornam uma caixa-preta em que se confia cegamente ou que se descarta. Dois custos específicos se repetem: a irreprodutibilidade (você não consegue reconstruir o conjunto de dados nem explicar uma discrepância sem o método de amostragem, a versão das diretrizes e o grupo de anotadores) e o viés oculto (rótulos vindos de um grupo restrito e não documentado carregam pontos cegos que permanecem invisíveis até virem à tona em produção). Os frameworks a seguir existem para tornar legíveis o quem e o como antes que qualquer um dos dois cause problemas.

Os três padrões

Cada framework mira em um artefato e num público diferentes, mas foram projetados para se encaixar.

As declarações de dados (Bender and Friedman, 2018) são o esquema específico do PLN. Elas caracterizam um conjunto de dados linguístico, a justificativa da curadoria, a variedade linguística e seus falantes, a demografia dos anotadores, as diretrizes e o uso pretendido, de modo que o leitor possa julgar como os resultados vão generalizar e quais populações os dados sub-representam. Recorra a uma declaração de dados quando os dados forem texto e a variedade linguística importar.

As fichas técnicas para conjuntos de dados (Gebru et al., 2021) são a versão de propósito geral, tomada da eletrônica, em que cada componente vem acompanhado de uma ficha técnica. Elas apresentam um conjunto padrão de perguntas sobre motivação, composição, processo de coleta, pré-processamento, usos recomendados e manutenção. Use uma ficha técnica para qualquer conjunto de dados de aprendizado de máquina, texto ou não; ela se sobrepõe bastante a uma declaração de dados, então num conjunto de dados linguístico você está na verdade escolhendo em torno de qual conjunto de perguntas se organizar, não fazendo os dois do zero.

Os cartões de modelo (Mitchell et al., 2019) documentam o modelo, não os dados: seu uso pretendido e, sobretudo, seu desempenho detalhado por grupos demográficos e outros, em vez de como um único número agregado. Um cartão de modelo é onde um problema de equidade se torna visível.

Os três formam uma cadeia. Uma ficha técnica ou uma declaração de dados documenta os dados; um cartão de modelo documenta o que foi construído a partir deles; e a seção de demografia dos anotadores do primeiro é exatamente o que torna interpretável a avaliação por grupos do último. Documente bem a anotação e você já terá percorrido a maior parte do caminho até um cartão de modelo defensável.

Framework	Documenta	Ideal para	Seções principais
Declaração de dados	Um conjunto de dados linguístico	Dados de PLN / texto	Justificativa da curadoria, variedade linguística, demografia de falantes e anotadores, diretrizes
Ficha técnica	Qualquer conjunto de dados de ML	Dados de ML em geral	Motivação, composição, coleta, usos, manutenção
Cartão de modelo	Um modelo treinado	Qualquer modelo publicado	Uso pretendido, avaliação desagregada, limitações

A reprodutibilidade é o quarto pilar

Documentação e reprodutibilidade são o mesmo objetivo sob dois ângulos. Pineau et al. (2021) relataram o programa de reprodutibilidade da NeurIPS e o condensaram em uma lista de verificação de reprodutibilidade: informe os dados exatos, os passos de coleta e pré-processamento, a configuração de avaliação e detalhes suficientes para reexecutar o trabalho. Para um projeto de anotação em específico, os fatos críticos para a reprodutibilidade são os que uma ficha técnica já pede: como os itens foram amostrados, qual versão das diretrizes foi usada, quem anotou e como a discordância foi tratada. Se você consegue responder a isso, o conjunto de dados está documentado e é reprodutível; se não, essa é uma lacuna a fechar antes da publicação, não depois.

Uma lista de verificação para a publicação

Antes de publicar, confirme que você consegue responder:

Como os itens foram amostrados e de onde?
Qual é a variedade linguística e quem escreveu o texto de origem?
Quem o anotou, quantas pessoas e qual é a composição demográfica do grupo?
Quais diretrizes eles seguiram e qual versão?
A discordância foi agregada em um rótulo de referência ou mantida como uma distribuição? Relate o acordo em qualquer caso.
Para que serve este conjunto de dados e para que ele não deveria ser usado?

Como fazer no Potato

A maior parte da documentação de um conjunto de dados já existe como artefatos do projeto, então você não parte de uma página em branco. A configuração é documentação: o YAML registra os esquemas, os conjuntos de rótulos e a estrutura da tarefa, versionados junto aos dados, e as instruções que você escreveu são a seção de diretrizes ao pé da letra. Se você executou uma fase de estudo preliminar, a demografia dos anotadores já está armazenada por anotador; agregue-a em distribuições para a seção de demografia dos anotadores. E a exportação mantém o anotador e o carimbo de data/hora em cada rótulo, de modo que a proveniência viaja com os dados em vez de ser removida:

json

{
  "id": "doc_001",
  "annotations": { "sentiment": "positive" },
  "annotator": "user_1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Ao publicar no Hub, gere o cartão do conjunto de dados como último passo da exportação e preencha suas seções a partir da configuração, das diretrizes e da demografia do estudo preliminar que você já tem.

Leituras adicionais

Como documentar seu conjunto de dados de anotação, o percurso narrado com uma declaração de dados trabalhada.
Como coletar a demografia dos anotadores de forma responsável, para fazer bem a seção de demografia dos anotadores.
Como redigir diretrizes de anotação, que servem também como seção de diretrizes.
Como exportar anotações para ML, para extrair rótulos e metadados de forma limpa.