Zyski:
- Potrafi opisać podstawową strukturę żądania API LLM (punkt końcowy, model, komunikaty, max_tokens)
- Rozumie różnicę pomiędzy rolami systemowymi, użytkownikami i asystentami oraz historią rozmów bezstanowych
- Potrafi czytać i interpretować pola (bloki treści, powód zatrzymania, użycie) zwróconej odpowiedzi
W poprzednich modułach korzystaliśmy ze sztucznej inteligencji z okna czatu. Jeśli jednak chcesz osadzić sztuczną inteligencję we własnym produkcie, automatyzacji lub przepływie pracy, interfejs czatu nie wystarczy; Trzeba połączyć się z modelem programowo, czyli za pomocą kodu lub narzędzia do automatyzacji. Nazwa tego mostu to API (Application Programming Interface, umowa, która pozwala dwóm programom komunikować się z pewnymi regułami). Po ukończeniu tej jednostki będziesz wiedział, co stanowi żądanie API LLM (Large Language Model), jakie role pełnią w wiadomościach i jak odczytać odpowiedź. Jest to fundament, na którym zostanie zbudowana reszta modułu.
Jak działa interfejs API?
Podstawowy przepływ w API jest następujący: wysyłasz żądanie w określonym formacie; Serwer zwraca odpowiedź w określonym formacie. W LLM jest to zwykle połączenie HTTP (HTTP: standardowy protokół przesyłania żądania-odpowiedzi w Internecie) do pojedynczego adresu (punktu końcowego, stałego adresu na serwerze obsługującym Twoje żądanie). Na przykład w interfejsie API do przesyłania wiadomości wszystkie żądania kierowane są pod jeden adres i są przenoszone w treści w formacie JSON (JavaScript Object Notation — format tekstowy składający się z par klucz/wartość, który może być odczytywany zarówno przez ludzi, jak i maszyny).
W żądaniu określasz przynajmniej te trzy rzeczy:
- Model: jakiego modelu będziesz używać (np. szybki i tani model lub mocny model).
- max_tokens: Maksymalna liczba tokenów (najmniejsza jednostka, w jakiej przetwarzany jest tekst, która zostanie szczegółowo przetworzona w następnej jednostce), jaką może wyprodukować model; tj. limit wyjściowy.
- wiadomości: lista wiadomości tworzących konwersację.
Krok po kroku: jak skonfigurować żądanie
- Przygotuj punkt końcowy i poświadczenia. Dodajesz swój klucz API (tajny ciąg znaków potwierdzający Twoją tożsamość) do żądania w nagłówku. Nigdy nie osadzasz klucza w kodzie; Bezpiecznym magazynowaniem zajmiemy się w bloku nr 9.
- Wybierz model i limit mocy. Lekki model + małe max_tokens do prostego zadania; Potężny model + większy limit dla złożonego zadania.
- Skonfiguruj listę wiadomości. List the system instruction, user message, and past rounds (if any).
- Wyślij żądanie i przeanalizuj odpowiedź. Przeczytaj treść tekstową, przyczynę zatrzymania i użycie tokenu ze zwróconego JSON.
Role wiadomości: system, użytkownik, asystent
Rozmowa składa się z wiadomości ułożonych w sekwencję, a każda wiadomość ma swoją rolę. Rola określa sposób, w jaki model traktuje ten tekst.
Rola
Kto pisze
Cel
systemu
Deweloper/operator
Stałe instrukcje, osobowość i zasady obowiązujące przez całą rozmowę
użytkownik
użytkownik końcowy
Bieżące pytanie lub dane wejściowe użytkownika
asystent
modelka
Odpowiedź wygenerowana przez model (i poprzednie odpowiedzi)
Rola systemowa jest dostępna jako osobne pole systemowe w treści żądania u większości dostawców; użytkownik i asystent są kolejno wyświetlani na liście wiadomości. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Jesteś asystentem wsparcia korporacyjnego. Podaj krótką, formalną i zweryfikowaną odpowiedź. Nie wymyślaj informacji, których nie jesteś pewien.", "messages": [ { "role": "user", "content": "Jak rozpocząć proces zwrotu?" } ]}
Mowa jest bezstanowa
Oto najczęstszy błędny pogląd: wywołania API LLM są bezstanowe — serwer nie zachowuje pamięci pomiędzy dwoma żądaniami. Model nie pamięta Twojej poprzedniej prośby. Jeśli konfigurujesz czat wielorundowy, przy każdej nowej prośbie będziesz musiał ponownie wysyłać poprzednie rundy. „Pamięć” modelu składa się z listy wysłanych przez Ciebie wiadomości.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Witam, nazywam się Deniz." }, { "role": "asystent", "treść": "Witam Deniz, w czym mogę pomóc?" }, { "role": "user", "content": "Właśnie powiedziałem swoje imię, pamiętasz?" } ]}
Prawidłowa odpowiedź na trzecią wiadomość zależy od wysłania obu poprzednich wiadomości. Jeśli go nie wyślesz, modelka nie będzie znała „Morza” i odpowie błędnie. Ma to również bezpośredni wpływ na koszt: im dłuższa rozmowa, tym większa lista, każde żądanie zużywa więcej tokenów.
Wskazówka: W przypadku długich rozmów podsumowywanie i przenoszenie starych rund (podsumowanie + kilka ostatnich rund) zamiast wysyłania całej historii zmniejsza koszty i zachowuje okno kontekstowe. Pogłębimy to w rozdziałach 6 i 11.
Przeczytaj odpowiedź
Kiedy model zwraca odpowiedź, otrzymujesz obiekt strukturalny, a nie zwykły tekst. Typowe obszary:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "asystent", "content": [ { "type": "text", "text": "Aby zainicjować zwrot, przejdź do strony „Moje zamówienia” na swoim koncie…” } ], „stop_reason”: „end_turn”, „usage”: { „input_tokens”: 47, „output_tokens”: 88 }}
- treść: sama odpowiedź; Jest to lista bloków treści. Pole tekstowe bloku tekstowego jest rzeczywistą odpowiedzią.
- stop_reason: Dlaczego model się zatrzymał. end_turn = naturalny koniec; max_tokens = utknął na limicie wyjściowym (odpowiedź może być niekompletna); odmowa = odmowa ze względów bezpieczeństwa. Twój kod powinien zawsze najpierw sprawdzić stop_reason.
- użycie: Numery tokenów wejściowych i wyjściowych. Stanowi podstawę śledzenia kosztów i limitów.
Uwaga: Jeśli stop_reason ma wartość max_tokens, odpowiedź nie jest zakończona. Traktowanie tego jako „udanej odpowiedzi” i pokazywanie użytkownikowi połowy tekstu to jeden z najczęstszych błędów w produkcji. Albo zwiększ max_tokens, albo użyj przesyłania strumieniowego.
Słaba zachęta/silna zachęta
To samo zadanie z dwoma różnymi monitami systemowymi:
# SŁABYJesteś asystentem. Odpowiedz na pytania.
# SILNYJesteś asystentem wsparcia korporacyjnego. Zasady: - Polegaj wyłącznie na informacjach zawartych w dostarczonym dokumencie polisy; Jeśli nie ma tego w dokumencie, powiedz „Nie mam tej informacji, kieruję ją do odpowiedniej jednostki”. - Odpowiedzi nie powinny przekraczać 3 zdań, być formalne i jasne. - Nie proś o podanie danych osobowych (numer identyfikacyjny TC, numer karty) i nie powtarzaj. - Nie zgaduj, kiedy nie jesteś pewien.
Potężna wersja; Definiuje zakres, formę, margines bezpieczeństwa i zachowanie w niepewności. Spójność wyników modelu wynika bezpośrednio z tej przejrzystości.
Trzy mini etui
Przypadek 1 — Bot wsparcia (pułapka bezpaństwowości). Zespół ds. handlu elektronicznego przeprowadził bota na żywo; Kiedy użytkownik powiedział „anuluj poprzednie zamówienie”, bot „zapomniał” numeru zamówienia. Powód: wysyłali każde żądanie tylko z ostatnią wiadomością. Rozwiązanie: dodali ostatnie 6 rund do listy wiadomości. Wynik: kontekst zachowany, ale ilość danych wejściowych na żądanie wzrosła z 40 do ~600 tokenów — lekcję dotyczącą kosztów omówimy w części 2.
Przypadek 2 – Niekompletne streszczenie umowy. Zespół prawny przygotowywał 10-stronicowy zarys umów; max_tokens: 300 pozostało na niskim poziomie, podsumowania ucinały się w połowie zdania. stop_reason za każdym razem wynosił max_tokens, ale nikt nie patrzył. zwiększono max_tokens do 1500 i dodano kontrolę stop_reason; Skrócona stawka sumaryczna spadła z 18% do 0%.
Przypadek 3 — Mieszanie ról. Zespół marketingowy zapisywał wszystkie instrukcje w wiadomości użytkownika, pozostawiając system pusty. Gdy dane wejściowe użytkownika były zmieszane z instrukcjami, model czasami wykonywał polecenie użytkownika, aby „zapomnieć o poprzednich zasadach”. Przenieśli do systemu stałe zasady; Oddzielenie danych wejściowych użytkownika od instrukcji znacznie zmniejszyło liczbę naruszeń zasad.
Typowe błędy
- Zapominanie o wysłaniu przeszłości: Uważa się, że modelka „nie pamięta”; mając na uwadze, że jest to bezpaństwowiec. Ty niesiesz kontekst.
- Nie patrząc na `stop_reason`: Odpowiedź zatrzymana za pomocą max_tokens jest uważana za zakończoną.
- Osadzanie instrukcji w `user`: Trwałe reguły w systemie; natychmiastowe wprowadzanie danych trafia do użytkownika. Mieszanie stwarza luki w zabezpieczeniach.
- Mylenie „treści” ze zwykłym ciągiem znaków: odpowiedzią jest lista bloków; przeczytaj pole tekstowe pierwszego bloku tekstowego, zweryfikuj jego typ przed pobraniem treści [0] za pomocą ślepego indeksu.
- Osadzanie klucza w kodzie: Użyj zmiennej środowiskowej (jednostka 9).
Deeper: Bloki treści i odpowiedzi wieloczęściowe
Zrozumienie, dlaczego pole treści w odpowiedzi jest listą, ma fundamentalne znaczenie dla zaawansowanych funkcji, z którymi spotkasz się później. Czasami model zwraca nie pojedynczy blok tekstu, ale kilka bloków: blok myślenia, po którym następuje blok tekstu; lub blok tekstu, po którym następuje blok użycia narzędzia. Dlatego ślepe liczenie treści [0] jako „odpowiedzi” jest kruche. Prawidłowe podejście polega na przejrzeniu listy i posortowaniu jej według typu: zbierasz zawartość tekstową bloków, których polem typu jest tekst, a inne typy (myślenie, narzędzie) traktujesz osobno.
To rozróżnienie oznacza w praktyce to, że można rejestrować rozumowanie modelu (jeśli istnieje) bez ujawniania go użytkownikowi, przekierowywać wywołania narzędzi do osobnej logiki i drukować jedynie rzeczywistą odpowiedź na ekranie. W miarę postępów modułu (szczególnie w jednostkach 4 i 11) zobaczysz, jak użyteczna jest ta struktura blokowa do sprawdzania poprawności i kierowania wynikami.
Kolejna praktyczna uwaga: możesz uzyskać dostęp do tego samego modelu z platform różnych dostawców (bezpośrednie API, za pośrednictwem dostawcy chmury). Chociaż adres punktu końcowego i format uwierzytelniania mogą się zmienić, podstawowe pojęcia, takie jak role komunikatów, bezstanowość i struktura odpowiedzi pozostają takie same. Zatem podstawy tego urządzenia mają zastosowanie niezależnie od platformy, z której korzystasz.
Podsumowując
Żądanie API LLM składa się z modelu, limitu wyjściowego i listy komunikatów; role (system, użytkownik, asystent) determinują zachowanie modelu. Wywołania są bezstanowe: przy każdym żądaniu przenosisz kontekst. Odpowiedź jest obiektem strukturalnym; Odczyt i interpretacja pól content, stop_reason i use to podstawa trwałości w produkcji.
Zadanie aplikacji
Wybierz zadanie z własnego zawodu (np. sortowanie przychodzącej poczty elektronicznej, tworzenie krótkich podsumowań). Na kartce papieru: (1) napisz zachętę systemową zawierającą 4-5 reguł, (2) skonfiguruj przykładową wiadomość użytkownika i 2-rundową historię, jeśli taka istnieje, (3) określ rozsądną wartość max_tokens i napisz uzasadnienie, (4) wypisz, które wartości stop_reason będziesz obsługiwał w zwróconej odpowiedzi i w jaki sposób.
lista kontrolna
- [ ] Potrafię policzyć trzy obowiązkowe części żądania (model, max_tokens, wiadomości).
- [ ] Potrafię wyjaśnić różnicę pomiędzy rolami systemowymi, użytkownikami i asystentami.
- [ ] Wiem, że rozmowy są bezpaństwowe i że muszę nieść przeszłość.
- Potrafię czytać i komentować treść [ ], przyczynę zatrzymania i pola użycia.
- [ ] Dzięki max_tokens mogę zauważyć i obsłużyć obciętą odpowiedź.