Configuration de l’API de transit dans les frameworks courants : du SDK à Dify

Préparez les trois valeurs

Quel que soit le framework, commencez par rassembler ces trois éléments. La configuration consistera ensuite à les remplir.

• URL de l’endpoint : https://api.llmzhongzhuan.com/v1. Conservez le suffixe /v1, mais n’ajoutez pas manuellement /chat/completions ; le SDK se charge de l’assemblage.
• Clé API : affichée immédiatement après l’inscription sur la page d’obtention de clé avec votre email et mot de passe. Chaque compte dispose d’une seule clé, qui peut être réinitialisée (l’ancienne devient alors invalide).
• Nom du modèle : il n’y en a qu’un seul, uncensored. Vous pouvez le vérifier via GET /v1/models.

Retenez également ces limites : la longueur totale de la fenêtre de contexte est de 100,000 tokens, le max_tokens par défaut est de 2048 (maximum 32,000), et chaque clé API est soumise à une limite de débit de 300 requêtes par minute. Ces chiffres seront réutilisés dans la section des paramètres.

Syntaxe des variables d’environnement

La cause la plus fréquente des incidents est la clé codée en dur. Il est recommandé de lire uniquement les variables d’environnement et de les injecter via le conteneur ou un gestionnaire de secrets. Les exemples ci-dessous utilisent API_KEY et 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"

Si vous utilisez un fichier .env, ajoutez-le à votre .gitignore. Le SDK Python officiel lit par défaut OPENAI_API_KEY et OPENAI_BASE_URL. Vous pouvez conserver ces noms ou passer explicitement les paramètres dans le constructeur. Cette dernière méthode évite les conflits avec des variables résiduelles et simplifie le débogage.

SDK Python et SDK Node.js OpenAI

Python nécessite v1+ de openai, Node v4+. La seule différence est syntaxique : passez l'URL et la clé à la construction du client. Voici un appel non-streaming Python avec affichage de l'usage :

复制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)

L’exemple Node.js utilise le streaming, courant pour l’effet « machine à écrire » côté client. Le serveur envoie automatiquement un dernier chunk avec l’usage à la fin de la requête, sans paramètre supplémentaire :

复制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");

L’exemple Node.js utilise un top-level await. Il nécessite un fichier .mjs ou la configuration "type": "module" dans package.json. Si votre environnement ne le supporte pas, enveloppez le code dans une fonction async.

LangChain : base_url pour ChatOpenAI

Aucun adaptateur spécifique n’est nécessaire. Utilisez la classe ChatOpenAI du package langchain_openai et pointez le paramètre base_url vers votre endpoint.

复制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)

Deux remarques : 1) Définissez explicitement max_tokens et timeout, car les valeurs par défaut peuvent ne pas convenir à votre cas d’usage. 2) Pour l’appel de fonctions, nous supportons le format OpenAI ; LangChain bind_tools fonctionne correctement. En streaming, consommez les chunks via stream().

LlamaIndex : OpenAILike

La classe OpenAI de LlamaIndex vérifie la liste officielle des modèles. Pour les modèles personnalisés, utilisez OpenAILike de llama-index-llms-openai-like avec l'endpoint 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("用一句话解释什么是幂等请求。"))

Le paramètre is_chat_model=True est crucial : il force l’utilisation de l’endpoint de chat plutôt que de l’ancien endpoint de complétion. Définissez context_window à 100 000 pour éviter que LlamaIndex ne tronque vos documents selon la valeur par défaut (quelques milliers de tokens).

Dify : fournisseur OpenAI-API-compatible

Dify est une plateforme visuelle qui utilise des formulaires plutôt que du code. L’interface peut varier légèrement selon les versions, mais les étapes restent identiques :

1. Allez dans « Paramètres », puis « Fournisseurs de modèles ». Sélectionnez « OpenAI-API-compatible » dans la liste et cliquez sur « Ajouter un modèle ».
2. Type de modèle : « LLM ». Nom du modèle : uncensored.
3. Clé API : saisissez votre clé. URL de l’endpoint : https://api.llmzhongzhuan.com/v1.
4. Longueur de la fenêtre de contexte : 100 000. Max tokens : 32 000.
5. Pour l’appel de fonctions dans les workflows, activez l’option correspondante. Gardez le streaming activé.
6. Créez une application de chat simple, sélectionnez le modèle ajouté et envoyez un message pour vérifier le retour.

La plateforme effectue parfois une requête de sondage à la sauvegarde. Si cela échoue, vérifiez l’URL (chemin en trop) ou la clé (espaces en trop). Si Dify est déployé dans un conteneur, assurez-vous que celui-ci a accès au domaine externe.

Paramètres et déploiement à vérifier avant la mise en production

Le fait que le framework fonctionne n’est que la première étape. Vérifiez les paramètres suivants avant la mise en production, car ils impactent le coût et le taux d’échec.

• max_tokens : 2048 par défaut. Augmentez-le explicitement pour les longs textes (max 32 000). Attention : la somme des tokens d’entrée et de sortie ne doit pas dépasser 100 000, sinon une erreur 400 est renvoyée.
• timeout : Les requêtes générant de longs textes sont plus lentes. En streaming, définissez un timeout de lecture d’au moins 60 secondes. En non-streaming, estimez-le selon la longueur maximale de sortie.
• temperature / top_p / stop : Ces paramètres standard sont transmis tels quels. Les valeurs définies dans le framework s’appliquent directement.
• Requêtes simultanées : Limite de débit de 300 requêtes par minute et par clé. Si plusieurs instances partagent la même clé, la limite est agrégée. Ne planifiez pas 300 requêtes par instance.
• Réessai : les mécanismes de réessai intégrés aux frameworks ciblent souvent uniquement les erreurs réseau. Pour les 429 et 503, vous devez ajouter une logique de backoff. Consultez la section sur la stabilité pour la syntaxe.

Pour le déploiement en conteneur, appliquez le même principe : ne mettez pas la clé dans l’image. Injectez-la au démarrage via l’outil d’orchestration. Voici la configuration minimale pour Docker Compose :

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

Dans Kubernetes, remplacez-les par une référence à un Secret, le principe restant identique. Nous recommandons également de préparer des comptes ou des clés distincts pour chaque environnement (développement, préproduction, production). Ainsi, une fuite de clé ou un épuisement du crédit sur un environnement n’affectera pas la production. Comme chaque compte ne dispose que d’une seule clé, il est préférable d’associer plusieurs comptes à plusieurs environnements et de précharger un solde suffisant pour chacun.

Enfin, la journalisation. Les modes debug affichent souvent les en-têtes complets, y compris Authorization. Désactivez ces logs en production ou masquez la clé. Enregistrez le champ usage : cela permet de vérifier la facturation et de détecter si un prompt a soudainement augmenté en taille.

Ordre de débogage en cas d’erreur

90 % des problèmes d’intégration se concentrent sur quelques points. Vérifiez dans l’ordre suivant pour résoudre les erreurs rapidement :

1. 401 : La clé est vide, des espaces ont été copiés, ou vous utilisez encore l'ancienne clé après la réinitialisation.
2. 404 : L'adresse pointe vers le chemin racine sans /v1, ou /chat/completions a été ajouté deux fois.
3. 402 : Le code d'erreur no_credit indique que le solde est épuisé ou que le crédit d'essai gratuit a expiré ; vous devez recharger votre crédit prépayé.
4. 400 : La cause courante est que la somme de l'entrée et de max_tokens dépasse 100 000, ou que le corps de la requête dépasse 8 Mo.
5. 429 / 503 : Le premier correspond à une limite de débit de 300 requêtes par minute, le second à un upstream_busy. Attendez quelques secondes et réessayez ; consultez la section Stabilité pour les détails.

Un autre problème souvent négligé concerne l'environnement réseau. Le réseau d'entreprise, les logiciels proxy ou les règles de groupe de sécurité peuvent permettre la résolution du nom de domaine tout en empêchant l'établissement d'une connexion HTTPS, ce qui se traduit par un blocage prolongé suivi d'un délai d'attente, plutôt que par un code d'erreur explicite. Dans ce cas, testez d'abord l'accès à /v1/models depuis la même machine avec curl : si la connexion réussit, le problème se situe au niveau de l'application ; sinon, vérifiez le proxy et le pare-feu. Notez la procédure de diagnostic dans la documentation de l'équipe pour faciliter l'intégration des nouveaux collègues.

Si les trois valeurs sont correctes mais que l’échec persiste, effectuez d’abord une requête directe via curl pour écarter un problème lié au framework. Pour comprendre ce que fait exactement le relais, consultez la section Principe du relais.