Настройка окружения | Курс LangChain урок 0

Цель урока: собрать окружение курса, получить ключ провайдера модели и скриптом проверить, что вызов модели из кода проходит.

Необходимые знания:

1) Python на уровне джуниора: функции, классы, аннотации типов

2) декораторы и Pydantic на базовом уровне, они понадобятся с урока 6

3) представление о том, что такое запрос по HTTP и что такое переменная окружения

4) командная строка: поставить пакет, запустить скрипт

Ключевые концепции:

1) виртуальное окружение и пакеты провайдеров моделей

2) init_chat_model и формат имени provider:model

3) переменные окружения и файл .env

4) параметр base_url и адреса, совместимые с OpenAI

5) типы исключений модели из langchain_core.exceptions

6) версии пакетов и политика поддержки версий

Зачем нужен нулевой урок

Дальше по курсу установка встречается один раз, в уроке 12, и там ставится один пакет. Окружение собирается здесь, а с урока 1 примеры идут так, будто оно у вас уже готово. Поэтому урок 0 заканчивается не заданием на понимание, а работающим скриптом.

Для кого этот курс

Курс написан для разработчиков на Python уровня джуниор и выше. Предполагается, что язык вы знаете и понимаете декораторы, а Pydantic видели хотя бы в чужом коде.

Машинное обучение знать не нужно. Курс про то, как собрать приложение вокруг готовой модели, а не про то, как модель обучить.

После курса вы умеете собрать агента, который:

1) использует инструменты и сам решает, какой вызвать

2) помнит текущую сессию и то, что было между сессиями

3) не переполняет контекстное окно на длинном диалоге

4) спрашивает разрешения человека перед опасным действием

5) переживает падение внешнего сервиса и повторяет запрос

6) проверяется набором примеров, а не ощущением автора

Границы курса

Темы которых нет в курсе.

RAG и поиск по документам не входят. Это отдельный курс.

LangGraph подаётся ровно настолько, насколько он виден из create_agent. Агент в LangChain, это граф, и в этом курсе речь пойдёт именно о его узлах. Состояние, рёбра, условные переходы, подграфы и возобновление, это отдельный курс.

deepagents не входит. Это готовый харнесс поверх агента LangChain, и это третий курс.

Нет интерфейса агента. Это про фронтенд и React, и клиентский код, а этот курс для разработчиков на Python.

Какой нужен Python

Документация даёт две разные цифры.

1) страница установки говорит "Requires Python 3.10+" в комментарии к команде

2) страница быстрого старта отдельной врезкой говорит: чтобы запустить код быстрого старта, используйте Python 3.11 или выше

На 3.10 пакет поставится, но за поведение примеров на нём я не отвечаю.

Проверьте, что у вас стоит:

python --version

Окружение и пакеты

Окружение курса, это venv рядом с проектом. На macOS и Linux:

python3.11 -m venv .venv
source .venv/bin/activate

На Windows команды python3.11 нет, используйте py:

py -3.11 -m venv .venv
.venv\Scripts\activate

Весь набор курса ставится одной командой:

pip install -U "langchain[openai]" langgraph python-dotenv

Что в этой команде.

1) langchain[openai], основной пакет вместе с интеграцией провайдера. Сам по себе langchain не умеет ходить ни к одному провайдеру, интеграции ставятся дополнением в квадратных скобках. Работаете не с OpenAI, возьмите своё дополнение из таблицы провайдеров ниже, в разделе про ключ

2) langgraph, на нём стоит агент, и с урока 12 вы работаете с его памятью сессии напрямую. Приехать он может и сам, зависимостью langgraph-prebuilt, но пакет, пришедший прицепом к чужой зависимости, в своём файле зависимостей держат отдельной строкой

3) python-dotenv, читает файл .env с ключом провайдера

Дальше по курсу ставится ещё один пакет: чекпойнтер на SQLite в уроке 12, там же сказано зачем.

При установке pip может напечатать уведомление о том, что доступна его более новая версия. Это уведомление, а не ошибка, на работу примеров оно не влияет.

Тот же набор, записанный файлом requirements.txt, пока без номеров версий:

langchain[openai]
langgraph
python-dotenv

Если вы работаете не с OpenAI, поменяйте дополнение в первой строке на своё. Как закрепить номера версий и зачем это нужно, разобрано в следующем разделе.

Заведите рядом файл .gitignore, чтобы ключ не уехал в репозиторий:

.env
.venv/
__pycache__/
*.pyc

Версии, на которых стоит курс

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

Номера в колонке "по документации", это последние записи в журнале изменений пакетов для Python на момент написания курса.

Про имя модели есть расхождение. На странице цен провайдера линейка называется deepseek-flash, а шлюз это имя не принимает и отвечает 400 model_not_found. Прежнее имя deepseek/deepseek-v4-flash принимается. Ставьте в MODEL_NAME то имя, которое принимает ваш адрес, имя из прайса берите как подсказку.

В колонке "прогон примеров курса" стоят точные номера установленных пакетов. Отсюда два способа записать свой requirements.txt.

1) перенести номера из этой колонки, закрепить их знаком == и переустановить набор поверх уже поставленного, командой pip install -r requirements.txt. Соберётся то же окружение, на котором получен вывод примеров в уроках. Закрепите заодно langchain-core и langchain-openai: код курса обращается к ним напрямую, а приезжают они зависимостями

2) оставить одни имена пакетов, без номеров. Приедут свежие версии, и надо быть готовым к расхождениям с выводом в уроках

Колонки таблицы не сходятся между собой, и это нормально. Журнал изменений объявляет минорные выпуски, 1.4.0 и 1.2.0, а с индекса пакетов к вам приедет последний патч той же ветки, 1.4.2 и 1.2.11. Патч это исправления и обновления безопасности без изменений в API.

Про сами номера версий полезно знать две вещи.

1) LangChain 1.0 и LangGraph 1.0 объявлены выпусками с долгой поддержкой. Пока не вышла версия 2.0, ветка 1.x остаётся активной, а переход между минорными версиями внутри неё безопасен по semver. Это значит, что 1.4.0 не сломает вам код, написанный на 1.1.0, и по той же причине патч свежее курсового вас беспокоить не должен

2) старые ветки, LangChain 0.3 и LangGraph 0.4, находятся в режиме поддержки до декабря 2026 года. Если вы читаете статью с LLMChain и цепочками, вы читаете про эту ветку

Версии у себя смотрят командой, и здесь есть подвох.

Привычный способ, атрибут пакета:

import langchain_core
print(langchain_core.__version__)

import langgraph
print(langgraph.__version__)

Первая половина работает. Вторая падает с AttributeError: пакет langgraph собран как пространство имён, атрибута __version__ у него нет. Документация этот способ по-прежнему советует, но с 17.03.2026 она не обновлялась и в этом месте отстала от пакета.

Рабочий способ, одинаковый для всех трёх пакетов, лежит в стандартной библиотеке Python. Он спрашивает номер не у пакета, а у менеджера пакетов:

from importlib.metadata import version

print(version("langchain"))
print(version("langchain-core"))
print(version("langgraph"))

Обратите внимание на имя: здесь пишется имя дистрибутива через дефис, langchain-core, а не имя модуля через подчёркивание. Эти три строки пойдут в проверочный скрипт.

Ключ провайдера и переменные окружения

Модель находится не у вас, а у провайдера, и каждый запрос к ней оплачивается по токенам. Значит, нужен ключ, а ключ нельзя хранить в коде.

Два способа: переменная окружения в оболочке или файл .env.

export OPENAI_API_KEY="your-api-key"

OPENAI_API_KEY=your-api-key

Имя переменной задаёт не LangChain, а провайдер. В таблице указан пакет, которым ставится интеграция:

Колонка "что ставить" подставляется в команду установки из раздела про окружение, на место langchain[openai]. У всех провайдеров, кроме OpenRouter, это дополнение основного пакета в квадратных скобках, у OpenRouter отдельный пакет.

Для Ollama ключ нужен только облачному сервису, локально запущенной модели он не требуется. Ниже написано именно про локальный запуск.

Файл .env сам себя в переменные окружения не превращает. Его читает библиотека python-dotenv, вызовом load_dotenv().

from dotenv import load_dotenv

load_dotenv()

Создайте файл .env рядом со скриптом и положите в него три строки, значения подставьте свои:

# Ключ провайдера. Для OpenAI и для любого адреса, совместимого с OpenAI.
OPENAI_API_KEY=

# Имя модели из списка вашего провайдера.
MODEL_NAME=

# Адрес, совместимый с OpenAI Chat Completions API.
# Оставьте пустым, если работаете с провайдером напрямую.
MODEL_BASE_URL=

Две переменные MODEL_NAME и MODEL_BASE_URL, это переменные курса, а не переменные LangChain. Фреймворк про них не знает, их читает код примера и передаёт значения в вызов. Сделано это для того, чтобы имя модели менялось в одном месте, а не в двадцати файлах примеров.

Смена провайдера, это одна строка

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

Каждая модель в LangChain реализует один и тот же интерфейс, независимо от провайдера. Выглядит это так:

from langchain.chat_models import init_chat_model

openai_model = init_chat_model("openai:gpt-5.5")
anthropic_model = init_chat_model("anthropic:claude-opus-4-8")
google_model = init_chat_model("google-genai:gemini-3.1-pro-preview")

for model in [openai_model, anthropic_model, google_model]:
    response = model.invoke("Explain quantum computing in one sentence.")
    print(response.text)

Строка "openai:gpt-5.5" читается как провайдер:модель. По префиксу init_chat_model сам находит нужный пакет интеграции и подставляет нужный класс. Префикс можно опустить, если имя модели однозначно.

Провайдера вы выбираете сами. Курс не привязан ни к одному из них и работает с любым, кто отдаёт совместимый протокол. Ниже три пути, и они отсортированы по тому, сколько от вас требуется: карта, зарубежный счёт, своё железо.

Путь первый, модель на своём железе. Единственный, который не требует ни карты, ни счёта за границей, ни оплаты за токены. Ollama один из самых доступных способов запустить у себя модель. Это же ответ на вопрос приватности: данные не уходят наружу.

from langchain.chat_models import init_chat_model

model = init_chat_model("ollama:devstral-2")

У этого пути есть ограничение. Небольшая модель на домашней машине заметно хуже держит вызов инструментов, а на вызове инструментов стоит половина курса, начиная с урока 9. Если агент у вас перестанет вызывать инструменты там, где в уроке он их вызывает, первым делом подозревайте модель, а не свой код.

Путь второй, маршрутизатор. По-английски router, он же прокси или шлюз: доступ к моделям многих провайдеров через один API и один счёт. У OpenRouter для него есть пакет langchain-openrouter, у LiteLLM пакет langchain-litellm, FuturMix подключается через ChatOpenAI.

from langchain.chat_models import init_chat_model

model = init_chat_model("openrouter:anthropic/claude-sonnet-4-6")
response = model.invoke("Hello!")

Путь третий, свой адрес, совместимый с OpenAI. Многие провайдеры отдают тот же протокол, что и OpenAI Chat Completions API, например Together AI и vLLM. Подключение к любому такому адресу:

model = init_chat_model(
    model="MODEL_NAME",
    model_provider="openai",
    base_url="BASE_URL",
    api_key="YOUR_API_KEY",
)

То же самое напрямую через класс:

from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    base_url="https://your-provider.com/v1",
    api_key="your-api-key",
    model="provider-model-name",
)

Здесь есть "но", и упрётесь вы в него на уроке 6. ChatOpenAI реализует официальную спецификацию OpenAI и только её. Нестандартные поля, которые сторонний провайдер кладёт в ответ, не извлекаются и не сохраняются. Если вам нужны особенности конкретного провайдера, берите его собственный пакет интеграции или маршрутизатор с отдельным пакетом.

Пример из моей практики, и его стоит читать именно как пример. Я работаю через шлюз rus-gpt.com: регистрация по аккаунту Яндекса, оплата рублями с российской карты. Протокол совместим с OpenAI, поэтому подключается шлюз теми же двумя параметрами, base_url и api_key. Это мой выбор, а не рекомендация, и условия проверяйте сами. Механика от выбора шлюза не зависит: любой совместимый адрес подключается одинаково.

Проверочный скрипт ниже написан так, что все три пути работают без правки кода.

Проверочный скрипт

Скрипт делает три вещи: печатает версии пакетов, собирает модель и делает один короткий запрос. Если он дошёл до конца, окружение курса готово.

Ниже текст скрипта. Скопируйте его в файл check_setup.py и запускайте.

import os
from importlib.metadata import version

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model

# Читает файл .env из текущей папки и кладёт значения в переменные окружения.
load_dotenv()

for package in ("langchain", "langchain-core", "langgraph"):
    print(f"{package}: {version(package)}")

# MODEL_NAME и MODEL_BASE_URL, это переменные курса, а не переменные LangChain.
# Фреймворк про них ничего не знает, мы сами передаём их значения в вызов.
model_name = os.environ["MODEL_NAME"]
base_url = os.getenv("MODEL_BASE_URL")

if base_url:
    # Путь для любого адреса, совместимого с OpenAI Chat Completions API.
    model = init_chat_model(
        model=model_name,
        model_provider="openai",
        base_url=base_url,
        api_key=os.environ["OPENAI_API_KEY"],
        temperature=0,
    )
else:
    # Путь напрямую к провайдеру. Ключ берётся из переменной окружения,
    # имя которой задаёт сам провайдер (например, OPENAI_API_KEY).
    model = init_chat_model(model_name, temperature=0)

response = model.invoke("Ответьте одним словом: готово")

print(response.text)
print(response.usage_metadata)

# Вывод:
# langchain: 1.4.2
# langchain-core: 1.6.3
# langgraph: 1.2.11
# Готово
# {'input_tokens': 12, 'output_tokens': 4, 'total_tokens': 16,
#  'input_token_details': {}, 'output_token_details': {}}

Запуск:

python check_setup.py

В этом коде принято пять решений.

Версии через importlib.metadata, а не через __version__. Атрибута __version__ у langgraph нет, разбор был выше. В скрипте стоит рабочий вариант, и он же показывает, что окружение собрано целиком. Если пакет не поставился, строка отвалится с PackageNotFoundError до того, как дело дойдёт до сети и денег.

temperature=0. Температура, это документированный параметр модели, он управляет случайностью вывода: выше число, разнообразнее ответ, ниже число, предсказуемее. Ноль стоит здесь как самое предсказуемое из доступных значений, а не как гарантия. Он убирает случайность выбора следующего токена там, где провайдер этот параметр вообще применяет.

При нулевой температуре не обязаны повторяться ни числа в usage_metadata, ни сам текст. Три прогона этого скрипта на одном ключе разошлись и в тексте, и в счётчике. Ответ пришёл то с точкой в конце, то без неё. Выход насчитал 4 токена в одном прогоне и 5 в двух других. На модели курса, как покажет замер в уроке 1, температура не применяется вовсе, и там разошёлся даже текст. Отсюда правило, которое понадобится в уроке 22 (он выйдет позже): проверять модель и агента сравнением с эталонной строкой нельзя, сравнивают поведение. В уроке 1 разберу, почему так и чем это мерять.

model.invoke("строка"). Модели можно передать одну строку, а можно список сообщений с ролями. Одной строки достаточно, чтобы проверить, что запрос уходит и ответ приходит. Роли и типы сообщений, это тема урока 3.

response.text. Метод invoke возвращает не строку, а объект сообщения модели. У него есть атрибут text с текстовым содержимым, и пишется он без скобок. Форма со скобками, response.text(), в текущей версии тоже отработает, но напечатает предупреждение о снятии с поддержки в версии 2.0.0. Если увидите её в чужом коде или в старой статье, это признак возраста примера. И отдельно: если invoke вернул строку, а не объект сообщения, вы взяли класс старого текстового интерфейса BaseLLM. Модели, которые собирает init_chat_model, всегда отвечают объектом AIMessage.

response.usage_metadata. Здесь лежат счётчики токенов, если провайдер их вернул. Поле объявлено как необязательное, и None в выводе, это не ошибка, а провайдер, который счётчики не отдаёт. Дальше по курсу по ним считаются деньги.

Распространённые ошибки

Все четыре ошибки ниже отдают типизированные исключения: основные пакеты интеграций поднимают стандартные типы из langchain_core.exceptions. Эти типы наследуются одновременно от базового типа LangChain и от типа исключения в SDK провайдера, так что ловить можно любой из двух.

У каждого типа есть атрибут is_retryable, и его учитывает средний слой повторов. Текст сообщения внутри исключения приходит от провайдера и у разных провайдеров разный, поэтому ловите тип, а не строку.

Оговорка по спискам "что проверить" ниже: авторы фреймворка пока помечают эти коды ошибок как относящиеся к версии для JavaScript. Причины отказа у провайдера общие для обоих языков, но на Python эти списки не проверены.

Ошибка 1: ключ не подхватился

# Неправильно: файл .env лежит рядом, но никто его не прочитал
from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.5", temperature=0)
# openai.OpenAIError: Missing credentials. Please pass an `api_key` ...

Что происходит: без ключа падает уже создание модели, до вызова дело не доходит. ChatOpenAI собирает клиента OpenAI прямо в конструкторе, а клиент без ключа не собирается. Ошибка приходит из пакета провайдера, openai.OpenAIError, и типом из langchain_core.exceptions она не является.

Ключ на месте, но неверный или истёкший, это уже другая история. Тогда модель создаётся, запрос уходит, и на invoke поднимается ModelAuthenticationError. Ловить можно и его, и OpenAIAuthenticationError из пакета интеграции, это один и тот же объект. Признак is_retryable у него False, повторять запрос бессмысленно.

Почему так: файл .env сам по себе на переменные окружения не влияет. Пока не вызван load_dotenv(), для процесса Python этого файла не существует.

Проверьте что: имя переменной написано без опечатки, значение у переменной есть, сторонний пакет вроде dotenv не помешал загрузке. И отдельным пунктом, способ обойти переменные окружения целиком и передать ключ явно.

# Правильно: сначала читаем .env
from dotenv import load_dotenv

load_dotenv()

# Или, если хотите исключить переменные окружения из уравнения,
# передайте ключ параметром
from langchain_openai import ChatOpenAI

model = ChatOpenAI(api_key="YOUR_KEY_HERE")

Ошибка 2: провайдер не узнаёт имя модели

# Опечатка в имени: лишний дефис, пропущенная цифра, чужой формат имени
model = init_chat_model("openai:gpt-5-5")
model.invoke("привет")   # ModelNotFoundError

Что происходит: поднимается ModelNotFoundError, провайдер не знает такого имени. Признак is_retryable у неё False: повторять тот же запрос бессмысленно.

Почему так: LangChain передаёт имя модели провайдеру как есть и не проверяет его у себя. Это же свойство даёт приятный побочный эффект: новая модель провайдера работает в тот день, когда вышла, обновлять LangChain для этого не нужно.

Причин две: опечатка в строке с именем и ограничения со стороны шлюза или обёртки, которые переименовывают или урезают список разрешённых моделей. Вторая причина касается вас, если вы работаете через адрес, совместимый с OpenAI. Список имён у шлюза свой, и имя, которое работает у OpenAI, там может не значиться.

# Правильно: имя берётся из списка вашего провайдера,
# а в курсе оно лежит в одной переменной
model = init_chat_model(os.environ["MODEL_NAME"], temperature=0)

Ошибка 3: упёрлись в ограничение частоты

for question in questions:          # сотня вопросов подряд
    model.invoke(question)          # ModelRateLimitError

Что происходит: поднимается ModelRateLimitError, вы превысили разрешённое провайдером число запросов за отрезок времени. У этого типа is_retryable равен True, то есть тот же запрос имеет смысл повторить позже.

Почему так: ограничение частоты стоит на стороне провайдера и обычно снимается само, когда окно истекает.

Что делать: поставить ограничитель частоты параметром rate_limiter при создании модели, кешировать ответы на повторяющиеся запросы, распределить запросы между несколькими провайдерами, попросить провайдера поднять лимит. Ограничитель частоты разберу в уроке 4.

Ошибка 4: сеть до провайдера не доходит

model.invoke("привет")   # ModelConnectionError или ModelTimeoutError

Что происходит: ModelConnectionError, если до провайдера не достучаться, и ModelTimeoutError, если ответ не пришёл за отведённое время. У обоих is_retryable равен True: повтор того же запроса может пройти.

Почему так: между вами и моделью сеть, и она не обязана работать.

Здесь важно знать поведение по умолчанию, иначе вы будете чинить то, что чинится само. Модели LangChain повторяют неудавшийся запрос с растущей паузой. Сетевые сбои, ограничение частоты (429) и ошибки сервера (5xx) повторяются. Ошибки клиента, например 401 или 404, никогда не повторяются, и это правильно: повторять запрос с неверным ключом бесполезно.

А вот число попыток по умолчанию у разных слоёв разное. В документации указано 6. В сборке курса это не так. ChatOpenAI из langchain-openai 1.6.2 держит max_retries пустым и передаёт число попыток клиенту OpenAI только тогда, когда вы задали его сами. У клиента по умолчанию 2. То есть на модели курса неудавшийся запрос повторяется дважды, а не шесть раз. Задавайте число попыток явно, тогда значения по умолчанию вас не касаются.

При нестабильном соединении поднимите число попыток и таймаут:

from langchain.chat_models import init_chat_model

model = init_chat_model(
    "google_genai:gemini-3.6-flash",
    max_retries=10,  # в документации указано 6, ChatOpenAI берёт 2 у клиента
    timeout=120,     # секунды
)

Практическое задание

Проверочный скрипт сейчас падает трассировкой. Для урока 0 это допустимо. Доведите его до состояния, в котором он объясняет причину отказа одной строкой.

Требования:

1) возьмите за основу check_setup.py из этого урока

2) оберните вызов модели в обработку исключений и разберите три типа отдельно: ModelAuthenticationError, ModelNotFoundError, ModelConnectionError. Импортируются они из langchain_core.exceptions

3) на каждый тип напечатайте одну строку подсказки на русском: что именно проверить в файле .env или в окружении

4) при отказе завершайте работу с кодом 1, при успехе с кодом 0

5) успешный путь оставьте прежним: версии пакетов, текст ответа, счётчики токенов

Как проверить результат, три прогона:

1) рабочий .env, скрипт печатает версии, ответ модели и счётчики, код возврата 0

2) в .env испорчен OPENAI_API_KEY, скрипт печатает подсказку про ключ, трассировки нет, код возврата 1

3) в .env испорчен MODEL_NAME, скрипт печатает подсказку про имя модели, код возврата 1

Подсказка: код возврата задаётся через raise SystemExit(1) в конце ветки обработки.

Итоги урока

Теперь у вас есть окружение, ключ и скрипт, который доказывает, что запрос к модели уходит и ответ приходит. Вы знаете, где закреплены версии курса, чем отличается переменная провайдера от переменной курса и что смена провайдера, это одна строка, а не переписывание кода.

И вы знаете, чего в курсе нет: поиска по документам, глубин LangGraph, харнесса deepagents и клиентского интерфейса.

Чего в этом уроке не хватило. Вы вызвали модель, не понимая, что она делает с вашей строкой. Непонятно, почему ответ на один и тот же вопрос каждый раз разный и откуда берётся счёт в токенах. Непонятно и то, почему модель уверенно выдумывает факты и почему у неё есть предел на длину разговора. Без этого дальнейшие решения курса выглядят набором правил, которые надо запомнить.

В уроке 1, "Как устроена языковая модель", разберу это устройство: токены и предсказание следующего, контекстное окно, температуру и то, во сколько обходится один запрос.

Код урока

Примеры этого урока лежат в репозитории курса, папка lesson_00. Закреплённые версии, на которых получен вывод в тексте, лежат в requirements.txt в корне репозитория.

Следующий урок: Как устроена языковая модель

Подписывайтесь на мой Telegram канал

Если вам нужен ментор и вы хотите научиться разрабатывать AI агентов, пишите, обсудим условия