LLM API на Python: полный технический гид 2026 — токены, streaming, function calling, RAG, batch

LLM API на Python — это не один навык, а пять взаимосвязанных: считать токены и предсказывать стоимость, использовать function calling для агентов и интеграций, стримить ответы через SSE для нормального UX, строить RAG-системы на embeddings и векторных БД, ускорять и удешевлять через async и Batch API. Этот pillar собирает все пять в один гид с runnable Python кодом, реальными цифрами и cross-references на детальные статьи. Если ты Python-разработчик, который запускает свой первый продакшен на LLM или оптимизирует существующий — читай по порядку или прыгай в нужную секцию.

Контекст: все примеры запускаются через OpenAI-совместимый endpoint Promptra. Это значит, что один pip install openai + base_url="https://api.promptra.ru/v1" даёт доступ к Claude Opus 4.7, GPT-5.5, Gemini 3.1 Pro, DeepSeek V4 Pro и десятку других моделей. Платишь в рублях на расчётный счёт российское юр.лицо, получаешь полный пакет закрывающих документов через ЭДО (Диадок, СБИС, Контур). Это не «обход блокировок», а легальный B2B-сервис в России. Курс ЦБ 71.668 ₽/$ на 2026-05-27 — все цены ниже считаны по нему.

1. Токены и расчёт стоимости — фундамент всего

Прежде чем запускать LLM в продакшен, ты должен уметь считать токены и предсказывать стоимость запроса до отправки. Без этого нельзя нормально планировать бюджет, выставлять usage-based pricing клиентам или решать, какую модель использовать под конкретную задачу.

Базовая механика: токен — это не символ и не слово, а кусок текста (subword), который модель видит как единицу. Английский текст: 1 токен ≈ 4 символа ≈ 0.75 слова. Русский: 1 токен ≈ 1.5-2 символа (кириллица кодируется плотнее — больше токенов на тот же объём). Код: 1 токен ≈ 3-4 символа. Это значит русская страница A4 (~3000 символов) — это 1500-2000 токенов, а английская — 700-900.

import tiktoken
enc = tiktoken.encoding_for_model("gpt-4o")  # совместимо с GPT-5
text = "Промтра — это российский LLM-агрегатор."
print(len(enc.encode(text)))  # 14 токенов

Для расчёта стоимости берёшь output-цену модели (output составляет 60-80% реального счёта), умножаешь на курс ЦБ, делишь на 1 миллион. Пример для Claude Sonnet 4.6: ответ на 800 output-токенов = 800 / 1_000_000 × 1070 ₽ ≈ 0.86 ₽ за один ответ. На 10 000 диалогов в день — 8 600 ₽. На дешёвой DeepSeek V4 Pro (60 ₽ output) — 480 ₽ в день, в 18 раз меньше.

Полный разбор tokenizer'ов для OpenAI/Anthropic/Gemini, формулы для всех 8 флагманских моделей в рублях, оптимизация промптов под плотность токенов — в детальной статье Как считать токены в LLM.

2. Function calling и tool use — основа агентов

Function calling (tool use) — это способ дать модели набор твоих Python-функций, которые она может вызывать структурированно. Поверх него строятся RAG-системы (поиск по корпоративной базе), агенты (модель сама решает какие шаги выполнить), и продуктовые интеграции (модель обновляет CRM, отправляет письма, делает запросы в API).

Базовая схема: определяешь tool как JSON-schema (имя, описание, параметры с типами), отправляешь модели вместе с user-сообщением, получаешь обратно tool_calls со структурированными аргументами, выполняешь функцию у себя, отправляешь результат обратно. Модель генерирует финальный ответ, опираясь на результат.

from openai import OpenAI
client = OpenAI(base_url="https://api.promptra.ru/v1", api_key="...")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Получить погоду в городе",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="claude-sonnet-4.6",
    messages=[{"role": "user", "content": "Какая погода в Москве?"}],
    tools=tools
)
# response.choices[0].message.tool_calls → [{name: "get_weather", arguments: '{"city": "Москва"}'}]

Важные нюансы — parallel tool calls (модель вызывает несколько функций за один шаг), structured outputs (гарантированный JSON-формат), streaming tool calls, error handling если функция падает. Полный гайд с production-ready code, схемами и обходом типовых граблей — в статье Function calling и tool use на Python.

3. Streaming через SSE — нормальный UX чата

Streaming — обязательная фича для любого LLM-чата. Без него пользователь смотрит на пустой экран 5-15 секунд (типичное время генерации ответа на 500-1000 токенов) и думает, что у тебя зависло. Streaming решает это через Server-Sent Events: модель отправляет chunk'и по мере генерации, ты их парсишь и показываешь по символу.

Сам OpenAI SDK обрабатывает SSE прозрачно — достаточно передать stream=True:

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Напиши длинный ответ"}],
    stream=True
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

В реальных приложениях критичны три аспекта. Первый — error handling: stream может прерваться на любом chunk'е, и обычный try/except не покроет (исключение прилетает асинхронно). Второй — backpressure: если фронт не успевает рендерить, нужно буферизовать. Третий — measurement: для UX важна не общая latency, а Time To First Token (TTFT) — задержка до первого видимого символа.

Production-ready реализации для FastAPI с async-stream, обработка SSE-ошибок и retry, integration с Anthropic streaming (другой протокол) — в статье Streaming LLM через SSE на Python.

4. Embeddings и RAG — поиск по своим данным

LLM сама по себе ничего не знает о твоей корпоративной базе, документах или API. Решение — RAG (Retrieval-Augmented Generation): ты заранее векторизуешь свои документы через embeddings-модель, складываешь векторы в специализированную БД, при запросе пользователя находишь топ-N релевантных кусков, и передаёшь их модели как контекст.

Базовый RAG-стек в 2026 году: - Embeddings-модель: OpenAI text-embedding-3-large (3072 dim, $0.13/1M токенов), Voyage AI voyage-3 (1024 dim, для русского отлично), Cohere embed-multilingual-v3 (1024 dim) - Векторная БД: pgvector для маленьких/средних объёмов (до 10M векторов), Qdrant для больших и production-нагрузки, Chroma для прототипов - Chunking стратегия: semantic chunking (по смысловым границам) выигрывает у fixed-size chunking в 1.5-2 раза по recall - Retrieval evaluation: meaure Recall@k и MRR на размеченном датасете перед прод-релизом

from openai import OpenAI
client = OpenAI(base_url="https://api.promptra.ru/v1", api_key="...")
emb = client.embeddings.create(
    model="text-embedding-3-large",
    input="Промтра — российский LLM-агрегатор"
)
vector = emb.data[0].embedding  # 3072-dim float list

Дальше — нормализация, индексация в векторной БД, query-side retrieval с фильтрами по метаданным, reranking через cross-encoder (опционально, даёт +10-20% к качеству). Все детали с runnable code, бенчмарками embeddings-моделей на русском, выбором между pgvector и Qdrant — в статье Embeddings и RAG-стек 2026.

5. Async и Batch API — производительность и -50% на стоимость

Если у тебя 100+ запросов в обработке, sequential API-вызовы — главное узкое место. Решение — два разных подхода под разные сценарии.

Async (asyncio + AsyncOpenAI) — для realtime параллелизма. Пять одновременных запросов летят параллельно вместо очереди. Типовая ускорение: 5-20× относительно sequential.

import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://api.promptra.ru/v1", api_key="...")

async def query(prompt):
    r = await client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": prompt}]
    )
    return r.choices[0].message.content

results = asyncio.run(asyncio.gather(*[query(p) for p in prompts]))

Batch API — для non-realtime пакетной обработки. OpenAI Batch и Anthropic Message Batches дают скидку 50% на токены при SLA 24 часа. Идеально для: классификации лога заявок, генерации описаний для каталога 50 000 SKU, разовой обработки исторических данных, ночных аналитических job'ов.

Считалка экономии: 100 000 GPT-5.4 запросов по ~1500 токенов output = 150M токенов × 1070 ₽/1M = 160 500 ₽. С Batch API — 80 250 ₽. Экономия 80 тысяч на одной job'е.

Когда что использовать, как составлять batch JSONL-файлы, как обрабатывать частичные failures, integration с очередями (Celery, RQ) для гибридных pipeline'ов — в детальном гайде Async и Batch API на Python.

Что читать дальше — путь от MVP к production

Эти 5 концепций покрывают 90% потребностей при работе с LLM API в продакшене. Следующие шаги зависят от того, что строишь:

Если строишь чат-бот: глубже изучи streaming + function calling. После — добавь semantic cache (Redis с embedding-keys) для сокращения счёта на 40-70%.

Если строишь RAG: после embeddings и retrieval разберись с evaluation (Recall@k, MRR на размеченном датасете), reranking через cross-encoder, hybrid search (BM25 + векторный). Это даёт +20-40% к качеству ответов.

Если строишь агент: function calling + async — твоя база. Дальше — orchestration через LangGraph или CrewAI, structured outputs для надёжности, observability через Langfuse.

Если оптимизируешь стоимость: token counting → выбор модели по соотношению цена/качество (см. GPT-5.5 vs Claude Opus 4.7) → semantic cache → Batch API для async workloads.

Если выбираешь поставщика API для бизнеса — пройди B2B чек-лист из 12 вопросов и сверь с публичными данными кандидатов. Для миграции с существующего OpenAI-аккаунта — пошаговый гайд переключения base_url за 10 минут.

Стек Promptra — что под капотом

Promptra даёт один OpenAI-совместимый endpoint ко всем флагманам без наценки на токены — цена 1-в-1 с провайдером по курсу ЦБ. Сервисная комиссия 5% берётся только при пополнении баланса, не при использовании. Это значит, что счёт за API масштабируется линейно с провайдерским, без хитрых множителей.

Технически: HTTP/2 proxy на собственной инфраструктуре в РФ + европейских регионах, OpenAI Chat Completions + Anthropic Messages + Google Generate Content protocols, sub-100ms добавки к latency провайдера, public status-page с p50/p99 метриками. Документация — на docs.promptra.ru, каталог моделей — на /models.

Для команд разработчиков — пошаговая настройка ChatGPT для команды в России с 5 разными способами и сравнением. Для интегратора, который хочет понять рынок целиком — обзор всех ключевых LLM-агрегаторов России 2026.

FAQ

С чего начать работать с LLM API на Python если ничего не знаю?

Начни с самого простого: pip install openai, получи API-ключ у Promptra (один OpenAI-совместимый endpoint ко всем флагманам — Claude, GPT, Gemini, DeepSeek), и в 10 строках кода сделай первый запрос. Дальше последовательно изучи 5 концепций: токены (как считается стоимость), function calling (как заставить модель вызывать твои функции), streaming (как получать ответ по частям), embeddings (для поиска по своим данным) и async/batch (для performance и скидки 50%). Каждая концепция — отдельная статья в этом гиде, читать в любом порядке.

Что лучше — OpenAI SDK или прямой HTTP-запрос к API?

Для большинства задач — официальный SDK (openai, anthropic, google-genai). Он закрывает retry, парсинг ошибок, streaming, типизацию tool_calls и обновляется при изменениях API. Прямой HTTP через httpx/requests имеет смысл только если нужна полная контроль над сетевыми параметрами (custom retry policy, специфичные заголовки, проксирование) или если SDK не покрывает редкий endpoint. Promptra полностью совместима с openai SDK — меняешь только base_url, остальной код не трогаешь.

Сколько стоит работать с LLM API в продакшене на Python?

Зависит от модели и объёма. Для прикидки: типовой чат-бот с 1000 диалогов в день на Claude Sonnet 4.6 (210 ₽ за 1М input + 1070 ₽ за 1М output по курсу ЦБ 71.668) обходится примерно в 6 000-15 000 ₽ в месяц. Та же нагрузка на GPT-5.5 (350/2150) — 10 000-25 000 ₽. Дешёвые модели типа DeepSeek V4 Pro (30/60) и Qwen 3.6 Plus (20/130) — десятки рублей в день. С Batch API и semantic cache можно срезать счёт в 2-4 раза. Конкретные тарифы — в сравнении цен LLM 2026.

Что такое function calling и почему все про него говорят?

Function calling (он же tool use) — это способ дать модели набор твоих функций, которые она может вызывать. Модель возвращает не текст, а структурированный JSON с именем функции и аргументами. Ты выполняешь функцию в своём коде, возвращаешь результат модели, она генерирует финальный ответ. Это базовый кирпич для агентов, RAG-систем и продуктовых интеграций — от поиска по корпоративной базе до автоматизации заявок. Поддерживается всеми флагманами: OpenAI, Anthropic, Google. Полный разбор — в статье function calling и tool use на Python.

Зачем нужен streaming и когда он критичен?

Streaming — это получение ответа модели по частям (chunk'ами) через Server-Sent Events, а не одним блоком в конце. Критичен в трёх сценариях: (1) UX чат-ботов — пользователь видит ответ сразу, как будто модель печатает; ожидание 5-15 секунд без визуальной обратной связи воспринимается как зависание; (2) длинные генерации (1000+ токенов) — пользователь успевает прочитать начало пока пишется конец; (3) early-stopping — можно остановить генерацию когда увидел нужную информацию, экономя токены. Подробно — в гайде streaming LLM через SSE.

Что лучше для production — Batch API или обычный API с async?

Это разные задачи. Batch API подходит когда у тебя пакет 100-100000 запросов которые не нужны прямо сейчас — например, ночная обработка лога, классификация исторических данных, генерация описаний для каталога товаров. OpenAI Batch и Anthropic Message Batches дают скидку 50% и SLA 24 часа. Обычный API с async (asyncio + aiohttp) — для realtime сценариев когда нужны параллельные запросы с низкой latency: множественные tool calls, A/B тест разных промптов, параллельный fetch для агента. Подробный разбор — в статье async и Batch API на Python.