Integración de TrueFoundry AI Gateway con LangSmith

Introducción

En este blog, veremos cómo poner en funcionamiento los sistemas de LLM mediante la combinación de Puerta de enlace de IA TrueFoundry con LangChain's Lang Smith en un único flujo de trabajo listo para la producción. Empezaremos explicando la arquitectura, explicando por qué al enrutar todo el tráfico de modelos y agentes a través de la puerta de enlace se crea un límite de ejecución limpio, y cómo LangSmith se convierte en el registro de los seguimientos y las evaluaciones. A continuación, analizaremos paso a paso la integración propiamente dicha con OpenTelemetry, e incluiremos qué hay que configurar en AI Gateway, qué terminales de ingestión de LangSmith usar y cómo funcionan la autenticación y el enrutamiento de proyectos.

También abordaremos en detalle la configuración local y de VPC: cómo implementar LangSmith autohospedado, cómo determinar la URL de ingesta de OTLP correcta en redes privadas y cómo validar la entrega de rastreo de extremo a extremo desde la puerta de enlace a LangSmith. Al final, tendrá un plan claro para pasar de «tenemos una aplicación de LLM» a «podemos operarla, depurarla y evaluarla continuamente de forma fiable en producción».

El plano de control que falta en las arquitecturas de IA

Los sistemas de IA modernos están distribuidos. Utilizan varios proveedores de modelos, varios entornos de ejecución y, cada vez más, varios agentes autónomos. Sin una capa de ejecución centralizada, no existe un lugar natural para hacer cumplir la gobernanza, aplicar políticas o capturar una telemetría coherente. Sin la observabilidad, los rastros se convierten en registros opacos que no reciben la información que los ingenieros necesitan para depurar el comportamiento de los modelos. Sin una evaluación continua, la calidad se convierte en una conversación subjetiva en lugar de en una señal mensurable.

AI Gateway de TrueFoundry aborda la primera mitad de este problema al actuar como una capa de ejecución unificada para todo el tráfico de LLM. LangSmith aborda la segunda mitad proporcionando una capacidad de observación y una evaluación diseñadas específicamente para los sistemas de LLM. La integración entre ellos es lo que convierte estas capacidades en un plano de control coherente.

Puerta de enlace de IA TrueFoundry

El Puerta de enlace de IA TrueFoundry establece un punto de entrada único y gobernado para todas las solicitudes de modelos y agentes. Las aplicaciones y los agentes ya no se comunican directamente con los proveedores de modelos. Hablan con el proxy de la puerta de enlace. Esta decisión arquitectónica es importante porque crea una superficie uniforme para la aplicación de políticas, las decisiones de enrutamiento y la generación de telemetría. La puerta de enlace determina qué modelo se usa, bajo qué restricciones, en qué entorno y con qué medidas de seguridad. También se convierte en el único lugar donde el comportamiento de la producción se puede observar de manera exhaustiva.

Para los líderes de plataformas, este es el punto en el que los sistemas de IA dejan de ser una colección de scripts de Python y comienzan a comportarse como una infraestructura.

Lang Smith

Si bien la pasarela determina dónde y cómo se ejecutan las solicitudes, Lang Smith es el lugar al que acude para reconstruir lo que realmente ocurrió como datos de seguimiento estructurados en lugar de registros dispersos. En la terminología de LangSmith, un rastro captura la secuencia de pasos de extremo a extremo para una sola solicitud (desde la entrada hasta la salida final), y cada paso dentro de ese seguimiento es un correr, una sola unidad de trabajo, como una llamada de LLM, un escalón en cadena, el formato de solicitudes o cualquier otra operación que desee ver. Los rastros se organizan en proyectos (un contenedor para todo lo relacionado con una aplicación o servicio determinado), y las conversaciones de varios turnos se pueden vincular como hilos para que puedas inspeccionar el comportamiento en todo un diálogo en lugar de en una solicitud aislada. Lee aquí si quieres profundizar más: Conceptos de observabilidad

LangSmith también considera los comentarios como un concepto de primera clase, ya que le permite adjuntar puntuaciones y criterios a las ejecuciones, ya sea que los comentarios provengan de personas, de evaluadores automatizados o de evaluadores en línea que utilizan el tráfico de producción. Esto es lo que lo convierte en algo más que «monitorizar»: permite realizar evaluaciones offline de conjuntos de datos seleccionados antes de su envío, así como evaluaciones en línea de interacciones reales de usuarios durante la producción, para detectar regresiones y hacer un seguimiento de la calidad en tiempo real.

Telemetría abierta

La integración de TrueFoundry y LangSmith se basa en Telemetría abierta. AI Gateway exporta los rastros mediante los protocolos estándar de OpenTelemetry, y LangSmith los ingiere como un backend compatible con OpenTelemetry. Esta elección de diseño evita un acoplamiento estrecho. Permite a las organizaciones adoptar LangSmith sin cambiar la forma en que implementan o distribuyen los modelos. También cumple con los requisitos empresariales que a menudo se ignoran en las primeras etapas de la creación de herramientas de IA, como los puntos finales específicos de una región, las implementaciones de LangSmith autohospedadas y los entornos aislados de VPC.

Descripción general de la integración

Por el lado de TrueFoundry, habilitas el exportador de trazas OpenTelemetry de AI Gateway. La puerta de enlace sigue siendo responsable de generar y almacenar los rastros que puedes ver en la interfaz de usuario de TrueFoundry Monitor, y la exportación de esos rastros es una operación aditiva que no cambia el comportamiento de almacenamiento de TrueFoundry. Consulta los documentos de exportación de Otel aquí: True Foundry

Por el lado de LangSmith, usted proporciona una clave de API para la autenticación y (opcionalmente) un nombre de proyecto para que los rastreos lleguen a un proyecto predecible en lugar de al predeterminado. La guía OpenTelemetry de LangSmith documenta los encabezados OTLP que se utilizan para la autenticación y el enrutamiento de proyectos. Documentos: Cadena LANG

Integración con LangSmith (SaaS) gestionado

Comience por generar una clave API de LangSmith desde la configuración del panel de control de LangSmith. A continuación, la guía de integración de TrueFoundry consiste en configurar el exportador OTEL de AI Gateway desde la interfaz de usuario de TrueFoundry. Para ello, vaya a la sección «Configuraciones» de AI Gateway, abra «OTEL Config», habilite la «Configuración del exportador de OTEL Traces», elija el exportador HTTP y establezca el punto final y la codificación.

Para LangSmith administrado, el punto final de ingestión de rastros es:

https://api.smith.langchain.com/otel/v1/traces


El documento de TrueFoundry invoca HTTP con Proto codificación para la configuración del exportador y también señala que LangSmith usa un único punto final de ingestión OTEL y admite la codificación Proto o JSON.

Por último, añada el encabezado de autenticación en la configuración del exportador. TrueFoundry documenta el encabezado requerido como clave x-api con el valor de la clave de la API de LangSmith.

En este punto, la verificación es intencionadamente aburrida: envía algunas solicitudes a través de AI Gateway, confirma que los rastros están visibles en la sección TrueFoundry Monitor y, a continuación, confirma que esos rastros aparecen en LangSmith, en Proyectos. A continuación se muestran algunas imágenes que le ayudarán a configurarlo.

Hospedaje automático de LangSmith en una VPC y exportación de trazas desde AI Gateway

LangSmith autohospedado está diseñado para entornos en los que los rastros y los artefactos de evaluación deben permanecer dentro de los límites de la red controlados. Tendrá que hospedar automáticamente la interfaz de usuario y la API de LangSmith, además de los almacenes de datos y los servicios de backend (PostgreSQL, Redis, ClickHouse y almacenamiento de blobs opcional).

Si vas a realizar una implementación en Kubernetes, la guía oficial «Cómo hospedar LangSmith en Kubernetes» se basa en HELM y explica explícitamente lo que debes proporcionar por adelantado: una clave de licencia de LangSmith, una clave de API salt y (si utilizas la autenticación básica) un secreto de JWT. También recomienda utilizar Postgres/Redis/Clickhouse gestionado de forma externa para la producción, en lugar de utilizar los valores predeterminados del clúster, ya que el volumen de seguimiento puede aumentar rápidamente. Para una lectura más profunda, recomendaría revisar los documentos de alojamiento automático en Kubernetes de LangSmith: Autohospedaje en kubernetes

Un archivo de valores mínimos de Helm tiene el siguiente aspecto:

configuración:
<your license key>Clave de licencia de Langsmith: «»
<your api key salt>ApiKeySalt: «»
Tipo de autenticación: mixto
Autenticación básica:
habilitado: verdadero
Correo electrónico inicial del administrador del órgano: "admin@your-company.com»
Contraseña inicial de administrador de la organización: «una contraseña segura con más de 12 caracteres»
<your jwt secret>JWT Secret: «»


La guía de Kubernetes también menciona una restricción operativa que sorprende a muchas redes bloqueadas: LangSmith requiere la salida para https://beacon.langchain.com para la verificación de licencias y los informes de uso, a menos que se ejecute en modo sin conexión. Tendrá que planificarlo de forma explícita en las revisiones de las políticas de salida de la VPC.

Una vez implementado, expones el servicio de interfaz de LangSmith detrás de un balanceador de cargas interno o una entrada privada para que solo se pueda acceder a la interfaz de usuario y las API desde los servicios aprobados. En la documentación se recomienda encarecidamente configurar el DNS y el SSL para el envío de rastreos cifrados.

Determinar la URL de ingesta de OTLP correcta para LangSmith autohospedado

Este es el detalle que tiende a confundirse en las configuraciones «locales»: la ruta de punto final de OTLP difiere entre la gestionada y la autohospedada porque la API autohospedada normalmente se ofrece bajo un /api/v1 prefijo.

La guía «Trace with OpenTelemetry» de LangSmith establece que, en el caso de LangSmith autohospedado, debe reemplazar el punto final base por el punto final de la API de LangSmith y agregar /api/v1, dando un ejemplo de punto final OTEL base como https://ai-company.com/api/v1/otel. También señala que algunos exportadores de OTLP requieren que añadas /v1/trazas solo cuando se envían rastreos. Compruébalo aquí: Documentos de LangChain

La configuración del exportador AI Gateway de TrueFoundry quiere punto final de rastreo completo (como se muestra en el ejemplo de LangSmith administrado) ... /hotel/v1/trazas).

En conjunto, la URL de ingesta autohospedada más común que configurará en AI Gateway es:

https://<your-langsmith-host>/api/v1/otel/v1/traces


La autenticación se sigue realizando con un encabezado de clave de API. Para el enrutamiento del proyecto, LangSmith documenta una opción Proyecto Langsmith encabezado que puedes incluir al lado clave x-api por lo que rastrea la tierra en un proyecto con nombre en lugar de «predeterminado».

Si su LangSmith está detrás del enrutamiento basado en rutas

Algunas empresas exponen las plataformas internas bajo un nombre de host compartido con prefijos de ruta (por ejemplo, https://platform.company.com/langsmith/dev/...). La guía de soporte de LangChain para el enrutamiento basado en rutas muestra cómo configurar Config.basePath/config.subdomain y dos variables de entorno para que las URL se generen correctamente en toda la aplicación cuando se utiliza una BasePath.

En esa configuración, la URL de rastreo de OTLP también debe incluir el prefijo de la ruta base. Conceptualmente se convierte en:

https://<hostname><basePath>/api/v1/otel/v1/traces


y el resto de la configuración de TrueFoundry AI Gateway (exportador HTTP, codificación Proto, encabezados) permanece sin cambios.

Validación operativa

Después de conectar el punto final, valide en tres lugares, ya que cada uno aísla un dominio de error diferente.

• Primero, confirme que la puerta de enlace esté produciendo trazas localmente en la interfaz de usuario del monitor de TrueFoundry; esto le indicará que la telemetría del lado de la puerta de enlace está funcionando.
• En segundo lugar, confirme que la puerta de enlace puede llegar a LangSmith a través de la red buscando un comportamiento de exportación correcto; en las VPC bloqueadas, los errores más comunes son la resolución de DNS, la falta de enrutamiento privado o los problemas de la cadena de confianza TLS cuando se utilizan CA internas.
• En tercer lugar, confirme que los rastros aparecen en el proyecto de LangSmith previsto; si aparecen inesperadamente en «predeterminado», normalmente se debe a que el encabezado del proyecto no estaba configurado, y la guía OTEL de LangSmith documenta el nombre exacto del encabezado que se va a utilizar.

Por qué esta arquitectura se mantiene a medida que se escala

La elección de diseño clave aquí es que TrueFoundry AI Gateway exporta los trazos mediante OpenTelemetry y LangSmith acepta los rastreos de OpenTelemetry directamente. El anuncio de LangChain sobre la ingestión de OTEL hace hincapié en que LangSmith puede ingerir trazas de OTEL procedentes de exportadores estándar, lo que hace que «Gateway emita, LangSmith registre».

Conclusión

Para los líderes de IA, la integración entre TrueFoundry y Langsmith proporciona una base compartida en la que la ejecución, la observabilidad y la evaluación permanecen alineadas a medida que los sistemas escalan. Permite a los equipos gestionar las aplicaciones de LLM con el mismo rigor que los servicios distribuidos, cumpliendo con los requisitos empresariales sin ralentizar el desarrollo, ya que la IA de producción necesita una infraestructura de nivel de producción.

La asociación se puede componer intencionalmente: TrueFoundry gobierna y dirige la ejecución, LangSmith registra y evalúa el comportamiento y OpenTelemetry los conecta. En conjunto, funcionan como un práctico plano de control que hace que las organizaciones pasen de ser demostraciones prometedoras a utilizar una IA fiable y responsable en la producción.