Как работают API больших языковых моделей

Что происходит, когда программа обращается к языковой модели: запрос и сообщения, max tokens и температура, токены и стоимость, потоковая передача, лимиты и ошибки, структурированный вывод, защита API-ключей и данных.

  • Продвинутый
  • 22 мин
  • 12 вопросов
  • Урок 11 из 16

В этом уроке ты узнаешь

  • Описывать части API-запроса: системный промпт, сообщения, max tokens, температуру
  • Оценивать расход токенов и стоимость приложения, в том числе понимать, почему длинные чаты дороже
  • Работать с потоковой передачей, лимитами и ошибками с помощью повторов и экспоненциальной задержки
  • Хранить API-ключи в секрете и соблюдать правила конфиденциальности и хранения данных

В чат-приложении ты пишешь вопрос и читаешь ответ. А если Мурад хочет, чтобы сайт школы отвечал на вопросы о расписании, или Лейле нужно за ночь рассортировать 5000 ответов на опрос? Вставлять 5000 сообщений вручную никто не станет. Программы общаются с языковыми моделями через API — модели те же, но вызываются из кода. Этот урок показывает, что передаётся между твоей программой и моделью, сколько это стоит и как делать это безопасно. Понадобятся идеи из урока «Как работают большие языковые модели»: токены, температура и контекстное окно.

API (программный интерфейс)Определение

Набор правил, по которым одна программа запрашивает услугу у другой. API языковой модели обычно — веб-сервис: твоя программа отправляет на сервер провайдера HTTP-запрос с JSON, сервер запускает модель и возвращает ответ тоже в JSON.

Из чего состоит запрос

Каждый провайдер называет поля немного по-своему, но почти в любом запросе есть одни и те же части:

ЧастьЧто делаетПример
Адрес и API-ключАдрес сервиса и секретный ключ, по которому узнают твой аккаунт (передаётся в заголовке)https://api.example.com/v1/chat
МодельКакая модель отвечает: крупные обычно способнее, но медленнее и дороже"model": "example-model"
Системный промптПравила для всего разговора: роль, тон, формат, ограничения«Ты репетитор. Отвечай не больше чем в 3 предложениях».
СообщенияРазговор в виде списка реплик, у каждой своя роль: user (человек) или assistant (прежние ответы модели){"role": "user", "content": "..."}
max tokensВерхний предел длины ответа; когда он достигнут, ответ обрывается"max_tokens": 300
ТемператураСлучайность: низкая — предсказуемо, выше — разнообразнее0–0,3 для сортировки, 0,8 для мозгового штурма
Точные названия полей и допустимые значения указаны в документации провайдера.
JSON
{
  "text": "A token is a small piece of text, such as a short word or part of a word, that the model reads and writes.",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 27, "output_tokens": 24 }
}
Иллюстративный ответ. Кроме текста, в нём сказано, почему модель остановилась (закончила или упёрлась в max tokens), и сколько токенов ушло, — именно за это ты платишь.

Один факт удивляет большинство новичков: модель не помнит предыдущих запросов. Каждый запрос независим. Чат-приложение лишь кажется помнящим: с каждым новым сообщением оно заново отправляет весь разговор — системный промпт и все прежние вопросы и ответы. Поэтому длинные чаты расходуют всё больше токенов, а контекстное окно ограничивает длину чата. (Некоторые сервисы умеют хранить историю за тебя, но модель всё равно получает её на вход.)

Что отправляется с третьим вопросом?

Задача

У приложения Мурада есть системный промпт, и с пользователем уже было два вопроса и два ответа. Теперь пользователь задаёт третий вопрос. Перечисли, что отправляет программа.

Показать решениеСкрыть решение

Решение

1) системный промпт;
2) user: вопрос 1;
3) assistant: ответ 1;
4) user: вопрос 2;
5) assistant: ответ 2;
6) user: вопрос 3.
Всего шесть элементов — модель отвечает на вопрос 3, видя всю историю. Если бы программа отправила только вопрос 3, модель не знала бы, к чему относятся слова «он» или «это».

Чтобы читать дальше, зарегистрируйся бесплатно

Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.

Токены и стоимость

Провайдеры считают использование в токенах — отдельно для входа (всё, что ты отправляешь) и выхода (всё, что пишет модель). Выходные токены обычно дороже входных. Цены указывают за миллион токенов, они сильно различаются между моделями и часто меняются, поэтому числа ниже придуманы для тренировки: всегда смотри актуальный прайс-лист своего провайдера.

C = N₁ · p₁ + N₂ · p₂

Где

C
стоимость одного запроса
N₁
число входных токенов (системный промпт + история + новое сообщение)
p₁
цена одного входного токена = цена за миллион / 1 000 000
N₂
число выходных токенов (ответ)
p₂
цена одного выходного токена

Вход и выход считаются отдельно; расходы за месяц = стоимость запроса × запросов в день × 30.

Расчёт стоимости (тренировочные цены: 0,50 $ за миллион входных и 2,00 $ за миллион выходных токенов)

Задача

1) Сколько стоит один запрос: 1200 входных и 300 выходных токенов?
2) Приложение отправляет 500 запросов в день, в каждом 1000 входных и 200 выходных токенов. Сколько стоят 30 дней?
3) В том же приложении ответы стали вдвое длиннее (400 выходных токенов). Сколько теперь стоят 30 дней?

Показать решениеСкрыть решение

Решение

1) C = 1200 · 0,0000005 + 300 · 0,000002 = 0,0006 + 0,0006 = 0,0012 $.
2) Один запрос: 0,0005 + 0,0004 = 0,0009 $. День: 0,0009 · 500 = 0,45 $. 30 дней: 13,50 $.
3) Один запрос: 0,0005 + 0,0008 = 0,0013 $. 30 дней: 0,0013 · 500 · 30 = 19,50 $ — одни только более длинные ответы подняли стоимость на 44%. max tokens и правило «отвечай кратко» экономят деньги.

Токены ограничивают и то, что помещается: вход и выход вместе должны уместиться в контекстное окно модели. Если отправить документ на 90 000 токенов модели с окном в 100 000 токенов, на ответ останется не больше 10 000 токенов, и max tokens должен укладываться в этот предел. Программа ниже показывает, почему длинный чат дорог:

Python
PRICE_IN = 0.50 / 1_000_000    # example price per input token (invented)
PRICE_OUT = 2.00 / 1_000_000   # example price per output token (invented)

system, question, answer = 300, 40, 160   # tokens in each part
history = 0
total_in = total_out = 0
for turn in range(1, 6):
    tokens_in = system + history + question   # the whole chat is sent again
    total_in += tokens_in
    total_out += answer
    print(f"turn {turn}: input {tokens_in} tokens, output {answer} tokens")
    history += question + answer

cost = total_in * PRICE_IN + total_out * PRICE_OUT
print(f"one chat: {total_in} in + {total_out} out = ${cost:.5f}")
print(f"1000 such chats: ${cost * 1000:.2f}")
Ожидаемый результат
turn 1: input 340 tokens, output 160 tokens
turn 2: input 540 tokens, output 160 tokens
turn 3: input 740 tokens, output 160 tokens
turn 4: input 940 tokens, output 160 tokens
turn 5: input 1140 tokens, output 160 tokens
one chat: 3700 in + 800 out = $0.00345
1000 such chats: $3.45
Вход растёт с каждой репликой, потому что весь чат отправляется заново: у пятого вопроса входных токенов больше чем втрое больше, чем у первого. Цены придуманы для тренировки.

Потоковая передача, лимиты и ошибки

Генерация длинного ответа занимает секунды. При потоковой передаче (streaming) сервер отправляет ответ небольшими частями по мере появления токенов, и пользователь сразу видит текст, а не смотрит на пустой экран. Общее время примерно то же, но ожидание ощущается гораздо короче. Счётчики токенов обычно приходят в конце потока, а программа должна быть готова к тому, что поток оборвётся на середине.

Провайдеры защищают серверы лимитами запросов (rate limits): максимальным числом запросов и токенов в минуту (иногда в сутки) для каждого аккаунта. При превышении сервер отвечает HTTP-кодом 429 Too Many Requests. Твоя программа должна быть готова к этой и другим ошибкам:

КодЗначениеЧто делать программе
400Неверный запрос: ошибочное поле или вход длиннее контекстного окнаИсправить запрос; повтор не поможет
401 / 403Ключа нет, он неверный или отозван, либо нет правПроверить ключ; не повторять
429Слишком много запросов или токенов в минутуПодождать и повторить с растущей паузой
500 / 503Сбой или перегрузка на сервереПодождать и повторить; после нескольких попыток остановиться

Экспоненциальная задержка (exponential backoff)Определение

Стратегия повторов: после каждой неудачной попытки программа ждёт вдвое дольше, чем в прошлый раз (1 с, 2 с, 4 с, 8 с…), плюс небольшую случайную добавку — jitter, чтобы тысячи клиентов не повторяли запросы в один и тот же момент.

  1. Отправь

    Отправь запрос с тайм-аутом, чтобы программа не ждала вечно.

  2. Успех

    Код 200: возьми ответ и счётчики токенов.

  3. Ошибка, которую надо исправить

    400, 401, 403: остановись, запиши ошибку в журнал и сообщи о ней — повтор не поможет.

  4. Временная ошибка

    429, 500, 503: подожди (экспоненциальная задержка + jitter) и повтори.

  5. Знай предел

    После нескольких попыток остановись и покажи пользователю вежливое сообщение: «Попробуйте ещё раз через минуту».

Python
import random

random.seed(1)
answers = [429, 429, 503, 200]   # what a busy server replies, one per try

def call_api(attempt):
    return answers[attempt]      # a real program sends an HTTP request here

wait = 1.0
for attempt in range(5):
    status = call_api(attempt)
    if status == 200:
        print(f"try {attempt + 1}: 200 OK, got the answer")
        break
    if status in (400, 401):
        print(f"try {attempt + 1}: {status}, fix the request; retrying will not help")
        break
    pause = wait + random.uniform(0, 0.5)    # exponential backoff + jitter
    print(f"try {attempt + 1}: {status}, wait {pause:.2f} s and retry")
    wait *= 2                                 # time.sleep(pause) in a real program
else:
    print("giving up after 5 tries")
Ожидаемый результат
try 1: 429, wait 1.07 s and retry
try 2: 429, wait 2.42 s and retry
try 3: 503, wait 4.38 s and retry
try 4: 200 OK, got the answer
Симуляция: вместо настоящего сервера ответы лежат в списке. Настоящая программа отправляет запрос и вызывает time.sleep(pause); паузы растут 1 → 2 → 4 с плюс jitter.

Ключи, конфиденциальность и данные

API-ключ — это пароль, привязанный к твоему счёту. Любой, у кого он есть, может пользоваться сервисом от твоего имени, а платить будешь ты. Утёкшие ключи находят быстро: автоматические боты постоянно сканируют открытые репозитории кода в поисках секретов.

  • Никогда не помещай ключ во фронтенд-код. JavaScript веб-страницы или код мобильного приложения может прочитать любой пользователь. Ключ остаётся на сервере (бэкенде), который вызывает модель и передаёт дальше только ответ.
  • Никогда не коммить ключ в репозиторий, особенно открытый. Храни его в переменной окружения или менеджере секретов, а файлы вроде .env добавь в .gitignore.
  • Ограничь ущерб: установи лимит расходов, используй отдельный ключ для каждого проекта и давай каждому ключу только нужные права.
  • Если ключ утёк, сразу отзови его и создай новый. Удалить файл из репозитория недостаточно: история его сохраняет.

Ключ в коде

API_KEY = "my-secret-key-123"      # visible to everyone who sees the code

Ключ в переменной окружения

import os

API_KEY = os.environ["AI_API_KEY"]  # set outside the code
Переменную окружения задают в терминале или в настройках хостинга, а код её только читает.

Всё, что ты отправляешь через API, попадает на серверы провайдера. Прежде чем строить приложение, прочитай политику использования и хранения данных провайдера: могут ли данные из API использоваться для обучения моделей, как долго и где хранятся запросы (например, для контроля злоупотреблений). Политики различаются у разных провайдеров, даже между бесплатными и платными тарифами, и со временем меняются. Отправляй только те данные, которые нужны для задачи, убирай лишние имена и номера, сообщай пользователям, что их текст обрабатывает ИИ-сервис, и соблюдай правила своей школы, компании и страны (в ЕС, например, GDPR).

Небольшая программа — и структурированный вывод

Вот полный запрос на Python с популярной библиотекой requests. Адрес, имя модели и названия полей — заполнители: у настоящих провайдеров свои названия, и у большинства есть официальная библиотека (SDK), которая собирает запрос за тебя. Но устройство везде одинаковое.

Python
import os
import requests

API_URL = "https://api.example.com/v1/chat"   # placeholder: your provider's address
API_KEY = os.environ["AI_API_KEY"]            # the key lives outside the code

body = {
    "model": "example-model",
    "system": "You are a friendly tutor. Answer in one sentence.",
    "messages": [{"role": "user", "content": "What is a token?"}],
    "max_tokens": 100,
    "temperature": 0.2,
}
headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(API_URL, json=body, headers=headers, timeout=30)
response.raise_for_status()          # stops with an error on 4xx / 5xx
data = response.json()

print(data["text"])
print("stop reason:", data["stop_reason"])
print("tokens in/out:", data["usage"]["input_tokens"], data["usage"]["output_tokens"])

Ожидаемый результат

A token is a small piece of text, such as a short word or part of a word, that the model reads and writes.
stop reason: end_turn
tokens in/out: 27 24
Иллюстрация: в браузере этот код не запускается (нет requests и нет ключа). Вывод выше получен от локального тестового сервера, имитирующего API. Перед реальным использованием задай переменную окружения AI_API_KEY вне кода.

Если программе нужны поля, а не связный текст, проси JSON со схемой — как в уроке «Продвинутые техники промптинга». У многих API для этого есть параметр (часто он называется response format или structured output), который заставляет модель следовать заданной JSON-схеме; программа всё равно должна проверять результат. Здесь помогает и низкая температура: формат нужен каждый раз один и тот же.

Мини-проект: бэкенд помощника по домашним заданиям

Задача

Класс Лейлы хочет сайт, где ученики могут задавать вопросы по математике. Спроектируй бэкенд: что отправляется, какие параметры выбраны, как обращаться с ключом и расходами.

Показать решениеСкрыть решение

Решение

Архитектура: браузер → сервер Лейлы → API ИИ. Ключ хранится только на сервере, в переменной окружения.
Системный промпт: «Ты репетитор по математике для 9–11 классов. Давай подсказки и задавай наводящие вопросы; не выдавай просто готовый ответ. Не больше 150 слов».
Параметры: max tokens 300, температура 0,3.
История: отправлять только последние 6 реплик, чтобы стоимость и контекст оставались небольшими.
Ошибки: 429 и 5xx — повтор с задержкой (не больше 4 попыток), затем «Попробуйте ещё раз через минуту».
Расходы: не больше 30 вопросов на ученика в день и месячный лимит расходов в настройках провайдера.
Конфиденциальность: никаких имён и e-mail в запросах; на странице — пометка, что вопросы обрабатывает ИИ-сервис.

Задание

Помощник по домашним заданиям получает 200 вопросов в день. В каждом запросе 900 входных и 300 выходных токенов. По тренировочным ценам (0,50 $ за миллион входных, 2,00 $ за миллион выходных токенов) выведи стоимость 30 дней с 2 знаками после точки (только число).

Задание · Python
PRICE_IN = 0.50 / 1_000_000
PRICE_OUT = 2.00 / 1_000_000
per_day = 200
tokens_in, tokens_out = 900, 300
# cost of one request, then of 30 days; print it with 2 decimals
Ожидаемый результат
6.30

Запомни

  • API-запрос несёт системный промпт, сообщения, имя модели и параметры вроде max tokens и температуры; ответ содержит текст, причину остановки и счётчики токенов.
  • Модель не помнит прежних запросов: программа заново отправляет историю, поэтому длинные чаты расходуют всё больше токенов.
  • Стоимость = входные токены × цена входа + выходные токены × цена выхода; цены указаны за миллион токенов и меняются — проверяй их.
  • Потоковая передача показывает ответ по мере генерации; при 429 и 5xx запрос повторяют с экспоненциальной задержкой, а 400 и 401 исправляют.
  • API-ключ — пароль, привязанный к твоему счёту: храни его на сервере в переменной окружения, никогда не во фронтенд-коде и не в репозитории.
  • Читай политику использования и хранения данных провайдера и отправляй только те данные, которые нужны задаче.
Заметил ошибку или неточность в уроке?

Проверь себя

Вопросов: 12. Каждый правильный ответ приносит XP.

Вопрос 1 / 12

Вопрос 1 / 12. Что содержит системный промпт в API-запросе?