Интеграция OpenRouter с LangChain: Полное руководство по настройке

В мире генеративного искусственного интеллекта гибкость и надежность становятся такими же важными, как и сама мощность моделей. Если вы разрабатываете сложные агенты или чат-боты с помощью LangChain, вы, вероятно, сталкивались с дилеммой: выбор одной модели ограничивает возможности, а управление множеством провайдеров вручную превращается в ад из API-ключей и ошибок соединения. Здесь на сцену выходит OpenRouter — платформа, которая действует как интеллектуальный маршрутизатор между вашими приложениями и сотнями моделей от десятков провайдеров. В этой статье мы подробно разберем, как интегрировать OpenRouter с LangChain, используя официальный пакет langchain-openrouter, чтобы получить доступ к экосистеме из 400+ моделей, автоматическому балансированию нагрузки и отказоустойчивости без написания лишнего кода.

Ранее многие разработчики использовали обходной путь, переопределяя base_url в стандартном ChatOpenAI. Однако сейчас существует выделенный пакет, который раскрывает весь потенциал платформы: от тонкой настройки провайдеров до кэширования промптов и структурированного вывода. Мы пройдем путь от базовой установки до продвинутых сценариев, таких как маршрутизация с резервным копированием (fallback) и работа с мультимодальными данными. Это руководство поможет вам построить надежное, масштабируемое и экономически эффективное приложение, которое не сломается, если один из провайдеров временно недоступен.

01Быстрый старт: Запуск за 5 минут

Чтобы начать работу с OpenRouter в вашем приложении на LangChain, не нужно переписывать архитектуру. Интеграция построена так, чтобы быть прямой заменой существующим чат-моделям. Весь процесс сводится к трем простым шагам: установка, аутентификация и вызов. Давайте разберем каждый из них подробно.

Шаг 1: Установка и аутентификация

Первое, что вам нужно сделать, — это установить пакет langchain-openrouter. Важно использовать флаг -U (upgrade), так как пакет находится в стадии бета-тестирования и развивается очень быстро. Регулярное обновление гарантирует, что вы будете использовать последние исправления ошибок и новые функции.

pip install -U langchain-openrouter

После установки необходимо настроить ключ API. OpenRouter требует ключ для доступа к своим моделям. Вы можете сгенерировать его на странице openrouter.ai/settings/keys. Ключ должен быть сохранен в переменной окружения OPENROUTER_API_KEY. LangChain автоматически считывает эту переменную, поэтому вам не нужно передавать ее явно в конструктор, если вы предпочитаете управлять секретами через окружение.

export OPENROUTER_API_KEY="sk-or-..."

Если вы работаете в среде, где переменные окружения недоступны, вы можете передать ключ явно в параметр api_key при инициализации модели. Это полезно для тестирования или в специфических корпоративных средах.

Шаг 2: Инициализация и вызов модели

Теперь, когда пакет установлен, мы можем создать экземпляр ChatOpenRouter. Ключевое отличие от стандартных моделей LangChain заключается в аргументе model. Здесь вы используете специфический формат provider/model (провайдер/модель). Например, anthropic/claude-sonnet-4.5. Остальные параметры, такие как temperature, max_tokens и max_retries, ведут себя точно так же, как и в любой другой модели LangChain.

from langchain_openrouter import ChatOpenRouter

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    temperature=0.7,
    max_tokens=1024,
    max_retries=2
)

response = model.invoke("Summarize this support ticket in one sentence.")
print(response.content)

Этот код создает цепочку, которая отправляет запрос к OpenRouter. Платформа обрабатывает маршрутизацию, выбор провайдера и возврат ответа. Если вы хотите убедиться, что ваш ключ работает, прежде чем подключать его к LangChain, вы можете использовать стандартный curl запрос, так как OpenRouter совместим с форматом API OpenAI.

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "Summarize this support ticket in one sentence."}]
  }'

Результат будет идентичным по структуре, что подтверждает совместимость. ChatOpenRouter — это просто типизированная обертка LangChain над этим конечным пунктом.

Шаг 3: Поддержка TypeScript

Для разработчиков на JavaScript/TypeScript путь аналогичен. Пакет @langchain/openrouter доступен в npm. Установка и использование выглядят очень похоже на Python-версию.

import { ChatOpenRouter } from '@langchain/openrouter';

const model = new ChatOpenRouter({
  model: 'anthropic/claude-sonnet-4.5',
  temperature: 0.8
});

const response = await model.invoke('Summarize this support ticket in one sentence.');
console.log(response.content);

Убедитесь, что вы устанавливаете последнюю версию пакета через npm install @langchain/openrouter. Полная документация доступна на странице интеграции OpenRouter и в справочнике LangChain.

02Выбор модели: Формат slug и каталог

Параметр model является единственным специфичным для OpenRouter элементом в вашей цепочке. Формат provider/model (например, openai/gpt-5-mini или deepseek/deepseek-r1) позволяет вам гибко переключаться между моделями. Ваша логика, определения инструментов и структура вывода остаются неизменными.

Актуальные строки provider/model всегда можно найти на странице openrouter.ai/models. Эта страница является источником истины: она показывает доступные модели, провайдеров, которые их предоставляют, и стоимость токенов. Важно регулярно проверять этот каталог, так как доступность моделей и цены могут меняться.

Для разработчиков, использующих агентов LangChain, существует удобный ярлык. Вы можете использовать префикс openrouter: при создании агента, что позволяет избежать явной инициализации конструктора ChatOpenRouter в некоторых случаях:

from langchain.agents import create_agent

agent = create_agent(
    model="openrouter:anthropic/claude-sonnet-4.5"
)

Префикс openrouter: сообщает LangChain разрешить модель через ChatOpenRouter. Это упрощает код и делает его более читаемым.

03Стриминг ответов

Для улучшения пользовательского опыта (UX) часто требуется отправлять токены по мере их генерации, а не ждать полного ответа. LangChain поддерживает это через метод stream_events. Асинхронная версия astream_events работает аналогично в асинхронных цепочках.

Важно отметить: стриминг не снижает стоимость. Вы платите за те же токены, что и при обычном запросе. Стриминг нужен только для UX, чтобы пользователь видел ответ в реальном времени.

for event in model.stream_events(
    "Explain provider routing in three sentences.",
    version="v3"
):
    if event["event"] == "on_chat_model_stream":
        print(event["data"]["chunk"].text, end="", flush=True)

Параметр version="v3" обеспечивает использование текущей схемы событий. В асинхронном коде используйте async for с astream_events.

Метаданные использования (usage_metadata) доступны в финальном агрегированном сообщении, поэтому вы можете получить количество токенов без дополнительного вызова API.

04Вызов инструментов и структурированный вывод

LangChain предоставляет мощные инструменты для работы с функциями (tool calling) и структурированными данными. OpenRouter поддерживает эти функции через bind_tools и with_structured_output.

Привязка инструментов с Pydantic

Используйте bind_tools для определения инструментов. Параметр strict=True заставляет модель строго следовать схеме, предотвращая выдумывание аргументов.

from pydantic import BaseModel, Field

class GetWeather(BaseModel):
    """Get the current weather for a city."""
    city: str = Field(description="City name, e.g. 'Lisbon'")

model_with_tools = model.bind_tools([GetWeather], strict=True)

result = model_with_tools.invoke("What's the weather in Lisbon?")
print(result.tool_calls)

Структурированный вывод

Метод with_structured_output привязывает схему ко всему ответу. По умолчанию используется function_calling, но можно указать method="json_schema" для нативного принуждения JSON-схемы, если модель это поддерживает.

class TicketSummary(BaseModel):
    sentiment: str
    priority: int
    summary: str

structured = model.with_structured_output(
    TicketSummary, 
    method="json_schema"
)

summary = structured.invoke("Customer is furious the export button is broken again.")
print(summary.priority, summary.summary)

Не все модели поддерживают все методы. Проверяйте каталог моделей на предмет доступных возможностей. Установка require_parameters: true в объекте провайдера (рассмотрено ниже) гарантирует, что запросы будут направляться только к провайдерам, которые уважают переданные параметры.

05Маршрутизация провайдеров и резервное копирование (Fallbacks)

Это одна из самых мощных функций OpenRouter. ChatOpenRouter позволяет вашей цепочке переживать сбои провайдеров без написания дополнительного кода для обработки ошибок.

Как это работает по умолчанию

Когда вы делаете вызов, OpenRouter выполняет балансировку нагрузки на основе цены между провайдерами, обслуживающими выбранную модель. Если провайдер имел сбой в последние 30 секунд, запрос автоматически перенаправляется на другого провайдера. Ваш код об этом не знает. Если запрос не может быть выполнен ни у одного провайдера, он не оплачивается.

Управление провайдерами через openrouter_provider

Вы можете явно указать предпочтения провайдера, передав объект openrouter_provider в конструктор:

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    openrouter_provider={
        "order": ["Anthropic", "Google"],
        "allow_fallbacks": True,
        "data_collection": "deny",
        "sort": "throughput"
    }
)

• order: Устанавливает приоритет провайдеров.
• allow_fallbacks: Разрешает падение за пределы предпочтительных провайдеров, если они недоступны.
• sort: Принимает "throughput" (пропускная способность) или "latency" (задержка), когда скорость важнее цены.
• data_collection: Значение "deny" перенаправляет запросы от провайдеров, которые обучают свои модели на ваших промптах. Это критически важно для корпоративной безопасности.
• only/ignore: Позволяют явно разрешать или исключать конкретных провайдеров.
• require_parameters: Устанавливает, что запросы должны направляться только к провайдерам, которые поддерживают точные параметры, которые вы отправляете.

Резервное копирование на уровне моделей

Помимо резервного копирования провайдеров, вы можете настроить резервное копирование на уровне моделей. Для этого используйте параметр route="fallback" и массив models в model_kwargs:

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    route="fallback",
    model_kwargs={
        "models": [
            "anthropic/claude-sonnet-4.5",
            "openai/gpt-5-mini",
            "google/gemini-3-flash-preview"
        ]
    }
)

Если основная модель недоступна, OpenRouter попытается следующую модель из массива. Параметр models не является аргументом конструктора, поэтому он передается через model_kwargs, который передает дополнительные параметры в API без изменений. Вы можете комбинировать этот массив с sort: {by, partition: "none"} в openrouter_provider, чтобы ранжировать конечные точки глобально по всем указанным моделям, а не по каждой модели отдельно.

Ваша цепочка LangChain указывает на один ChatOpenRouter, но OpenRouter распределяет запрос по провайдерам, и вы оплачиваете только успешный запуск.

06Рассуждение, мультимодальность, кэширование и наблюдаемость

OpenRouter предоставляет доступ к передовым функциям через простые параметры конструктора или запроса.

Рассуждение (Reasoning)

Для моделей, поддерживающих цепочку рассуждений (Chain of Thought), вы можете установить бюджет рассуждений с помощью параметра reasoning:

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    reasoning={
        "effort": "high",
        "summary": "auto"
    }
)

Параметр effort варьируется от xhigh до none. Количество токенов рассуждения отображается в usage_metadata.output_token_details.reasoning, что позволяет точно видеть стоимость "мышления" модели.

Мультимодальные входы

Изображения, аудио, видео и PDF-файлы передаются через блоки контента HumanMessage, как это обычно делается в LangChain. Поддержка зависит от конкретной модели, поэтому проверяйте каталог.

Кэширование промптов

Вы можете включить кэширование, добавив маркер cache_control: {"type": "ephemeral"} в блок контента сообщения. Чтения кэша отображаются в usage_metadata.input_token_details.cache_read, что позволяет отслеживать экономию.

Наблюдаемость (Observability)

Передайте session_id (до 256 символов) для группировки связанных запросов и объект trace для метаданных запроса. OpenRouter пересылает эти данные в ваши настроенные места назначения Broadcast, так что трассировка попадает в ваш стек мониторинга без дополнительной инструментации.

07Частые проблемы и способы их решения

При работе с новым пакетом могут возникнуть некоторые типичные проблемы. Вот как их решить:

1. Совместимость версий: langchain-openrouter находится в бета-стадии и требует текущей версии LangChain. Он не обратно совместим со старыми версиями. Закрепите версию из PyPI и обновите LangChain вместе с ним. Не копируйте закрепление версии из старых руководств.
2. Паттерн ChatOpenAI + base_url: Если вы используете старую версию LangChain, вы все еще можете использовать ChatOpenAI с переопределенным base_url на https://openrouter.ai/api/v1. Однако для текущих версий LangChain выделенный пакет ChatOpenRouter предоставляет более чистый доступ к маршрутизации провайдеров, рассуждениям и структурированному выводу. Нет срочности в миграции, если ваша текущая настройка работает, но для новых проектов используйте новый пакет.
3. Модель возвращает один и тот же ответ: Если модель всегда выдает одинаковый ответ, это почти всегда связано с температурой или кэшированием, а не с ошибкой. Установите ненулевую температуру и проверьте, активно ли кэширование промптов.
4. Поддержка параметров на уровне модели: Не все модели поддерживают все параметры. Если вы не уверены, установите require_parameters: true в openrouter_provider, чтобы запросы направлялись только к провайдерам, принимающим ваши параметры, или сначала проверьте страницу модели в каталоге.

Стандартизируйте использование пакета ChatOpenRouter, закрепите его из PyPI или npm и держите строки моделей актуальными, проверяя openrouter.ai/models. Настройте openrouter_provider один раз, и каждый вызов в вашей цепочке наследует отказоустойчивость между провайдерами, оплачивая только успешный запуск.

08Часто задаваемые вопросы

Является ли OpenRouter тем же, что и LangChain?

Нет. Они дополняют, а не конкурируют. OpenRouter — это провайдер моделей и маршрутизатор, стоящий за одним API, совместимым с OpenAI, дающим доступ к 400+ моделям от 70+ провайдеров. LangChain — это фреймворк оркестрации, в котором вы строите цепочки и агенты. Вы используете OpenRouter как модель внутри LangChain через ChatOpenRouter.

Как использовать OpenRouter с LangChain?

Установите langchain-openrouter, установите OPENROUTER_API_KEY и создайте экземпляр ChatOpenRouter(model="provider/model"). Затем вызовите .invoke(...), .stream_events(...), .bind_tools(...) или .with_structured_output(...) как любую другую модель чата LangChain. Пакет находится в бета-стадии; закрепите версию из PyPI или npm. Путь TypeScript использует @langchain/openrouter с той же структурой.

Поддерживает ли LangChain вызов инструментов и структурированный вывод OpenRouter?

Да. Используйте model.bind_tools([...]) для инструментов и model.with_structured_output(Schema, method="json_schema") для типизированных ответов, оба с strict=True для принуждения схемы. Это первоклассные методы текущего пакета ChatOpenRouter и заменяют более старые обходные пути JSON-схемы на пути ChatOpenAI.

Могу ли я настроить маршрутизацию провайдеров или резервное копирование из LangChain?

Да. Передайте openrouter_provider={...} для управления провайдерами и model_kwargs={"models": [...]} для резервного копирования на уровне моделей. Резервное копирование провайдеров включено по умолчанию: OpenRouter выполняет балансировку нагрузки на основе цены и перенаправляет запросы от провайдеров со сбоем в последние 30 секунд. Неудачные запросы не оплачиваются; вы платите только за успешный запуск.

Нужен ли мне все еще паттерн ChatOpenAI + base_url?

Не в текущей версии LangChain. Выделенный пакет ChatOpenRouter является текущим путем и обеспечивает более чистый доступ к маршрутизации провайдеров, рассуждениям и структурированному выводу. Переопределение ChatOpenAI, указывающее base_url на https://openrouter.ai/api/v1 с вашим ключом OpenRouter, все еще работает как резервный вариант для старых версий LangChain, предшествующих пакету.

Какие модели я могу использовать?

Любую из 400+ моделей в каталоге, через slug provider/model. Проверьте openrouter.ai/models для актуальных строк, возможностей на уровне модели и цен. Доступные модели и ставки за токен меняются, поэтому относитесь к каталогу как к источнику истины.

09Что это значит на практике

Интеграция OpenRouter с LangChain через пакет langchain-openrouter — это не просто техническая замена API-ключа. Это архитектурное решение, которое повышает надежность ваших приложений. Вместо того чтобы писать сложную логику для обработки ошибок сети, переключения провайдеров при сбоях или управления несколькими ключами API, вы делегируете эти задачи платформе OpenRouter.

Для разработчиков из России и других регионов, где доступ к некоторым облачным сервисам может быть ограничен или нестабилен, возможность автоматического переключения между 70+ провайдерами является критически важной. Вы можете настроить openrouter_provider так, чтобы запросы шли через провайдеров с низкой задержкой или тех, кто не собирает данные, обеспечивая как скорость, так и конфиденциальность. Кроме того, экономическая эффективность достигается за счет балансировки нагрузки на основе цены: OpenRouter выбирает наиболее выгодного провайдера для каждой модели, что может существенно снизить затраты на токены в высоконагруженных приложениях.

В конечном итоге, использование ChatOpenRouter позволяет вам сосредоточиться на логике вашего агента, промптах и пользовательском опыте, а не на инфраструктурных проблемах. Это делает разработку AI-приложений более быстрой, безопасной и масштабируемой.

Источник: OpenRouter ↗