Beim Aufbau einer LangChain-Anwendung ist der erste Schritt oft nicht die Chain, sondern der Key. Derselbe Code läuft lokal, meldet nach dem Deployment aber 401; oder ein Key wird in ein Notebook geschrieben und später vergessen. Das Problem liegt selten am Framework, sondern an Herkunft, Ladereihenfolge und Rechtegrenzen des Keys.

Dieser Artikel folgt der Reihenfolge Herkunft, Konfiguration, Isolation, Rotation und Fehlersuche und beschreibt, wie API-Keys in LangChain-Projekten verwaltet werden sollten. Konkrete Modelle, Kontingente und Preise entnehmen Sie den Modellpreisen und der Dokumentation des jeweiligen Anbieters.

Hinweis: LangChain ist eine Marke von LangChain, Inc. Dieser Artikel dient der technischen Konfiguration; es besteht keine Zugehörigkeit oder Kooperation mit LangChain, Inc. Das Verhalten der Integrationspakete kann sich mit Versionen ändern; maßgeblich ist die Dokumentation der jeweiligen Version.

1. Zuerst klarstellen: LangChain stellt keine Modell-Keys aus

LangChain ist ein Open-Source-Framework für die Anwendungsentwicklung und verbindet Modelle, Tools, Retrieval und Ablaufsteuerung. Es bringt in der Regel kein Modellkontingent mit, daher gibt es keinen „LangChain-Modell-Key“. Die Zugangsdaten, die Sie in LangChain eintragen, gehören dem Modellanbieter, der Cloud-Plattform oder einem AI-Gateway.

Im Projekt gibt es mindestens drei Arten von Zugangsdaten mit völlig unterschiedlichem Zweck:

Zugangsdaten Zweck Bezugsquelle
Modell-API-Key Aufruf von Chat-, Reasoning- und Embedding-Modellen Konsole des Modellanbieters oder AI-Gateways
LANGCHAIN_API_KEY Tracing und Evaluation mit LangSmith LangSmith, nur bei aktivierter Observability nötig
Cloud-Plattform-Zugangsdaten Zugriff auf gehostete Modelle oder Cloud-Ressourcen Zugriffskonsole des jeweiligen Cloud-Anbieters

Wer die drei zu einem einzigen Key zusammenfasst, erhält zu weitreichende Rechte und erschwert die Rotation. Erst nach Zweck trennen, dann konfigurieren.

2. Umgebungsvariablen: Standardkonvention und explizite Übergabe

ChatOpenAI aus langchain-openai liest standardmäßig OPENAI_API_KEY; bei OpenAI-kompatiblen Endpunkten wird die Adresse über den Parameter base_url gesetzt. Minimale Konfiguration:

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

# Liest .env aus der Projektumgebung; in Produktion Systemvariablen oder Secret-Manager nutzen
load_dotenv()

llm = ChatOpenAI(
    model=os.environ["ZSQH_MODEL"],       # Modell-ID gemäß Preisseite
    api_key=os.environ["ZSQH_API_KEY"],   # alternativ der Standard OPENAI_API_KEY
    base_url="https://ai.zhongshangqihang.com/v1",
    temperature=0,
)

print(llm.invoke("Erkläre in einem Satz, was ein API-Gateway ist").content)

Einige leicht übersehene Details:

  • Umgebungsvariablen werden beim Erzeugen des Client-Objekts gelesen, nicht beim Import des Moduls. Wird in einem Notebook nachträglich os.environ gesetzt, muss die ChatOpenAI-Instanz neu erzeugt werden.
  • Eine explizit übergebene leere Zeichenkette überschreibt die Umgebungsvariable. Bei 401 zuerst prüfen, ob im Code Reste wie api_key="" stehen.
  • Verschiedene Integrationspakete lesen unterschiedliche Variablennamen; Anthropic und Google haben eigene Konventionen, maßgeblich ist die jeweilige Dokumentation.
  • init_chat_model kann Modelle verschiedener Anbieter einheitlich erzeugen, zusätzliche Parameter und Standardvariablen bleiben aber Sache der darunterliegenden Integration und sollten nach Upgrades erneut geprüft werden.

3. .env und SecretStr: zwei Schutzlinien für die lokale Entwicklung

Eine .env-Datei ist lokal praktisch, erfordert aber zwei Disziplinen.

Erstens gehört .env niemals ins Versionskontrollsystem. Beim Projektstart in .gitignore eintragen und zusätzlich eine .env.example ohne echte Werte einchecken, damit neue Teammitglieder die benötigten Variablen kennen. Wurde die Datei versehentlich eingecheckt, reicht Löschen nicht aus, denn die Historie bleibt; den betroffenen Key sofort widerrufen und anschließend die Repository-Historie behandeln.

Zweitens SecretStr in LangChain kennen. Die Schlüsselfelder von ChatOpenAI werden üblicherweise als SecretStr gespeichert und beim Ausgeben des Objekts oder in Logs maskiert statt im Klartext gezeigt. Das verhindert einen Teil versehentlicher Ausgaben, aber nicht den aktiven Aufruf von get_secret_value(), manuell zusammengesetzte Header oder das Protokollieren ganzer Anfragen in Ausnahmen. „Das Framework maskiert“ bedeutet nicht „Logs sind unbedenklich“.

Beim Container-Deployment Keys nicht ins Image schreiben; Build-Argumente und Image-Schichten können erhalten bleiben. Besser zur Laufzeit über Umgebungsvariablen oder einen Secret-Manager injizieren.

4. Mehrere Anbieter, mehrere Modelle: ein Key oder viele?

Die Antwort hängt davon ab, ob der Zugang einheitlich ist. Mit einem AI-Gateway genügt meist ein Gateway-Key für mehrere Modelle, die über den Parameter model unterschieden werden; bei direkter Anbindung mehrerer Anbieter wird üblicherweise pro Anbieter ein eigener Key benötigt.

Variablennamen sollten lesbar und im Team festgelegt sein:

  • Gateway: ZSQH_API_KEY, ZSQH_BASE_URL.
  • Anbieter: die vom Integrationspaket erwarteten Namen, etwa ANTHROPIC_API_KEY, GOOGLE_API_KEY.
  • Umgebungssuffixe: _DEV, _STAGING, _PROD, damit Test-Keys nicht in die Produktion gelangen.

Mehrere Modelle bedeuten auch Fallback und Routing. LangChain kann mit .with_fallbacks() bei Ausfall des Hauptmodells auf ein Ersatzmodell wechseln; auch das Ersatzmodell braucht vollständige Authentifizierung. Nicht annehmen, „ein Key kann alle Modelle aufrufen“: Das Gateway kann eine Modell-Whitelist haben, und Anbieter-Keys können nur für bestimmte Modelle gelten. Verfügbare Modell-IDs stehen auf den Modellpreisen.

5. Minimale Rechte: Keys nach Umgebung und Zweck trennen

Das Ziel der Key-Verwaltung ist nicht „möglichst wenige Keys“, sondern „möglichst klare Grenzen“. Umsetzbar:

  • Entwicklung, Staging und Produktion nutzen eigene Keys; der Produktions-Key liegt nicht auf Entwicklerrechnern.
  • Jede Anwendung und jedes Teammitglied erhält einen eigenen Key; keine gemeinsame Nutzung.
  • Test-Keys erhalten ein niedrigeres Budget und einen eingeschränkten Modellbereich.
  • IP-Whitelist, Kontingentwarnungen und Modell-Whitelist in der Konsole aktivieren, sofern verfügbar.
  • In Logs, Tickets und Screenshots nur die letzten Zeichen des Keys zeigen.

Unterstützt das Gateway Verbrauchsstatistiken pro Key, dient derselbe Key der Kostenrechnung und der Fehlerlokalisierung; ein gemeinsamer „Allzweck-Key“ macht ungewöhnliche Rechnungen nicht zuordenbar.

6. Rotation und Widerruf: erst neu, dann umschalten, dann alt sperren

Eine Rotation mindestens alle 90 Tage wird empfohlen; bei Personalabgang, Geräteverlust, fehlerhaft geteilter Konfiguration oder vermuteter Offenlegung sofort. Die Reihenfolge darf nicht vertauscht werden:

  1. In der Konsole einen neuen Key anlegen und mit Datum oder Version benennen, etwa prod-app-202610.
  2. Den neuen Key in den Secret-Manager oder die Umgebungsvariablen der Deployment-Plattform eintragen.
  3. Anwendung neu starten oder neu deployen und bestätigen, dass der neue Prozess den Wert geladen hat.
  4. Eine echte Anfrage senden und prüfen, ob das Modell antwortet und der Verbrauch beim neuen Key verbucht wird.
  5. Eine Zeit lang beobachten, ob noch alte Instanzen aufrufen.
  6. Erst nach Bestätigung den alten Key widerrufen und die interne Dokumentation aktualisieren.

Werden Keys aus Umgebungsvariablen gelesen, ist für die Rotation meist keine Codeänderung nötig, aber ein Neustart oder Rolling Release. Langlebige Verbindungen oder dauerhaft laufende Prozesse können den alten Key weiter halten; vor dem Widerruf prüfen, ob alle Instanzen ersetzt sind.

7. CI und Teamarbeit: Keys gehören nicht in Logs

CI-Umgebungen führen automatisch aus und bewahren Logs auf; sie sind ein häufiger Ort für Schlüssellecks. Einige Grundregeln:

  • Keys in verschlüsselten Secrets der CI-Plattform ablegen, nicht im Klartext in Pipeline-Dateien.
  • Debug-Optionen abschalten, die Befehle wiedergeben, damit set -x keine Header ausgibt.
  • Für CI einen eigenen Key mit niedrigem Limit und eingeschränktem Modellbereich anlegen.
  • Secret-Scanner als Prüfung vor dem Commit einsetzen und bei Verdacht sofort blockieren.
  • Bei Code-Reviews .env, Konfigurationsdateien und Test-Snapshots als sensible Dateien behandeln.

Die Übergabedokumentation sollte Verantwortlichen, Zweck, Erstellungsdatum, nächsten Rotationstermin sowie den Widerrufsprozess bei Personalabgang und Geräteverlust festhalten.

8. Fehlersuche: erst Variablen, dann Protokoll

Bei Authentifizierungsfehlern in dieser Reihenfolge prüfen; das ist meist schneller als wiederholtes Neuanlegen des Keys:

  1. Prüfen, ob die Variable im Prozess ankommt: nur ihre Existenz ausgeben, nicht den Wert. Notebook-Kernel neu starten, im Container bestätigen, dass die richtige Service-Instanz die Variable erhalten hat.
  2. Explizite Überschreibungen kontrollieren: Wird im Code oder in Konfigurationsdateien ein leeres api_key oder eine falsche base_url übergeben?
  3. Protokollpfad abgleichen: OpenAI-kompatible Endpunkte enden üblicherweise auf /v1; ein fehlendes oder zusätzliches Segment führt meist zu 404.
  4. Modell-ID prüfen: Der Anzeigename ist nicht die API-Bezeichnung; Zeichen für Zeichen mit der Preisseite abgleichen.
  5. Nach Statuscode verzweigen: 401 den Key selbst, 403 Rechte und Modellbereich, 429 Parallelität und Kontingent, 5xx zuerst erneut versuchen und die Anfragezeit notieren.
  6. Netzwerk und Proxy prüfen: Proxy-Variablen und Unternehmenszertifikate können Anfragen scheitern lassen, deren Fehlermeldung wie ein Authentifizierungsproblem aussieht.

Pro Durchgang nur eine Variable ändern. Erst den Key, dann das Modell wechseln, um schnell zu erkennen, ob „der Key nicht funktioniert“ oder „das Modell nicht verfügbar ist“.

Häufige Fragen

Benötigt LangChain selbst einen API-Key?

Das Framework selbst nicht. Erst beim Aufruf entfernter Modelle, von Embedding-Diensten oder der Observability von LangSmith werden entsprechende Zugangsdaten benötigt.

Warum kommt trotz gesetzter Umgebungsvariable weiterhin 401?

Vier häufige Ursachen: Die Variable gilt nur im aktuellen Terminal, der Notebook-Kernel wurde nicht neu gestartet, der Code übergibt explizit einen leeren Key, oder der Key enthält führende bzw. nachfolgende Leerzeichen oder Zeilenumbrüche. Zuerst bestätigen, dass die Variable im Prozess vorhanden ist, dann prüfen, ob sie vom Code überschrieben wird.

Kann ein Key mehrere Modelle gleichzeitig aufrufen?

Das hängt vom Dienst hinter dem Key ab. Ein einheitliches Gateway erlaubt meist mehrere Modelle aus seinem Katalog; bei direkter Anbieteranbindung hat jeder Anbieter einen eigenen Key. Auch bei Mehrmodell-Unterstützung kann eine Whitelist gelten; maßgeblich sind die Konsolenrechte.

Erscheint der Key in den Tracing-Aufzeichnungen von LangSmith?

Tracing speichert vor allem Ein- und Ausgaben sowie Aufrufketten; ob Header enthalten sind, hängt von Integration und Maskierung ab. Die Tracing-Plattform ist kein Key-Tresor; benutzerdefinierte Callbacks, Ausnahmelogs und Debug-Proxys geben Header leichter preis. Vor dem Aktivieren die Maskierungseinstellungen prüfen.

Muss nach einer Key-Rotation Code geändert werden?

Werden Keys aus Umgebungsvariablen oder einem Secret-Manager gelesen, meist nicht; nur Wert aktualisieren und neu starten bzw. deployen. Sind Keys fest im Code, Notebook oder Image verdrahtet, zuerst auf externe Injektion umstellen und dann rotieren.

Nächste Schritte

Die Key-Verwaltung in LangChain lässt sich in vier Sätzen zusammenfassen: Keys gehören dem Modellanbieter, nicht dem Framework; lokal .env, in Produktion ein Secret-Manager; Keys nach Umgebung und Zweck trennen; bei der Rotation erst neu anlegen, dann den alten widerrufen. Für einen einheitlichen Mehrmodell-Zugang und Verbrauchs- sowie Kontingentverwaltung pro Key können Sie sich im ZSQH AI Gateway registrieren; Modelle und Preise entnehmen Sie den Modellpreisen.

Weiterlesen: