Непроизводственные развертывания позволяют запускать вашего агента параллельно с продакшеном под другим именем, чтобы вы могли протестировать изменения на реальной инфраструктуре до того, как они дойдут до пользователей.
Как только голосовой агент запущен, вам рано или поздно потребуется среда для тестирования изменений перед их выкатом: чтобы опробовать новую модель на реальной инфраструктуре до того, как к ней обратятся абоненты, дать коллеге послушать измененный промпт или запустить два агента рядом для сравнения.
До сих пор это означало создание совершенно второго агента со своим собственным проектом, ключами API и секретами, которые нужно синхронизировать. Это работает, но требует слишком много настроек для еще одного экземпляра кода, который вы уже развернули, и они начинают расходиться в тот момент, когда вы обновляете один и забываете про другой.
Непроизводственное развертывание — это ваш агент, работающий под другим именем: тот же образ, что и в продакшене, в том же проекте и с теми же секретами. У вас может быть сразу несколько таких развертываний, а создание нового занимает всего одну команду.
Как работают непроизводственные развертывания#
У каждого агента есть одно зарезервированное развертывание под названием production. Оно создается вместе с агентом, является целью по умолчанию для любой команды и продолжает работать после развертывания агента. То, что вы добавляете дополнительно — самое интересное.
Непроизводственное развертывание запускает тот же образ контейнера, что и продакшн. Вам не нужно собирать что-то отдельное. Вы указываете имя для сборки, и она разворачивается рядом с остальными. Она живет в том же проекте, использует те же секреты агента, а обратиться к ней можно с помощью одного флага: --deployment <name>. Если опустить флаг, вы работаете с продакшеном.
Непроизводственные развертывания также обходятся дешево в обслуживании. Одно из них переходит в спящий режим, когда им никто не пользуется, и просыпается при следующем запросе. Пока оно спит, вы ничего не платите, а когда бодрствует, его вычислительные ресурсы включаются в существующий счет вашего агента. Таким образом, развертывание для стейджинга, к которому вы обращаетесь дважды в неделю, остается неактивным и бесплатным все остальное время.
Последние две строки — это то, что стоит учитывать при планировании. Повторное развертывание в непроизводственной среде немедленно прекращает ее активные сессии, а откат (rollback) доступен только для продакшена. Продакшн обновляется плавно и дает активным сессиям до часа на завершение. Оставляйте трафик, который нельзя прерывать, на продакшене, а непроизводственные развертывания используйте как места для экспериментов.
Один агент, один набор секретов#
Секреты принадлежат агенту, и каждое развертывание этого агента имеет к ним доступ. Например, если ваш агент вызывает OpenAI в качестве внешнего провайдера моделей, задайте OPENAI_API_KEY один раз, и продакшн, стейджинг и любые другие развертывания будут читать одно и то же значение. Ничего не нужно копировать между разными местами и поддерживать в синхронном состоянии.
Когда непроизводственному развертыванию требуется другое значение — например, отдельный ключ для биллинга при тестировании или другой провайдер для одного конкретного сценария использования, — ваш агент выбирает его во время выполнения. Каждое развертывание знает свое собственное имя благодаря переменной окружения LIVEKIT_AGENT_DEPLOYMENT. Для непроизводственных развертываний это значение равно имени развертывания, а для продакшена оно пустое, поэтому вы можете использовать ветвление:
Тот же подход в Node.js:
Эта же переменная полезна, когда непроизводственному развертыванию требуется немного иное поведение во время выполнения. Прочитайте ее в начале кода вашего агента, и вы сможете протестировать новый промпт, модель или интеграцию в рамках развертывания с определенным именем, в то время как продакшн продолжит использовать стабильный путь.
Работа с развертываниями из CLI#
Команды create, deploy, promote, logs и delete поддерживают необязательный флаг --deployment. Передайте его, чтобы указать на непроизводственное развертывание, или оставьте пустым, чтобы команда применилась к продакшну. Чтобы запустить развертывание из того же кода, собескте и отправьте образ под определенным именем:
После этого используйте тот же флаг для остальных этапов жизненного цикла: просматривайте логи конкретного непроизводственного развертывания, продвигайте его проверенный образ в продакшн или удалите его, когда закончите. (Команды lk agent status, versions и list не поддерживают этот флаг. Вместо этого они выводят каждое развертывание в отдельной колонке.) Полный справочник по командам находится в документации, но сам принцип всегда остается неизменным.
Один флаг, с которым нужно быть осторожным: lk agent delete без флага --deployment удаляет всего агента целиком, включая продакшн. Всегда передавайте имя, если вы хотите удалить только непроизводственное развертывание.
Направление вызова на непроизводственное развертывание#
Код вашего агента не меняется. LiveKit Cloud сообщает агенту, в рамках какого развертывания он запущен, а SDK берет на себя все остальное.
Для этого требуется свежая версия SDK: livekit-agents 1.6 или новее для Python, @livekit/agents 1.7.1 или новее для Node. В более старых версиях агент определяется как продакшн, поэтому вызовы, предназначенные для него, никогда не доходят, и он начинает принимать реальный трафик. Обновитесь перед созданием.
Чтобы обратиться к непроизводственному развертыванию, укажите параметр deployment рядом с agent_name везде, где вы выполняете диспетчеризацию. Оставьте его пустым, и вы попадете на продакшн.
Самый быстрый способ направить реальный вызов на такое развертывание — использовать токен:
То же поле доступно в API диспетчеризации и в диспетчеризации на основе встроенных в токен данных, поэтому любой используемый вами способ будет работать одинаково.
Поскольку каждое развертывание находится в одном проекте под управлением одного набора ключей, вы можете описать процесс релиза с помощью правил для веток. Запускайте CLI в вашем рабочем процессе и выбирайте целевое окружение в зависимости от ветки: слияние с main обновляет стейджинг-развертывание, слияние с релизной веткой обновляет продакшн:
Чтобы перед выкаткой в продакшн требовалось одобрение человека, поместите эту задачу в окружение GitHub (GitHub environment) с обязательными рецензентами. Окружение GitHub и имя развертывания независимы друг от друга, поэтому вы можете настроить ворота проверки для продакшн-окружения, не меняя порядок выкладки в стейджинг.
Полезно знать#
Развертывания доступны на тарифе Ship и выше. Каждый тариф предоставляет определенное количество непроизводственных развертываний на агента: 2 для Ship и 5 для Scale. Одно развертывание учитывается в лимите независимо от того, бодрствует оно или спит, поэтому удаляйте его, чтобы освободить слот.
Вы создаете развертывания и управляете ими из CLI. В панели управления вы можете выбрать развертывание при диспетчеризации через Agent Console или правило SIP-диспетчеризации, а на странице с подробной информацией об агенте отображается, на каком развертывании работает каждая версия. Ограничение, о котором стоит знать на данный момент: продакшн — это единственное развертывание, которое отправляет метрики в Agent Observability, поэтому для проверки непроизводственного развертывания пока используйте логи. Метрики для каждого отдельного развертывания появятся в будущем.
Попробуйте#
Если вы используете тариф Ship или Scale, возьмите уже развернутого агента и запустите рядом с ним стейджинг-развертывание с помощью одной команды:
Полное руководство со всеми флагами, детальным описанием поведения LIVEKIT_AGENT_DEPLOYMENT и полей диспетчеризации смотрите в руководстве по развертыванию агентов.