Como construir uma camada semântica para IA: métricas, relações e regras de negócio

Para construir uma camada semântica para IA, comece com um cálculo de negócio acordado, implemente-o na granularidade correta e exponha-o por uma interface de consultas controlada. Amplie o escopo quando a primeira métrica estiver verificada.

Este guia usa uma loja fictícia. É um pequeno padrão de implementação, não uma plataforma semântica completa. A introdução às camadas semânticas explica o conceito.

1. Defina o contrato da métrica

Decisão	Definição do exemplo
Métrica	Vendas líquidas de mercadorias
Pedidos incluídos	Pagos e que não sejam de teste
Valor	Após descontos; sem impostos e frete
Reembolsos	De mercadorias, concluídos, atribuídos ao pedido original
Moeda	Apenas USD neste exemplo
Tempo	Data de pagamento no fuso de relatório acordado
Histórico	Atualizado quando chegam reembolsos posteriores
Responsável	Uma pessoa de negócio que aprova a definição

Esta é uma métrica operacional, não uma definição de reconhecimento contábil de receita. Se você precisa de um retrato histórico imutável ou de um relatório de caixa, defina outra métrica.

2. Estabeleça o que cada linha representa

Suponha que orders tenha uma linha por pedido e refunds uma linha por evento de reembolso. Os valores são centavos inteiros. O processo anterior já converteu o horário do pagamento para a data do relatório e separou reembolsos de mercadorias daqueles de impostos e frete.

Um pedido pode ter vários reembolsos. Some-os antes de unir as tabelas:

CREATE VIEW order_net_sales AS
WITH completed_refunds AS (
  SELECT order_id, SUM(merchandise_refund_cents) AS refund_cents
  FROM refunds
  WHERE status = 'completed'
  GROUP BY order_id
)
SELECT
  o.order_id,
  o.reporting_date,
  o.country,
  o.merchandise_cents - COALESCE(r.refund_cents, 0) AS net_sales_cents
FROM orders o
LEFT JOIN completed_refunds r ON o.order_id = r.order_id
WHERE o.status = 'paid' AND o.is_test = 0;

A união à esquerda preserva pedidos sem reembolso. Ela não valida os dados de origem: identificadores duplicados ou reembolsos classificados incorretamente ainda causam erros. Essas condições exigem verificações de qualidade.

3. Conecte o modelo aos termos do negócio

Registre order_id como chave única, net_sales_cents como métrica de soma, e reporting_date e country como dimensões permitidas. Documente as convenções de moeda e reembolsos junto à métrica.

Se usar dbt, consulte sua documentação de modelos semânticos para a versão instalada. Em outra ferramenta, expresse o mesmo contrato usando a sintaxe correspondente.

A aplicação poderia oferecer esta solicitação limitada ao agente:

{
  "metric": "net_merchandise_sales",
  "group_by": ["country"],
  "start_date": "2026-08-01",
  "end_date_exclusive": "2026-09-01"
}

É uma interface ilustrativa, não a API de um fornecedor. O serviço deve validar campos, passar os valores com segurança, aplicar permissões e rejeitar combinações não suportadas. A identidade vem da autenticação, não de um identificador de cliente escolhido pelo modelo.

4. Confira o cálculo separadamente

O pedido real pago A100 tem 10.000 centavos e um reembolso concluído de 2.000. A101 tem 6.000 sem reembolso. Ambos pertencem a agosto.

SELECT SUM(net_sales_cents) / 100.0 AS net_merchandise_sales_usd
FROM order_net_sales
WHERE reporting_date >= '2026-08-01'
  AND reporting_date < '2026-09-01';

O resultado esperado é 140,00. Adicione um pedido de teste de 500,00 e um cancelado de 70,00: o total deve continuar igual. Divida o reembolso em dois eventos que somem 20,00 e repita o teste.

Teste também reembolsos pendentes, pedidos sem reembolso, limites do período e períodos vazios. Decida quando mostrar zero e quando informar que não há dados suficientes.

5. Teste o agente, além da métrica

Pergunte “vendas líquidas de agosto” e “mercadorias de agosto após reembolsos”. Verifique se usam a mesma definição. Diante de “quanto geramos de receita?”, confira se é necessário pedir esclarecimento.

Peça dados fora do escopo do usuário e verifique se o sistema de execução bloqueia o acesso. Confira se a explicação preserva unidades, datas e limitações do resultado.

6. Mantenha a definição

Versione o modelo, exija revisão de mudanças e repita os testes quando as tabelas, uniões ou ferramentas do agente mudarem. Atribua um responsável a cada métrica e mostre quando os dados foram atualizados.

Para investigar diferenças, use nosso guia de diagnóstico de respostas de IA. A Timewise Labs pode ajudar na implementação.

Adaptado do artigo da Labs4Change.