API Gemini у Python: той самий безстановий цикл із ролями моделей та об’єктами чату.

Після OpenAI та Claude Gemini від Google є третім постачальником, який дотримується такої ж схеми: безстановий кінцевий пункт, розмова, позначена роллю, та повна історія, яка надсилається з кожним запитом. Gemini додає до цього ще одну приємну особливість у своїй номенклатурі.

Перейменування, а не переробка

Структура розмови у Gemini збігається зі структурою у OpenAI та Claude, за винятком двох перейменувань. Роль асистента тепер називається model. Ця назва, мабуть, є більш чесною, адже „асистент“ натякає на певну персону, тоді як model просто вказує на те, що текст походить з моделі. Вона займає ту саму позицію у списку. Системний запит стає system_instruction та передається через об’єкт конфігурації, а не у списку повідомлень. Це є розвитком ідеї „системи окремо“ від Claude на ще один рівень.

Список повідомлень доступний під іменем contents. Кожен етап у ньому містить parts, адже Gemini роботизовано обробляє текст, зображення та аудіо. При чаті з простим текстом усе це не видно: входять рядки, а вихідним є resp.text.

Одне попередження щодо бібліотек перед наведенням коду. Протягом років Google випустив кілька пакетів для Python, і старі навчальні матеріали сповнені застарілими імпортами, такими як google-generativeai та інструменти з епохи Bard. Текущим офіційним SDK є google-genai, який імпортується за допомогою from google import genai, і саме його використовують тут.

Налаштування та один етап

Встановіть його за допомогою pip install google-genai, створіть ключ у Google AI Studio та експортуйте його як GEMINI_API_KEY. Клієнт отримує ключ з середовища, тому в коді він ніколи не з’являється.

# current official SDK: pip install google-genai
from google import genai
from google.genai import types

client = genai.Client()  # key from env

resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Why does Gemini name the reply "
             "role 'model', not 'assistant'?",
    config=types.GenerateContentConfig(
        system_instruction="Be concise.",
        temperature=0,
    ),
)
print(resp.text)

У порівнянні з двома попередніми постачальниками тут messages тепер називається contents, а один хід може бути просто рядком тексту. Попередження системи вводиться у поле GenerateContentConfig. Параметр температури знову є звичайним полем конфігурації, яке було видалено у поточному SDK Claude. Відповідь — це просто resp.text, а кількість токенів вказується у resp.usage_metadata як prompt_token_count та candidates_token_count; це ті самі показники, але під іншими назвами від Google. Завжди фіксуйте їх.

Цикл керованої історії

Можливо безпосереднє портування власної функції ask(): зберігайте значення user та model у списку, додавайте кожну зміну та щоразу передавайте contents=. Це працює. Проте SDK містить зручність, якої клієнти OpenAI та Anthropic не мають вже з самого початку: об’єкт чату, який бере на себе додавання даних.

chat = client.chats.create(
    model="gemini-2.5-flash",
    config=types.GenerateContentConfig(
        system_instruction="Be concise.",
    ),
)

r1 = chat.send_message(
    "Define a context window."
)
print(r1.text)

r2 = chat.send_message(
    "Now for a five-year-old."
)
print(r2.text)

for turn in chat.get_history():
    part = turn.parts[0].text[:40]
    print(turn.role, "->", part)

Відповідь на наступне запитання надається в контексті, оскільки об’єкт чату тихо відтворює попередню переписку, що саме робила б функція, написана вручну. Якщо пройтися по результатам get_history() у кінці, можна побачити чергування ходів user та model — саме той список, який був надісланий у попередньому запиті. На стороні сервера нічого не зберігається. Об’єкт чату зберігає введення на клієнті, тому токени вводу все одно накопичуються з кожним ходом, і довгі чати коштують більше за один виклик.

Одна річ не змінилася: сервіс, що стоїть за SDK, нічого не пам’ятає між запитами.

Зручність має свою ціну, і це стає важливим пізніше при роботі з фреймворками. Керована історія означає менше коду та менше помилок, принаймні до моменту, коли доводиться скорочувати старі записи, узагальнювати їх чи вставляти отримані документи посеред розмови. Тоді вам знадобиться звичайний список. LangChain знаходиться на тому самому рівні цієї шкали, але на один рівень вище. Звикніть як до списку, який ведеться вручну, так і до керованих об’єктів — жоден з них не може вас обмежити.

Запуск прикладу

pip install -r requirements.txt
export GEMINI_API_KEY="AIza..."
python examples/part04_gemini.py

Скрипт по черзі охоплює три аспекти: один раунд обміну повідомленнями, цикл ручного переліку для підтвердження еквівалентності та керований чат із виведенням історії. Кількість токенів фіксується після кожного виклику. Якщо ключ не встановлений, скрипт негайно зупиняється із чітким повідомленням. Оскільки виклики є дійсними та оплачуваними, не запускайте його в середовищі CI.

Три постачальники, одна структура

Швидке порівняння всіх трьох. OpenAI розглядає system як повідомлення та залишає історію на ваш розсуд. Claude робить system окремим параметром, вимагає вказати max_tokens та також залишає історію на ваш розсуд. Gemini включає system_instruction до конфігурації, називає асистента model та зберігатиме історію, якщо ви це дозволите. Усі три працюють за однаковим безстановим циклом: надсилати повну розмову, отримувати відповідь, додавати її та продовжувати.

Саме тому фреймворки з кількома постачальниками можуть залишатися легкими, і тому зміна постачальника не мусить викликати страху. Міграція — це просто заміна імен, а не повне переписування.