Treine o seu primeiro modelo com as suas anotações

Novo na v2.14.0

Este tutorial treina um classificador de sentimento com os rótulos de um estudo de exemplo e mostra as respostas do classificador ao próximo anotador como pré-rótulos. O tutorial é escrito para um responsável por estudo que experimenta o treinamento de modelos do Potato pela primeira vez, e cada etapa roda em um laptop sem GPU e sem instalar nada além do próprio Potato. Você inicia o projeto de avaliações de exemplo do Potato, faz o simulador de usuários rotular 120 das 160 avaliações do projeto, treina sklearn-text na página Training do administrador, lê a pontuação em itens reservados da execução e entra como um novo anotador para ver as respostas do modelo. Para saber o que cada parte do ciclo faz em geral, consulte a visão geral do treinamento de modelos.

Instalando o Potato e o projeto de exemplo

O tutorial usa sklearn-text, um treinador que transforma cada avaliação em atributos TF-IDF e ajusta um classificador de regressão logística. sklearn-text não precisa de nenhuma instalação extra, porque o scikit-learn é uma das dependências centrais do Potato. O projeto de exemplo fica no repositório do Potato no GitHub, e não no pacote pip, então instale o Potato e clone o repositório:

pip install --upgrade potato-annotation
git clone https://github.com/davidjurgens/potato.git
cd potato

Todos os comandos abaixo rodam a partir da raiz do repositório. A pasta do projeto examples/ai-assisted/model-training/ contém três arquivos:

• config.yaml é a configuração do estudo, com os comandos deste tutorial nos comentários.
• data/reviews.json contém 160 avaliações sintéticas de produtos, um objeto JSON por linha com um id e um text.
• data/gold.json dá o rótulo correto de cada avaliação. O simulador responde a partir deste arquivo.

A configuração de exemplo

A configuração define um esquema radio chamado sentiment, com os rótulos positive e negative, e liga o treinamento de modelos. O bloco abaixo é o arquivo distribuído sem os comentários, e o arquivo passa em python -m potato.validate_cli --strict sem alterações:

annotation_task_name: "Review Sentiment (model training demo)"
 
data_files:
  - "data/reviews.json"
 
item_properties:
  id_key: "id"
  text_key: "text"
 
task_dir: "."
output_annotation_dir: "annotation_output"
 
require_password: false
admin_api_key: "demo-admin-key"
 
num_annotators_per_item: 1
 
annotation_schemes:
  - annotation_type: "radio"
    name: "sentiment"
    description: "Is this review positive or negative?"
    labels:
      - "positive"
      - "negative"
    sequential_key_binding: true
 
model_training:
  enabled: true
  writeback:
    schemas: ["sentiment"]
    include_unlabeled: true
    min_confidence: 0.6

Quatro configurações moldam o tutorial:

• num_annotators_per_item: 1 dá a cada avaliação um rótulo. Três anotadores simulados com 40 avaliações cada cobrem então 120 avaliações diferentes e deixam 40 sem rótulo para o modelo.
• require_password: false permite que um novo anotador entre apenas com um nome de usuário. A última etapa entra dessa forma.
• admin_api_key: "demo-admin-key" abre as páginas de administração. Troque a chave em qualquer servidor que outras pessoas possam acessar.
• model_training registra as rotas /admin/training. O bloco writeback mostra aos anotadores as predições do esquema sentiment, e a seção sobre gravação de volta, mais adiante, explica cada chave.

Iniciando o servidor na porta 8000

Inicie o Potato com a configuração de exemplo:

potato start examples/ai-assisted/model-training/config.yaml -p 8000

O servidor carrega as 160 avaliações e serve a página de anotação em http://localhost:8000. Se a porta 8000 estiver ocupada na sua máquina, passe outra porta a -p e use essa porta em todas as URLs abaixo.

Rotulando 120 avaliações com o simulador

O modelo precisa de rótulos humanos para aprender. O simulador de usuários faz o papel de três anotadores. Cada anotador simulado responde a partir do arquivo gold e acerta a maioria das respostas. Execute o simulador em um segundo terminal, a partir da raiz do repositório:

python -m potato.simulator --server http://localhost:8000 --users 3 \
  --strategy gold_standard --competence good=1.0 --max-annotations 40 \
  --gold-file examples/ai-assisted/model-training/data/gold.json \
  --sequential --fast-mode --no-export

--strategy gold_standard faz cada anotador simulado responder a partir de gold.json, e --competence good=1.0 dá aos três anotadores o perfil good do simulador. Um anotador good sorteia uma acurácia entre 0,80 e 0,90 e responde a cada avaliação corretamente com essa probabilidade. Os rótulos contêm, portanto, erros, como os rótulos de uma equipe real. --sequential executa os três anotadores um após o outro, --fast-mode elimina as pausas entre as respostas e --no-export dispensa a gravação dos arquivos de resultado do próprio simulador. O simulador termina em cerca de dois segundos e encerra com um resumo. Confira se o resumo informa Total annotations: 120 antes de continuar. Você também pode rotular avaliações à mão em http://localhost:8000. sklearn-text se recusa a ajustar o modelo com menos de 10 itens rotulados na divisão train.

Abrindo a página Training com a chave de administrador

A página Training exige uma sessão de administrador. Abra http://localhost:8000/admin, digite demo-admin-key quando a página pedir a chave de API e depois abra http://localhost:8000/admin/training.

A página Training depois de duas execuções de sklearn-text no projeto de exemplo

O painel Start a run, no alto, reúne toda a configuração. Schema lista o único esquema do projeto, sentiment (radio). Trainer lista os 38 treinadores, e um treinador que o projeto não consegue executar traz o motivo ao lado do nome, como "not installed". A página seleciona sklearn-text sempre que sklearn-text serve ao esquema. Runs on mostra o único backend do projeto, local (this machine).

Treinando sklearn-text

Deixe Parameters vazio para usar os padrões do treinador e clique em Train now. A execução resolve as anotações em um rótulo por avaliação, divide as 120 avaliações rotuladas em conjuntos train, val e test e ajusta o modelo em um processo separado. A nossa execução levou 1,5 segundo, e o painel mostrou "Run finished." quando a execução terminou.

sklearn-text usa por padrão o TfidfVectorizer do scikit-learn para os atributos e LogisticRegression para o classificador. Com 50 ou mais itens na divisão train, sklearn-text também calibra as confianças do classificador. A calibração usa o escalonamento de Platt abaixo de 1.000 itens de treinamento e a regressão isotônica a partir de 1.000 itens. O modelo calibrado só é mantido se a calibração custar no máximo 0,05 de acurácia de treinamento. A calibração importa aqui porque a etapa de gravação de volta compara cada confiança com min_confidence.

Para iniciar a mesma execução a partir de um script, envie a chave de administrador no cabeçalho X-API-Key:

curl -X POST -H "X-API-Key: demo-admin-key" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "sklearn-text", "schemas": ["sentiment"]}'

A resposta traz o novo run_id e "started": true.

A página da execução e a pontuação em itens reservados

A execução concluída aparece na tabela Runs com os tamanhos de train e val e a sua Held-out score. Clique no ID da execução para abrir a página da execução em /admin/training/runs/<run_id>. A página da execução lista o status, o treinador, o backend, os tamanhos das divisões, a semente da divisão, a pontuação em itens reservados e os parâmetros da execução, depois uma tabela com todas as métricas e o log da execução.

Por padrão, uma execução reserva 15% dos itens rotulados para val e 15% para test, e split_seed decide quais itens vão para onde. A divisão permanece a mesma de uma execução para outra enquanto split_seed mantém o valor, então duas execuções com os mesmos rótulos são pontuadas nos mesmos itens. A pontuação em itens reservados de uma execução de sklearn-text é o macro-F1 em val. O macro-F1 calcula a média do F1 de cada rótulo, aqui positive e negative. A execução também registra a acurácia e o macro-F1 em test. A acurácia na divisão train é registrada como train_accuracy e nunca é usada como pontuação. Na nossa execução, o log dizia:

[info] Read 76 labelled rows from the train split
[info] Applied sigmoid calibration over 5 folds
[info] Held-out val macro_f1: 0.725

A documentação do próprio Potato relata uma execução no mesmo projeto, e a tabela coloca essa execução ao lado da nossa:

Os seus números serão diferentes dos de ambas as colunas, porque cada anotador simulado sorteia uma acurácia ao acaso e comete erros diferentes. Na nossa execução, os rótulos simulados coincidiram com gold.json em 97 das 120 avaliações e em 15 das 19 avaliações de val. A pontuação em itens reservados mede a concordância com os rótulos dos seus anotadores, e não com um gabarito, então erros dos anotadores em val reduzem a pontuação. Todos os 73 pré-rótulos que a nossa execução publicou coincidiram com gold.json. Em um estudo real sem arquivo gold, leia uma pontuação baixa em itens reservados como um motivo para verificar a concordância entre os anotadores antes de culpar o modelo.

Ligando a gravação de volta para o esquema

As predições de uma execução chegam aos anotadores somente pela gravação de volta. A configuração de exemplo já liga a gravação de volta para o esquema sentiment. Para o seu próprio projeto, adicione este bloco em model_training na configuração e reinicie o servidor:

model_training:
  enabled: true
  writeback:
    schemas: ["sentiment"]
    include_unlabeled: true
    min_confidence: 0.6

writeback.schemas nomeia os esquemas cujas predições os anotadores veem. A lista vem vazia por padrão, então ligar o treinamento não muda nada na página de anotação até que você nomeie um esquema. include_unlabeled: true faz cada execução prever também as avaliações que ninguém rotulou, além das avaliações de val e test. Sem include_unlabeled, uma execução prevê apenas as avaliações de val e test, e essas avaliações já têm um rótulo humano. min_confidence: 0.6 mantém uma predição fora da página de anotação quando a confiança do modelo fica abaixo de 0,6. O Potato ainda armazena a predição.

A gravação de volta roda após toda execução bem-sucedida e ignora qualquer item da divisão train da execução. Na nossa execução, o modelo previu 84 avaliações (19 de val, 25 de test e as 40 sem rótulo), 11 predições ficaram abaixo de 0,6, e a execução publicou as outras 73. O campo writeback de GET /admin/training/api/status dá as mesmas contagens, com o resumo "Published 73 prediction(s) as prelabels." As predições armazenadas são gravadas de volta de novo quando o servidor inicia, então os pré-rótulos sobrevivem a uma reinicialização. Para retirar os pré-rótulos de uma execução dos itens, envie DELETE /admin/training/api/runs/<run_id>/predictions.

Um pré-rótulo visto por um novo anotador

Abra http://localhost:8000 em uma janela privada do navegador e entre com um nome de usuário que ninguém usou, como newannotator. Cada avaliação rotulada já tem o seu único rótulo, então o novo anotador recebe as 40 avaliações sem rótulo, e o contador de progresso na nossa execução mostrava 0/40. A nossa primeira avaliação era "The toaster: Disappointed, it stopped working within a week. Much smaller than the photos suggest." com Negative já selecionado, com confiança de 0,68.

Uma avaliação que abre com a resposta do modelo selecionada, antes de o anotador salvar qualquer coisa

O pré-rótulo não é salvo enquanto o anotador apenas olha a avaliação, e o indicador de status mostra "Not labeled" até que o anotador salve uma resposta. A resposta do modelo passa a ser a resposta do anotador quando o anotador altera a seleção ou clica em Next. Na nossa execução, as 5 avaliações sem rótulo cuja predição ficou abaixo de min_confidence abriram sem nada selecionado. Um anotador excluído da ajuda de máquina com ai_support.holdout não vê pré-rótulos. Os pré-rótulos puxam os anotadores para a resposta do modelo, então ligue a gravação de volta quando a pontuação em itens reservados for alta o bastante para merecer confiança, e observe os anotadores que aceitam todos os pré-rótulos com as verificações de detecção de pré-rótulos aceitos no automático.

Próximos passos

O mesmo projeto comporta mais alguns experimentos antes de você passar para os seus próprios dados:

• Mude um parâmetro. Digite {"vectorizer_kwargs": {"ngram_range": [1, 2]}} em Parameters e treine de novo para acrescentar pares de palavras aos atributos. A nossa segunda execução com pares de palavras obteve 0,774 de macro-F1 em val na mesma divisão e publicou 74 pré-rótulos. Um nome de parâmetro que sklearn-text não aceita é recusado, com a lista dos nomes que o treinador aceita.
• Experimente um transformer. hf-text-classification (pip install "potato-annotation[train-text]") e setfit (pip install "potato-annotation[embeddings]") aprendem o mesmo esquema, e a página de treinadores dá os parâmetros de cada treinador.
• Feche o ciclo. Modelo no ciclo acrescenta a fila de revisão, o retreinamento conforme as anotações chegam com auto_retrain e o salvamento da divisão de uma execução como versão do conjunto de dados.
• Leve o treinamento para uma GPU. Treine em um servidor com GPU, em um cluster SLURM ou em uma máquina atrás de NAT envia as mesmas execuções para outra máquina.
• Treine outros tipos de modelo. Os tutoriais de ajuste fino de LLMs, modelos de visão, modelos de áudio e modelos para ciências seguem as mesmas etapas com outros treinadores e esquemas.

Todas as chaves usadas aqui estão listadas na referência de configuração do treinamento de modelos. Inicie a primeira execução do seu próprio projeto copiando o bloco model_training acima para a sua configuração e nomeando o seu esquema em writeback.schemas.

Leitura complementar

• Visão geral do treinamento de modelos
• Configuração do treinamento de modelos
• Treinadores
• Simulador de usuários
• Painel de administração
• Aprendizado ativo
• Referência de treinamento de modelos no repositório do Potato, com as seções completas de parâmetros de sklearn-text, pontuações em itens reservados e gravação de volta