Duże modele językowe o otwartych wagach zmieniły sposób, w jaki zespoły inżynierskie myślą o infrastrukturze AI. W przeciwieństwie do zamkniętych API, gdzie dostawca kontroluje sprzęt, wagi modelu i harmonogram wydawniczy, modele open-weight oddają te decyzje w Twoje ręce. Sam wybierasz, gdzie model będzie działał, jak będzie dostrajany i kiedy — o ile w ogóle — zaktualizujesz go do nowszego checkpointu. Taki poziom kontroli jest potężny, ale oznacza również, że praca związana z integracją spoczywa bezpośrednio na Twoich barkach.

Jeśli korzystasz dotychczas z zarządzanych API, takich jak GPT-4 od OpenAI czy Claude od Anthropic, dobra wiadomość jest taka, że wielu dostawców hostingu modeli open-weight i silników wnioskowania (inference engines) posługuje się obecnie tym samym językiem: HTTP POST, payloady JSON i uwierzytelnianie za pomocą tokena bearer. Mechanika wydaje się znajoma, ale szczegóły mają większe znaczenie, ponieważ to Ty, a nie dostawca, odpowiadasz za niezawodność, kontrolę kosztów i kształtowanie zachowań modelu.

Podstawy wywołania API

W swojej istocie integracja opiera się na żądaniu POST. Uwierzytelniasz się za pomocą standardowego tokena bearer w nagłówku Authorization. Body żądania to obiekt JSON, a jego najważniejszym polem jest tablica messages. Tablica ta podąża za znanym formatem czatu: naprzemienne role system, user i assistant.

Oto jak w praktyce wygląda minimalna struktura żądania:

  • Ustaw nagłówek Authorization na Bearer <your-token>.
  • Wyślij payload JSON zawierający co najmniej identyfikator model oraz listę messages.
  • Uwzględnij max_tokens i temperature, jeśli chcesz mieć kontrolę nad determinizmem lub kreatywnością odpowiedzi.

Odpowiedź zwraca tablicę choices oraz obiekt usage. Nie ignoruj bloku usage. Zawiera on pola prompt_tokens, completion_tokens oraz sumę całkowitą. Jeśli stosujesz self-hosting, jest to sygnał informujący o tym, czy dana interakcja z użytkownikiem jest kosztowna. Jeśli płacisz zewnętrznemu dostawcy wnioskowania, są to Twoje dane rozliczeniowe. W obu przypadkach loguj te dane od pierwszego dnia.

Streaming i dlaczego warto go używać

Nikt nie lubi wpatrywać się w spinner ładowania przez trzy sekundy, zanim pojawi się jakikolwiek blok tekstu. Streaming rozwiązuje ten problem. Zamiast czekać, aż model ukończy całe generowanie, serwer wysyła tokeny w miarę ich tworzenia. Twój klient otrzymuje zdarzenia Server-Sent Events lub odpowiedzi HTTP typu chunked i może wyświetlać słowa w momencie ich napływania.

Włącz streaming, ustawiając flagę stream: true w swoim payloadzie JSON. Po stronie klienta będziesz zazwyczaj parsuć strumień linia po linii, szukając prefiksów data:. Jeśli połączenie zostanie przerwane w trakcie strumieniowania, bądź gotowy na ponowne połączenie lub powrót do ponowienia próby bez streamingu. Postrzegane opóźnienie Twojej aplikacji czatu drastycznie spada, a użytkownicy mają wrażenie, że system „myśli” razem z nimi, zamiast przetwarzać ich żądanie w trybie wsadowym.

Function Calling w rzeczywistych procesach pracy

Model, który zwraca jedynie czysty tekst, jest użyteczny, ale model, który potrafi wywoływać narzędzia, jest znacznie bardziej przydatny. Function calling pozwala zdefiniować schemat JSON opisujący dostępne operacje — np. search_orders lub update_profile — a model decyduje, kiedy ich użyć. Zamiast zadawać użytkownikowi pytanie pomocnicze, model generuje ustrukturyzowane wywołanie funkcji z argumentami wyodrębnionymi z rozmowy.

Na przykład, jeśli użytkownik zapyta: „Jakie było moje ostatnie zamówienie?”, Twój schemat może definiować funkcję get_recent_orders z parametrem limit. Model zwraca wywołanie narzędzia, Twój backend wykonuje zapytanie do bazy danych, a następnie przekazujesz wynik z powrotem do modelu jako wiadomość z odpowiedzią funkcji. Model syntetyzuje wówczas odpowiedź w języku naturalnym.

Aby to zaimplementować:

  • Dostarcz tablicę tools lub functions w swoim payloadzie.
  • Zdefiniuj każde narzędzie za pomocą name, description oraz schematu parameters.
  • Sprawdź odpowiedź pod kątem sygnału tool-calls finish reason lub podobnego wskaźnika.
  • Wykonaj funkcję w swoim backendzie z rygorystyczną walidacją. Nigdy nie ufaj surowym wynikom modelu, pozwalając im na niezweryfikowane (unsanitized) uderzenie do bazy danych.
  • Dołącz wynik funkcji do historii wiadomości i wyślij zapytanie uzupełniające, aby model mógł wygenerować ostateczną odpowiedź.

Ten wzorzec niweluje lukę między tekstem generatywnym a systemami deterministycznymi. Twoja sztuczna inteligencja może czytać kalendarze, odpytywać API lub wyzwalać webhooki bez konieczności sztywnego kodowania każdej gałęzi logiki.

Przygotowanie do środowiska produkcyjnego

Uruchamianie modeli open-weight na produkcji naraża Cię na te same scenariusze awarii, co każdy system rozproszony, plus kilka unikalnych. Wnioskowanie modelu jest intensywne obliczeniowo, a punkty końcowe (endpoints) mogą nie wytrzymać obciążenia. Oto jak zapewnić stabilność swojej aplikacji.

Błędy i ponawianie prób

  • 429 Too Many Requests: To sygnał limitowania liczby żądań (rate-limit). Zastosuj wykładniczy czas oczekiwania z jitterem (exponential backoff with jitter). Zacznij od krótkiego opóźnienia, podwajaj je przy kolejnych błędach 429 i ogranicz do kilku sekund, aby nie przeciążać serwera.
  • 5xx Server Errors: Są one zazwyczaj przejściowe, zwłaszcza jeśli kierujesz żądania do puli procesorów GPU. Ponawiaj próby, ale ustal twardy limit liczby podejść – trzy to powszechnie stosowana wartość domyślna.
  • 4xx Client Errors: Nie ponawiaj ich bezmyślnie. Błąd 400 oznacza, że Twój payload jest błędnie sformatowany, 401 oznacza, że Twój token jest nieprawidłowy, a 404 oznacza, że identyfikator modelu nie istnieje pod tym endpointem. Zamiast zapętlać się, napraw żądanie