Classificar com IA

Tipo: Referência
Para: Engenharia de dados, Desenvolvedor
Na tela: HorusETL › Dataflows › editor do Dataflow

Para cada linha, o Classificar com IA manda algumas colunas a um modelo de IA e acrescenta as colunas que ele devolve. Você define as colunas novas (nome, tipo, descrição e, se quiser, a lista de valores aceitos), e o modelo preenche uma por linha. Serve para classificar, padronizar ou tirar um dado de um texto livre: categoria de um produto, sentimento de um comentário, cidade escrita de dez jeitos.

Na biblioteca	`kind` no YAML	Grupo	Entradas
Classificar com IA	`AIExtract`	Inteligência Artificial	uma

Quem pode usar

O recurso precisa estar liberado para o Tenant. Sem a liberação, o nó falha com "AIExtract não habilitado para este tenant". A liberação é feita pela HorusBI.
O grupo de quem executa precisa da permissão de IA, a mesma que libera o chat. Sem ela: "Seu grupo não tem acesso a recursos de IA." As permissões estão em Grupos e permissões.

Consumo

Cada chamada ao modelo consome créditos de IA, como o chat. O tier escolhido e o volume de texto enviado decidem quanto. A aba Modelo de IA mostra, em cada tier, uma estimativa de custo por mil linhas. Se o Tenant tiver chave própria de IA configurada, o nó usa essa chave e não consome créditos.

O resultado fica guardado por Tenant. Uma linha com o mesmo conteúdo nas colunas de entrada, a mesma configuração dos campos, o mesmo contexto e o mesmo modelo é respondida pelo que já está guardado, sem chamar o modelo de novo. Reexecutar o Dataflow sobre as mesmas linhas não cobra de novo; mudar a descrição de um campo cobra. Para forçar uma classificação nova das mesmas linhas, mude o Contexto (opcional) ou o tier.

Campos

O botão do nó abre Configurar Classificação por IA, em cinco abas.

Aba	Na tela	No YAML (`options`)	Tipo	Padrão	Regra
Entrada	Colunas de entrada	`inputColumns`	lista de colunas	nenhuma	Obrigatório. Só estas colunas vão para o modelo. Mande só o que ajuda a decidir: cada coluna a mais aumenta o consumo
Entrada	Contexto (opcional)	`contextHint`	texto	vazio	Uma frase sobre os dados, como "produtos de e-commerce de moda feminina"
Modelo de IA	tier	`tier`	texto	`fast`	Ultra-rápido (`turbo`), Rápido (`fast`), Equilibrado (`balanced`), Máxima precisão (`smart`)
Campos de saída	lista de campos	`outputColumns`	lista	nenhum	Obrigatório. Veja Campos de saída
Avançado	Linhas por batch	`batchSize`	inteiro	`100`	De 1 a 1.000 linhas por chamada ao modelo
Avançado	Batches paralelos	`maxParallelBatches`	inteiro	`5`	De 1 a 20 chamadas ao mesmo tempo

A aba Código mostra um script Python equivalente à configuração, para copiar ou baixar.

Campos de saída

Na tela	Chave em `outputColumns`	Regra
nome	`name`	Maiúsculas, começa com letra, só `A-Z`, `0-9`, `_`, `#` e `$`, até 30 caracteres. Não pode repetir. A tela ajusta o nome digitado a essa regra
tipo	`type`	Texto (`string`), Número inteiro (`int`), Número decimal (`float`), Sim/Não (`bool`)
Descrição do campo	`description`	Mínimo de 10 caracteres. É o que o modelo lê para decidir
valores permitidos	`values`	Só em Texto. Com valores, o modelo só pode responder um deles. Vazio aceita texto livre
cardinalidade	`cardinality`	Um valor (`single`, padrão), Vários — em texto (`join`) ou Vários — em linhas (`explode`)
Separador:	`separator`	Para Vários — em texto. `,` (padrão), `;` , `\|`, `/` ou quebra de linha
Obrigatório — rejeita resultados sem esse campo	`required`	Ligado por padrão. Desligado, o modelo pode deixar o campo vazio

Tipos na saída: Número inteiro e Número decimal viram número; Sim/Não vira o texto true ou false; o resto vira texto.
Vários — em linhas: a linha se repete uma vez para cada valor devolvido. Só um campo por nó pode usar essa opção: a tela avisa quando há mais de um, e a execução recusa. Se o modelo não devolver nenhum valor, a linha sai uma vez, com o campo vazio.
A descrição decide a qualidade. "Sentimento" rende menos que "Sentimento do comentário do cliente: Positivo, Negativo ou Neutro".
Acima de 8 campos, a tela avisa: "Muitos campos aumentam custo e tempo. Considere dividir em múltiplos nós."

Saída e falhas

A saída tem todas as colunas da entrada, na mesma ordem, seguidas das colunas novas.

As linhas vão em batches. Se algum batch falhar, o nó inteiro falha com "N/M batch(es) falharam durante AIExtract.", seguido dos primeiros erros. Os batches que deram certo ficam guardados e não são cobrados de novo na próxima execução.

yaml

- internalId: classificar_produtos
  kind: AIExtract
  inputs: [ext_produtos]
  options:
    inputColumns: [NOME_PRODUTO, DESCRICAO]
    contextHint: Catálogo de loja de material de construção
    tier: fast
    batchSize: 100
    maxParallelBatches: 5
    outputColumns:
      - name: CATEGORIA
        type: string
        description: Categoria principal do produto no catálogo
        values: [Hidráulica, Elétrica, Pintura, Ferramentas, Outros]
        cardinality: single
        required: true
      - name: TAGS
        type: string
        description: Características do produto citadas no texto, como cor e material
        cardinality: join
        separator: ", "
        required: false

Relacionado

Pelo Lumo CLI

O nó também pode ser escrito e versionado em YAML. Veja a referência de flow.

Classificar com IA ​

Quem pode usar ​

Consumo ​

Campos ​

Campos de saída ​

Saída e falhas ​

Relacionado ​