> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Использование APIMart в Dify
> Подробное руководство по настройке и использованию API-сервиса APIMart в LLMOps-платформе Dify. Этот гайд поможет настроить APIMart API в Dify для создания мощных AI-приложений.
## Предварительные требования
Перед началом убедитесь:
1. **Аккаунт Dify зарегистрирован**
Зайдите на [официальный сайт Dify](https://dify.ai/) и зарегистрируйте аккаунт, выберите облачную или self-hosted версию
2. **Получен API-ключ APIMart**
Войдите в [консоль APIMart](https://apimart.ai/keys), чтобы получить API-ключ (начинается с `sk-`)
**Совет:** если у вас ещё нет аккаунта APIMart, сначала зарегистрируйтесь на [APIMart](https://apimart.ai) и получите API-ключ.
## Шаг 1: Войдите в Dify и откройте настройки
### 1.1 Доступ к платформе Dify
* **Облачная версия:** перейдите на [https://cloud.dify.ai](https://cloud.dify.ai) и войдите
* **Self-hosted:** перейдите по адресу вашего развёртывания Dify
*Главный интерфейс Dify со списком приложений и кнопкой создания приложения*
### 1.2 Перейдите к настройкам моделей
1. Кликните по **значку аватара** в правом верхнем углу
2. Выберите **Settings**
3. Выберите **Model Provider** в левом меню
*Найдите опцию "Model Provider" в левом меню*
**Примечание:** Dify поддерживает настройку нескольких провайдеров моделей. Можно использовать APIMart наряду с другими провайдерами.
## Шаг 2: Добавьте провайдера моделей APIMart
**Способы настройки:** Существует два способа настройки APIMart в Dify:
**Способ 1 (рекомендуется):** использовать функцию Custom API провайдера OpenAI
* В настройках провайдера OpenAI напрямую измените Base URL на `https://api.apimart.ai/v1`
* Введите ваш API-ключ APIMart
* Быстрее и проще
**Способ 2:** добавить как кастомного провайдера моделей (метод этого руководства)
* Более гибко, можно отдельно управлять провайдером APIMart
* Удобно для одновременного использования нескольких API-провайдеров
Оба способа функционально идентичны. Выбирайте по предпочтению.
### 2.1 Выберите способ настройки
#### Способ 1: использовать OpenAI Custom API (рекомендуется)
1. Найдите провайдера **OpenAI** на странице Model Provider
2. Кликните кнопку **Configure** или **Settings**
3. На странице конфигурации:
* **API Key**: введите ваш API-ключ APIMart (`sk-xxxxxxxxxxxx`)
* **API Base URL** или **Base URL**: введите `https://api.apimart.ai/v1`
4. Кликните **Save**
*Настройте API Key и Base URL APIMart в провайдере OpenAI*
5. После настройки вернитесь на страницу провайдера OpenAI и просмотрите **Model List**
6. В списке моделей найдите нужные вам модели (например, `gpt-4o`, `gpt-4o-mini`, `chatgpt-4o-latest` и т. д.)
7. Кликните **переключатель** справа от модели, чтобы включить её (синий — включена)
*Включите нужные модели в списке моделей OpenAI*
**Важно:** включайте только модели, которые реально поддерживаются APIMart!
Хотя список моделей OpenAI в Dify отображает много моделей, корректно работать будут только поддерживаемые APIMart. Включение неподдерживаемых моделей приведёт к ошибкам вызовов API.
Полный список поддерживаемых моделей см. в [документации API APIMart](https://docs.apimart.ai).
**Поддерживаемые и рекомендуемые модели APIMart:**
**Серия GPT:**
* `gpt-5` / `gpt-5-chat-latest` — модели серии GPT-5
* `chatgpt-4o-latest` / `gpt-4o` — последняя модель GPT-4o
* `gpt-4o-mini` — быстрая и экономичная версия
* `gpt-4.1` / `gpt-4.1-mini` — серия GPT-4.1
**Серия Claude:**
* `claude-sonnet-4-5-20250929` — Claude Sonnet 4.5
* `claude-haiku-4-5-20251001` — Claude Haiku 4.5
**Серия Gemini:**
* `gemini-2.0-flash-exp` — Google Gemini 2.0 Flash
Можно включить несколько моделей одновременно и гибко переключаться между ними в приложениях.
После завершения можно сразу использовать. Перейдите к **Шагу 3**.
#### Способ 2: добавить кастомного провайдера моделей
На странице Model Provider:
1. Прокрутите вниз до раздела **Custom Model**
2. Кликните кнопку **+ Add Model**
*Прокрутите к разделу кастомных моделей и кликните кнопку "+ Add Model"*
### 2.2 Настройте провайдера APIMart
В диалоге конфигурации заполните следующую информацию:
| Поле | Значение |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| **Model Name** | `APIMart` или кастомное имя |
| **Model Type** | выберите `LLM` (Large Language Model) |
| **API Key** | ваш API-ключ APIMart (`sk-xxxxxxxxxxxx`) |
| **API endpoint URL** | `https://api.apimart.ai/v1` |
| **Endpoint model name** | введите конкретное имя модели (например, `gpt-4o`, `gpt-4o-mini`, `claude-sonnet-4-5-20250929` и т. д.) |
*Заполните конфигурацию провайдера APIMart*
**Важно:**
* Base URL должен включать суффикс `/v1`: `https://api.apimart.ai/v1`
* API Key должен быть получен из консоли APIMart и начинаться с `sk-`
* Убедитесь, что на ключе достаточный баланс
### 2.3 Добавьте больше моделей (необязательно)
Чтобы добавить больше моделей, повторите шаги выше:
1. В разделе кастомных моделей снова кликните **+ Add Model**
2. Заполните конфигурацию для другой модели
3. Кликните Save
*Повторите шаги для настройки нескольких разных моделей*
**Рекомендуемые модели для добавления:**
#### Серия GPT-4/5
| ID модели | Имя модели | Длина контекста | Сценарий |
| ------------- | ----------- | --------------- | ----------------------------------------- |
| `gpt-5` | GPT-5 | 128 000 | Сложные задачи, обработка длинного текста |
| `gpt-4o` | GPT-4o | 128 000 | Качественный чат, генерация кода |
| `gpt-4o-mini` | GPT-4o Mini | 128 000 | Быстрый ответ, выгодно |
#### Серия Claude
| ID модели | Имя модели | Длина контекста | Сценарий |
| ---------------------------- | ----------------- | --------------- | -------------------------------- |
| `claude-sonnet-4-5-20250929` | Claude Sonnet 4.5 | 200 000 | Сложное рассуждение, анализ кода |
| `claude-haiku-4-5-20251001` | Claude Haiku 4.5 | 200 000 | Быстрый ответ, простые задачи |
#### Серия Gemini
| ID модели | Имя модели | Длина контекста | Сценарий |
| ---------------------- | ---------------- | --------------- | --------------------------------------------- |
| `gemini-2.0-flash-exp` | Gemini 2.0 Flash | 32 000 | Мультимодальное, приложения реального времени |
**Рекомендации по производительности:**
* 💰 **Выгодные:** `gpt-4o-mini`, `claude-haiku-4-5-20251001`
* 🚀 **Производительные:** `gpt-5`, `gpt-4o`, `claude-sonnet-4-5-20250929`
* ⚡ **Быстрый ответ:** `gemini-2.0-flash-exp`, `gpt-4o-mini`
## Шаг 3: Используйте модели APIMart в приложениях
### 3.1 Создайте новое приложение
1. Вернитесь на главную Dify
2. Кликните кнопку **Create App**
3. Выберите тип приложения:
* **Chatbot** — диалоговое приложение
* **Text Generator** — приложение генерации текста
* **Agent** — интеллектуальный агент
* **Workflow** — сложное workflow-приложение
*Выберите тип приложения для создания нового приложения*
### 3.2 Выберите модель APIMart
На странице оркестрации приложения:
1. Найдите область **Model Settings**
2. Кликните выпадающий список **Select Model**
3. Выберите провайдера **APIMart**
4. Выберите настроенную модель (например, `gpt-4o`)
*Выберите модель провайдера APIMart в приложении*
### 3.3 Настройте параметры модели
Настройте параметры модели по необходимости:
| Параметр | Описание | Рекомендуемое значение |
| --------------------- | ------------------------------- | ----------------------------------- |
| **Temperature** | контролирует случайность вывода | 0,7 (креативность) / 0,3 (точность) |
| **Max Tokens** | максимальная длина вывода | 2000-4000 |
| **Top P** | параметр nucleus sampling | 0,9 |
| **Presence Penalty** | снижает повторения | 0,0-0,5 |
| **Frequency Penalty** | снижает частые слова | 0,0-0,5 |
*Настройте параметры модели в зависимости от потребностей приложения*
## Шаг 4: Создание и тестирование приложения
### 4.1 Добавьте промпты
На странице оркестрации приложения:
1. Напишите промпты в области **System Prompt**
2. Используйте переменные, чтобы сделать приложение динамичным:
* `{{variable_name}}` — переменная пользовательского ввода
* `{{context}}` — контекст базы знаний
**Пример промпта:**
```
You are a professional customer service assistant, skilled at answering product questions.
Product Information: {{product_info}}
Please provide accurate and friendly answers based on user questions. If unsure, honestly inform the user.
User Question: {{user_question}}
```
*Пишите и настраивайте промпты в редакторе*
### 4.2 Добавьте базу знаний (необязательно)
Если нужны возможности RAG (Retrieval Augmented Generation):
1. Кликните **Knowledge Base** в левом меню
2. Создайте новую базу знаний и загрузите документы
3. Подключите базу знаний на странице оркестрации приложения
4. Настройте параметры поиска
### 4.3 Тестирование приложения
1. Вводите тестовые вопросы в правой панели **Preview**
2. Просматривайте эффективность ответов ИИ
3. При необходимости настраивайте промпты и параметры
4. Повторяйте тестирование до удовлетворительного результата
*Тестируйте эффективность приложения в панели предпросмотра*
### 4.4 Опубликуйте приложение
После тестирования:
1. Кликните кнопку **Publish** в правом верхнем углу
2. Выберите способ публикации:
* **API Call** — интеграция через API
* **Embed in Website** — сгенерируйте код встраивания
* **Public Link** — сгенерируйте ссылку для шеринга
*Выберите подходящий способ публикации*
## Шаг 5: Мониторинг и оптимизация
### 5.1 Просмотр логов приложения
На странице деталей приложения:
1. Кликните вкладку **Logs**
2. Просматривайте все записи диалогов
3. Анализируйте вопросы пользователей и ответы ИИ
4. Находите возможности для улучшения
*Просматривайте и анализируйте логи использования приложения*
### 5.2 Мониторинг использования API
Войдите в [консоль APIMart](https://apimart.ai/overview), чтобы посмотреть:
* 📊 **Статистика вызовов API** — общее количество вызовов, процент успеха
* 💰 **Детали расходов** — дневные/месячные расходы
* 📈 **Тенденции использования** — изменения использования
* 🔍 **Логи запросов** — подробные записи запросов
### 5.3 Оптимизация производительности приложения
Оптимизация на основе данных мониторинга:
1. **Корректировка выбора модели**
* Используйте `gpt-4o-mini` для простых задач, чтобы сократить расходы
* Используйте `gpt-4o` или `claude-sonnet-4-5` для сложных задач, чтобы улучшить качество
2. **Оптимизация промптов**
* Делайте промпты более чёткими и конкретными
* Добавляйте примеры для повышения эффективности
* Используйте chain-of-thought для лучшего рассуждения
3. **Настройка кэширования**
* Включите кэширование для похожих вопросов
* Сократите расходы на вызовы API
## Расширенные возможности
### Использование оркестрации workflow
Функция workflow Dify позволяет:
1. **Условные ветви** — выполнение разной логики в зависимости от условий
2. **Сотрудничество нескольких моделей** — комбинируйте преимущества моделей
3. **Вызов внешних инструментов** — вызывайте API, базы данных и другие ресурсы
4. **Передача переменных** — передавайте данные между разными узлами
### Настройка возможностей агента
Создавайте интеллектуальных агентов с моделями APIMart:
1. **Вызов инструментов** — позвольте ИИ вызывать внешние инструменты
2. **Управление памятью** — поддерживайте долговременную память диалога
3. **Автономное принятие решений** — ИИ автономно планирует шаги выполнения
### Мультимодальные приложения
Используйте мультимодальные возможности APIMart:
1. **Понимание изображений** — используйте `gpt-4o` или `claude-3` для обработки изображений
2. **Генерация изображений** — интегрируйте API генерации изображений APIMart
3. **Обработка голоса** — интегрируйте сервисы TTS и STT
## Часто задаваемые вопросы
### Q1: Не удаётся подключиться к сервису APIMart?
**Решение:**
1. **Проверьте Base URL**:
* Убедитесь, что это `https://api.apimart.ai/v1` (включает `/v1`)
* Не добавляйте лишние пути и не пропускайте `/v1`
2. **Проверьте API Key**:
* Убедитесь, что API Key начинается с `sk-`
* Проверьте действительность ключа в [консоли APIMart](https://apimart.ai/keys)
3. **Проверьте сетевое подключение**:
* Убедитесь, что сервер может получить доступ к `https://api.apimart.ai`
* Для self-hosted версий нужно обеспечить сетевое подключение сервера
### Q2: Модель медленно отвечает?
**Решение:**
1. **Переключитесь на более быстрые модели**:
* Используйте `gpt-4o-mini` вместо `gpt-4o`
* Используйте `gemini-2.0-flash-exp` для более быстрого ответа
2. **Оптимизируйте длину промпта**:
* Уменьшите ненужный контекст
* Упростите описания промптов
3. **Настройте поиск по базе знаний**:
* Уменьшите количество извлечённых документов
* Увеличьте порог сходства
### Q3: Вызовы API падают или возвращают ошибки?
**Распространённые ошибки и решения:**
| Сообщение об ошибке | Причина | Решение |
| --------------------------- | ------------------------------------- | --------------------------------------------------------------------- |
| `401 Unauthorized` | Недействительный или истёкший API Key | Получите API Key заново и обновите конфигурацию |
| `429 Too Many Requests` | Превышен лимит запросов | Настройте параметры параллелизма приложения или подождите и повторите |
| `500 Internal Server Error` | Временная проблема на сервере | Подождите несколько минут и повторите |
| `insufficient_quota` | Недостаточный баланс аккаунта | Пополните в консоли |
| `context_length_exceeded` | Ввод превышает длину контекста | Уменьшите длину ввода или используйте модель с большим контекстом |
### Q4: Как сократить расходы на использование API?
**Советы по оптимизации расходов:**
1. **Выбор модели**:
* Используйте `gpt-4o-mini` для простых задач (стоимость составляет лишь 1/10 от `gpt-4o`)
* Рассмотрите более экономичные модели для пакетных задач
2. **Включите кэширование**:
* Возвращайте кэшированные результаты для одинаковых вопросов
* Настройте сопоставление по сходству в Dify
3. **Оптимизируйте длину вывода**:
* Устанавливайте разумные Max Tokens
* Избегайте генерации слишком длинных ответов
4. **Используйте потоковый вывод**:
* Улучшает пользовательский опыт без увеличения затрат
### Q5: Как обращаться с чувствительными данными?
**Рекомендации по безопасности данных:**
1. **Используйте переменные окружения**:
* Не хардкодьте API Key в коде
* Используйте функцию переменных окружения Dify
2. **Настройте контроль доступа**:
* Установите разрешения доступа к приложению
* Включите аутентификацию для вызовов API
3. **Аудит логов**:
* Регулярно проверяйте логи приложения
* Отслеживайте аномальные паттерны доступа
## Лучшие практики
### 1. Промпт-инжиниринг
**Структурированные промпты:**
```
# Role Definition
You are a professional [role description]
# Task Objective
You need to help users [task description]
# Output Requirements
- Requirement 1
- Requirement 2
- Requirement 3
# Input Information
{{user_input}}
```
### 2. Управление базой знаний
* **Стратегия разбиения**: установите разумный размер чанков документов (рекомендуется 500-1000 символов)
* **Метаданные**: добавляйте метаданные к документам для упрощения поиска
* **Регулярные обновления**: поддерживайте актуальность содержимого базы знаний
### 3. Обработка ошибок
* **Дружелюбные сообщения**: предоставляйте пользователям чёткие сообщения об ошибках
* **Запасная стратегия**: переключайтесь на резервную модель при сбое основной
* **Механизм повтора**: автоматический повтор при временных ошибках
### 4. Мониторинг производительности
* **Установите оповещения**: оповещения о низком балансе, высоких показателях ошибок
* **Регулярный анализ**: анализируйте данные использования еженедельно/ежемесячно
* **Непрерывная оптимизация**: корректируйте конфигурацию на основе данных
## Примеры сценариев использования
### 1. Интеллектуальная клиентская поддержка
**Конфигурация приложения:**
* Модель: `gpt-4o-mini` (выгодная)
* База знаний: документация продукта, FAQ
* Функции: автоматический ответ на распространённые вопросы, эскалация сложных к человеку
### 2. Помощник по созданию контента
**Конфигурация приложения:**
* Модель: `gpt-4o` или `claude-sonnet-4-5` (высокое качество)
* Функции: генерация статей, рерайт, полировка
* Параметры: Temperature=0,8 (усиление креативности)
### 3. Ассистент по коду
**Конфигурация приложения:**
* Модель: `claude-sonnet-4-5` (отлично для кода)
* Функции: генерация, объяснение, отладка кода
* База знаний: документация проекта, API-документация
### 4. Ассистент анализа данных
**Конфигурация приложения:**
* Модель: `gpt-4o` (сильное рассуждение)
* Инструменты: выполнение Python-кода, визуализация данных
* Функции: анализ данных, генерация отчётов
## Возможности
Используя Dify + APIMart, вы можете:
* 🤖 **Быстро создавать AI-приложения** — создавайте мощные AI-приложения без кодирования
* 📚 **Расширение базой знаний** — технология RAG позволяет ИИ отвечать на основе ваших данных
* 🔧 **Гибкие workflow** — визуально оркестрируйте сложную AI-логику
* 🎯 **Точное управление промптами** — контроль версий и A/B-тестирование
* 📊 **Полный мониторинг и аналитика** — понимайте использование и производительность приложения
* 🔌 **Несколько способов интеграции** — API, встраивание, WebApp и др.
* 👥 **Командное сотрудничество** — поддержка совместной разработки несколькими пользователями
* 🌐 **Поддержка нескольких моделей** — гибко переключайтесь между разными AI-моделями
## Поддержка и помощь
Если у вас возникнут проблемы:
* 📚 [Документация APIMart](https://docs.apimart.ai)
* 📚 [Официальная документация Dify](https://docs.dify.ai)
* 💬 [Сообщество Discord](https://discord.gg/V8zqssyZ5c)
* 🐦 [Twitter @APIMart\_](https://x.com/APIMart_)
* 📧 Техническая поддержка: [zhihong@apimart.ai](mailto:zhihong@apimart.ai)
***
Зарегистрируйтесь в APIMart прямо сейчас, получите API-ключ и создавайте мощные AI-приложения в Dify!