Gemini 4 Argon API: czat w Pythonie z natywnym strumieniowaniem

Rozmowa przez API Gemini 4 Argon korzysta z natywnej treści Gemini: contents, ról i parts. Pierwsze żądanie jest niewielkie. Trudniejsze jest poprawne zachowanie odpowiedzi przed wysłaniem kolejnego pytania. Odtworzenie tury modelu wyłącznie z widocznego tekstu może spowodować utratę podpisanej treści. Dodanie do historii pustej wiadomości oznaczającej ładowanie może z kolei unieważnić następne żądanie.

Ten poradnik korzysta z biblioteki standardowej Pythona i natywnego endpointu SeedRouter. Obejmuje czat tekstowy i strumieniowanie. Pełna dokumentacja API opisuje cały kontrakt parametrów; tutaj prześledzimy drogę od jednego żądania do działającej rozmowy.

Przed pierwszym żądaniem

Potrzebujesz Pythona 3, klucza API SeedRouter i wystarczającego salda konta. Przechowuj klucz w zmiennej środowiskowej o nazwie SEEDROUTER_API_KEY; nie umieszczaj go w kodzie źródłowym ani w pakiecie wysyłanym do przeglądarki. Każda wysłana wiadomość może generować opłaty. Przykład nie ponawia żądań automatycznie ani nie wywołuje kontynuacji.

ID modelu to gemini-4-argon, a model należy wskazać w ścieżce endpointu. Google opisuje ten format w przewodniku po natywnym generowaniu. SeedRouter używa uwierzytelniania Bearer, jak pokazano poniżej.

Wyślij jedno żądanie do API Gemini 4 Argon

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

Odpowiedź to sekwencja zdarzeń wysyłanych przez serwer, a nie pojedynczy dokument JSON. Każde zdarzenie data: zawiera natywny JSON Gemini. Widoczny tekst znajduje się w candidates[].content.parts[].text; niektóre części zawierają zamiast niego rozumowanie lub podpisy. usageMetadata może dotrzeć oddzielnie od tekstu, więc przeczytaj strumień do ostatniego zdarzenia, zanim uznasz odpowiedź za kompletną.

Ten celowo niewielki limit wyjścia służy wstępnej kontroli działania. Rozumowanie również go zużywa, dlatego odpowiedź może pozostać niepełna. Świadomie zwiększ go dla trudniejszych zadań; nie zamieniaj niepełnej odpowiedzi w niewidoczną pętlę ponowień.

Uruchom rozmowę z dwiema turami w Pythonie

Pobierz pełny przykład w Pythonie, zapisz go lokalnie i uruchom:

python3 gemini-4-argon-chat.py

Zapytaj „Explain a mutex in one sentence”, a potem „Give a Python example of that idea”. Skrypt czeka na twój wpis przed każdym żądaniem. Pusty wiersz kończy działanie. Podstawowa zasada budowania historii wygląda tak:

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

Skrypt do pobrania dostarcza także ustawienia generowania, analizuje ramki SSE, wypisuje wyłącznie tekst niebędący rozumowaniem i zapisuje historię tylko po otrzymaniu przyczyny zakończenia STOP z niepustymi parts. Błąd API, przerwany strumień lub pusta odpowiedź pozostawiają poprzednią historię bez zmian. Skrypt nie wysyła wiadomości ponownie bez powiadomienia.

Krótki fragment powyżej wyjaśnia strukturę danych; uruchom cały plik, aby uzyskać pełną obsługę żądań. Dla odpowiedzi bez strumieniowania odpowiednią operacją jest generateContent, a przykłady w dokumentacji pokazują cURL, Python, Node.js i Go.

Zachowuj natywne parts, a nie wskaźnik ładowania

Drugie żądanie powinno zawierać trzy rzeczywiste tury: pierwszą wiadomość użytkownika, ukończoną odpowiedź modelu i drugą wiadomość użytkownika. Komunikat „Myślę…” w interfejsie nie jest kolejną turą modelu.

Błąd taki jak contents.3.parts: Too small: expected array to have >=1 items oznacza, że czwarty element treści ma pustą tablicę parts. Indeksowanie zaczyna się od zera. Zanim zmienisz prompt lub model, sprawdź sposób budowania historii. Wskaźnik ładowania należy do stanu wyświetlania; nigdy nie powinien przyjmować postaci { "role": "model", "parts": [] } w żądaniu.

Zachowuj wszystkie zwrócone części w kolejności, w tym thoughtSignature i części oznaczone jako rozumowanie, nawet jeśli interfejs je ukrywa. Przewodnik Google po podpisach rozumowania wyjaśnia, dlaczego te pola o niejawnej strukturze muszą zostać zachowane w kolejnych turach. Nie edytuj, nie wymyślaj ani nie odtwarzaj podpisu. Przechowuj natywną historię oddzielnie od tekstu wyświetlanego w interfejsie.

Ta sama zasada zachowania treści dotyczy rozmów z narzędziami, ale wykonanie narzędzia i zwrócenie wyniku wymaga bardziej rozbudowanej pętli aplikacji. Ten przykład tekstowy nie implementuje takiej pętli i nie powinien być przedstawiany jako kompletny agent programistyczny.

Odczytuj zużycie i obsługuj zatrzymanie

Dla bezpośrednich żądań zachowuj ostatnie wartości zużycia zgłoszone w strumieniu. Nie sumuj powtarzanych wartości skumulowanych w obrębie jednego żądania. Zwykłe wejście to promptTokenCount minus cachedContentTokenCount; płatne wyjście obejmuje zarówno candidatesTokenCount, jak i thoughtsTokenCount. Poradnik cenowy wyjaśnia, jak przeliczyć te liczniki na budżet.

Ctrl+C zatrzymuje przykład bez wysyłania kolejnego żądania. Przerwanie lokalnego odczytu nie dowodzi, że zdalne generowanie nie zużyło tokenów. Jeśli strumień zakończy się przed otrzymaniem danych o zużyciu, sprawdź zapis użycia na koncie. Przykład zachowawczo wyklucza niepełną turę z przyszłej historii; przechowywanie częściowych odpowiedzi to osobna decyzja projektowa.

Long decode to jeszcze inny przypadek. Przyczyna zakończenia CONTINUATION wznawia pierwotne generowanie za pomocą tokenu kontynuacji; nie jest nową wiadomością użytkownika. Google wymaga pierwotnego żądania i najnowszego tokenu, bez dopisywania częściowego wyjścia do contents. Zobacz przewodnik po long decode. Ten skrypt wprowadzający zatrzymuje się zamiast implementować automatyczną kontynuację.

Co zostało zweryfikowane?

Podstawowe strumieniowanie tekstu przeszło lokalny test całego przepływu przez Playground SeedRouter. Parsowanie i zarządzanie historią w przykładzie są sprawdzane na syntetycznych strumieniach, w tym z podpisanymi częściami, pustymi odpowiedziami i przerwaniami. Te dane testowe weryfikują oprogramowanie; nie są dodatkowymi uruchomieniami modelu. Narzędzia, multimedia i kontynuacja nadal wymagają osobnych testów możliwości, zanim będzie można opisać je jako zweryfikowane integracje.

Pytania o API

Czy mogę zastąpić nazwę modelu OpenAI nazwą gemini-4-argon?

Sama zmiana nazwy nie konwertuje formatów wiadomości. Ten poradnik używa natywnych pól Gemini contents i parts. Sprawdź, czy klient obsługuje ten protokół oraz skonfigurowane uwierzytelnianie i endpoint.

Dlaczego odpowiedź jest pusta, mimo że zużyto tokeny?

Rozumowanie może wyczerpać limit wyjścia, a ustawienia bezpieczeństwa lub niepełne generowanie również mogą uniemożliwić pojawienie się widocznego tekstu. Sprawdź przyczynę zakończenia i zużycie. Nie wstawiaj pustej tury modelu i nie powtarzaj płatnego żądania automatycznie.

Czy kontekst miliona tokenów oznacza milion tokenów wyjścia?

Nie. Wejście, rozumowanie i wyjście współdzielą kontekst. Długie generowanie ma też limity na żądanie i może wymagać kontynuacji. Planuj budżet dla wspólnej sumy, a nie osobnych limitów wejścia i wyjścia.

Dodawaj funkcje, gdy rozmowa już działa

Zacznij od jednej kompletnej odpowiedzi, a następnie potwierdź, że druga tura otrzymuje pierwotną natywną treść. Dodając załączniki, narzędzia lub trwałe przechowywanie, oddzielaj historię API Gemini 4 Argon od stanu wyświetlania. Playground modelu i przewodnik po dostępie to kolejne kroki do interaktywnego użycia i poznania wymagań konta.