Подключение Zukko к Dify: OpenAI-совместимый API для LLM-приложений

Dify — платформа для сборки LLM-приложений: чат-ботов, агентов и рабочих процессов в визуальном редакторе. Подключить к Dify OpenAI-совместимый API можно через плагин-провайдер OpenAI-API-compatible, и Zukko подключается именно так: один ключ fetch_... даёт модели Claude, GPT и GLM для любых узлов. Ниже — пошаговая настройка, разбор полей формы, выбор модели под задачу и типичные ошибки.

Как в Dify устроены провайдеры моделей

В актуальных версиях Dify провайдеры моделей ставятся как плагины. Для Zukko нужен плагин OpenAI-API-compatible — универсальный провайдер для сервисов с API в формате OpenAI. После установки к нему можно добавить любую модель по имени.

Управлять провайдерами могут только владелец и администраторы рабочего пространства. Подключённые модели становятся доступны всем приложениям этого пространства.

Подключение OpenAI-совместимого API в Dify: пошагово

1. Откройте Integrations → Model Provider (в старых версиях — настройки рабочего пространства → Model Provider).
2. Найдите OpenAI-API-compatible в разделе установки провайдеров или в Marketplace и установите плагин.
3. На карточке провайдера нажмите Add Model.
4. Заполните форму (таблица ниже) и сохраните. Dify проверит данные, прежде чем сделать модель доступной.
5. Повторите для каждой модели, которую хотите использовать. Повторно вводить ключ не обязательно: Dify хранит ключи провайдера, и их можно выбрать из сохранённых (Manage Credentials).

Поля формы

Пояснения к полям, на которых чаще всего ошибаются:

• API Base URL — подсказка в самом плагине выглядит как https://api.openai.com/v1, то есть адрес с /v1, но без /chat/completions. Для Zukko — ровно https://api.zukko.pro/v1.
• Model context size — по умолчанию 4096. Если оставить так, Dify будет считать, что модель принимает всего 4096 токенов, и на длинных промптах или больших фрагментах базы знаний сообщит, что запрос слишком длинный. Укажите реальный контекст: 1 000 000 для claude-opus-5-5, claude-sonnet-5, gpt-5.6-sol и gpt-5.6-luna, 128 000 для glm-5.3 и glm-5.3-flash. Можно и меньше, если хотите ограничить расход.
• Upper bound for max tokens — по умолчанию тоже 4096. Это верхняя граница ползунка max tokens в узлах; ставьте столько, сколько реально нужно для ответов.
• Function calling, Vision и другие возможности — в форме есть отдельные настройки для вызова инструментов, изображений и других типов ввода. Они нужны для агентов и узлов с инструментами. Включайте их, только если модель это поддерживает, и проверяйте на тестовом запросе.

Актуальный список id — GET https://api.zukko.pro/v1/models (см. документацию по моделям↗) или страница «Модели» в кабинете.

Модели по умолчанию и база знаний

Кнопка Default Models в правом верхнем углу страницы провайдеров задаёт модели, которые используются, если в приложении или узле модель не выбрана:

• System Reasoning Model — для общих задач; сюда можно поставить одну из моделей Zukko;
• Embedding Model и Rerank Model — для индексации и поиска в базе знаний.

Среди моделей Zukko сейчас только чат-модели, моделей эмбеддингов и реранкинга нет. Для базы знаний подключите отдельного провайдера эмбеддингов, а для генерации ответов используйте модели Zukko.

Выбор модели и стоимость

В Dify модель выбирается для каждого узла, и это удобно для экономии. Пример рабочего процесса из трёх LLM-узлов:

• классификация запроса на glm-5.3-flash, 800 токенов: 800 × $0.04 / 1 000 000 = $0.000032;
• основной ответ на claude-sonnet-5, 6 000 токенов: 6 000 × $0.3 / 1 000 000 = $0.0018;
• проверка ответа на gpt-5.6-luna, 1 500 токенов: 1 500 × $0.1 / 1 000 000 = $0.00015.

Итого $0.001982 за запуск, или около $1.98 за 1 000 запусков. Подходит ли дешёвая модель для конкретного узла, проверьте сами: прогоните через узел 20–30 реальных примеров на двух моделях, сравните результат и расход в разделе «Использование» кабинета.

Частые ошибки

Dify не сохраняет модель: проверка данных не прошла

Чаще всего виноват адрес (нет /v1 или есть лишний /chat/completions), id модели с опечаткой или ключ, скопированный не полностью. Проверьте все три поля.

401 и 403

401 — неверный ключ: он начинается с fetch_ и копируется целиком. 403 model_not_allowed_for_key — модели нет в списке разрешённых для этого ключа; добавьте её в настройках ключа в кабинете.

Запрос или промпт слишком длинный

Проверьте Model context size: если там осталось 4096, увеличьте значение до реального контекста модели. Если же запрос действительно превышает контекст, API вернёт 413 — сократите промпт или число фрагментов из базы знаний.

400 на моделях Claude

Модели claude-sonnet-5 и claude-opus-5-5 могут отклонять запрос с ошибкой 400, если temperature отличается от 1 или top_p меньше 0.99. В Dify параметры LLM-узла включаются по отдельности: для Claude оставьте temperature и top_p выключенными.

402 и 429

402 — закончился баланс, пополните его в кабинете. 429 — слишком частые запросы; при массовых запусках рабочих процессов снизьте параллельность.

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

Можно ли разделить расходы по приложениям?

Да. Создайте в кабинете отдельные ключи с собственными дневными и месячными лимитами и добавьте их в Dify как разные учётные данные. Расходы по каждому ключу видны в разделе «Использование», а как работают лимиты — описано в документации по лимитам ключей↗.

Работает ли это в облачной версии Dify и в self-hosted?

Плагин OpenAI-API-compatible доступен в обоих вариантах. В self-hosted версии убедитесь, что сервер Dify имеет выход в интернет к api.zukko.pro.

Нужен ли отдельный провайдер для моделей Claude?

Нет. Zukko сам конвертирует форматы, поэтому модели Claude добавляются в тот же провайдер OpenAI-API-compatible, что и GPT с GLM. Подробнее — в документации о выборе формата↗.

С чего начать?

Создайте ключ в кабинете Zukko↗, добавьте в Dify одну модель, например claude-sonnet-5, и соберите простой чат-бот, чтобы проверить подключение.