Version: 1.4.2

Обращение к нексусу

Запрос к нейросети отправляется по пути /v1/<путь конечной точки>, где конечная точка – это путь метода той нейросети, на которую настроен нексус. Тело запроса и тело ответа принадлежат самой нейросети: платформа проверяет токен и лимиты, подставляет параметры нексуса и передает запрос дальше без преобразования.

Если путь конечной точки вам неизвестен, обратитесь к нексусу через конверт – там достаточно имени нексуса.

Как строится путь

Путь запроса повторяет конечную точку нексуса. Нексус, настроенный на конечную точку /chat/completions, вызывается запросом POST /v1/chat/completions; нексус на /embeddings – запросом POST /v1/embeddings.

Единого перечня путей у платформы нет. Набор доступных путей определяется тем, какие нексусы выданы вашей инсталляции, и меняется вместе с ними. Путь конкретного нексуса узнайте у администратора инсталляции.

Если у конечной точки есть подстановка – например /status/poll/{task_id}, – в запросе подставляется значение: GET /v1/status/poll/abc123. Число сегментов пути в запросе и в конечной точке должно совпадать.

Как указать нексус

Нексус указывается одним из двух способов:

поле model в теле запроса – так нексус выбирают клиентские библиотеки OpenAI;
заголовок X-NEXUS – имеет приоритет над полем model.

Если нексус не указан ни тем, ни другим способом, платформа возвращает ответ 400.

note

Имя нексуса – это адрес, а не выбор модели. Какая модель обработает запрос, определяет настройка нексуса: если в ней указана модель, значение поля model при передаче в нейросеть заменяется на нее. Чтобы обратиться к другой модели, укажите другой нексус.

Пример запроса

curl https://<адрес инсталляции>/v1/chat/completions \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -H "X-SESSION-ID: demo-001" \
  -d '{
        "model": "<имя нексуса>",
        "messages": [{"role": "user", "content": "Привет"}]
      }'

Ответ возвращается таким, каким его вернула нейросеть:

{
  "id": "chatcmpl-a1b2c3",
  "object": "chat.completion",
  "choices": [
    { "index": 0, "finish_reason": "stop",
      "message": { "role": "assistant", "content": "Здравствуйте! Чем могу помочь?" } }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 34, "total_tokens": 46 }
}

Ответ, если указанный нексус не выдан вашей инсталляции:

{"error": "nexus \"<имя нексуса>\" not found"}

Остальные поля тела запроса – temperature, max_tokens, tools, response_format и любые другие – доходят до нейросети без изменений.

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

Заголовки запроса

Заголовок	Обязательно	Описание
`Authorization`	Да	Укажите API-токен с префиксом `Bearer`. Читайте подробнее в статье Аутентификация.
`Content-Type`	Да/Нет	Укажите `application/json`. Заголовок обязателен, если запрос содержит тело.
`X-NEXUS`	Нет	Укажите имя нексуса вместо поля `model`.
`X-SESSION-ID`	Нет	Укажите собственный идентификатор запроса. Значение попадает в журнал обращений.
`X-AIN-SOURCEID`	Нет	Укажите идентификатор запроса, если заголовок `X-SESSION-ID` не используется. При заданном `X-SESSION-ID` значение этого заголовка в журнал не попадает.
`X-AIN-USERNAME`	Нет	Укажите имя пользователя вашей системы, от лица которого выполняется запрос. Значение попадает в журнал обращений. Если заголовок не задан, в журнале указывается владелец токена.
`X-AIN-TAGS`	Нет	Укажите метки, по которым связанные обращения группируются в журнале.

tip

Платформа не возвращает собственный идентификатор запроса. Чтобы обращение можно было найти в журнале, задавайте X-SESSION-ID самостоятельно и сохраняйте его значение у себя.

Обращение по имени нексуса

Тот же запрос отправляется по пути /nexuses/<имя нексуса>/<путь конечной точки>. Это отдельный корень, в /v1 он не входит:

curl https://<адрес инсталляции>/nexuses/<имя нексуса>/chat/completions \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Привет"}]}'

Отличия от обращения по пути нейросети два:

нексус указывается в пути, поэтому поле model и заголовок X-NEXUS не нужны;
заголовок X-AIN-USERNAME на этом маршруте не действует – в журнале обращений указывается владелец токена.

Этот способ применяется, когда приложение хранит имя нексуса отдельно от тела запроса.

Нексусы с методом GET

Метод, с которым платформа обращается к нейросети, задается в настройке нексуса и может не совпадать с методом вашего запроса. Если нексус настроен на метод GET, тело запроса в нейросеть не передается – параметры такому нексусу передаются строкой запроса:

curl "https://<адрес инсталляции>/v1/status/poll/abc123?verbose=true" \
  -H "Authorization: Bearer <токен>"

Клиентские библиотеки OpenAI

Нексус, настроенный на конечную точку, куда обращается библиотека OpenAI, вызывается этой библиотекой напрямую. В качестве base_url подставляется значение base_api_url из файла AI-профиля целиком, вместе с /v1:

from openai import OpenAI

client = OpenAI(
    base_url="https://<адрес инсталляции>/v1",
    api_key="<токен>",
)

resp = client.chat.completions.create(
    model="<имя нексуса>",
    messages=[{"role": "user", "content": "Привет"}],
)
print(resp.choices[0].message.content)

Совместимость определяется нексусом, а не платформой. Библиотека обращается к фиксированному набору путей – /chat/completions, /embeddings, /responses, /audio/*, – и работает с теми нексусами, которые настроены на эти конечные точки и отвечают в том же формате. Нексусы на других путях вызываются прямым HTTP-запросом или через конверт.

Потоковые ответы

Потоковая передача поддерживается на запросах по пути нейросети. Запрос на потоковый ответ отличается от обычного одним полем тела – "stream": true:

curl -N https://<адрес инсталляции>/v1/chat/completions \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "<имя нексуса>",
        "messages": [{"role": "user", "content": "Привет"}],
        "stream": true,
        "stream_options": {"include_usage": true}
      }'

Ответ приходит с заголовком Content-Type: text/event-stream, события разделяются пустой строкой, последнее событие – data: [DONE].

Расход токенов модели в поток по умолчанию не попадает. Чтобы получить его, передайте "stream_options": {"include_usage": true} – тогда перед завершающим событием добавится еще одно, с пустым choices и полем usage.

Поле stream принадлежит нейросети, а не платформе: его понимают те нексусы, которые настроены на конечные точки с потоковой передачей.

note

Код 200 приходит вместе с первым событием потока. Если нейросеть не начала отвечать, приходят обычные коды ошибок, например 408 или 504. Ошибка, возникшая у нейросети после начала передачи, кодом ответа не отражается – ее нужно искать в содержимом потока. Считайте ответ незавершенным, если событие data: [DONE] не пришло.

Ограничения

Ограничение	Значение
Максимальный размер тела запроса	50 МБ
Время ожидания ответа нейросети	600 секунд по умолчанию, значение задается в поле Timeout конфигурации нексуса
Время до начала ответа	1800 секунд по умолчанию, значение задается при установке платформы

Если нейросеть не ответила за время, заданное в поле Timeout, платформа возвращает ответ 408. Если в поле Bypass конфигурации нексуса указана другая конфигурация, запрос повторяется через нее, и общее время ожидания складывается из значений Timeout обеих конфигураций.

Если нейросеть не начала отвечать за 1800 секунд, платформа возвращает ответ 504. Обычный ответ передается целиком, поэтому для него это ограничение действует на весь ответ. В потоковом режиме оно действует только до первого события.

В потоковом режиме значение поля Timeout ограничивает всю передачу, включая получение событий. Если оно истекло во время передачи, поток прерывается без события data: [DONE] – читайте выше, в разделе Потоковые ответы.

Число одновременных соединений платформа не ограничивает, но все запросы учитываются в ограничениях по частоте. Читайте подробнее в статье Ошибки и лимиты.

Как строится путь​

Как указать нексус​

Пример запроса​

Заголовки запроса​

Обращение по имени нексуса​

Нексусы с методом GET​

Клиентские библиотеки OpenAI​

Потоковые ответы​

Ограничения​