Guía esencial para garantizar la estabilidad al adoptar una API de lenguaje natural en producción (Microsoft Developer Community)

Principios clave

• Al construir una API de lenguaje natural para producción, es indispensable separar semantic parsing y execution
• El LLM debe usarse solo para convertir lenguaje natural → solicitudes estructuradas canónicas (canonical structured requests)
• El lenguaje natural debe tratarse solo como entrada, no como contrato de API (el lenguaje es frágil)

Problemas de usar lenguaje natural directamente

• Comportamiento no determinista (nondeterministic behavior)
• Lógica de negocio basada en prompts → difícil de depurar y reproducir
• Contrato de API implícito → pequeños cambios alteran el comportamiento
• Se producen fallas silenciosas (silent failures), lo que vuelve frágil al sistema

Arquitectura: separación en 2 capas

1. Semantic Parse API (lenguaje natural → estructura)

• Acepta la entrada de texto del usuario
• Extrae intent y entities con un LLM
• Completa un esquema predefinido
• Si falta información, hace preguntas de clarificación (sin ejecutar lógica de negocio)
• Actúa como compilador (p. ej., “blue backpack but cheaper” → {intent: “recommend_similar”, reference_product_id: “blue_backpack_123”, price_bias: -0.8})

2. Structured Execution API (estructura → ejecución)

• Acepta solo entradas estructuradas
• Es determinista, versionable y comprobable mediante pruebas
• No procesa lenguaje natural; funciona como un backend estable

Elemento principal: Canonical Schemas

• Contratos por intent definidos en código (campos obligatorios/opcionales, rangos de valores, reglas de validación)
• Absorben las variaciones del lenguaje natural → garantizan una salida consistente
• Funcionan como la columna vertebral del contrato de API

Schema Completion (Clarification)

• Si falta información, responde con needs_clarification (campos faltantes, pregunta dirigida, estado actual)
• La memoria se gestiona con un objeto de estado (la API es stateless)
• El cliente envía el estado para mantener la conversación → al completarse, se ejecuta canonical_request

Orquestación: uso de LangGraph

• Modelado de flujos de trabajo estructurados (clasificación de intent → extracción de entities → fusión de schema → validación → enrutamiento a completado/Clarification)
• Las decisiones se toman en código; el LLM solo propone
• Transiciones de estado claras, observabilidad y reintentos seguros

Medidas de seguridad: Confidence Gates

• Exigir un confidence score en la salida del LLM
• Si no alcanza el umbral, se bloquea la ejecución y se solicita clarificación (p. ej., “the bag” ambiguo → baja confianza → pregunta adicional)
• Evita interpretaciones erróneas silenciosas

Normalización: Lightweight Ontologies

• Basadas en código (intents permitidos, synonym mappings, validación entre campos)
• Los valores propuestos por el LLM → se normalizan con código (p. ej., “cheaper” → price_bias: -0.7)
• Si hay inconsistencias lógicas, se pide clarificación (p. ej., barato + alta calidad → pregunta sobre prioridad)

Consideraciones de rendimiento

• Latencia: clasificación de intent ~40ms, extracción de entities ~200ms, validación 1ms → total 250300ms
• Aceptable en una UX de chat y más barato que el costo de los errores

Lecciones principales (Key Takeaways)

• El lenguaje no es un contrato de API; debe transformarse en estructura
• El lado del servidor debe ser dueño del schema completion
• El LLM debe usarse solo para discovery y extraction, no para la ejecución
• La seguridad y el determinismo son la máxima prioridad
• Basado en experiencia real construyendo sistemas con Azure OpenAI + LangGraph

https://aisparkup.com/posts/9012