Пользовательские эндпоинты

Функция пользовательских эндпоинтов позволяет подключать к Elftia локально развёрнутые сервисы вывода LLM (например, Ollama или LM Studio) или корпоративные частные API. Большинство локальных фреймворков вывода предоставляют OpenAI-совместимый API, что упрощает настройку.

Когда использовать

• Вы хотите запускать модели с открытым исходным кодом локально (Llama, Qwen, Mistral и др.) для полностью офлайн-использования
• Ваша компания развернула приватный LLM-сервис во внутренней сети
• Вы используете Azure OpenAI Service вместо официального API OpenAI
• Вам нужно подключиться к собственному кластеру вывода (например, vLLM или TGI)
• Вы хотите использовать графическую среду локального вывода LM Studio

Ollama

Ollama — самый популярный инструмент для запуска локальных моделей, поддерживающий загрузку и запуск широкого спектра моделей с открытым исходным кодом в один клик.

Предварительные требования

• Ollama установлена (скачать)
• Загружена хотя бы одна модель (например, ollama pull llama3.1)

Шаги

1. Убедитесь, что Ollama запущена
   • Windows/macOS: после установки Ollama по умолчанию работает как фоновый сервис
   • Linux: запустите ollama serve для старта сервиса
   • Адрес по умолчанию: http://localhost:11434

2. В Elftia откройте Настройки → Управление провайдерами

3. Найдите провайдер Ollama по умолчанию (если он отсутствует, нажмите Добавить провайдера → выберите шаблон Ollama)

4. Проверьте конфигурацию:

Поле	Значение
Формат API	openai
Base URL	http://localhost:11434/v1
API Key	(оставьте пустым — по умолчанию Ollama не требует аутентификации)

5. Добавьте загруженные модели:
   • Нажмите Добавить модель
   • Введите название модели так, как оно отображается в Ollama (совпадает с выводом ollama list)
   • Примеры: llama3.1, qwen2.5:14b, codellama:34b

6. Включите переключатель Включено и сохраните

7. Модели Ollama теперь будут отображаться в списке выбора модели в интерфейсе чата

Популярные модели Ollama

Название модели	Параметры	Сценарий использования	Команда загрузки
llama3.1	8B	Общий чат	ollama pull llama3.1
llama3.1:70b	70B	Высококачественный чат	ollama pull llama3.1:70b
qwen2.5:14b	14B	Чат на китайском/английском	ollama pull qwen2.5:14b
codellama:34b	34B	Генерация кода	ollama pull codellama:34b
deepseek-coder-v2	16B	Помощь с кодом	ollama pull deepseek-coder-v2
mistral	7B	Лёгкий чат	ollama pull mistral
llava	7B	Понимание изображений	ollama pull llava

Удалённая Ollama

Если Ollama запущена на другой машине в локальной сети:

1. На машине с Ollama установите переменную окружения OLLAMA_HOST=0.0.0.0:11434
2. Перезапустите сервис Ollama
3. В Elftia измените Base URL на http://<remote-IP>:11434/v1

LM Studio

LM Studio предоставляет графический интерфейс для управления локальными моделями и их вывода, а также встроенный API-сервер, совместимый с OpenAI.

Предварительные требования

• LM Studio установлена (скачать)
• Загружена и запущена хотя бы одна модель

Шаги

1. Запустите локальный сервер в LM Studio:
   • Откройте LM Studio
   • Перейдите на вкладку Local Server
   • Загрузите модель
   • Нажмите Start Server
   • Запомните адрес сервера (по умолчанию http://localhost:1234)

2. В Elftia откройте Настройки → Управление провайдерами

3. Нажмите Добавить провайдера → выберите Пользовательский провайдер

4. Заполните конфигурацию:

Поле	Значение
Название	LM Studio
Формат API	openai
Base URL	http://localhost:1234/v1/chat/completions
API Key	lm-studio (LM Studio не проверяет ключ, но если поле обязательно — введите любое значение)

5. Добавьте модели:

   • Введите название модели так, как оно отображается в загруженных моделях LM Studio
   • Название модели должно совпадать с идентификатором, отображаемым в LM Studio

6. Проверьте соединение, включите и сохраните

vLLM / Text Generation Inference

vLLM и TGI — высокопроизводительные движки вывода LLM, широко применяемые в производственных развёртываниях. Оба предоставляют OpenAI-совместимый API.

Конфигурация vLLM

1. Запустите сервис vLLM (пример):

   python -m vllm.entrypoints.openai.api_server \
     --model meta-llama/Llama-3.1-8B-Instruct \
     --port 8000

2. В Elftia добавьте пользовательского провайдера:

Поле	Значение
Название	vLLM Local
Формат API	openai
Base URL	http://localhost:8000/v1/chat/completions
API Key	(оставьте пустым или введите значение --api-key из vLLM)

3. Добавьте модели: используйте имя, указанное в параметре --model при запуске vLLM

Конфигурация TGI

1. После запуска сервиса TGI используйте его OpenAI-совместимый эндпоинт

2. В Elftia добавьте пользовательского провайдера:

Поле	Значение
Название	TGI
Формат API	openai
Base URL	http://localhost:8080/v1/chat/completions
API Key	(оставьте пустым или введите соответствующее значение)

Azure OpenAI

Azure OpenAI Service использует те же модели, что и OpenAI, но размещает их на платформе Azure, предлагая корпоративные SLA и гарантии соответствия требованиям по работе с данными.

Предварительные требования

• Подписка Azure и доступ к Azure OpenAI Service
• Ресурс Azure OpenAI, созданный на портале Azure
• Хотя бы одна развёрнутая модель (с именем развёртывания)

Шаги

1. Получите следующие данные на портале Azure:
   • Endpoint: в формате https://<resource-name>.openai.azure.com
   • API Key: доступен на странице «Ключи и эндпоинт»
   • Имя развёртывания: доступно на странице «Развёртывания моделей»
   • Версия API: рекомендуется 2024-08-01-preview

2. В Elftia откройте Настройки → Управление провайдерами

3. Нажмите Добавить провайдера → выберите шаблон Azure OpenAI

4. Заполните конфигурацию:

Поле	Значение	Пример
Формат API	azure-openai	--
Base URL	Эндпоинт Azure	https://my-resource.openai.azure.com
API Key	API-ключ Azure	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Версия API	Номер версии API	2024-08-01-preview

5. Добавьте модели:

   • Используйте имя развёртывания Azure в качестве идентификатора модели (не название модели)
   • Например, если вы развернули gpt-4o под именем my-gpt4o, введите my-gpt4o в качестве идентификатора модели

6. Проверьте соединение, включите и сохраните

Azure vs. стандартный OpenAI

Функция	OpenAI	Azure OpenAI
Base URL	https://api.openai.com/v1/...	https://<resource>.openai.azure.com
Аутентификация	Authorization: Bearer sk-...	api-key: ...
Указание модели	По названию модели (например, gpt-4o)	По имени развёртывания
Версия API	Не требуется	Обязательна (параметр URL)
Формат API	openai	azure-openai

Справочник по конфигурации

Следующие параметры применяются в сценариях с пользовательскими эндпоинтами:

Настройка	Тип	По умолчанию	Описание
Название	Строка	--	Пользовательское отображаемое имя
Формат API	Перечисление	openai	Локальные сервисы обычно используют openai; Azure — azure-openai
Base URL	URL	--	Адрес API сервиса вывода
API Key	Строка	(пусто)	Обычно не требуется для локальных сервисов; обязателен для Azure
Версия API	Строка	(пусто)	Требуется только для Azure OpenAI, например 2024-08-01-preview
Список моделей	Массив	(пусто)	Введите вручную названия доступных в сервисе моделей
Трансформер	Массив	(пусто)	Пользовательские эндпоинты обычно не требуют дополнительного трансформера

Примечания о поведении

Особенности локальных сервисов

• Нет проверки API-ключа: большинство локальных сервисов (Ollama, LM Studio) не требуют API-ключа. Если поле API Key в Elftia обязательно — введите любое значение-заглушку
• Горячая загрузка моделей: некоторые сервисы поддерживают динамическую загрузку моделей. После добавления новой модели в сервис просто добавьте её название в Elftia
• Ограничение параллелизма: локальные сервисы обычно обрабатывают только один запрос одновременно; установите лимит параллелизма равным 1
• Задержка первого ответа: локальным моделям может потребоваться несколько секунд для загрузки в память GPU; первый запрос будет ощутимо медленнее

Прокси и сеть

• Локальные сервисы (localhost / 127.0.0.1) не проходят через глобальный прокси
• Сервисы в локальной сети могут потребоваться добавить в список исключений прокси в зависимости от вашей конфигурации

Возможности моделей

Флаги возможностей для локальных моделей (поддержка изображений, вызов функций и т. д.) нужно устанавливать вручную в Elftia. Если модель поддерживает работу с изображениями, но флаг не установлен, Elftia не будет отправлять ей изображения.

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

Проблема	Возможная причина	Решение
Соединение отклонено	Локальный сервис не запущен	Убедитесь, что Ollama/LM Studio/vLLM запущены
Таймаут соединения	Неверный порт или брандмауэр блокирует соединение	Проверьте номер порта; убедитесь, что брандмауэр разрешает соединение
Модель не найдена	Название модели не совпадает с серверным	Используйте ollama list или список моделей сервера для проверки названия
Удалённое подключение к Ollama не работает	По умолчанию Ollama слушает только localhost	Установите OLLAMA_HOST=0.0.0.0:11434 и перезапустите
LM Studio возвращает пустой ответ	Модель не загружена в память	Убедитесь, что модель загружена и отображается как «Ready» в LM Studio
Azure возвращает 404	Неверное имя развёртывания	Убедитесь, что в качестве идентификатора модели используется имя развёртывания, а не название модели
Azure возвращает 401	Неверная версия API или ключ	Проверьте поле версии API и API Key
Кракозябры в ответе	Модель не поддерживает данный язык	Переключитесь на модель с поддержкой нужного языка (например, Qwen, ChatGLM)
Недостаточно памяти GPU	Модель слишком большая	Выберите меньшую квантованную версию (например, llama3.1:8b-q4_0)
Запрос зависает без ответа	Локальный сервис загружает модель	Дождитесь завершения загрузки модели; первый запрос может занять 10–30 секунд

Связанные страницы

• Обзор LLM-провайдеров — понимание системы провайдеров и форматов API
• Добавление провайдера — полное руководство по добавлению провайдера
• Пулы API-ключей — управление несколькими ключами для облачных провайдеров
• Параметры модели — настройка параметров генерации, таких как temperature