LangChain и собственный API: Base URL, ключ и модель (2026)

LangChain сам по себе не является сервисом моделей: он связывает промпты, модели, инструменты и парсеры вывода в приложение. Если целевой сервис предоставляет OpenAI-совместимый интерфейс, его можно подключить через ChatOpenAI из langchain-openai, направив запросы на собственный Base URL. На практике чаще всего тормозят не фреймворк, а три поля: до какого уровня указывать адрес, откуда читается ключ и совпадает ли имя модели с тем, что опубликовано на шлюзе.

Материал идёт по порядку «установка — минимальный пример — переменные окружения — цепочки — стриминг — агенты — ошибки — миграция». Версии LangChain меняются быстро, поэтому имена классов и параметры сверяйте с документацией установленной версии.

Примечание: LangChain — товарный знак LangChain, Inc., OpenAI — товарный знак его правообладателя; материал не связан с указанными компаниями. Имена моделей и цены — на странице цены на модели, детали интерфейса — в официальной документации.

1. Установка: два основных пакета

Создайте виртуальное окружение и установите пакеты:

python -m venv .venv
source .venv/bin/activate
pip install -U langchain langchain-openai

langchain-openai — пакет интеграции с OpenAI и совместимыми интерфейсами, langchain даёт верхнеуровневые возможности вроде цепочек и агентов, а langchain-core устанавливается как зависимость. В продакшене фиксируйте версии в requirements.txt, чтобы на разных машинах не получались несовместимые API. Старый импорт langchain.chat_models.ChatOpenAI из прошлых руководств уже перенесён; новый путь — langchain_openai.

2. Минимальный пример: ChatOpenAI на собственный адрес

Ключевые параметра три: model, base_url и api_key. base_url обычно указывают до /v1, без /chat/completions — клиент добавит путь сам.

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="имя-вашей-модели",
    base_url="https://адрес-вашего-шлюза/v1",
    api_key="sk-ваш-ключ",
    temperature=0.3,
    timeout=60,
)

resp = llm.invoke("Объясни в одном предложении, что такое OpenAI-совместимый интерфейс.")
print(resp.content)

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

Запросите через curl base_url плюс /chat/completions и убедитесь, что адрес и ключ рабочие.
Создайте ChatOpenAI в Python и вызовите invoke один раз.
Напечатайте resp.content и resp.response_metadata, сверьте имя модели и поля расхода.
После успеха добавляйте шаблон промпта, парсер вывода и инструменты.

Если здесь возникает 404, проверьте уровень адреса; 401 — ключ и заголовок авторизации; сообщение об отсутствии модели — запросите /v1/models и сверьте имя. Имя модели должно точно совпадать с тем, что возвращает шлюз: регистр, суффикс даты и псевдоним тоже считаются различием.

3. Параметры и переменные окружения

Не вшивайте ключ в код. OpenAI SDK читает OPENAI_API_KEY, а также может читать OPENAI_BASE_URL; часть старых примеров и документации использует OPENAI_API_BASE. Поведение различается между версиями, поэтому надёжнее передавать параметры явно, а переменные окружения использовать как значения по умолчанию.

Параметр	Назначение	Обычная запись
`model`	Идентификатор модели	Совпадает с ответом `/v1/models`
`base_url`	Корневой адрес API	`https://host/v1`
`api_key`	Ключ авторизации	Передать явно или читать `OPENAI_API_KEY`
`temperature`	Случайность выборки	В пределах поддержки модели
`timeout`	Тайм-аут одного запроса	По длине задачи
`max_retries`	Число повторов на клиенте	Обычно около 2

Для локальной разработки можно использовать файл .env вместе с python-dotenv, но .env обязательно добавьте в .gitignore. В команде разделяйте ключи по проектам и средам, задавайте отдельные лимиты для теста и продакшена, чтобы при инциденте можно было отключить только нужный ключ.

4. Цепочки: соединяем промпт и модель через LCEL

Язык выражений LangChain (LCEL) собирает компоненты через символ трубопровода. Базовая цепочка — «промпт → модель → парсер вывода»:

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "Ты помощник технической поддержки. Отвечай конкретно, сначала давай вывод."),
    ("user", "{question}"),
])

chain = prompt | llm | StrOutputParser()
print(chain.invoke({"question": "До какого уровня указывать Base URL?"}))

invoke принимает один вход и возвращает один результат, batch обрабатывает список, stream отдаёт данные по частям. Парсер вывода превращает сообщение модели в строку или структурированный объект; если нужен JSON, сначала используйте структурированный вывод, поддерживаемый моделью, и только затем добавляйте разбор и валидацию — не полагайтесь на один промпт.

5. Потоковый вывод и пакетные вызовы

Стриминг подходит для чат-интерфейсов и длинных ответов:

for chunk in chain.stream({"question": "Объясни, что такое вызов инструментов"}):
    print(chunk, end="", flush=True)

Если invoke работает, а stream не выдаёт текст по частям, обычно виноват буферизующий прокси на пути или отсутствие поддержки потока у upstream. Проверьте, возвращает ли шлюз text/event-stream и отключена ли буферизация на обратном прокси. В пакетных вызовах учитывайте параллелизм: batch может отправлять запросы одновременно; при 429 снизьте параллелизм или разбейте вызовы на части, сохраняя неудачные элементы для повторного запуска.

6. Агенты: модель плюс инструменты плюс цикл

Агент по сути — цикл: модель решает, нужен ли инструмент, среда выполняет его и возвращает результат, модель определяет следующий шаг до финального ответа. В LangChain 1.x есть высокоуровневые интерфейсы вроде create_agent; в версиях 0.3 и раньше обычно использовался AgentExecutor. Синтаксис различается, поэтому копирование старых руководств часто приводит к ошибке импорта.

Инструмент описывается декоратором; имя функции, типы параметров и строка документации влияют на выбор модели:

from langchain_core.tools import tool

@tool
def get_order_status(order_id: str) -> str:
    """Возвращает статус доставки по номеру заказа."""
    return "Отправлено, ожидаемая доставка в течение трёх дней"

При подключении собственного шлюза учитывайте: вызов инструментов требует полной поддержки tools, tool_choice и формата возврата результатов. Некоторые совместимые сервисы реализуют только базовый диалог — при вызове инструментов они игнорируют параметры или возвращают ошибку. Сначала проверьте один инструмент на простом вопросе, затем увеличивайте их число и включайте параллельные вызовы.

7. Частые ошибки и диагностика

Симптом	Возможная причина	Что делать
401 Unauthorized	Ключ неверен, не передан или содержит пробелы	Передайте `api_key` явно, проверьте переменные окружения
404 model_not_found	Несовпадение имени модели или лишний путь в адресе	Запросите `/v1/models`, оставьте в `base_url` только `/v1`
429 Too Many Requests	Высокий параллелизм или исчерпана квота	Снизьте параллелизм, разбейте на пакеты, используйте задержку
400 context_length_exceeded	Вход превышает контекстное окно	Обрежьте историю, разделите документы, сначала суммируйте
OutputParserException	Формат ответа модели не соответствует ожиданиям	Задайте формат, добавьте проверку, повторите один раз
APIConnectionError / тайм-аут	Сеть, прокси, сертификат или сбой upstream	Проверьте переменные прокси, DNS и тайм-ауты
Вызов инструментов не реагирует	Upstream не поддерживает протокол tools	Смените модель или используйте обычную цепочку

При диагностике сначала обойдите LangChain и обратитесь к тому же адресу через curl или OpenAI SDK. Если прямое подключение работает, а LangChain нет — ищите в именах параметров, переменных окружения или версии; если падают оба — проблема в шлюзе, ключе или сети.

8. Миграция со старых версий

Путь импорта: langchain.chat_models.ChatOpenAI заменяется на langchain_openai.ChatOpenAI.
Имена параметров: model_name — на model, openai_api_base — на base_url.
Старый класс OpenAI для текстовых дополнений постепенно уступает чат-моделям; в новых проектах сразу используйте ChatOpenAI.
Старые цепочки и агенты в 1.x частично перенесены в пакет совместимости; перед миграцией прочитайте официальные примечания и не смешивайте несколько мажорных версий.
Управление зависимостями: перед обновлением зафиксируйте версии и прогоните ключевую цепочку в тестовой среде, особенно стриминг, вызов инструментов и структурированный вывод.

Частые вопросы

Нужно ли указывать `/v1` в base_url?

Большинство OpenAI-совместимых сервисов требует указывать до /v1, а клиент добавляет /chat/completions сам. Некоторые шлюзы размещают версию по другому пути — сверяйтесь с документацией провайдера. Простой критерий: curl-запрос на base_url + /chat/completions должен проходить.

Можно ли использовать переменную OPENAI_BASE_URL?

Да, OpenAI SDK её читает; часть старой документации называет её OPENAI_API_BASE. Поддержка зависит от версии, поэтому в продакшен-коде лучше передавать base_url явно, чтобы различия окружений не отправляли запрос не туда.

Почему invoke работает, а stream ничего не выводит?

Частые причины — буферизация прокси, отсутствие потоковой поддержки у upstream или обработка потока как обычной строки в коде. Сначала убедитесь, что тип ответа — поток событий, затем проверьте настройки обратного прокси и способ чтения.

Можно ли подключить через LangChain модели Claude, DeepSeek и другие?

Да. Если сервис предоставляет OpenAI-совместимый интерфейс, достаточно ChatOpenAI с другим адресом и именем модели; при нативном протоколе провайдера используется соответствующий пакет интеграции. Параметры и поддержка инструментов различаются, проверяйте их отдельно.

Агент возвращает ошибку параметров при вызове инструмента — что делать?

Сначала проверьте, соответствует ли структура вызова инструмента протоколу, затем — типы параметров и обязательные поля функции. Некоторые совместимые шлюзы не полностью поддерживают параллельные вызовы: отключите параллельность, дайте по одному инструменту и сужайте проблему.

Что дальше

Главное при подключении LangChain к собственному API — зафиксировать адрес, ключ и имя модели, проверить минимальным запросом и только затем добавлять цепочки и инструменты. Если нужен единый OpenAI-совместимый вход, виртуальные ключи и учёт расхода, зарегистрируйтесь в ZSQH AI Gateway; модели и цены — на странице цены на модели.