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.

Promptra — Russian LLM API aggregator. One OpenAI-compatible endpoint to all flagship models: OpenAI (GPT-5.5, GPT-5.4), Anthropic (Claude Opus 4.7, Sonnet 4.6), Google (Gemini 3.1 Pro, 3.5 Flash), DeepSeek V4 Pro, Qwen 3.6 Plus.

Provider prices 1-to-1 at CBR rate — no markup on tokens. Ruble billing per contract, full closing documents through EDI. No VPN — legal B2B service in Russia.

Try: promptra.ru · model catalog · docs