В чат-приложении ты пишешь вопрос и читаешь ответ. А если Мурад хочет, чтобы сайт школы отвечал на вопросы о расписании, или Лейле нужно за ночь рассортировать 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 для мозгового штурма |
{
"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 }
}Один факт удивляет большинство новичков: модель не помнит предыдущих запросов. Каждый запрос независим. Чат-приложение лишь кажется помнящим: с каждым новым сообщением оно заново отправляет весь разговор — системный промпт и все прежние вопросы и ответы. Поэтому длинные чаты расходуют всё больше токенов, а контекстное окно ограничивает длину чата. (Некоторые сервисы умеют хранить историю за тебя, но модель всё равно получает её на вход.)
Что отправляется с третьим вопросом?
Задача
У приложения Мурада есть системный промпт, и с пользователем уже было два вопроса и два ответа. Теперь пользователь задаёт третий вопрос. Перечисли, что отправляет программа.
Показать решениеСкрыть решение
Решение
2) user: вопрос 1;
3) assistant: ответ 1;
4) user: вопрос 2;
5) assistant: ответ 2;
6) user: вопрос 3.
Всего шесть элементов — модель отвечает на вопрос 3, видя всю историю. Если бы программа отправила только вопрос 3, модель не знала бы, к чему относятся слова «он» или «это».
Чтобы читать дальше, зарегистрируйся бесплатно
Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.
Токены и стоимость
Провайдеры считают использование в токенах — отдельно для входа (всё, что ты отправляешь) и выхода (всё, что пишет модель). Выходные токены обычно дороже входных. Цены указывают за миллион токенов, они сильно различаются между моделями и часто меняются, поэтому числа ниже придуманы для тренировки: всегда смотри актуальный прайс-лист своего провайдера.
Где
- C
- стоимость одного запроса
- N₁
- число входных токенов (системный промпт + история + новое сообщение)
- p₁
- цена одного входного токена = цена за миллион / 1 000 000
- N₂
- число выходных токенов (ответ)
- p₂
- цена одного выходного токена
Вход и выход считаются отдельно; расходы за месяц = стоимость запроса × запросов в день × 30.
Расчёт стоимости (тренировочные цены: 0,50 $ за миллион входных и 2,00 $ за миллион выходных токенов)
Задача
1) Сколько стоит один запрос: 1200 входных и 300 выходных токенов?
2) Приложение отправляет 500 запросов в день, в каждом 1000 входных и 200 выходных токенов. Сколько стоят 30 дней?
3) В том же приложении ответы стали вдвое длиннее (400 выходных токенов). Сколько теперь стоят 30 дней?
Показать решениеСкрыть решение
Решение
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 должен укладываться в этот предел. Программа ниже показывает, почему длинный чат дорог:
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, чтобы тысячи клиентов не повторяли запросы в один и тот же момент.
Отправь
Отправь запрос с тайм-аутом, чтобы программа не ждала вечно.
Успех
Код 200: возьми ответ и счётчики токенов.
Ошибка, которую надо исправить
400, 401, 403: остановись, запиши ошибку в журнал и сообщи о ней — повтор не поможет.
Временная ошибка
429, 500, 503: подожди (экспоненциальная задержка + jitter) и повтори.
Знай предел
После нескольких попыток остановись и покажи пользователю вежливое сообщение: «Попробуйте ещё раз через минуту».
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), которая собирает запрос за тебя. Но устройство везде одинаковое.
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-схеме; программа всё равно должна проверять результат. Здесь помогает и низкая температура: формат нужен каждый раз один и тот же.
Мини-проект: бэкенд помощника по домашним заданиям
Задача
Класс Лейлы хочет сайт, где ученики могут задавать вопросы по математике. Спроектируй бэкенд: что отправляется, какие параметры выбраны, как обращаться с ключом и расходами.
Показать решениеСкрыть решение
Решение
Системный промпт: «Ты репетитор по математике для 9–11 классов. Давай подсказки и задавай наводящие вопросы; не выдавай просто готовый ответ. Не больше 150 слов».
Параметры: max tokens 300, температура 0,3.
История: отправлять только последние 6 реплик, чтобы стоимость и контекст оставались небольшими.
Ошибки: 429 и 5xx — повтор с задержкой (не больше 4 попыток), затем «Попробуйте ещё раз через минуту».
Расходы: не больше 30 вопросов на ученика в день и месячный лимит расходов в настройках провайдера.
Конфиденциальность: никаких имён и e-mail в запросах; на странице — пометка, что вопросы обрабатывает ИИ-сервис.
Задание
Помощник по домашним заданиям получает 200 вопросов в день. В каждом запросе 900 входных и 300 выходных токенов. По тренировочным ценам (0,50 $ за миллион входных, 2,00 $ за миллион выходных токенов) выведи стоимость 30 дней с 2 знаками после точки (только число).
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-ключ — пароль, привязанный к твоему счёту: храни его на сервере в переменной окружения, никогда не во фронтенд-коде и не в репозитории.
- Читай политику использования и хранения данных провайдера и отправляй только те данные, которые нужны задаче.