Configura l'API proxy nei framework comuni: da SDK a Dify

Raccogli i tre valori necessari

Indipendentemente dal framework, verifica di avere questi tre elementi prima di procedere con la configurazione.

• Endpoint: https://api.llmzhongzhuan.com/v1. Mantieni /v1 alla fine, ma non aggiungere /chat/completions: l'SDK lo aggiunge automaticamente.
• Chiave: visualizzata subito dopo la registrazione con email e password nella pagina di recupero chiave. Una chiave per account, resettabile; quella vecchia diventa immediatamente invalida.
• Nome del modello: unico, uncensored. Puoi verificarlo con GET /v1/models.

Ricorda questi limiti: contesto totale di 100.000 token, max_tokens predefinito 2048, massimo 32.000, 300 richieste al minuto per chiave. Questi numeri verranno usati ripetutamente nelle impostazioni dei parametri successive.

Sintassi delle variabili d'ambiente

Scrivere la chiave hardcoded nel codice è la causa più comune di incidenti. È consigliato leggere solo le variabili d'ambiente, iniettate dal container o dal gestore dei segreti. Gli esempi usano API_KEY e 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"

Se usi .env, aggiungilo a .gitignore. L'SDK Python legge OPENAI_API_KEY e OPENAI_BASE_URL. Puoi usare questi nomi o passarli esplicitamente nel costruttore. I parametri espliciti evitano interferenze da variabili residue sulla macchina.

SDK Python e Node.js di OpenAI

Python richiede openai v1+, Node v4+. La differenza è solo sintattica: passa endpoint e chiave alla creazione del client. Ecco un esempio Python non-streaming che stampa usage per verificare le deduzioni:

复制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'esempio Node usa lo streaming, il metodo più comune per l'effetto macchina da scrivere frontend. Il server invia automaticamente un frammento finale con usage senza parametri extra:

复制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'esempio Node usa top-level await: serve un file .mjs o "type": "module" in package.json. Se il runtime non lo supporta, incapsula il codice in una funzione async.

LangChain: base_url per ChatOpenAI

Non servono adapter speciali: usa ChatOpenAI dal pacchetto langchain_openai impostando base_url.

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

Due avvertenze: 1) Imposta esplicitamente max_tokens e timeout, i default potrebbero non adattarsi al tuo caso. 2) Per la chiamata di funzioni, usa bind_tools; per lo streaming, consuma i chunk dentro stream().

LlamaIndex: OpenAILike

La classe OpenAI di LlamaIndex verifica se il nome del modello è nella lista ufficiale, generando un errore per i modelli custom. Usa invece OpenAILike da llama-index-llms-openai-like: non fa questa verifica e usa api_base per l'endpoint.

复制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("用一句话解释什么是幂等请求。"))

Imposta is_chat_model=True per usare l'endpoint chat. Imposta context_window a 100000 per evitare che LlamaIndex tronchi il contesto a valori di default.

Dify: provider OpenAI-API-compatible

Piattaforme visuali come Dify non usano codice, ma configurano tramite form. L'interfaccia varia leggermente tra versioni, ma i passaggi sono gli stessi:

1. Vai su "Impostazioni" > "Fornitori di modelli", seleziona "OpenAI-API-compatible" e aggiungi un modello.
2. Tipo modello: "LLM". Nome modello: uncensored.
3. API Key: inserisci la tua chiave. API endpoint URL: https://api.llmzhongzhuan.com/v1.
4. Lunghezza contesto modello: 100000. Limite massimo token: 32000.
5. Abilita il supporto alla chiamata di funzioni se necessario nel workflow. Mantieni attivo lo streaming.
6. Salva, crea un'app chat semplice, seleziona il modello e invia un messaggio per verificare la risposta.

Dify potrebbe inviare una richiesta di test al salvataggio. Se fallisce, controlla errori nell'URL o spazi nella chiave. Se Dify è in un container, verifica che abbia accesso a internet.

Parametri da verificare prima del deploy

Far funzionare il codice è solo il primo passo. Verifica questi parametri per ottimizzare costi e affidabilità.

• max_tokens: default 2048, aumenta esplicitamente per output lunghi (max 32.000). Input + Output non devono superare 100.000 token, altrimenti errore 400.
• timeout: le richieste lunghe richiedono più tempo. Imposta il timeout di lettura a >60s per lo streaming, o stima il tempo massimo per il non-stream.
• temperature / top_p / stop: parametri standard passati direttamente al backend. Non servono switch aggiuntivi.
• Concorrenza: 300 richieste/min per chiave. Se più istanze condividono la chiave, il limite è aggregato. Non pianificare 300 richieste per istanza.
• Riprova: il retry del framework copre solo errori di rete. Per 429 e 503 aggiungi tu la backoff, come descritto nella sezione sulla stabilità.

Per i container, la logica è "nessuna chiave nell'immagine": inietta le variabili all'avvio. Ecco la configurazione minima per 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 usa un riferimento a Secret. Usa credenziali diverse per ambienti (dev, staging, prod) per isolare i rischi. Poiché ogni account ha una sola chiave, usa più account e ricarica il saldo per ciascuno.

Gestione log: in debug i log mostrano l'header Authorization. Disabilita il debug in produzione o maschera la chiave nei log. Salva il campo usage per conciliare le fatture e rilevare prompt inaspettati.

Ordine di risoluzione degli errori

Il 90% dei problemi di integrazione si concentra in pochi punti. Segui questo ordine per risolvere rapidamente:

1. 401: la chiave è vuota, è stato copiato uno spazio o si sta usando ancora la chiave vecchia dopo il reset.
2. 404: l'indirizzo punta alla radice senza /v1, oppure hai aggiunto una volta di troppo /chat/completions.
3. 402: il codice di errore è no_credit, il che significa che il saldo è esaurito o il credito di prova è scaduto; devi ricaricare il credito prepagato.
4. 400: la causa più comune è che l'input con max_tokens supera i 100.000 token, oppure il corpo della richiesta supera gli 8 MB.
5. 429 / 503: il primo indica un limite di richieste di 300 al minuto, il secondo è un upstream_busy; attendi qualche secondo e riprova. Per i dettagli, consulta la guida alla stabilità.

Un altro problema spesso trascurato è l'ambiente di rete. La rete aziendale, un software proxy o le regole del security group possono permettere la risoluzione del nome di dominio ma impedire la connessione HTTPS, causando un blocco prolungato seguito da timeout invece di un codice di errore esplicito. In questi casi, usa prima curl per accedere a /v1/models dalla stessa macchina: se la connessione va a buon fine, il problema è a livello applicativo; altrimenti, controlla il proxy e il firewall. Documenta la procedura di risoluzione dei problemi nel wiki del team: così i nuovi colleghi potranno integrarsi più velocemente la prossima volta.

Se i tre valori sono corretti ma fallisce, usa curl per escludere problemi del framework. Per capire cosa fa esattamente il proxy, leggi principi dell'API proxy.