Интеграция LLM провайдеров

О чем эта страница

Эта документация объясняет, как подключить и использовать LLM (Large Language Model) провайдеры в Rumess. Вы узнаете:

Для кого: менеджеры продуктов, бизнес-пользователи, backend и frontend разработчики.

Быстрый старт

  1. Выберите или создайте пресет — набор параметров для LLM модели (температура, токены и т.д.)
  2. Примените пресет к агенту — свяжите пресет с вашим AI-агентом
  3. Используйте агента через API — отправляйте сообщения и получайте ответы

Минимальный пример: 

POST /api/v1/client/ai-agents/{agent_id}/apply-preset/


Authorization: Bearer {token}
{"preset_id": 123}

Подробности ниже.

Как это работает

Концептуальная модель

LLM Provider (провайдер)


    ↓
Preset (пресет) — параметры модели
    ↓
Agent (агент) — ваш AI-помощник
    ↓
Chat/API — использование

Провайдер — это сервис, который предоставляет доступ к AI-моделям (например, OpenAI, Anthropic, или общий провайдер от Rumess).

Пресет — это конфигурация модели: какая модель использовать, температура, максимальное количество токенов, дополнительные параметры.

Агент — это ваш AI-помощник, который использует пресет для общения с пользователями.

Типы провайдеров

ТипВидимостьУправлениеИспользование
Общие (Shared)Видны всем организациямТолько просмотрЧерез пресеты
Приватные (Private)Только ваша организацияПолное управлениеЧерез пресеты

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

Приватные провайдеры создаются вашей организацией. Только вы и администратор можете их видеть и управлять ими.

Типичные сценарии использования

Сценарий 1: Использование готового провайдера

Задача: Начать использовать AI без настройки собственного провайдера.

Шаги:

  1. Откройте список пресетов: GET /api/v1/client/llm/presets/
  2. Найдите пресет с scope: "global" (общий пресет)
  3. Примените пресет к агенту: POST /api/v1/client/ai-agents/{agent_id}/apply-preset/
  4. Используйте агента для чата

Время: 2-3 минуты.

Сценарий 2: Создание своего провайдера

Задача: Подключить свой API ключ от OpenAI, Anthropic и т.д.

Шаги:

  1. Создайте провайдера: POST /api/v1/client/llm/providers/
  2. Создайте пресет для этого провайдера: POST /api/v1/client/llm/presets/
  3. Примените пресет к агенту
  4. Используйте агента

Время: 5-10 минут.

Сценарий 3: Тестирование перед использованием

Задача: Проверить, как работает пресет, не сохраняя изменения в агенте.

Решение: Используйте Playground: POST /api/v1/client/ai-agents/{agent_id}/test-with-preset/

Использование агентов

Применение пресета к агенту

Применяет пресет к агенту, обновляя его конфигурацию LLM.

Endpoint: 

POST /api/v1/client/ai-agents/{agent_id}/apply-preset/


Authorization: Bearer {access_token}
Content-Type: application/json

Запрос: 

{


  "preset_id": 123
}

Ответ: 200 OK (без тела) или ошибка.

Роли: owner, admin.

Чат с агентом

Отправка сообщения агенту и получение ответа.

Endpoint: 

POST /api/v1/ai/agents/{agent_id}/chat/


Authorization: Bearer {access_token}
Content-Type: application/json

Запрос: 

{


  "message": "Привет!",
  "conversation_id": 456,  // опционально — ID существующего диалога
  "use_rag": true,         // использовать RAG (поиск по документам)
  "use_tools": true        // использовать инструменты агента
}

Ответ: 

{


  "content": "Привет! Чем могу помочь?",
  "conversation_id": 456,
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}

Роли: owner, admin, member, viewer.

Тестирование пресета (Playground)

Тестирует агента с выбранным пресетом без сохранения изменений. Использование токенов записывается.

Endpoint: 

POST /api/v1/client/ai-agents/{agent_id}/test-with-preset/


Authorization: Bearer {access_token}
Content-Type: application/json

Запрос: 

{


  "preset_id": 123,
  "message": "Привет!",
  "context": {}  // опционально — дополнительный контекст
}

Ответ: 

{


  "ok": true,
  "preset_id": 123,
  "model": "gpt-4o-mini",
  "output": "Привет! Чем могу помочь?",
  "tokens_used": 18,
  "response_time": 850,
  "metadata": {
    "prompt_tokens": 10,
    "completion_tokens": 8
  }
}

Роли: owner, admin.

Использование общих провайдеров

Что такое общие провайдеры

Общие (shared) провайдеры предоставляются администратором и доступны всем организациям. Они уже настроены и готовы к использованию.

Особенности:

Как использовать общий провайдер

  1. Найдите пресет с общим провайдером:
   GET /api/v1/client/llm/presets/
Ищите пресеты с "scope": "global" и "provider_display_name" нужного провайдера.

  1. Примените пресет к агенту (см. раздел "Использование агентов")
  1. Используйте агента для чата через API

Важно: Для общих провайдеров не нужно указывать base_url или API ключи — они уже настроены администратором.

Управление провайдерами

Получение списка провайдеров

Endpoint: 

GET /api/v1/client/llm/providers/


Authorization: Bearer {access_token}

Ответ: 

{


  "results": [
    {
      "id": 1,
      "name": "rumess",
      "display_name": "Rumess",
      "base_url": "",
      "is_active": true,
      "has_api_key": true,
      "scope": "global",
      "can_edit": false,
      "created_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "name": "openai",
      "display_name": "Мой OpenAI",
      "base_url": "https://api.openai.com/v1",
      "is_active": true,
      "has_api_key": true,
      "scope": "tenant",
      "can_edit": true,
      "created_at": "2025-01-02T00:00:00Z"
    }
  ]
}

Поля:

Создание провайдера

Endpoint: 

POST /api/v1/client/llm/providers/


Authorization: Bearer {access_token}
Content-Type: application/json

Запрос: 

{


  "name": "openai",
  "display_name": "Мой OpenAI",
  "base_url": "https://api.openai.com/v1",
  "new_api_key": "sk-...",
  "is_active": true
}

Поля:

Ответ: 201 Created с данными созданного провайдера.

Роли: owner, admin.

Ошибки:

Удаление провайдера

Endpoint: 

DELETE /api/v1/client/llm/providers/{provider_id}/


Authorization: Bearer {access_token}

Ответ: 204 No Content при успехе.

Роли: owner, admin.

Ограничения: Можно удалять только свои провайдеры (scope: "tenant"). Общие провайдеры удалить нельзя.

Управление пресетами

Получение списка пресетов

Endpoint: 

GET /api/v1/client/llm/presets/


Authorization: Bearer {access_token}

Ответ: 

{


  "results": [
    {
      "id": 1,
      "name": "Rumess Default",
      "provider": "rumess",
      "provider_display_name": "Rumess",
      "model_name": "Rumess",
      "temperature": 0.7,
      "max_tokens": 1000,
      "extra_params": {},
      "is_active": true,
      "is_default": false,
      "scope": "global",
      "can_edit": false,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Поля:

Создание пресета

Endpoint: 

POST /api/v1/client/llm/presets/


Authorization: Bearer {access_token}
Content-Type: application/json

Запрос: 

{


  "name": "GPT-4o для чата",
  "provider": "openai",
  "model_name": "gpt-4o-mini",
  "temperature": 0.7,
  "max_tokens": 1000,
  "extra_params": {
    "top_p": 0.9,
    "frequency_penalty": 0.5
  },
  "is_default": false,
  "is_active": true
}

Поля:

Ответ: 201 Created с данными созданного пресета.

Роли: owner, admin.

Удаление пресета

Endpoint: 

DELETE /api/v1/client/llm/presets/{preset_id}/


Authorization: Bearer {access_token}

Ответ: 204 No Content при успехе.

Роли: owner, admin.

Ограничения: Можно удалять только свои пресеты (scope: "tenant"). Общие пресеты удалить нельзя.

Параметры пресета

Основные параметры

ПараметрТипДиапазонОписание
temperatureчисло0.0 - 2.0Параметр творчества модели. Чем выше, тем более креативные ответы. Рекомендуется 0.7 для большинства задач.
max_tokensчисло> 0Максимальное количество токенов в ответе модели. Ограничивает длину ответа.

Рекомендации:

Дополнительные параметры (extra_params)

Дополнительные параметры передаются в формате JSON объекта в поле extra_params.

ПараметрТипДиапазонОписание
top_pчисло0.0 - 1.0Выборка ядра (nucleus sampling). Контролирует разнообразие ответов.
frequency_penaltyчисло-2.0 - 2.0Штраф за частоту использования токенов. Положительные значения снижают вероятность повторения.
presence_penaltyчисло-2.0 - 2.0Штраф за присутствие токенов. Положительные значения поощряют новые темы.
stopмассив строк—Массив строк для остановки генерации.
max_completion_tokensчисло> 0Лимит токенов ответа (альтернатива max_tokens).

Пример: 

{


  "top_p": 0.9,
  "frequency_penalty": 0.5,
  "presence_penalty": 0.3,
  "stop": ["\n\n", "---"],
  "max_completion_tokens": 2000
}

Примечание: Не все провайдеры поддерживают все параметры. Проверьте документацию вашего провайдера.

Ошибки и ограничения

Коды ошибок HTTP

КодНазваниеПричинаРешение
400Bad RequestНеверные данные в запросеПроверьте формат JSON и обязательные поля
401UnauthorizedОтсутствует или неверный токенПроверьте заголовок Authorization: Bearer {token}
402Payment RequiredТребуется активная подпискаАктивируйте подписку в личном кабинете
403ForbiddenНедостаточно правТребуется роль owner или admin для создания/редактирования
404Not FoundПровайдер, пресет или агент не найденПроверьте ID в URL
429Too Many RequestsПревышена квота использования токенов или API вызововДождитесь обновления квоты или обновите план подписки
500Internal Server ErrorОшибка LLM API или внутренняя ошибка сервераОбратитесь в поддержку
503Service UnavailableLLM сервис временно недоступен (timeout, rate limit, connection error)Повторите запрос позже

Ограничения

Безопасность

Хранение данных

Роли и права доступа

Действиеowneradminmemberviewer
Просмотр провайдеров/пресетов✅✅✅✅
Создание провайдеров/пресетов✅✅❌❌
Редактирование провайдеров/пресетов✅✅❌❌
Удаление провайдеров/пресетов✅✅❌❌
Использование агентов (чат)✅✅✅✅
Применение пресетов к агентам✅✅❌❌

Рекомендации

Дополнительная информация

Для получения помощи:

Последнее обновление: 2025-01-14