К содержимому

Spring AI API: подключение и настройка моделей

Spring AI подключает шлюз свойствами spring.ai.openai.*. В документации адрес дан без /v1, но разные версии склеивают путь по-разному: проверьте реальный адрес в логе запроса.

  • Тип: Фреймворк и SDK
  • Протокол: OpenAI Chat Completions
  • Статус: Частично
Сверено частично, 2026-10-02: в документации клиента есть пробел или источники расходятся. Не проверено вручную. Что проверить пробой, описано в разделе «Ловушки».

Что заработает

ВозможностьОтметкаПримечание
ЧатДа
Потоковый ответДа
Вызов инструментовДаРаботает у моделей с поддержкой инструментов.

Настройка

Понадобятся ключ из раздела «Ключи» кабинета и идентификатор модели. В примерах подставлена модель gpt-5.6-luna; для протокола Anthropic Messages подставлена claude-haiku-5-5. Свою модель выбирайте в каталоге.

Клиенту нужен ключ. Задайте его в переменной окружения RELAY_API_KEY: примеры ниже читают ключ оттуда. Чтобы переменная сохранялась между сеансами, добавьте строку export в ~/.zshrc (bash: ~/.bashrc, bash на macOS: ~/.bash_profile), в PowerShell вызовите [Environment]::SetEnvironmentVariable с областью User, в cmd выполните setx и откройте новое окно. Окно, открытое до setx, переменную не увидит.

Ключ в переменной окружения

macOS и Linux

bash
read -rs RELAY_API_KEY && export RELAY_API_KEY

Windows PowerShell

bash
$env:RELAY_API_KEY = "YOUR_API_KEY"

Windows cmd

bash
set "RELAY_API_KEY=YOUR_API_KEY"
  1. Добавьте стартер OpenAI и задайте ключ в переменной RELAY_API_KEY.
  2. Заполните spring.ai.openai.base-url, api-key и модель из каталога, в примере gpt-5.6-luna.
  3. Включите журнал HTTP-клиента и убедитесь, что запрос уходит на https://relay-llm.ru/v1/chat/completions.

Свойства приложения

src/main/resources/application.properties

src\main\resources\application.properties

text
spring.ai.openai.base-url=https://relay-llm.ru
spring.ai.openai.api-key=${RELAY_API_KEY}
spring.ai.openai.chat.options.model=gpt-5.6-luna

Проверка

Сначала проверьте ключ и адрес без клиента. В ответе должно быть is_active: true.

macOS и Linux

bash
curl https://relay-llm.ru/v1/key \
  -H "Authorization: Bearer $RELAY_API_KEY"

Windows PowerShell

bash
curl.exe https://relay-llm.ru/v1/key `
  -H "Authorization: Bearer $env:RELAY_API_KEY"

Windows cmd

bash
curl https://relay-llm.ru/v1/key ^
  -H "Authorization: Bearer %RELAY_API_KEY%"

Затем проверьте сам клиент.

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

Запрос из клиента появится в журнале запросов кабинета с моделью, токенами и стоимостью.

Ограничения протоколов

OpenAI Chat Completions

Работают чат-модели каталога по пути /v1/chat/completions. Не поддерживаются /v1/embeddings, /v1/audio/*, /v1/moderations, /v1/batches, Assistants и Realtime: функции клиента, которым они нужны, не заработают.

Ловушки

  • Версия 1.x сама дописывает путь /v1/chat/completions, поэтому адрес указан без /v1. Для версии 2.0.1 правило не подтверждено. Если в логе путь без /v1, добавьте его в адрес.
  • Параметр temperature не поддерживается у моделей gpt-5: не задавайте его.
  • Для модели Claude через Anthropic-стартер адрес задаётся без /v1 в spring.ai.anthropic.base-url. Эту связку мы не проверяли.

Официальная документация: Spring AI API: подключение и настройка моделей

Подключение клиентов: общие сведения и все клиенты

Обработка ошибок и повторы

Модели и ключ: список моделей в API

Ключи в кабинете

Готовы? Три шага, чтобы начатьВойдите в консоль · пополните баланс · создайте API Key