Migracja API: Rozwiązywanie typowych błędów integracji LLM

Nieprawidłowa konfiguracja adresu Base URL

Pierwszym punktem awarii jest niemal zawsze adres URL bazowy. Po zmianie dostawcy musisz zaktualizować punkt końcowy, do którego łączy się Twój SDK. Nieprawidłowy URL powoduje błąd 404 lub 403 jeszcze zanim ładunek opuści Twoją maszynę.

Upewnij się, że Twój klient wskazuje na poprawną domenę. Dla naszej usługi adres URL bazowy to https://api.apimigration.com/v1. Ten URL działa ze standardowymi SDK OpenAI, po prostu zmieniając base_url parametr.

• Sprawdź protokół (HTTPS vs HTTP).
• Sprawdź obecność ukośników na końcu w konfiguracji klienta.
• Potwierdź, że ścieżka wersji (/v1) pasuje do Twojej specyfikacji API.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

Ignorowanie limitów okna kontekstowego

Twój model ma sztywny limit 100,000 tokenów dla połączonego promptu i uzupełnienia. Jeśli go przekroczysz, API odrzuci żądanie lub wycisze ucięcie historii w zależności od implementacji. Zawsze śledź swoje zużycie tokenów, aby uniknąć osiągnięcia tej granicy.

Maksymalna ilość danych wyjściowych na żądanie wynosi 16,000 tokenów. Jeśli nie ustawisz max_tokens, domyślnie to 2 048 tokenów. Ta różnica jest znacząca w zadaniach generowania treści długich.

• Monitoruj całkowitą liczbę tokenów na żądanie.
• Ustaw max_tokens wyraźnie dla długich wyjść.
• Wdroż logikę okna przesuwającego dla bardzo długich rozmów.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Niepoprawna implementacja strumieniowania

Odpowiedzi strumieniowe wymagają specyficznej obsługi zdarzeń wysyłanych przez serwer (SSE). Jeśli traktujesz strumień jako pojedynczy obiekt JSON, Twój kod się zawiesi lub ulegnie awarii. Każdy fragment zawiera częściowe dane, a ostatni fragment zawiera statystyki użycia tokenów.

Czytaj strumień inkrementalnie. Przetwarzaj każde zdarzenie przy jego napływaniu. Zmniejsza to postrzegane opóźnienie dla użytkowników końcowych. Nie czekaj na całą odpowiedź przed przetwarzaniem.

• Otwórz połączenie i czytaj linia po linii.
• Parsowanie data: linie jako JSON.
• Obsługuj [DONE] poprawnie zasygnalizować.

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell the story in second person."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Pominięcie limitów szybkości

Nasz API obsługuje 300 żądań na minutę na klucz. Jeśli Twoja aplikacja generuje szczytowe obciążenie, otrzymasz błędy 429 Too Many Requests. Musisz zaimplementować backoff wykładniczy, aby obsłużyć te błędy w sposób graceful.

Żądania równoległe są również ograniczone do 8 jednocześnie na klucz. Przekroczenie tego limitu może spowodować wyczerpanie puli połączeń. Śledź ściśle swoje równoległe połączenia.

• Zaimplementuj wykładnicze zwalnianie dla błędów 429.
• Ogranicz równoczesne połączenia do 8.
• Użyj wzorca circuit breaker przy dużym obciążeniu.

Copyimport OpenAI from "openai";

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

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

Zakładając standardowe formaty JSON

Mimo że stosujemy formaty kompatybilne z OpenAI, założenia mogą zepsuć Twoją integrację. Upewnij się, że żądasz json_object w response_format if you need strict JSON. Without this, the model may return markdown or plain text.

Przeanaluj odpowiedź dokładnie. Zweryfikuj strukturę JSON przed jej użyciem. Zapobiega to błędom czasu wykonania w usługach downstream.

• Ustaw response_format do {"type": "json_object"}.
• Zweryfikuj JSON przed parsowaniem.
• Obsługuj nieprawidłowe odpowiedzi w sposób elegancki.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

Ignorowanie obsługi błędów

API mogą zawieść. Występują timeouty sieciowe, błędy serwera i nieprawidłowe payloady. Twój kod musi obsługiwać te błędy bez awarii. Zapisuj szczegóły błędów w logach w celu debugowania.

Sprawdź kod błędu i komunikat. Ponów próbę przy błędach przejściowych. Zakończ szybko przy błędach trwałych. To rozróżnienie oszczędza czas i zasoby.

• Loguj kody błędów i komunikaty.
• Ponów próbę przy błędach 5xx z backoffem.
• Szybko testuj błędy 4xx.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Płatność i problemy z rotacją kluczy

Nasze API opiera się na kredytach zaliczkowych w kryptowalucie. Kredyty nie wygasają. Jeśli zabraknie środków, zapytania nie zostaną zrealizowane. Monitoruj swoje saldo i doładuj je, zanim spadnie do zera.

Każde konto ma jeden aktywny klucz. Wygenerowanie nowego klucza natychmiast unieważnia stary. Upewnij się, że wdrożenie aktualizuje klucz atomowo, aby uniknąć przestojów.

• Monitoruj regularnie saldo kredytowe.
• Zaktualizuj klucze atomowo.
• Zaktualizuj wszystkie wystąpienia jednocześnie.

Copyimport OpenAI from "openai";

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

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

Podsumowanie najlepszych praktyk

Sukces migracji zależy od uwagi na szczegóły. Zweryfikuj swój adres URL bazowy. Szanuj limity kontekstu. Obsługuj strumieniowanie poprawnie. Zarządzaj limitami szybkości. Waliduj JSON. Obsługuj błędy. Zarządzaj płatnościami i kluczami. Postępowanie zgodnie z tymi krokami zapewnia płynne przejście.

Przetestuj swoją integrację dokładnie przed uruchomieniem. Użyj kredytu próbnego, aby zweryfikować swoją konfigurację. Zapobiega to kosztownym przestojom w produkcji.

• Zweryfikuj bazowe adresy URL.
• Szanuj limity kontekstu.
• Obsługuj strumieniowanie poprawnie.
• Zarządzaj limitami szybkości.
• Zweryfikuj JSON.
• Obsługuj błędy.
• Zarządzaj płatnościami i kluczami.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'