Configuração do motor de rotulagem

Tudo o que o motor de rotulagem faz é definido em um único bloco labeling_engine. Um bloco inválido impede o servidor de iniciar e lista todos os problemas de uma vez. Para que os anotadores recebam as solicitações do motor, defina também assignment_strategy: engine. Definir essa estratégia sem um motor habilitado é um erro de validação.

O bloco tem as seções abaixo, cada uma explicada mais adiante:

assignment_strategy: engine
 
labeling_engine:
  enabled: true
  schemas: [sentiment]            # default: every scheme a source can label
  sources: []
  cascade: [laya, gemma]          # default: the first source alone
  contracts: []
  humans: {}
  crowd: {}
  budgets: {}
  runtime: {}
  features: {}
  redaction: {}
  distill: {}

Chaves de nível superior

Cinco chaves ficam diretamente sob labeling_engine:

Fontes

Uma fonte é um modelo, ou um conjunto de rótulos já existente, que propõe um rótulo e uma confiança para cada item. Toda fonte tem um id único e um kind, e uma chave desconhecida em uma fonte é um erro:

Tudo o que pode mudar uma resposta (modelo, prompt, temperatura, opções) entra no hash de versão da fonte. Uma nova versão torna stale todos os contratos que dependem da fonte.

Uma resposta que não é um valor que o esquema aceita, como um rótulo fora da sua lista, um campo numérico que não é número ou uma lista em um esquema de uma escolha entre N, é registrada como erro e nunca como rótulo, e a mensagem da execução conta esses erros. Um item cujas chamadas falham é solicitado de novo em execuções posteriores, no máximo três vezes por versão da fonte, e depois disso aguarda uma fonte alterada (uma chave ou um prompt corrigido é uma nova versão). Uma execução em que uma fonte falha não interrompe os outros níveis. O nível seguinte rotula todos os itens, e potato label run sai com status 1 e nomeia a fonte que falhou.

Métodos de confiança

As regras de aceitação do motor aplicam limiares à confiança de cada predição, então a forma como uma fonte informa a confiança decide quanto o motor consegue aceitar. confidence.method aceita um de cinco valores:

Opções específicas do tipo

Cinco tipos de fonte leem opções próprias:

• decision cobre o Laya no mesmo processo, ou qualquer servidor /v1/systemone, como o Jev hospedado ou o OpenJev. Uma passagem direta devolve uma probabilidade para cada opção, e funciona em esquemas radio, select, likert e slider. endpoint_type precisa ser laya ou systemone, e systemone precisa de base_url, a raiz do servidor (uma URL terminada em /v1/systemone também é aceita). O estado é enviado como {"text": ...} nos dois casos, então um checkpoint dá as mesmas respostas no mesmo processo e por trás do laya-serve, e options: {state_key: ""} envia a string pura. Em escalas de avaliação (likert, slider), os escores do Laya mal conseguem acompanhar a escala, então confira alguns itens antes de confiar nele. O endpoint laya no mesmo processo precisa de pip install 'potato-annotation[decision]'.
• detector lê caixas de um detector de objetos em esquemas image_annotation. keep_threshold (0.35) define o escore a partir do qual uma caixa faz parte da predição. Caixas entre candidate_threshold (0.05) e keep_threshold reduzem a confiança da imagem. label_map mapeia as classes do detector para os rótulos do esquema, e classes não mapeadas são ignoradas. image_field nomeia o campo do item com o caminho ou a URL da imagem. Os caminhos são resolvidos como a página de anotação os resolve, com /media/x.jpg sob o media_directory da tarefa e um caminho relativo sob task_dir.
• judge aceita rubric (por padrão, a descrição do esquema), fields (os campos do item mostrados ao juiz, em ordem) e swap_order, que pergunta duas vezes com a ordem dos rótulos invertida e transforma um veredito que muda em abstenção. Em esquemas de traces de agentes (process_reward, trajectory_eval, ...), o juiz rotula cada passo.
• vlm usa um endpoint de visão (openai_vision, anthropic_vision, ollama_vision). Para um modelo auto-hospedado atrás de um servidor compatível com OpenAI, use openai_vision com base_url.
• trained aceita artifact_dir, trainer (sklearn-text por padrão) e run_id. Normalmente é a destilação que cria esta fonte, e não uma configuração escrita à mão.

humans

O bloco humans define quem rotula e como o motor faz a amostragem:

crowd

O bloco crowd vale quando crowd está em humans.pools, e o Prolific é a única plataforma de crowdsourcing que o motor consegue controlar:

O recrutamento no crowdsourcing é uma simulação por padrão, e o planejador relata o que faria. Gastar dinheiro exige features.crowd_live_spend: true e um teto budgets.human_usd, e uma configuração que liga o gasto real sem o teto é rejeitada. Crowdsourcing explica como configurar o próprio estudo no Prolific.

budgets

O bloco budgets interrompe o gasto antes que um limite seja ultrapassado:

runtime

O bloco runtime controla lotes, concorrência e por quanto tempo uma pessoa pode manter uma solicitação:

features

Todos os recursos vêm desligados por padrão, exceto drift:

redaction

redaction.categories lista quais entre email, url, ip, card, ssn, phone e handle mascarar, e por padrão inclui todas. O mascaramento só se aplica com features.pii_redaction, e só a APIs de terceiros. Tipos de endpoint auto-hospedados (vllm, ollama, laya, yolo, ...) não são mascarados onde quer que rodem, e nenhum endpoint cujo base_url esteja na mesma máquina é mascarado.

distill

Com features.distill ligado, o motor treina um modelo barato com os rótulos do estudo e o coloca em primeiro na cascata:

Itens das divisões cert e de auditoria nunca entram no conjunto de treino, então o modelo destilado nunca é testado em rótulos com que foi treinado.

Validação

potato validate config.yaml verifica o bloco labeling_engine junto com o resto da configuração, e cada erro nomeia sua chave, por exemplo labeling_engine.sources[1].kind must be one of ... ou labeling_engine.contracts[0].error is required for selective_risk. A validação também recusa:

• uma chave de contrato que o tipo de contrato não lê, como um erro de digitação em error;
• um contrato em um esquema que nenhuma fonte da cascata consegue rotular, com o motivo de cada fonte;
• um contrato em um esquema que o motor não consegue pontuar (texto livre, pairwise);
• uma fonte decision cujo endpoint_type não é um modelo de decisão, e uma fonte llm, vlm ou judge cujo endpoint_type é um; e
• no_worse_than_human com humans.overlap_k abaixo de 3.

A validação também avisa quando budgets.human_labels é pequeno demais para certificar um contrato selective_risk mesmo que todas as respostas da máquina estivessem certas. Aumente o orçamento, ou afrouxe error, até esse aviso sumir.

Leitura adicional

• O motor de rotulagem
• Contratos do motor de rotulagem
• Linha de comando, REST API, ferramentas MCP e SDK
• Suporte de IA, para os tipos de endpoint que as fontes compartilham com o resto do Potato

Para detalhes de implementação, consulte a documentação de origem.