Cómo construir una capa semántica para IA: métricas, relaciones y reglas de negocio

Para construir una capa semántica para IA, empezá por un cálculo de negocio acordado, implementalo en la granularidad correcta y exponelo mediante una interfaz de consultas controlada. Ampliá el alcance cuando la primera métrica esté verificada.

Esta guía usa una tienda ficticia. Es un patrón pequeño de implementación, no una plataforma semántica completa. La introducción a las capas semánticas explica el concepto.

1. Acordá la definición de la métrica

Decisión	Definición del ejemplo
Métrica	Ventas netas de mercadería
Pedidos incluidos	Pagados y no pertenecientes a pruebas
Importe	Después de descuentos; sin impuestos ni envío
Reembolsos	De mercadería, completados, atribuidos al pedido original
Moneda	Solo USD en este ejemplo
Tiempo	Fecha de pago en la zona horaria de reporte acordada
Historia	Se actualiza cuando llegan reembolsos posteriores
Responsable	Una persona de negocio que aprueba la definición

Esta es una métrica operativa, no una definición de reconocimiento contable de ingresos. Si necesitás una foto histórica inmutable o un reporte de caja, definí otra métrica.

2. Establecé qué representa cada fila

Supongamos que orders tiene una fila por pedido y refunds una fila por evento de reembolso. Los importes son centavos enteros. El proceso previo ya convirtió la fecha de pago a la fecha de reporte y separó los reembolsos de mercadería de los de impuestos y envío.

Un pedido puede tener varios reembolsos. Sumalos antes de unir las tablas:

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;

La unión izquierda conserva pedidos sin reembolsos. No valida los datos de origen: identificadores duplicados o reembolsos mal clasificados siguen causando errores. Esas condiciones requieren controles de calidad.

3. Conectá el modelo con los términos del negocio

Registrá order_id como clave única, net_sales_cents como métrica de suma, y reporting_date y country como dimensiones admitidas. Documentá las convenciones de moneda y reembolsos junto a la métrica.

Si usás dbt, consultá su documentación de modelos semánticos para la versión instalada. En otra herramienta, expresá el mismo acuerdo usando su sintaxis correspondiente.

La aplicación podría ofrecerle al agente esta solicitud limitada:

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

Es una interfaz ilustrativa, no una API de un proveedor. El servicio debe validar campos, pasar los valores de forma segura, aplicar permisos y rechazar combinaciones no admitidas. La identidad proviene de la autenticación, no de un identificador de cliente elegido por el modelo.

4. Verificá el cálculo por separado

El pedido real pagado A100 tiene 10.000 centavos y un reembolso completado de 2.000. A101 tiene 6.000 sin reembolso. Ambos corresponden 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';

El resultado esperado es 140,00. Agregá un pedido de prueba de 500,00 y uno cancelado de 70,00: el total debe seguir igual. Dividí el reembolso en dos eventos que sumen 20,00 y repetí la prueba.

Probá también reembolsos pendientes, pedidos sin reembolso, límites del período y períodos vacíos. Decidí cuándo mostrar cero y cuándo indicar que no hay datos suficientes.

5. Probá al agente, además de la métrica

Preguntá «ventas netas de agosto» y «mercadería de agosto después de reembolsos». Verificá que usen la misma definición. Ante «¿cuánto ingreso generamos?», comprobá si corresponde pedir aclaración.

Pedí datos fuera del alcance del usuario y verificá que el sistema de ejecución impida acceder a ellos. Revisá que la explicación conserve unidades, fechas y limitaciones del resultado.

6. Mantené la definición

Versioná el modelo, exigí revisión de cambios y repetí las pruebas cuando cambien las tablas, las uniones o las herramientas del agente. Asigná un responsable a cada métrica y mostrale al usuario cuándo se actualizaron los datos.

Para investigar diferencias, usá nuestra guía de diagnóstico de respuestas de IA. Timewise Labs puede ayudarte con la implementación.

Adaptado del artículo de Labs4Change.