API-middeling configureren in veelgebruikte frameworks: van SDK tot Dify

Verzamel eerst de drie waarden

Ongeacht het framework: verzamel eerst deze drie waarden. De rest van de configuratie is slechts invullen.

• Endpoint: https://api.llmzhongzhuan.com/v1. Behoud /v1, maar voeg /chat/completions niet toe; de SDK voegt dit zelf toe.
• API-sleutel: wordt direct na registratie met e-mail en wachtwoord op de sleutelpagina weergegeven. Elk account heeft er één; je kunt hem resetten, waarna de oude direct ongeldig wordt.
• Modelnaam: alleen uncensored. Controleer met GET /v1/models.

Onthoud ook deze grenzen: totale contextlengte van 100.000 tokens, een standaard max_tokens van 2048 (maximaal 32.000) en 300 verzoeken per minuut per sleutel. Deze getallen kom je terug in de parameterconfiguratie.

Opmaak van omgevingsvariabelen

Het hardcoden van de API-sleutel is de meest voorkomende oorzaak van fouten. We raden aan alleen omgevingsvariabelen te gebruiken die tijdens de deploy door een container of secretsbeheer worden ingelezen. We gebruiken API_KEY en API_BASE in alle voorbeelden.

复制# 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"

Als je een .env-bestand gebruikt, voeg het dan toe aan .gitignore. De officiële Python SDK leest standaard OPENAI_API_KEY en OPENAI_BASE_URL. Je kunt deze namen gebruiken of expliciete parameters in de constructor gebruiken. Expliciete parameters voorkomen storing door oude omgevingsvariabelen.

OpenAI Python SDK en Node SDK

Python vereist v1+ van openai, Node.js vereist v4+. Het verschil is syntaxis; geef endpoint en sleutel op bij clientconstructie. Eerst Python niet-streaming met usage-uitvoer voor kostencontrole:

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

Node.js voorbeeld met streaming, ideaal voor de typemachine-effecten op de frontend. Aan het einde van een streaming-verzoek voegt de server automatisch een fragment met usage toe; je hebt geen extra parameters nodig:

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

Het Node-voorbeeld gebruikt top-level await, dus je hebt een .mjs-bestand nodig of stelt "type": "module" in package.json in. Ondersteunt je runtime dit niet? Pak de code dan in een async-functie.

LangChain: base_url voor ChatOpenAI

LangChain vereist geen speciale adapter. Gebruik ChatOpenAI uit langchain_openai en wijs base_url naar het 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)

Twee kleine herinneringen. Eerst: stel max_tokens en timeout expliciet in, want de standaardwaarden voldoen niet altijd aan je behoeften. Tweed: als je function calling gebruikt, ondersteunt onze site OpenAI-tools. Gebruik LangChain's bind_tools en verwerk de streaming-response in blokken via stream().

LlamaIndex: OpenAILike

De ingebouwde OpenAI-klasse van LlamaIndex controleert of de modelnaam in de officiële lijst staat. Gebruik bij aangepaste modellen OpenAILike uit llama-index-llms-openai-like. Deze klasse voert deze controle niet uit en gebruikt andere parameter- en adresnamen (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("用一句话解释什么是幂等请求。"))

is_chat_model=True is cruciaal voor het gebruik van de chat-API. Stel context_window in op 100.000 om ongewenste truncatie van documenten te voorkomen.

Dify: leverancier "OpenAI-API-compatible"

Dify is een visueel platform zonder code dat via formulieren wordt geconfigureerd. De interface kan per versie iets verschillen, maar de stappen zijn hetzelfde:

1. Ga naar "Instellingen", open "Modelleverancier" en selecteer "OpenAI-API-compatible" in de lijst. Klik op "Model toevoegen".
2. Selecteer modeltype "LLM" en vul uncensored in als modelnaam.
3. Vul je sleutel in bij API Key en https://api.llmzhongzhuan.com/v1 bij API endpoint URL.
4. Vul bij modelcontextlengte 100000 in en bij maximale tokenlimiet 32000.
5. Schakel function calling in als je tools in workflows wilt gebruiken; houd streaming ingeschakeld.
6. Sla op, maak een eenvoudige chat-applicatie aan, selecteer het zojuist toegevoegde model en stuur een bericht om te controleren of de respons correct is.

Het platform voert soms een testverzoek uit bij het opslaan. Mislukt dit, controleer dan op extra paden of spaties in de sleutel. Bij container-deployment: zorg dat de container toegang heeft tot het externe domein.

Parameters en deploy-configuratie voor productie

Het lukt draaien van het framework is pas het begin. Controleer de volgende parameters voor je live gaat, want ze bepalen de kosten en de foutmarge.

• max_tokens: standaard 2048; verhoog dit expliciet voor lange outputs tot het maximum van 32,000. Let op: input plus output mag niet meer dan 100,000 bedragen, anders krijg je een 400-fout.
• timeout: lange outputs duren langer. Stel de read-timeout bij streaming in op minimaal 60 seconden; bij niet-streaming schat je de timeout op basis van de langste verwachte output.
• temperature / top_p / stop: Standaard samplingparameters worden doorgegeven. Ingestelde waarden in het framework worden direct toegepast zonder extra schakelaars.
• Concurrency: 300 verzoeken/min per sleutel. Bij meerdere instanties met dezelfde sleutel wordt de limiet samengerekend. Plan niet per instantie op 300.
• Retry: Framework-retries zijn vaak alleen voor netwerkfouten. Voor 429 en 503 moet je zelf backoff toevoegen; zie de sectie over stabiliteit voor de implementatie.

Bij deploy naar containers geldt dezelfde logica: geen sleutels in de image, maar injectie door de orchestrator bij het opstarten. Hier is de minimale compose-configuratie:

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

In Kubernetes vervang je dit door een Secret-referentie. Het principe blijft hetzelfde. Gebruik voor verschillende omgevingen (dev, staging, prod) aparte accounts of sleutels. Zo voorkom je dat een lek of leeg saldo in één omgeving de productie beïnvloedt. Omdat elk account maar één sleutel heeft, zijn meerdere accounts aan te raden voor multi-env setups, elk met een vooraf opgeladen tegoed.

Tot slot: logging. Veel frameworks loggen in debug-modus volledige request headers, inclusief Authorization. Schakel dit uit in productie of maskeer de sleutel in je logfilters. Log het usage-veld wel; dit helpt bij het controleren van de factuur en signaleert als prompts onverwacht langer worden.

Foutopsporing bij foutmeldingen

90% van de problemen tijdens de integratiefase zit op een paar plekken. Controleer in de volgende volgorde voor de snelste oplossing:

1. 401: De sleutel is leeg, er zijn spaties mee gekopieerd, of je gebruikt nog de oude sleutel na het resetten.
2. 404: Het adres is ingesteld op de root-path zonder /v1, of /chat/completions is een keer te veel toegevoegd.
3. 402: Foutcode no_credit betekent dat het saldo op is of de proefversie is verlopen; je moet prepaid tegoed opwaarderen.
4. 400: De meest voorkomende oorzaak is dat de invoer samen met max_tokens de 100.000 overschrijdt, of dat de request body groter is dan 8 MB.
5. 429 / 503: De eerste is een rate limit van 300 verzoeken per minuut, de tweede is upstream_busy. Wacht een paar seconden en probeer het opnieuw; zie stabiliteit voor meer informatie.

Een ander veel over het hoofd gezien probleem is de netwerkomgeving. Een bedrijfsnetwerk, proxysoftware of firewallregels kunnen ervoor zorgen dat de domeinnaam wel wordt opgelost, maar er geen HTTPS-verbinding tot stand kan worden gebracht. Dit uit zich in een lange wachttijd gevolgd door een time-out, in plaats van een duidelijke foutcode. Als dit gebeurt, probeer dan eerst /v1/models met curl vanaf dezelfde machine. Als dat werkt, ligt het probleem in de applicatielaag; als dat niet werkt, controleer dan de proxy en de firewall. Documenteer het probleemoplossingsproces in de teamdocumentatie, zodat nieuwe collega's bij de volgende integratie minder tijd kwijt zijn.

Als alle drie de waarden correct zijn maar het nog steeds misgaat, stuur dan eerst een verzoek met curl om frameworkproblemen uit te sluiten. Wil je weten wat de relay precies doet? Lees dan de relay-architectuur terug.