langfuse-hotswap

Горячая замена языковой модели в цепочке LangChain через промпт Langfuse.

Управление промптами в Langfuse выносит шаблон из кода: его правят в интерфейсе, присваивают версии метку production, и сервис забирает её сам. Модель при этом остаётся в коде. gpt-5.5, temperature=0.2 и max_tokens=800 прописаны рядом с цепочкой, и любое их изменение требует коммита и деплоя. В результате промпт, подобранный под одну модель, попадает в эксплуатацию с той моделью, которая была в последнем деплое.

langfuse-hotswap переносит модель в конфигурацию промпта:

{"provider": "openai", "model": "gpt-5.5", "temperature": 0.2, "max_tokens": 800}

и предоставляет LangChain Runnable, который при каждом вызове получает промпт, собирает по нему цепочку template | model и пересобирает её, когда промпт меняется. Код создаёт модели и определяет, какие их поля разрешено менять через Langfuse; Langfuse задаёт значения.

Возможности

• Одна версия промпта — одна модель. Шаблон, провайдер, имя модели и параметры версионируются, помечаются и откатываются вместе.
• Любая чат-модель LangChain. Создайте в коде ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI, ChatOllama или любую другую и передайте их фабрике под именами. Чтобы переключиться между ними, достаточно изменить конфигурацию.
• Полноценный Runnable. Поддерживаются invoke, ainvoke, stream, astream, batch, abatch, astream_events, with_fallbacks, with_retry и композиция с другими runnable.
• Только явно разрешённое. Конфигурация меняет лишь те поля модели, которые код перечислил в allowed_config_keys, и ничего, пока он этого не сделал. Ключи, адреса и HTTP-клиенты живут в объектах моделей, созданных в коде.
• Устойчивость к сбоям. Если новая версия промпта не собирается или Langfuse недоступен, последняя исправная цепочка продолжает обслуживать запросы, а ошибка записывается в журнал.
• Правила подстановки Langfuse — или ваши. Переменные подставляет TemplateParser из SDK, поэтому модель получает ровно то, что вы видите в playground. Плейсхолдеры поддерживаются. f-string, mustache и jinja2 включаются одним аргументом create.
• Трассировка привязана к промпту. Цепочка передаёт промпт в метаданных, поэтому трассы, собранные обработчиком обратных вызовов Langfuse, связаны с версией промпта.

Когда библиотека не нужна

• Один промпт, одна модель, менять её из интерфейса не планируется. Достаточно get_prompt() и init_chat_model().
• Смена модели обязана проходить код-ревью. Смысл библиотеки именно в том, что перенос метки меняет поведение в эксплуатации. В таком случае держите модель в коде, а Langfuse используйте только для шаблона.
• Модель должна выбираться для каждого запроса — по арендатору, по тарифу пользователя. Цепочка следует за промптом, а не за запросом. Создайте по цепочке на каждый промпт и распределяйте запросы между ними.
• LangChain не используется. Библиотека реализует Runnable LangChain поверх чат-моделей LangChain.
• Промпты редактируют люди, которым нельзя доверять. По умолчанию они могут лишь переключаться между моделями, созданными в коде, но каждый разрешённый ключ — параметр в их руках, в том числе лимит токенов и, как следствие, стоимость. Сначала ограничьте доступ к метке production в Langfuse.

Требования

Python 3.11+, langchain-core>=1,<2, langfuse>=4,<6, а также пакет LangChain для каждого используемого провайдера. Формату шаблонов jinja2 нужна дополнительная зависимость jinja2. Пакет содержит маркер py.typed.

Неофициальный проект, не связанный с Langfuse и LangChain.

Куда дальше

Быстрый старт запускает цепочку за шесть шагов. Понятия называют части библиотеки; в руководстве каждой посвящена страница. Как это работает объясняет механизм и сравнивает библиотеку с использованием SDK напрямую.