Dify объединяет оркестрацию промптов, базу знаний, воркфлоу и агентов в одном визуальном интерфейсе. Сам по себе он не производит модели: возможности приходят от подключённых провайдеров. Распространённая практика команд — развернуть Dify на собственном сервере и подключить единый API-шлюз через OpenAI-совместимый интерфейс, оставив управление ключами, моделями и расходом на стороне шлюза.

Далее — порядок: развёртывание, добавление провайдера, заполнение параметров, минимальный воркфлоу, командное использование и защита. Названия интерфейса, плагинов и переменных сверяйте с официальной документацией текущей версии; модели и цены — на странице цены на модели, тарифы могут меняться.

Примечание: Dify — товарный знак его правообладателя. Материал носит технический характер и не означает подчинения или сотрудничества с указанными компаниями.

1. Облако или собственный сервер

Dify предлагает облачный сервис и community-версию для самостоятельного развёртывания. Облако избавляет от эксплуатации и подходит для быстрой проверки; при самостоятельном развёртывании данные остаются на вашем сервере, что важно для команд с требованиями к сети, данным и правам.

  • Только пробный запуск: облако быстрее, но проверьте расположение данных и доступность сети.
  • Нужны внутренние модели или собственные плагины: самостоятельное развёртывание гибче, но обновления, резервные копии и HTTPS — на вас.
  • Долгая командная работа: в обоих случаях планируйте роли участников, управление ключами и бюджет.

2. Развёртывание через Docker Compose

Для community-версии рекомендуется Docker Compose. Текущая документация указывает минимум 2 ядра CPU и 4 GiB памяти; виртуальной машине Docker Desktop на macOS рекомендуется не менее 8 GiB. Для Linux нужны Docker 19.03 или новее и Compose 2.24 или новее.

  1. Клонируйте репозиторий на последнем теге release; понадобятся git, curl и jq.
  2. Перейдите в каталог dify/docker и скопируйте .env.example в .env.
  3. Запустите сервисы командой docker compose up -d.
  4. Проверьте состояние через docker compose ps и дождитесь готовности сервисов.
  5. Откройте http://адрес-сервера/install, создайте администратора, затем войдите через корневой адрес.
git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
docker compose up -d
docker compose ps

По умолчанию доступ идёт через порт 80, точка инициализации — /install. Количество контейнеров меняется от версии к версии, не ориентируйтесь на старые руководства; статус Exited у init_permissions обычно означает разовую задачу и является нормой.

Конфигурация хранится в .env и перекрывает одноимённые переменные в envs/. После изменений выполните docker compose down, затем up -d. Перед обновлением прочитайте примечания к версии, сравните новые переменные в .env.example и не переносите старый compose-файл без проверки.

3. Добавление OpenAI-совместимого провайдера

Управлять провайдерами моделей могут только владелец рабочего пространства и администраторы. Вход обычно находится в Integrations или в настройках Model Provider: сначала установите плагин OpenAI-API-compatible, затем нажмите Setup и заполните учётные данные. Названия меняются от версии к версии; если не нашли пункт, сверьтесь с текущей документацией.

Типичный порядок добавления модели:

  1. Установите или включите OpenAI-совместимый плагин.
  2. Укажите API Key и собственный Base URL.
  3. Сохраните и дождитесь успешной проверки учётных данных.
  4. Добавьте модель и выберите её тип.
  5. Заполните имя модели, длину контекста и переключатели возможностей.
  6. Проверьте через тестовый вход или минимальное приложение.
Поле Как заполнять Частая ошибка
Base URL Обычно до /v1, например https://ai.zhongshangqihang.com/v1 Добавляют /chat/completions и получают 404
API Key Вставляют целиком, без ручного Bearer Пробелы, переводы строк или кавычки дают 401
Имя модели Совпадает с /v1/models или страницей цены на модели Ошибка в регистре или суффиксе даты — model not found
Тип модели LLM, Embedding, Rerank, речь и другие — по назначению Неверный тип, и модель не видна в приложении
Длина контекста Реальное значение провайдера с запасом Указывают теоретический максимум, длинный запрос отклоняется
Возможности Потоковый вывод, вызов функций, зрение — по фактической поддержке Агент не вызывает инструменты, загрузка изображений отклоняется

Под одним провайдером можно добавить несколько моделей и настроить каждую отдельно. В названии полезно указывать назначение или версию. После подключения Embedding-модели к базе знаний размерность фиксируется; при смене модели индекс обычно приходится пересоздавать.

4. Сначала проверка через curl, потом тест в Dify

Если тестировать сразу в интерфейсе, при сбое трудно понять, где проблема: в шлюзе, сети или полях. Сначала проверьте upstream через curl:

export ZSQH_API_KEY="sk-ваш-ключ"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ваш-model-id","messages":[{"role":"user","content":"Ответь только OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Ответ с choices означает, что ключ, адрес и имя модели корректны. 401 — проверьте ключ, 404 — путь, model not found — имя модели. Base URL указывайте до /v1, а не полный путь интерфейса; Bearer вручную не добавляйте, Dify добавит его сам.

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

5. Минимальный воркфлоу

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

  1. В Studio создайте Workflow или Chatflow: для диалога — Chatflow, для пакетной обработки и автоматизации — Workflow.
  2. В начальном узле определите входную переменную, например query.
  3. Добавьте узел LLM, выберите только что подключённого провайдера и модель, сошлитесь на переменную начального узла в промпте.
  4. Добавьте конечный узел и передайте вывод LLM в выходную переменную.
  5. Запустите тест с реальным вопросом и просмотрите вход, выход и расход токенов по каждому узлу.
  6. После проверки опубликуйте и вызывайте через встроенную страницу или API приложения.

Если нужен поиск, добавьте перед LLM узел поиска по знаниям и заранее настройте Embedding и Rerank в настройках рабочего пространства. Для ветвления используйте классификатор вопросов или условный переход. Узел Agent подходит для вызова инструментов, но выбирайте модель с поддержкой вызова функций: сначала проверьте инструменты отдельно, затем включайте в основной процесс.

Для каждого узла LLM и Agent модель можно выбрать отдельно; узлы без выбора используют модель рабочего пространства по умолчанию. Для простой классификации и переписывания хватит небольшой модели, для финальной генерации — сильной. Ключевые узлы лучше привязывать явно, чтобы поведение не менялось при смене модели по умолчанию.

6. Командная работа: участники, ключи и среды

Участники рабочего пространства обычно делятся на владельца, администратора, редактора и обычного участника; права зависят от версии и тарифа. Учётные данные провайдера относятся ко всему рабочему пространству, а не к личным настройкам, поэтому число администраторов стоит ограничивать.

  • Для разработки и продакшена используйте разные учётные данные или ключи — так проще ставить лимиты и отзывать доступ.
  • Для каждого приложения создавайте отдельный API Key; ключ приложения действует только на это приложение, но охватывает всех его конечных пользователей.
  • Вызывающая сторона различает пользователей параметром user; не встраивайте ключ приложения во фронтенд или клиент.
  • Корневой адрес сервисного API Dify Cloud — https://api.dify.ai/v1; при самостоятельном развёртывании используйте свой домен с /v1.
  • Заголовок запроса — Authorization: Bearer <key>; вызывайте API только с бэкенда.

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

7. Чек-лист безопасности и эксплуатации

  1. Включите HTTPS и не выставляйте порт 80 напрямую; обратный прокси должен отвечать и за сертификат, и за контроль доступа.
  2. После инициализации ограничьте /install, используйте сильные пароли и включите доступную двухфакторную аутентификацию.
  3. Храните ключи только в .env или менеджере секретов, не коммитьте их в репозиторий; при смене участников выполняйте ротацию.
  4. Открывайте в файрволе только необходимые порты; база данных и векторное хранилище не должны быть доступны из интернета.
  5. Настройте SSRF-прокси и сетевой выход по текущей документации; перед изменением сети прочитайте описание .env.
  6. Регулярно делайте резервные копии PostgreSQL, загруженных файлов и .env и проверяйте восстановление.
  7. Перед обновлением создавайте копию, фиксируйте тег release и следуйте примечаниям соответствующей версии.
  8. На стороне шлюза задайте бюджет, лимиты параллелизма и оповещения, чтобы циклы не расходовали квоту.
  9. В узлах кода запускайте только собственный проверенный код и не считайте их универсальной границей безопасности.

Безопасность — не разовая настройка, а процесс, который пересматривают при обновлениях, смене участников и ротации ключей.

8. Быстрый справочник ошибок

  • 401 Unauthorized: неверный ключ или лишние символы; вставьте заново и проверьте, что ключ относится к нужному провайдеру.
  • 404 или model_not_found: неверный путь Base URL или несовпадающее имя модели; сверьте /v1 и идентификатор.
  • Тайм-аут запроса: Dify не может достучаться до upstream или тот отвечает медленно; проверьте DNS, файрвол, прокси и SSRF.
  • Провайдер не устанавливается: недоступен маркетплейс плагинов или несовместима версия; проверьте сеть и документацию.
  • Модель не выбирается в приложении: неверный тип или узел не привязан; проверьте список моделей и конфигурацию узла.
  • Сбой поиска по базе знаний: несовпадение размерности Embedding или индекс не построен; смените модель или пересоздайте индекс.

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

Каков минимум для самостоятельного развёртывания Dify?

Текущая документация указывает 2 ядра CPU и 4 GiB памяти; для Docker Desktop на macOS рекомендуется не менее 8 GiB. На практике учитывайте параллелизм и объём базы знаний, а для продакшена оставляйте запас.

Как выбрать между Dify Cloud и собственным сервером?

Для быстрой проверки без эксплуатации выбирайте облако; если данные должны оставаться на вашем сервере, нужны внутренние сервисы или собственные плагины — самостоятельное развёртывание. Оба варианта подключают OpenAI-совместимые модели; разница — в ответственности за эксплуатацию и сетевых границах.

Провайдер добавлен, но модель не видна в приложении

Сначала проверьте тип модели, например не выбран ли Embedding вместо LLM; затем — добавлена ли модель под этим провайдером и привязана ли она к приложению или узлу. Некоторые узлы принимают только модели с определёнными возможностями.

Нужно ли выбирать модель для каждого узла отдельно?

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

Можно ли команде пользоваться одним API Key?

Можно, но не рекомендуется. Общий ключ не позволяет различить вызывающих, при утечке пострадает больше систем, а лимиты настроить сложнее. Выдавайте ключи по приложениям или средам, различайте конечных пользователей параметром user и регулярно меняйте ключи.

Что дальше

Подключение Dify можно разбить на четыре шага: запустить экземпляр, проверить upstream через curl, заполнить параметры моделей по их реальным возможностям и проверить привязку узлов на минимальном воркфлоу. Если нужен единый OpenAI-совместимый вход и управление расходом, зарегистрируйтесь в ZSQH AI Gateway; модели и тарификация — на странице цены на модели.

Читайте также: