Buscar K
Aparência
Classificação por IA (AIExtract)
O nó AIExtract enriquece cada linha do DataFrame com campos extraídos ou classificados por um LLM. Você define o schema de saída — nome, tipo e descrição de cada campo — e a IA preenche esses campos para cada registro.
Funcionalidades
- Classifica, normaliza ou extrai informações estruturadas de texto livre
- Schema tipado com vocabulário fechado opcional (lista de valores permitidos)
- Cardinalidade flexível: um valor por linha, vários em texto, ou expansão de linhas (explode)
- Múltiplos tiers de modelo com custo e qualidade distintos
- Cache automático por tenant + modelo + schema + registro — sem custo duplo
- Processamento em batches com paralelismo configurável
Parâmetros de Configuração
Geral
- Colunas de entrada (
inputColumns) — Quais colunas enviar ao LLM como contexto. Inclua apenas o que é relevante; colunas desnecessárias aumentam custo. - Dica de contexto (
contextHint) — Instrução adicional sobre o domínio dos dados (ex:"dados de e-commerce B2B"). Opcional. - Tier do modelo (
tier) — Qualidade e custo do LLM. Padrão:fast.
Performance
| Parâmetro | Padrão | Máximo | Descrição |
|---|---|---|---|
batchSize | 100 | 1000 | Registros por chamada ao LLM |
maxParallelBatches | 5 | 20 | Batches processados em paralelo |
Tiers de Modelo
| Tier | Modelo | Entrada | Saída | Uso recomendado |
|---|---|---|---|---|
free | GPT-OSS 20B | grátis | grátis | Testes — pode alucinar |
turbo | Mercury 2 (diffusion) | $0,25/M | $0,75/M | Alto volume, geração ~5× mais rápida |
fast | Grok 4.1 Fast | $0,20/M | $0,50/M | Padrão — melhor custo-benefício |
balanced | Gemini 2.5 Flash | $0,30/M | $2,50/M | Schemas complexos ou textos longos |
smart | Gemini 3 Flash Preview | $0,50/M | $3,00/M | Máxima precisão |
Schema de Saída
Cada campo define o que a IA deve extrair. Os campos originais do input são preservados; os campos abaixo são adicionados ao output.
| Propriedade | Obrigatório | Descrição |
|---|---|---|
name | sim | Nome da coluna — MAIÚSCULAS, sem acentos, max 30 chars |
type | sim | string, int, float ou bool |
description | sim | O que o campo representa. Mínimo 10 caracteres. Quanto mais preciso, melhor o resultado. |
values | não | Lista de valores permitidos (vocabulário fechado, só para type: string) |
cardinality | não | single (padrão), join ou explode |
separator | não | Separador para cardinality: join. Padrão: , |
required | não | Se true, rejeita registros onde esse campo não foi retornado |
Cardinalidade
| Modo | Comportamento | Exemplo |
|---|---|---|
single | 1 valor por linha | "Eletrônicos" |
join | Múltiplos valores serializados em texto | "Doce, Salgado, Picante" |
explode | 1 linha de output por valor — expande o DataFrame | 3 valores → 3 linhas |
Apenas 1 campo por nó pode usar cardinality: explode. Múltiplos campos explode gerariam produto cartesiano. Divida em nós AIExtract separados se necessário.
Boas Práticas
Descrições de campo — A qualidade da classificação depende da qualidade das descrições.
| Ruim | Bom |
|---|---|
"Categoria do produto" | "Categoria principal do produto: Eletrônicos, Vestuário, Alimentos, Móveis ou Outros" |
"Sentimento" | "Sentimento do comentário do cliente: Positivo, Negativo ou Neutro" |
Vocabulário fechado — Use values sempre que houver uma lista finita de categorias. Reduz alucinações e garante consistência no DW.
Colunas de entrada — Envie apenas as colunas relevantes. Colunas irrelevantes consomem tokens e podem confundir o modelo.
Cache — O cache é automático por (tenant, modelo, schema, contextHint, registro). Para forçar reclassificação, mude o contextHint ou o tier.
Quantidade de campos — Mais de 8 campos por nó aumenta custo e latência. Considere dividir em múltiplos nós.
Limites
| Limite | Valor |
|---|---|
| Registros por batch | 1 – 1.000 |
Campos com cardinality: explode por nó | máx. 1 |
Comprimento mínimo de description | 10 caracteres |
| Campos recomendados por nó | até 8 |
Permissões
O nó requer a permissão use_ai_etl no usuário que executa o fluxo. A feature pode ser desabilitada por tenant via allow_etl_ai: false na configuração do tenant.