# NVIDIA Structured Data Models: previsões tabulares sem treino e os cuidados que a biblioteca exige

> A NVIDIA lançou a biblioteca Structured Data Models, que reúne modelos pré-treinados para tabelas e bancos relacionais sob uma interface PyTorch e faz previsões sem treino, apenas com exemplos rotulados no contexto. A novidade importa porque iguala ou supera baselines treinados em vários cenários, mas os padrões da biblioteca podem descartar colunas importantes e até vazar dados se as colunas de tempo não forem declaradas.

Publicado em 2026-10-18 · https://invision.dreamvision.com.br/blog/nvidia-structured-data-models-previsoes-tabulares-sem-treino-e-os-cuidados-que-a

## Pontos-chave
- A biblioteca Structured Data Models reúne TabICLv2, KumoTabular e KumoRelational em uma interface PyTorch e faz previsões sem treino.
- Em classificação binária, os modelos pré-treinados igualaram ou superaram baselines do scikit-learn treinados nas mesmas linhas.
- A receita padrão do TabICLv2 descarta colunas de data/hora e texto, com aviso único por processo.
- O modelo relacional sem coluna de tempo declarada pode vazar dados e apresentar AUC artificialmente alta.
- O GradientExplainer reporta apenas o último estimador e exige seleção de classes pelo nome para evitar inversão de sinal.

## O que é a biblioteca Structured Data Models, da NVIDIA?
A Structured Data Models é uma biblioteca da NVIDIA que coloca vários modelos de fundação pré-treinados para dados tabulares atrás de uma única interface PyTorch. Ela permite fazer previsões sem treinar: basta fornecer linhas rotuladas como contexto e as linhas que se quer prever.

A biblioteca encapsula o TabICLv2 e o KumoTabular para tabelas únicas e o KumoRelational para bancos de dados relacionais completos. Todos respondem por aprendizado em contexto: a resposta sai em uma única passada para frente, na forma de probabilidades ou de uma distribuição preditiva completa.

O pacote no PyPI é apenas um placeholder; a instalação deve ser feita a partir do repositório no GitHub, fixando o commit em que o notebook foi verificado.


## Como funcionam as previsões sem treino na prática?
Os modelos tabulares recebem um contexto rotulado e linhas de consulta não rotuladas. A saída é um TableTensor com uma coluna de probabilidade por classe, nomeada pelo rótulo, sem etapa de ajuste nem hiperparâmetros.

No conjunto de câncer de mama, com 300 linhas rotuladas e 269 a prever, o TabICLv2 e o KumoTabular alcançaram acurácia de 0,970 e AUCs de 0,996 e 0,995 sem treino. Uma regressão logística e um gradient boosting ajustados nas mesmas 300 linhas ficaram em 0,970 e 0,993, e 0,967 e 0,992, respectivamente.

O parâmetro num_estimators define quantas visões do dado com pré-processamentos diferentes o modelo media, o que funciona como um ensemble embutido.


## O que é o TableTensor e por que os tipos semânticos importam?
Tudo na biblioteca passa pelo TableTensor, uma subclasse de tensor do PyTorch que mantém um bloco tipado por tipo semântico: numérico, categórico, data/hora, texto e identificador. A função infer_stypes decide os tipos automaticamente.

Com os padrões, ela erra em casos realistas: um comentário de texto livre vira categórico com 400 níveis e um id de chamado vira número, de modo que ambos chegariam ao modelo como features. Passar os sinalizadores de inferência para texto e id corrige isso.

A volta para o pandas preserva todos os valores, inclusive ausentes, mas não todos os dtypes: números retornam como float32, inteiros anuláveis viram floats com NaN e strings categóricas retornam como categoria do pandas.

Datas ficam armazenadas como microssegundos inteiros. Uma coluna em nanossegundos com segundos inteiros converte bem, mas um único valor com dígitos de nanossegundos faz a coluna inteira falhar; por isso, é preciso truncar os timestamps para microssegundos antes.


## Como reutilizar o contexto e obter distribuições calibradas?
Chamar o modelo diretamente reencoda o contexto a cada chamada. Quando as mesmas linhas rotuladas vão responder a vários lotes de consultas, o método fit codifica o contexto uma vez em um cache de chaves e valores, e predict executa apenas as linhas de consulta. Nada é aprendido nesse fit: ele apenas memoriza os exemplos.

Em regressão, o modelo não devolve um único número, mas 999 quantis por linha de consulta, ou seja, uma distribuição preditiva completa em uma passada. No conjunto de diabetes, com 300 linhas rotuladas, a mediana dessa distribuição teve RMSE de 53,6, ligeiramente melhor que o RidgeCV (54,3) e claramente melhor que o gradient boosting (64,7).

A calibração também aparece: o intervalo entre os percentis 10 e 90 conteve 81,0% dos alvos reservados, e o intervalo entre 5 e 95, 91,5%, próximos dos 80% e 90% nominais. Já a faixa de 50% ficou estreita, com 43,7%.


## Quais são as armadilhas silenciosas da biblioteca?
O pré-processamento é uma Recipe de processadores combináveis, e a receita padrão do TabICLv2 só tem ramos para colunas categóricas e numéricas. Colunas de data/hora e de texto, portanto, nunca viram features.

Em chamados cuja escalação depende de quando foram abertos e de palavras como 'reembolso', a receita padrão marcou AUC de 0,525, perto do acaso. A biblioteca emite um RuntimeWarning nomeando os tipos ignorados, mas ele aparece só uma vez por processo; depois, todas as execuções seguintes descartam essas colunas em silêncio.

O GradientExplainer tem duas armadilhas. A função de saída é chamada uma vez por estimador e cada chamada sobrescreve a anterior, então a explicação obtida é apenas a do último estimador. Além disso, cada estimador tem sua própria ordem de classes; selecionar a probabilidade por posição de coluna inverte o sinal em alguns seeds, enquanto selecionar pelo nome da classe acerta em todos.

No ambiente, o próprio erro de importação do pyg-lib monta uma URL a partir da versão exata de patch do PyTorch, que leva a uma página vazia; é preciso construir a URL a partir da versão maior e menor.


## Como o modelo relacional lida com bancos de dados e por que a coluna de tempo é crucial?
O KumoRelational recebe um banco relacional em vez de uma tabela única. Nele, o RelationalData guarda as tabelas e as chaves estrangeiras, e o amostrador percorre essas chaves a partir de cada linha da tarefa, coletando até 16 vizinhos por salto.

Em um banco sintético de loja com 800 clientes, 60 produtos e um ano de pedidos, o TabICLv2 usando só a tabela de clientes com região e plano alcançou AUC de 0,556. Com seis features de histórico construídas à mão, chegou a 0,828. O KumoRelational nas tabelas brutas, sem features manuais, alcançou 0,823.

O ponto crítico: declarar a data do pedido como coluna de tempo faz a caminhada ser temporal. Sem essa declaração, o amostrador pode retornar pedidos posteriores ao corte, que são exatamente os que definem o rótulo, e a AUC sobe para 0,940. O modelo deixa de prever e passa a ler a resposta, sem erro algum. Em um banco real, um modelo relacional suspeitosamente melhor que o baseline manual é o primeiro a ser reexecutado com todas as colunas de tempo declaradas.


## O que isso muda para quem usa IA?
A promessa central da biblioteca se confirma: nos cenários testados, os modelos pré-treinados igualaram ou superaram baselines do scikit-learn treinados nas mesmas linhas, sem treino, e entregaram distribuições preditivas calibradas de graça. No caso relacional, chegaram perto da acurácia de um pipeline de features feito à mão.

A lição prática é que os padrões merecem mais escrutínio do que os modelos. Texto livre e IDs não são detectados sem pedido explícito, a receita padrão descarta data/hora e texto com aviso único, o explicador reporta apenas o último estimador e exige seleção de classes por nome, e um modelo relacional sem coluna de tempo produz um número impressionante e sem significado.

Cada um desses problemas tem correção de uma linha, mas todos passam em silêncio se não forem verificados. Antes de confiar na saída, confira o que chega ao modelo. Para quem desenvolve com IA, a Invision oferece acesso a vários modelos por uma chave só, o que simplifica testar diferentes abordagens sem trocar de integração.


## Perguntas frequentes
### O que é a biblioteca Structured Data Models da NVIDIA?
É uma biblioteca que reúne modelos de fundação pré-treinados para tabelas e bancos relacionais sob uma interface PyTorch, permitindo previsões sem treino a partir de exemplos rotulados fornecidos no contexto.

### Como fazer previsão tabular sem treinar modelo?
Basta passar linhas rotuladas como contexto e as linhas a prever. O modelo aprende em contexto e retorna probabilidades ou uma distribuição preditiva em uma única passada, sem etapa de fit ou ajuste de hiperparâmetros.

### Por que o modelo relacional pode vazar dados?
Se a coluna de tempo não for declarada, o amostrador pode coletar registros posteriores ao corte, que definem o rótulo. O modelo então lê a resposta em vez de prever, e a métrica fica artificialmente alta sem gerar erro.

### Quais cuidados tomar com a receita padrão de pré-processamento?
A receita padrão do TabICLv2 ignora colunas de data/hora e de texto. É preciso adicionar processadores como AddCalendarFields e TFIDF para que esses dados virem features; caso contrário, o desempenho fica próximo do acaso.

### Como o GradientExplainer deve ser usado corretamente?
A função de saída é chamada uma vez por estimador e sobrescreve o resultado anterior, então é preciso explicar com um único estimador. Além disso, selecione a classe pelo nome da coluna, não pela posição, para evitar inversão de sinal.

Fonte original: [How to Make Zero-Training Tabular Predictions with NVIDIA Structured Data Models](https://www.marktechpost.com/2026/10/17/how-to-make-zero-training-tabular-predictions-with-nvidia-structured-data-models/) (MarkTechPost).
