Как развернуть inference-сервер с Replicate

После выполнения этой инструкции вы запустите локальный HTTP inference-сервер на базе Replicate Cog и проверите его через GET /health-check и POST /predictions. Если вам нужен не локальный процесс, а управляемый приватный endpoint, из той же модели можно перейти к Replicate Deployments.

• ⏱️ Время: редакционная оценка 20–40 минут, если Docker и Cog уже установлены; дольше, если вы ещё не подготовили predict.py.
• 🎯 Сложность: средний.
• 💰 Стоимость: локальный запуск зависит от вашей машины; Replicate использует usage-based billing, а private deployments тарифицируются по setup, idle и active time. Актуальные ставки и железо перепроверьте на официальной странице pricing.
• 🛠️ Что потребуется: macOS, Linux или Windows 11 через WSL2; установленный и запущенный Docker; установленный Cog; код или логика вашей модели для predict.py; аккаунт Replicate только если вы хотите перейти к облачному deployment.
• 📌 Актуальность: инструкция собрана по официальным источникам Replicate и Cog на 2026-08-15. Latest release page Cog показывала v0.21.0, но перед фиксацией версии перепроверьте текущий релиз.

Практический вердикт: если вам нужен HTTP endpoint для локальной отладки, достаточно cog serve. Если нужны автоскейлинг, rollout-контроль и rollback, локальный сервер не заменяет Replicate deployment. Редакционное ограничение: в этом source pack нет всех OS-специфичных команд установки Cog и полного актуального cloud-flow публикации версии модели, поэтому перед продакшен-развёртыванием перепроверьте README, release page и текущую документацию Replicate.

Пошаговая инструкция

1. Подготовьте поддерживаемое окружение и запустите Docker.

   Работайте на macOS, Linux или Windows 11 через WSL2: именно такие варианты описаны в официальных материалах Cog. Docker обязателен для использования Cog, поэтому перед началом запустите Docker и убедитесь, что вы планируете запускать сервер именно в таком окружении.

   Ожидаемый результат: у вас есть поддерживаемая ОС, Docker запущен, а Cog уже установлен или готов к установке по актуальному официальному README.

2. Инициализируйте пакет модели командой cog init.

   Создайте пустую рабочую директорию и выполните инициализацию. Это официальный стартовый путь для custom-model flow у Replicate.

   mkdir replicate-inference
   cd replicate-inference
   cog init

   Ожидаемый результат: в каталоге появляются как минимум файлы cog.yaml и predict.py.

3. Опишите контракт предсказания в predict.py и согласуйте его с cog.yaml.

   Именно эти два файла образуют базовую упаковку модели в официальном потоке Replicate/Cog. В predict.py задайте логику inference и входы, а в cog.yaml — конфигурацию образа и зависимости, которые нужны вашему предиктору.

   Здесь нет универсального рабочего примера для всех моделей: схема входного JSON для POST /predictions зависит от того, какие поля вы определите в predict.py. Если у вас уже есть готовый предиктор, просто приведите cog.yaml и код к одной схеме.

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

4. Поднимите локальный HTTP inference-сервер через cog serve.

   Для постоянного HTTP endpoint используйте именно cog serve. В официальном потоке также встречается cog run, но для server-сценария нужен режим serve.

   cog serve

   После старта Cog поднимет локальный HTTP API и выведет в терминал базовый адрес сервера. Сохраните этот адрес: дальше он нужен для проверки readiness и первого inference-запроса.

   Ожидаемый результат: сервер запущен, а в логах виден его базовый URL.

5. Проверьте readiness через GET /health-check.

   Сделайте запрос к health endpoint на базовом адресе, который показал Cog. Это официальный способ понять, что контейнер готов принимать inference-запросы.

   curl -i <BASE_URL>/health-check

   Ожидаемый результат: сервер возвращает 200 OK. Если этого нет, не переходите к inference: сначала проверьте логи сборки и старта контейнера.

6. Отправьте первый inference-запрос в POST /predictions.

   Теперь отправьте HTTP-запрос в основной endpoint предсказаний. Тело запроса должно соответствовать тем входным полям, которые вы определили в predict.py.

   curl -X POST <BASE_URL>/predictions 
     -H 'Content-Type: application/json' 
     -d '{"input":{"<поле_из_predict.py>":"<тестовое_значение>"}}'

   Это шаблон, а не универсальный payload: подставьте реальные имена полей и тестовые значения своей модели. Для многоаргументного предиктора просто добавьте остальные поля внутрь объекта input.

   Ожидаемый результат: вы получаете HTTP-ответ от prediction endpoint. Точная форма ответа зависит от вашей модели и актуальной реализации HTTP API, поэтому сверяйте схему с вашим кодом и документацией Cog.

7. Если нужен managed endpoint, создайте Replicate deployment из проверенной версии модели.

   Этот шаг нужен только если локальный сервер уже работает и вы хотите вынести модель в облачный private endpoint. По официальной документации deployment создаётся из Deployments area или со страницы версии модели. В конфигурации указываются name, version, hardware, min/max instances и cost estimate.

   Replicate описывает deployments как private dedicated API endpoints с autoscaling, rolling updates, canary deployments и instant rollbacks. Если же вам достаточно локальной отладки или собственного сервера без managed-слоя, на шаге 6 можно остановиться.

   Ожидаемый результат: у вас либо остаётся локальный Cog server, либо появляется облачный private deployment на стороне Replicate.

Как проверить, что всё работает

• Локальный сервер отвечает на /health-check. Проверка считается успешной, если вы видите 200 OK.
• POST /predictions принимает корректный JSON. Если запрос доходит до endpoint, но inference не стартует, почти всегда проблема в несоответствии полей из input вашему predict.py.
• Изменение входа меняет результат. Отправьте как минимум два разных тестовых запроса и убедитесь, что выход зависит от входных данных, а не от статического заглушечного кода.
• Для облачного варианта deployment находится в рабочем состоянии. Статус и параметры deployment проверяйте в текущем интерфейсе Replicate; точная детализация availability и регионов в официальных источниках из этого pack не закреплена.

Частые ошибки и исправления

• ❌ Ошибка: сервер не стартует локально.
  ✅ Решение: проверьте, что Docker действительно запущен. Cog требует Docker, и без него локальный server flow не работает.
• ❌ Ошибка: вы запускаете всё на Windows без WSL2 и сталкиваетесь с несовместимостью.
  ✅ Решение: используйте Windows 11 через WSL2 или переключитесь на macOS/Linux — именно такие варианты описаны в официальных материалах.
• ❌ Ошибка: /health-check не возвращает 200 OK.
  ✅ Решение: не тестируйте inference раньше времени. Дождитесь полного старта контейнера и перечитайте логи, которые выводит cog serve.
• ❌ Ошибка: POST /predictions отвечает ошибкой валидации или «ничего не происходит».
  ✅ Решение: сверяйте JSON с теми полями, которые вы определили в predict.py. Универсального payload для всех моделей у Cog нет.
• ❌ Ошибка: deployment проходит по бюджету или железо недоступно в ожидаемой конфигурации.
  ✅ Решение: перед созданием deployment ещё раз проверьте hardware options, cost estimate, billing и доступность в текущем UI Replicate. Эти параметры меняются со временем.

Безопасность и ограничения

• Cog даёт локальный HTTP API, но сам по себе не превращает модель в managed production platform с автоскейлингом.
• Для облачного сценария Replicate Deployments описаны как private dedicated endpoints. Если вам нужна именно приватность на стороне Replicate, ориентируйтесь на deployments, а не на локальный cog serve.
• При создании модели в Replicate можно выбирать visibility: public или private.
• Replicate использует pay-as-you-go billing; для private deployments отдельно учитываются setup, idle и active time.
• Hardware pricing и доступность железа нужно проверять прямо перед запуском: это time-sensitive параметры.
• Документация из этого source pack не фиксирует доступность deployment по регионам. Если регион критичен, перепроверьте это в текущем UI или support-материалах Replicate.
• В документации по созданию моделей отмечен лимит: до 1,000 моделей на аккаунт.

Что делать дальше

• Если вам важнее максимальная скорость inference для LLM, сравните этот путь с vLLM для быстрого inference.
• Если вы хотите полностью свой стек без привязки к managed-платформе, посмотрите инструкцию как развернуть open-source LLM на сервере.
• Если нужен локальный OpenAI-совместимый endpoint, изучите LocalAI — локальный inference stack с OpenAI-совместимым API.
• Если вы выносите inference в сервис и хотите трассировку вызовов, добавьте наблюдаемость через LangSmith.

Источники

• Deploy a custom model
• Create a deployment
• Deployments
• Create a model
• Run a model
• Official models
• Pricing
• Billing
• replicate/cog
• Release v0.21.0 · replicate/cog
• HTTP API

Вопросы и ответы

Можно ли развернуть inference-сервер с Replicate без облачного deployment?

Да. Официальный путь начинается с локального запуска через Cog и cog serve. Этого достаточно, если вам нужен локальный HTTP endpoint для отладки или внутреннего использования.

Нужен ли Docker?

Да. В официальном репозитории Cog прямо указано, что Docker обязателен для использования.

Работает ли это на Windows?

Официально в материалах Cog описан вариант для Windows 11 через WSL2. Если вы запускаете всё на Windows без WSL2, этот маршрут не считается базовым поддерживаемым сценарием из текущего source pack.

Когда нужен Replicate deployment, а когда достаточно Cog?

Если вам нужен локальный server и проверка модели, достаточно Cog. Если нужен private dedicated endpoint с autoscaling, rolling updates и rollback, переходите к Replicate Deployments.

Можно ли просто взять official model вместо своего сервера?

Да, если вам не нужен собственный образ модели. Official models у Replicate описаны как managed always-on APIs; для их HTTP path документация отдельно отмечает, что версию можно не указывать.