TrueFoundry AI Gateway-Integration mit LangSmith

Einführung

In diesem Blog erfahren Sie, wie Sie LLM-Systeme operationalisieren können, indem Sie die TrueFoundry KI-Gateway mit LangChain's Lang Smith in einem einzigen, produktionsbereiten Workflow. Wir erklären zunächst die Architektur, warum das Routing des gesamten Modell- und Agentenverkehrs durch das Gateway eine klare Ausführungsgrenze schafft und wie LangSmith zum Datensatz für Traces und Auswertungen wird. Dann gehen wir Schritt für Schritt durch die eigentliche Integration mithilfe von OpenTelemetry, einschließlich der Konfiguration im AI Gateway, der zu verwendenden LangSmith-Aufnahmeendpunkte und der Funktionsweise von Authentifizierung und Projekt-Routing.

Wir werden auch das On-Premise/VPC-Setup im Detail behandeln: wie man selbst gehostetes LangSmith bereitstellt, wie man die richtige OTLP-Ingestion-URL in privaten Netzwerken ermittelt und wie man die End-to-End-Trace-Übertragung vom Gateway zu LangSmith validiert. Am Ende haben Sie einen klaren Plan für den Übergang von „Wir haben eine LLM-App“ zu „Wir können sie in der Produktion zuverlässig betreiben, debuggen und kontinuierlich evaluieren“.

Die fehlende Steuerungsebene in KI-Architekturen

Moderne KI-Systeme sind verteilt. Sie verwenden mehrere Modellanbieter, mehrere Ausführungsumgebungen und zunehmend mehrere autonome Agenten. Ohne eine zentrale Ausführungsebene gibt es keinen natürlichen Ort, um Governance durchzusetzen, Richtlinien anzuwenden oder konsistente Telemetriedaten zu erfassen. Ohne Beobachtbarkeit werden Traces zu undurchsichtigen Protokollen, die genau die Informationen übersehen, die Ingenieure zum Debuggen des Modellverhaltens benötigen. Ohne kontinuierliche Bewertung wird Qualität eher zu einer subjektiven Konversation als zu einem messbaren Signal.

Das AI Gateway von TrueFoundry löst die erste Hälfte dieses Problems, indem es als einheitliche Ausführungsebene für den gesamten LLM-Verkehr fungiert. LangSmith adressiert die zweite Hälfte, indem es Beobachtbarkeit und Evaluierung bietet, die speziell für LLM-Systeme entwickelt wurden. Die Integration zwischen ihnen macht diese Fähigkeiten zu einer kohärenten Steuerungsebene.

TrueFoundry KI-Gateway

Das TrueFoundry KI-Gateway richtet einen einzigen, kontrollierten Einstiegspunkt für alle Modell- und Agentenanfragen ein. Anwendungen und Agenten kommunizieren nicht mehr direkt mit Modellanbietern. Sie sprechen mit dem Gateway-Proxy. Diese architektonische Entscheidung ist wichtig, da sie eine einheitliche Oberfläche für die Durchsetzung von Richtlinien, Routing-Entscheidungen und die Generierung von Telemetriedaten bietet. Das Gateway bestimmt, welches Modell unter welchen Einschränkungen, in welcher Umgebung und mit welchen Schutzmaßnahmen verwendet wird. Es wird auch zu dem einzigen Ort, an dem das Produktionsverhalten umfassend beobachtet werden kann.

Für Plattformführer ist dies der Punkt, an dem KI-Systeme aufhören, eine Sammlung von Python-Skripten zu sein und sich wie eine Infrastruktur verhalten.

Lang Smith

Während das Gateway festlegt, wo und wie Anfragen ausgeführt werden, Lang Smith ist der Ort, an dem Sie rekonstruieren können, was tatsächlich als strukturierte Trace-Daten statt als verstreute Protokolle passiert ist. In LangSmiths Terminologie eine Spur erfasst die vollständige Abfolge von Schritten für eine einzelne Anfrage (von der Eingabe bis zur endgültigen Ausgabe), und jeder Schritt innerhalb dieses Traces ist ein Lauf, eine einzelne Arbeitseinheit wie ein LLM-Anruf, ein Kettenschritt, die Formatierung von Eingabeaufforderungen oder jede andere Operation, die Sie einsehen möchten. Die Ablaufverfolgungen sind unterteilt in Projekte (ein Container für alles, was mit einer bestimmten Anwendung oder einem bestimmten Dienst zu tun hat), und Konversationen mit mehreren Runden können als Threads verknüpft werden, sodass Sie das Verhalten in einem gesamten Dialog und nicht in einer einzelnen Anfrage untersuchen können. Lesen Sie hier, wenn Sie tiefer eintauchen möchten: Konzepte der Beobachtbarkeit

LangSmith betrachtet Feedback auch als erstklassiges Konzept, sodass Sie Durchläufe mit Punktzahlen und Kriterien versehen können — unabhängig davon, ob das Feedback von Menschen, automatisierten Evaluatoren oder Online-Evaluatoren stammt, die den Produktions-Traffic nutzen. Das macht es zu mehr als „Überwachung“: Es unterstützt eine Bewertungsschleife, in der Sie vor dem Versand kuratierte Datensätze offline evaluieren können, und Online-Bewertungen realer Benutzerinteraktionen in der Produktion, um Regressionen zu erkennen und die Qualität in Echtzeit zu verfolgen.

Telemetrie öffnen

Die Integration von TrueFoundry und LangSmith basiert auf Telemetrie öffnen. Das AI Gateway exportiert Traces mithilfe von OpenTelemetry-Standardprotokollen, und LangSmith nimmt diese Traces als OpenTelemetry-kompatibles Backend auf. Diese Designwahl vermeidet eine enge Kopplung. Es ermöglicht Unternehmen, LangSmith einzuführen, ohne die Art und Weise zu ändern, wie sie Modelle bereitstellen oder weiterleiten. Es ermöglicht auch Unternehmensanforderungen, die in der frühen Phase der KI-Tools oft ignoriert werden, wie z. B. regionsspezifische Endpunkte, selbst gehostete LangSmith-Bereitstellungen und VPC-isolierte Umgebungen.

Überblick über die Integration

Auf der TrueFoundry-Seite aktivieren Sie den OpenTelemetry-Traces-Exporter des AI Gateways. Das Gateway ist weiterhin für das Generieren und Speichern von Traces verantwortlich, die Sie in der TrueFoundry Monitor-Benutzeroberfläche anzeigen können. Das Exportieren dieser Traces ist ein additiver Vorgang, der das Speicherverhalten von TrueFoundry nicht ändert. Sehen Sie sich die Dokumente zum Exportieren von OTEL hier an: Wahre Gießerei

Auf der LangSmith-Seite geben Sie einen API-Schlüssel für die Authentifizierung und (optional) einen Projektnamen an, sodass Traces in einem vorhersehbaren Projekt landen und nicht im Standardprojekt. Das OpenTelemetry-Handbuch von LangSmith dokumentiert die OTLP-Header, die für die Authentifizierung und das Projekt-Routing verwendet werden. Dokumente: Lang-Kette

Integration mit Managed LangSmith (SaaS)

Generieren Sie zunächst einen LangSmith-API-Schlüssel aus den LangSmith-Dashboard-Einstellungen. Im Integrationsleitfaden von TrueFoundry müssen Sie dann den AI Gateway OTEL Exporter von der TrueFoundry-Benutzeroberfläche aus konfigurieren, indem Sie zum Abschnitt „Konfigurationen“ von AI Gateway gehen, „OTEL Config“ öffnen, „OTEL Traces Exporter Configuration“ aktivieren, den HTTP-Exporter auswählen und den Endpunkt und die Codierung festlegen.

Für verwaltetes LangSmith lautet der Endpunkt für die Erfassung von Traces:

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


Das Dokument von TrueFoundry ruft HTTP auf mit Proto Kodierung für die Exportprogramm-Konfiguration. Außerdem wird darauf hingewiesen, dass LangSmith einen einzelnen OTEL-Aufnahmeendpunkt verwendet und die Proto- oder JSON-Codierung unterstützt.

Fügen Sie abschließend den Authentifizierungsheader in der Exportkonfiguration hinzu. TrueFoundry dokumentiert den erforderlichen Header als x-api-Schlüssel mit Ihrem LangSmith-API-Schlüsselwert.

An dieser Stelle ist die Überprüfung absichtlich langweilig: Senden Sie ein paar Anfragen über das AI Gateway, stellen Sie sicher, dass die Spuren im TrueFoundry Monitor-Bereich sichtbar sind, und bestätigen Sie dann, dass diese Spuren in LangSmith unter Projekte angezeigt werden. Im Folgenden finden Sie einige Bilder, die Ihnen bei der Einrichtung helfen sollen.

LangSmith selbst in einer VPC hosten und Traces aus dem AI Gateway exportieren

Das selbst gehostete LangSmith wurde für Umgebungen entwickelt, in denen Traces und Bewertungsartefakte innerhalb kontrollierter Netzwerkgrenzen verbleiben müssen. Sie müssen die LangSmith-UI/API sowie die Backend-Dienste und Datenspeicher (PostgreSQL, Redis, ClickHouse und optionaler Blob-Speicher) selbst hosten.

Wenn Sie die Bereitstellung auf Kubernetes durchführen, basiert das offizielle Handbuch „Self-Host LangSmith on Kubernetes“ auf HELM-basiert und genau beschreibt, was Sie im Voraus angeben müssen: einen LangSmith-Lizenzschlüssel, einen API-Schlüssel Salt und (wenn Sie Basic Auth verwenden) ein JWT-Geheimnis. Es wird auch empfohlen, extern verwaltetes Postgres/Redis/Clickhouse für die Produktion zu verwenden und nicht clusterinterne Standardwerte, da das Trace-Volumen schnell wachsen kann. Für genaueres Lesen würde ich empfehlen, LangSmiths Self-Host in den Kubernetes-Dokumenten durchzugehen: Selbsthosting auf Kubernetes

Eine Datei mit minimalen Helm-Werten sieht wie folgt aus:

Konfiguration:
<your license key>LangSmith-Lizenzschlüssel: "“
<your api key salt>API-Schlüssel Salt: „“
AuthType: gemischt
Grundlegende Auth:
aktiviert: wahr
Erste OrgAdmin-E-Mail: "admin@your-company.com“
InitialOrgAdmin-Passwort: „Ein starkes Passwort mit -12+-Zeichen“
<your jwt secret>JWT-Secret: „“


Der Kubernetes-Leitfaden weist auch auf eine betriebliche Einschränkung hin, die viele gesperrte Netzwerke überrascht: LangSmith benötigt Egress, um https://beacon.langchain.com zur Lizenzüberprüfung und Nutzungsberichterstattung, sofern Sie nicht im Offline-Modus arbeiten. Dies müssen Sie bei der Überprüfung der VPC-Richtlinien für ausgehenden Datenverkehr ausdrücklich einplanen.

Nach der Bereitstellung stellen Sie den LangSmith-Frontend-Dienst hinter einem internen Load Balancer oder einem privaten Ingress bereit, sodass die Benutzeroberfläche und die APIs nur von zugelassenen Diensten aus erreichbar sind. In den Dokumenten werden Sie nachdrücklich dazu angehalten, DNS und SSL für die verschlüsselte Übermittlung von Trace-Daten zu konfigurieren.

Ermitteln der richtigen OTLP-Erfassungs-URL für selbst gehostetes LangSmith

Dies ist das Detail, das bei „lokalen“ Setups dazu neigt, durcheinander zu geraten: Der OTLP-Endpunktpfad unterscheidet sich zwischen verwaltetem und selbst gehostetem, da die selbst gehostete API normalerweise unter einem /api/v1 Präfix.

In der Anleitung „Trace with OpenTelemetry“ von LangSmith heißt es, dass Sie für selbst gehostetes LangSmith den Basisendpunkt durch Ihren LangSmith-API-Endpunkt ersetzen und anhängen sollten /api/v1, mit einem Beispiel für einen OTEL-Basisendpunkt wie https://ai-company.com/api/v1/otel. Es wird auch darauf hingewiesen, dass bei einigen OTLP-Exporteuren das Anhängen erforderlich ist /v1/spuren nur beim Senden von Spuren. Schau hier nach: LangChain-Dokumente

Die AI Gateway-Exporter-Konfiguration von TrueFoundry benötigt den Endpunkt für vollständige Traces (wie das verwaltete LangSmith-Beispiel zeigt) ... /otel/v1/traces).

Zusammengenommen lautet die häufigste selbst gehostete Aufnahme-URL, die Sie im AI Gateway konfigurieren, wie folgt:

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


Die Authentifizierung erfolgt weiterhin mit einem API-Schlüssel-Header. Für das Projekt-Routing dokumentiert LangSmith eine optionale Langsmith-Projekt Header, den Sie nebenbei einfügen können x-api-Schlüssel Traces landen also in einem benannten Projekt und nicht in einem „Standard“.

Wenn Ihr LangSmith hinter dem pfadbasierten Routing steckt

Einige Unternehmen stellen interne Plattformen unter einem gemeinsamen Hostnamen mit Pfadpräfixen zur Verfügung (z. B. https://platform.company.com/langsmith/dev/...). Die Support-Anleitung von LangChain für pfadbasiertes Routing zeigt, wie man Folgendes einstellt Config.basePath/config.subdomain und zwei Umgebungsvariablen, sodass URLs in der gesamten Anwendung korrekt generiert werden, wenn ein BasePath verwendet wird.

In diesem Setup sollte Ihre OTLP-Traces-URL auch das Basispfadpräfix enthalten. Konzeptionell wird es:

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


und der Rest der TrueFoundry AI Gateway-Konfiguration (HTTP-Exporter, Protokodierung, Header) bleibt unverändert.

Operative Validierung

Nachdem Sie den Endpunkt verkabelt haben, überprüfen Sie ihn an drei Stellen, da jede eine andere Fehlerdomäne isoliert.

• Stellen Sie zunächst sicher, dass das Gateway lokal in der Monitor-Benutzeroberfläche von TrueFoundry Traces erzeugt. Dies zeigt Ihnen, dass Ihre Gatewayseitige Telemetrie funktioniert.
• Stellen Sie zweitens sicher, dass das Gateway LangSmith über das Netzwerk erreichen kann, indem Sie nach erfolgreichem Exportverhalten suchen. Bei gesperrten VPCs sind die häufigsten Fehler die DNS-Auflösung, fehlendes privates Routing oder Probleme mit der TLS-Vertrauenskette, wenn interne CAs verwendet werden.
• Stellen Sie drittens sicher, dass Traces im vorgesehenen LangSmith-Projekt erscheinen. Wenn sie unerwartet auf „Standard“ landen, liegt das normalerweise daran, dass der Projekt-Header nicht gesetzt wurde, und der OTEL-Leitfaden von LangSmith dokumentiert den genauen Header-Namen, der verwendet werden soll.

Warum diese Architektur bei der Skalierung standhält

Die wichtigste Designwahl hier ist, dass das TrueFoundry AI Gateway Traces mithilfe von OpenTelemetry exportiert und LangSmith OpenTelemetry-Traces direkt akzeptiert. LangChains Ankündigung der OTEL-Aufnahme betont, dass LangSmith OTEL-Traces von Standardexportern aufnehmen kann, was zu „Gateway-Emits, LangSmith-Datensätzen“ führt.

Fazit

Für KI-Verantwortliche bietet die TrueFoundry-LangSmith-Integration eine gemeinsame Grundlage, auf der Ausführung, Beobachtbarkeit und Bewertung bei der Skalierung der Systeme aufeinander abgestimmt bleiben. Sie ermöglicht es Teams, LLM-Anwendungen mit der gleichen Genauigkeit zu verwalten wie verteilte Dienste, um Unternehmensanforderungen zu erfüllen, ohne die Entwicklung zu verlangsamen, da die Produktions-KI eine Infrastruktur benötigt, die für die Produktion geeignet ist.

Die Partnerschaft ist bewusst zusammensetzbar: TrueFoundry steuert und leitet die Ausführung weiter, LangSmith zeichnet das Verhalten auf und bewertet es, und OpenTelemetry verbindet sie. Zusammen bilden sie eine praktische Kontrollebene, die Unternehmen von vielversprechenden Demos zu einer zuverlässigen, rechenschaftspflichtigen KI in der Produktion macht.