Konfiguracja API pośredniego w popularnych frameworkach: od SDK po Dify

Zbierz trzy niezbędne wartości

Niezależnie od wybranego frameworka, najpierw upewnij się, że posiadasz te trzy elementy – reszta konfiguracji to tylko ich wpisanie.

• Endpoint: https://api.llmzhongzhuan.com/v1. Zachowaj /v1, ale nie dodawaj /chat/completions — SDK łączy ścieżkę automatycznie.
• Klucz API: Po rejestracji na stronie pobierania klucza wyświetla się od razu. Każdy kontroli ma jeden klucz. Można go zresetować; stary klucz traci ważność natychmiast.
• Nazwa modelu: Jedyna dostępna to uncensored. Możesz ją zweryfikować samodzielnie, wykonując GET /v1/models.

Zapamiętaj też limity: okno kontekstu to 100,000 tokenów, max_tokens domyślnie 2048, max 32,000. Limit zapytań to 300 na minutę na klucz. Te wartości wrócą w ustawieniach.

Składnia zmiennych środowiskowych

Najczęstszą przyczyną problemów jest wpisanie klucza na sztywno w kodzie. Zalecamy odczytywanie zmiennych środowiskowych, a ich wpisywanie w trakcie wdrażania przez kontenery lub menedżer haseł. Poniższe przykłady dla różnych frameworków używają zmiennych API_KEY i 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"

Jeśli używasz pliku .env, pamiętaj, aby dodać go do .gitignore. Oficjalny SDK Pythona domyślnie odczytuje OPENAI_API_KEY i OPENAI_BASE_URL. Możesz użyć tych nazw lub jawnie przekazać argumenty w konstruktorze. Jawne przekazywanie chroni przed interferencją starych zmiennych w środowisku, co ułatwia debugowanie.

OpenAI Python SDK i Node SDK

Wymagana jest wersja v1 pakietu openai dla Pythona oraz v4 dla Node.js. Różnica polega tylko na składni – przy tworzeniu klienta podajesz adres i klucz. Najpierw przykład nie-strumieniowego wywołania w Pythonie z wypisaniem usage, aby łatwo sprawdzić naliczenia:

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

Przykład w Node.js używa strumieniowania, co jest standardem dla efektu „maszyny do pisania” w interfejsach. Po zakończeniu strumienia serwer automatycznie wysyła fragment z usage, więc nie potrzebujesz dodatkowych parametrów:

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

Przykład w Node.js używa top-level await, więc wymagany jest plik .mjs lub ustawienie "type": "module" w package.json. Jeśli Twoje środowisko tego nie wspiera, opakuj kod w funkcję async.

LangChain: base_url w ChatOpenAI

W LangChain nie potrzebujesz dedykowanych adapterów. Użyj klasy ChatOpenAI z pakietu langchain_openai i wskaż parametr 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)

Dwie uwagi. Po pierwsze, jawnie ustaw max_tokens i timeout, ponieważ wartości domyślne mogą nie pasować do Twoich potrzeb. Po drugie, jeśli używasz wywoływanie funkcji w łańcuchu, strona obsługuje format narzędzi OpenAI, więc LangChain bind_tools działa poprawnie. W trybie strumieniowania konsumuj odpowiedzi po kawałkach w stream().

LlamaIndex: OpenAILike

Domyślna klasa OpenAI w LlamaIndex weryfikuje, czy model jest na oficjalnej liście, co powoduje błąd przy niestandardowych nazwach. Użyj zamiast tego OpenAILike z pakietu llama-index-llms-openai-like. Nie wykonuje on tej weryfikacji, a nazwa parametru adresu to 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("用一句话解释什么是幂等请求。"))

Kluczowe jest is_chat_model=True, które wymusza użycie interfejsu czatu zamiast starego interfejsu uzupełniania tekstu. Ustaw context_window na 100000, aby LlamaIndex nie przycinał dokumentów domyślnie przy kilku tysiącach tokenów.

Dify: dostawca OpenAI-API-compatible

Platformy wizualne jak Dify nie wymagają kodu, a konfiguracja odbywa się przez formularze. Teksty w interfejsie mogą się różnić w zależności od wersji, ale kroki są takie same:

1. Przejdź do „Ustawienia”, znajdź stronę „Dostawcy modeli”, wybierz „OpenAI-API-compatible” z listy i kliknij „Dodaj model”.
2. Wybierz typ modelu „LLM”, a w polu nazwa modelu wpisz uncensored.
3. W polu API Key wpisz swój klucz, a w API endpoint URL wpisz https://api.llmzhongzhuan.com/v1.
4. W polu długość kontekstu modelu wpisz 100000, a w polu maksymalna liczba tokenów wpisz 32000.
5. Jeśli chcesz używać wywoływanie funkcji w przepływie pracy, włącz opcję wsparcia dla wywoływania funkcji. Zostaw włączony strumieniowanie.
6. Po zapisaniu utwórz prostą aplikację czatu, wybierz właśnie dodany model i wyślij wiadomość, aby upewnić się, że odpowiedź jest poprawna.

Platforma może wysłać żądanie testowe przy zapisie. Jeśli się nie powiedzie, przyczyną jest zwykle nadmiarowa ścieżka w adresie lub spacje wokół klucza. Jeśli Dify działa w kontenerze, upewnij się, że kontener ma dostęp do zewnętrznych domen.

Parametry i konfiguracja wdrożenia przed uruchomieniem

Uruchomienie frameworka to tylko pierwszy krok. Przed wdrożeniem zweryfikuj poniższe parametry, ponieważ wpływają one na koszty i liczbę błędów.

• max_tokens: domyślnie 2048. Zwiększ jawnie dla długich odpowiedzi, maksymalnie do 32,000. Pamiętaj, że suma tokenów wejściowych i wyjściowych nie może przekroczyć 100,000, w przeciwnym razie otrzymasz błąd 400.
• timeout: żądania z długą odpowiedzią trwają dłużej. W trybie strumieniowania ustaw timeout odczytu na co najmniej 60 sekund, a w trybie nie-strumieniowym oszacuj go na podstawie maksymalnej długości odpowiedzi.
• temperature / top_p / stop: Te standardowe parametry próbkowania są przekazywane dalej. Wartości ustawione w frameworku zadziałają bezpośrednio, bez konieczności dodatkowych przełączników.
• Równoległe zapytania: Limit to 300 zapytań na minutę na klucz. Limit jest sumowany dla wielu instancji, nie planuj po 300 na każdą.
• Ponawianie: Domyślne mechanizmy ponawiania w frameworkach często dotyczą tylko błędów sieciowych. Dla 429 i 503 dodaj własne wykładnicze zwiększanie opóźnień (backoff), zgodnie z opisem w artykule o stabilności.

Podczas wdrażania w kontenerach zasada pozostaje ta sama: „nie przechowuj klucza w obrazie”. Poniżej minimalna konfiguracja w compose:

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

W Kubernetesie użyj Secretów, zasada się nie zmienia. Sugeruję przygotować różne konta lub klucze dla różnych środowisk (dev, staging, prod). Dzięki temu wyciek lub wyczerpanie salda w jednym środowisku nie wpłynie na produkcję. Ponieważ każde konto ma tylko jeden klucz, lepiej użyć wielu kont i doładować je.

Ostatni punkt to logi. Frameworki w trybie debugowania drukują pełne nagłówki z Authorization. Wyłącz tryb debugowania w produkcji lub wyczyść klucz w filtrze logów. Zapisuj pole usage, aby porównać rachunek i wykryć nagły wzrost długości promptu.

Kolejność diagnostyki przy błędach

90% problemów podczas fazy integracji koncentruje się w kilku miejscach. Najszybszą diagnostykę uzyskasz, stosując się do poniższej kolejności:

1. 401: Klucz API jest pusty, skopiowano go ze spacjami lub używasz starego klucza po jego zresetowaniu.
2. 404: Adres został zapisany jako ścieżka główna bez /v1 lub zawiera podwójne /chat/completions.
3. 402: Kod błędu to no_credit, co oznacza, że saldo się wyczerpało lub kredyt próbny wygasł — konieczne jest doładowanie przedpłaconego kredytu.
4. 400: Przyczyną jest przekroczenie 100 000 tokenów (input + max_tokens) lub przekroczenie 8 MB.
5. 429 / 503: Pierwszy to limit zapytań (300 na minutę), drugi to upstream_busy. Poczekaj kilka sekund i spróbuj ponownie — szczegóły znajdziesz w praktykach stabilności.

Innym problemem jest sieć. Sieć firmowa, proxy lub reguły firewalla mogą zezwolić na rozwiązanie nazwy domeny, ale uniemożliwić połączenie HTTPS. Testuj endpoint /v1/models za pomocą curl. Jeśli działa, problem jest po stronie aplikacji; jeśli nie, sprawdź proxy i firewall.

Jeśli wartości są poprawne, wywołaj curl, aby wykluczyć problemy frameworku. Aby zrozumieć zasady działania proxy, przeczytaj ten artykuł.