Konfiguration der API-Weiterleitung in gängigen Frameworks: Vom SDK bis Dify

Sorge zuerst für die drei Werte

Egal welches Framework du nutzt: Stelle sicher, dass du über diese drei Werte verfügst. Die nachfolgende Konfiguration besteht im Wesentlichen aus dem Ausfüllen dieser Felder.

• Endpunkt-URL: https://api.llmzhongzhuan.com/v1. Achte darauf, dass das Ende /v1 erhalten bleibt, aber füge kein /chat/completions hinzu. Das SDK hängt dies automatisch an.
• Schlüssel: Er wird nach der Registrierung mit E-Mail und Passwort auf der Schlüssel erhalten-Seite sofort angezeigt. Jedes Konto hat genau einen Schlüssel. Du kannst ihn zurücksetzen; der alte Schlüssel wird sofort ungültig.
• Modellname: Es gibt nur einen: uncensored. Du kannst dies über GET /v1/models selbst überprüfen.

Merke dir außerdem folgende Grenzen: Das Kontextfenster umfasst insgesamt 100.000 Token. Der Standardwert für max_tokens beträgt 2048, das Maximum liegt bei 32.000. Pro Schlüssel sind 300 Anfragen pro Minute erlaubt. Diese Zahlen werden bei der Parametereinstellung wieder relevant.

Schreibweise der Umgebungsvariablen

Das Festcodieren des Schlüssels im Code ist eine häufige Fehlerquelle. Der empfohlene Ansatz ist das Auslesen von Umgebungsvariablen, die beim Deployment von Containern oder Key-Management-Systemen injiziert werden. Die folgenden Beispiele für verschiedene Frameworks verwenden die Variablen API_KEY und API_BASE.

复制# Linux / macOS：写进 ~/.zshrc 或 .env 加载脚本
export API_KEY="替换为你的密钥"
export API_BASE="https://api.llmzhongzhuan.com/v1"

# Windows PowerShell（仅当前会话）
$env:API_KEY = "替换为你的密钥"
$env:API_BASE = "https://api.llmzhongzhuan.com/v1"

Wenn du eine .env-Datei nutzt, vergiss nicht, sie in .gitignore aufzunehmen. Das offizielle Python SDK liest standardmäßig OPENAI_API_KEY und OPENAI_BASE_URL. Du kannst diese Variablennamen beibehalten oder die Parameter explizit im Konstruktor übergeben. Der Vorteil der expliziten Übergabe ist, dass alte, im System verbliebene Variablen nicht stören, was die Fehlersuche erleichtert.

OpenAI Python SDK und Node SDK

Für Python benötigst du die Version v1 oder höher des Pakets openai, für Node.js Version v4 oder höher. Der einzige Unterschied liegt in der Syntax. Beim Erstellen des Clients übergibst du einfach Endpunkt-URL und Schlüssel. Zuerst sehen wir die nicht-streamende Python-Anfrage, inklusive Ausgabe der usage-Daten zur Kostenkontrolle:

复制import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "写一条 20 字以内的发布公告标题。"}],
    max_tokens=100,
)
print(resp.choices[0].message.content)
print(resp.usage)

Das Node.js-Beispiel verwendet Streaming. Dies ist die gängigste Methode für den Typewriter-Effekt im Frontend. Am Ende der Streaming-Anfrage sendet der Server automatisch ein finales Chunk mit usage-Daten. Es werden keine zusätzlichen Parameter benötigt:

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.API_BASE ?? "https://api.llmzhongzhuan.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "列出三个命名服务端日志字段的好习惯。" }],
  stream: true,
  max_tokens: 300,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
process.stdout.write("\n");

Das Node.js-Beispiel verwendet Top-Level Await. Dafür benötigst du eine .mjs-Datei oder die Einstellung "type": "module" in der package.json. Falls deine Laufzeitumgebung dies nicht unterstützt, packe den Code in eine async-Funktion.

LangChain: base_url für ChatOpenAI

In LangChain ist kein spezieller Adapter erforderlich. Nutze einfach die Klasse ChatOpenAI aus dem Paket langchain_openai und verweise die Eigenschaft base_url auf deine API.

复制import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    temperature=0.7,
    max_tokens=500,
    timeout=60,
)

print(llm.invoke("把“服务已降级”改写成对用户友好的一句话。").content)

Zwei Hinweise: Erstens solltest du max_tokens und timeout explizit setzen, da die Standardwerte nicht immer zu deinem Use Case passen. Zweitens: Wenn du in einer Chain Function Calling nutzt, unterstützt unsere Seite OpenAI-kompatible Tools. Die LangChain-Funktion bind_tools funktioniert einwandfrei. Beim Streaming kannst du die Antworten im stream()-Aufruf chunkweise verarbeiten.

LlamaIndex: OpenAILike

Die eingebaute Klasse OpenAI in LlamaIndex prüft, ob der Modellname in der offiziellen Liste enthalten ist. Bei benutzerdefinierten Namen tritt ein Fehler auf. Nutze stattdessen OpenAILike aus dem Paket llama-index-llms-openai-like. Diese Klasse führt keine Prüfung durch. Die Benennung der Parameter unterscheidet sich: Die Endpunkt-URL heißt hier api_base.

复制import os
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    model="uncensored",
    api_base=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    is_chat_model=True,
    context_window=100000,
    max_tokens=500,
)

print(llm.complete("用一句话解释什么是幂等请求。"))

Die Einstellung is_chat_model=True ist entscheidend. Sie weist LlamaIndex an, den Chat-Endpunkt statt des alten Completion-Endpunkts zu nutzen. Setze context_window auf 100000. LlamaIndex schneidet deine Dokumente dann nicht fälschlicherweise bei den Standard-Tausenden von Token ab.

Dify: Anbieter „OpenAI-API-compatible“

Visuelle Plattformen wie Dify arbeiten nicht mit Code, sondern mit Konfigurationsformularen. Die Benutzeroberfläche variiert je nach Version leicht, aber die Schritte sind im Wesentlichen identisch:

1. Gehe zu „Einstellungen“, suche die Seite „Modellanbieter“ und wähle in der Liste „OpenAI-API-compatible“. Klicke auf „Modell hinzufügen“.
2. Wähle bei Modelltyp „LLM“. Gib bei Modellname uncensored ein.
3. Gib bei API Key deinen Schlüssel ein. Trage bei API Endpoint URL https://api.llmzhongzhuan.com/v1 ein.
4. Gib bei Modell-Kontextlänge 100000 und bei maximalen Token-Limits 32000 ein.
5. Wenn du Function Calling in Workflows nutzen möchtest, aktiviere die Option zur Unterstützung von Function Calling. Halte das Streaming aktiviert.
6. Speichere die Einstellungen, erstelle eine einfache Chat-Anwendung, wähle das gerade hinzugefügte Modell aus und sende eine Nachricht, um die korrekte Antwort zu bestätigen.

Die Plattform sendet manchmal beim Speichern eine Test-Anfrage. Wenn dies fehlschlägt, hast du wahrscheinlich einen Pfad doppelt angegeben oder Leerzeichen im API-Schlüssel. Wenn du Dify in einem Container betreibst, stelle sicher, dass der Container externe Domänen erreichen kann.

Parameter und Deployment-Methoden vor dem Go-Live

Das Framework läuft, doch vor dem Live-Gang prüfe diese Parameter: Sie bestimmen Kosten und Fehlerquote.

• max_tokens: Standardwert 2048. Erhöhe diesen Wert explizit, wenn du lange Ausgaben benötigst. Das Maximum liegt bei 32.000. Beachte, dass die Summe aus Input- und Output-Token 100.000 nicht überschreiten darf, sonst erhältst du einen 400er-Fehler.
• timeout: Lange Ausgaben dauern länger. Im Streaming-Szenario solltest du den Read-Timeout auf über 60 Sekunden setzen. Im nicht-streamenden Modus schätze den Timeout basierend auf der maximalen Ausgabelänge.
• temperature / top_p / stop: Diese Standard-Sampling-Parameter werden durchgereicht. Werte, die du im Framework setzt, werden direkt wirksam. Es werden keine zusätzlichen Schalter benötigt.
• Concurrency: Pro Schlüssel sind 300 Anfragen pro Minute erlaubt. Wenn mehrere Service-Instanzen denselben Schlüssel nutzen, wird das Ratenlimit zusammengefasst. Plane nicht für jede Instanz separat 300 Anfragen.
• Retry: Framework-interne Retry-Mechanismen behandeln oft nur Netzwerkfehler. Für 429 und 503 musst du eigene Backoff-Strategien implementieren. Die Vorgehensweise findest du im Artikel zur Stabilität.

Beim Deployment in Containern gilt ebenfalls das Prinzip „Keine Schlüssel im Image“. Die Injektion erfolgt durch das Orchestrierungstool beim Start. Hier ist die Minimal-Konfiguration für Docker Compose:

复制# docker-compose.yml 片段
services:
  app:
    image: your-app:latest
    environment:
      API_BASE: https://api.llmzhongzhuan.com/v1
      API_KEY: ${API_KEY}   # 从宿主机环境或 .env 读取，不写进镜像

In Kubernetes ersetzt du dies durch eine Secret-Referenz. Das Prinzip bleibt gleich. Es empfiehlt sich, für verschiedene Umgebungen (Entwicklung, Staging, Produktion) separate Konten oder Schlüssel zu verwenden. So beeinträchtigt ein Schlüsselverlust oder ein erschöpftes Guthaben in einer Umgebung nicht die Live-Umgebung. Da jedes Konto nur einen Schlüssel hat, solltest du für mehrere Umgebungen mehrere Konten anlegen und für jedes Konto ein angemessenes Prepaid-Guthaben vorladen.

Abschließend zu den Logs: Viele Frameworks geben im Debug-Modus vollständige Request-Header aus, darunter auch Authorization. Deaktiviere solche Debug-Ausgaben in der Produktion oder filtere den Schlüssel in den Log-Filtern heraus. Das Protokollieren des usage-Felds ist eine gute Praxis. Es hilft dir, die Abrechnung zu überprüfen, und warnt dich frühzeitig, wenn die Prompts für eine bestimmte Funktion plötzlich länger werden.

Reihenfolge der Fehlerbehebung bei Problemen

Probleme während der Integrationsphase konzentrieren sich zu 90 % auf wenige Stellen. Die schnellste Fehlerbehebung erfolgt in der folgenden Reihenfolge:

1. 401: Der Schlüssel ist leer, beim Kopieren wurden Leerzeichen eingefügt oder du verwendest nach dem Zurücksetzen noch den alten Schlüssel.
2. 404: Die Adresse zeigt auf den Root-Pfad ohne /v1 oder du hast /chat/completions doppelt angegeben.
3. 402: Der Fehlercode no_credit bedeutet, dass dein Guthaben aufgebraucht ist oder das Testguthaben abgelaufen ist. Lade dein Prepaid-Guthaben auf.
4. 400: Häufige Ursache: Die Eingabe zusammen mit max_tokens überschreitet 100.000 Token oder der Request-Body ist größer als 8 MB.
5. 429 / 503: Die 429 bedeutet ein Ratenlimit von 300 Anfragen pro Minute. Die 503 bedeutet upstream_busy. Warte einige Sekunden und versuche es erneut. Siehe Stabilitätspraxis für Details.

Ein weiterer, oft übersehener Punkt ist die Netzwerkumgebung. Firmennetzwerke, Proxy-Software oder Sicherheitsregeln können dazu führen, dass die DNS-Auflösung erfolgreich ist, die HTTPS-Verbindung aber nicht aufgebaut wird. Das äußert sich durch ein Langes Warten und einen Timeout, ohne dass ein spezifischer Fehlercode ausgegeben wird. Teste in diesem Fall zuerst den Zugriff auf /v1/models mit curl auf demselben Gerät. Funktioniert es, liegt das Problem in der Anwendungsschicht. Wenn nicht, überprüfe Proxy und Firewall. Dokumentiere den Lösungsweg im Team-Wiki, damit neue Kollegen beim nächsten Setup weniger Zeit investieren müssen.

Wenn alle drei Werte korrekt sind und es dennoch fehlschlägt, führe zuerst eine direkte Anfrage mit curl aus, um Probleme im Framework auszuschließen. Wenn du verstehen möchtest, was die Weiterleitung genau tut, lies den Artikel Prinzip der Weiterleitung.