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 і будзе зберагаць історыю, калі вы на тое падазрэўваеце. Усі трох працуюць на аднам і тым жа безстановым цыкле: адправіце цэлы разговор, прыміце адпаведзь, дадаце яе і запускіце цыкл зноў.

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