Grounding: modelo semântico, catálogo sem PII, snapshot

Selo de estado: Preview (teto atual do produto) · Curso ACD-410 — Ingestia AI: perguntar aos dados com proveniência · Aula 2 de 8 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai explicar o que a IA recebe e o que nunca recebe — por capacidade, com o nome certo de cada peça do contexto: modelo semântico, catálogo sem dado pessoal e snapshot do painel.

Vídeo#

Identificador no manifesto: acd-410-02-como-a-ia-entende-seus-dados · duração-alvo 7 min · tela do produto: /query.

Roteiro de gravação (5 capítulos):

#	Minutagem-alvo	Capítulo	Tela do produto
1	0:00–0:45	Abertura: título + selo `Preview`. O problema: um modelo de linguagem sabe português, não sabe o que é "receita" na sua empresa.	`/query`
2	0:45–2:30	As três formas de contexto: modelo semântico (ids de tabelas/relações/medidas), catálogo sem dado pessoal (schema Silver/Gold) e snapshot (linhas do painel). Mostrar o rótulo de contexto usado na tela.	`/query`
3	2:30–4:15	O que nunca sai: colunas marcadas como dado pessoal, dado de outro cliente e nada além do que quem perguntou já vê (segurança por linha aplicada antes do prompt). Tudo entra em fence `<dados>`, tratado como dado e nunca como instrução.	`/query`
4	4:15–6:00	Grounding em ação: perguntar "explique a medida Receita" e mostrar a resposta citando a descrição escrita por um humano no modelo. Depois, provocar a ambiguidade e ver a recusa antes de gastar token.	`/dashboards/[id]` (aba do modelo → painel lateral ✨)
5	6:00–7:00	Limites: grounding reduz mas não elimina erro; a avaliação humana de grounding é gate pendente. Encerramento com o "faça você mesmo".	`/query`

Conteúdo#

O problema que o grounding resolve

Um modelo de linguagem "cru" sabe português, mas não sabe que na Aurora Varejo receita exclui devoluções, nem que a coluna valor convive com valor_liquido. Sem contexto ele chuta. Grounding é dar a ele o mínimo necessário — a estrutura e as definições do seu modelo — para que ele fale a sua língua e, principalmente, para que a resposta possa ser verificada.

É por isso que esta aula vem antes de qualquer pergunta: a qualidade do que você recebe na aula 3 depende do que você entregou aqui.

As três formas de contexto (e quem usa cada uma)

Capacidade	Recebe	Não recebe
Text-to-SQL, geração assistida	estrutura: o modelo semântico publicado (ids de tabelas, relações e medidas) ou o schema do catálogo	linhas de dados — só estrutura
Q&A, insights	snapshot do painel (linhas por widget), sujeito à política de envio externo	mais do que quem perguntou vê
Narrativa de relatório	resultados do relatório (período atual e anterior)	—

Tudo isso viaja dentro de um fence <dados id="…">, com a regra fixa no prompt: o que está entre <dados> é dado bruto, nunca instrução. Os tokens de fence são neutralizados dentro do conteúdo, então não existe texto capaz de "fechar" o fence e virar ordem — é a defesa contra injeção de prompt, coberta por uma suíte adversarial.

O que nunca sai, em nenhuma capacidade

Colunas marcadas como dado pessoal — excluídas na origem, antes de montar o prompt. A IA nem sabe que existem.
Dado de outro workspace — uma guarda de prefixo descarta qualquer tabela fora do seu workspace, mesmo que o catálogo estivesse corrompido.
Mais do que você vê — nas capacidades que leem linhas, a IA recebe a visão segura: segurança por linha do próprio membro e dado pessoal mascarado. Ela nunca vê mais do que quem perguntou.
Credencial, senha ou chave — a política de saída remove isso antes da chamada. O produto diz isso na própria tela do assistente.

Determinístico × LLM dentro do grounding

Explicar uma medida tem duas respostas possíveis, e vale saber qual você está lendo:

	Descrição da medida (determinística)	Explicação pela IA (LLM, Preview)
De onde vem	texto escrito por uma pessoa no modelo (até ~300 caracteres), ao lado das pastas e do selo de medida certificada	gerada no Q&A, a partir do modelo e da descrição que estão no grounding
Envolve LLM?	não	sim
Garantia	é a fonte de verdade humana	descreve o cálculo e precisa de citação verificável para afirmar número
Custo	zero	consome orçamento de IA

Daí sai uma regra prática: escreva descrições claras nas medidas centrais. Elas ajudam humanos e dão à IA chão firme para explicar, reduzindo resposta vaga.

Dois ganhos concretos do modelo semântico publicado

Menos ambiguidade. Se um termo da pergunta casa com duas ou mais medidas, a IA recusa antes de gastar token e pergunta qual você quis dizer.
Verificabilidade. Se a resposta citar um id que não existe no modelo publicado, a saída é descartada. SQL sem fundamento no modelo real não chega até você.

Nas telas

Em /query, o bloco "Como funciona" fecha com duas frases que são exatamente esta aula: nenhuma credencial, senha ou chave é enviada ao modelo e colunas marcadas como dado pessoal não entram no que é enviado. Abaixo dele, o rótulo de contexto usado diz qual das três origens está em vigor: "Modelo semântico publicado", "Suas tabelas tratadas" (camadas Silver e Gold) ou "Amostra de demonstração" — esta última vem marcada como exemplo, com o aviso de que nenhum número ali veio dos seus dados, e com o próximo passo: conectar uma fonte e publicar um pipeline até Silver.

No painel, o ✨ trabalha sobre o snapshot: a caixa de pergunta avisa "respostas baseadas nos dados já carregados". Em /auditoria, o evento ai.usage registra o resumo de envio externo — quantas tabelas do schema e quantas linhas viajaram (zero linhas no text-to-SQL).

Exemplo: a Aurora Varejo

Ana abre o painel comercial e pergunta no ✨: "explique a medida Receita".

A resposta esperada descreve o cálculo com base no que está no grounding: "Receita soma o valor líquido das vendas e exclui devoluções — conforme a descrição da medida no modelo publicado", citando a medida e a origem, sem inventar número. Se Ana tivesse perguntado "qual a receita?" num workspace onde existem Receita bruta e Receita líquida, a resposta esperada é uma recusa antes de gastar token, listando as duas opções.

Nota

Na notação de fórmulas do produto, cita-se outra medida com MEDIDA('Receita') e agrega-se uma coluna com SOMA(valor). É assim que a medida aparece no editor e é assim que a IA deve citá-la.

Erros comuns

Erro	Por que é errado
Achar que a IA aprende com os seus dados	não há treino com os seus dados e o produto não guarda histórico de conversa. Cada chamada remonta o contexto; o que fica é a trilha de auditoria
Perguntar sem período	o grounding diz quais números existem, não quando você quer. Sem período, a consulta varre tudo
Aceitar número sem citação	grounding bom não garante resposta certa — garante resposta conferível. Sem citação, você não conferiu nada
Supor que o snapshot é "agora"	o Q&A lê a última materialização do painel, não o datalake ao vivo

O que o grounding NÃO faz

Grounding reduz, mas não elimina, erro de LLM. Ele não valida a sua interpretação de negócio, não transforma uma medida mal definida em medida certa e não dá à IA acesso a dado que você não tem. O grounding no modelo central está em Preview e a avaliação humana de qualidade do grounding é gate pendente — motivo pelo qual nada aqui é anunciado como GA.

Faça você mesmo#

No workspace de treino Aurora Varejo, como admin ou dona. Atenção: os passos 4 e 5 disparam chamadas a modelo e consomem o orçamento de IA do workspace (centavos por pergunta, visíveis em /auditoria); os passos 1 a 3 não custam nada.

Abra /query e leia o rótulo de contexto usado. Anote qual das três origens está ativa e, se for "Amostra de demonstração", qual é o próximo passo que a tela sugere.
Abra o editor do painel comercial, aba do modelo, e localize a medida Receita. Leia a descrição escrita no modelo — a resposta determinística, sem IA nenhuma.
Se a descrição estiver vazia ou vaga, escreva uma frase clara (o que entra, o que é excluído). É a melhoria de grounding mais barata que existe.
No painel, abra o ✨ e pergunte "explique a medida Receita". Compare a explicação da IA com a descrição do passo 2: ela acrescentou algo? Inventou algo?
Agora provoque a ambiguidade: pergunte "qual a receita?" num escopo onde exista mais de uma medida parecida e confirme se veio recusa com opções em vez de um chute.
Em /auditoria, encontre os eventos da sua pergunta e leia o resumo de envio externo: quantas tabelas e quantas linhas saíram.

Você terminou quando você conseguir dizer, para cada uma das cinco capacidades com LLM, qual das três formas de contexto ela recebe — e apontar na auditoria quantas linhas saíram na sua pergunta.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

Capacidades ensinadas#

C02.5 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".