Version: 1.4.0

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

Запрос к нейросети отправляется по пути /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. Заголовки уходят вместе с первым событием, поэтому ошибка, возникшая у нейросети после начала передачи, кодом ответа не отражается – ее нужно искать в содержимом потока. Считайте ответ незавершенным, если событие data: [DONE] не пришло.

Ограничения

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

Если нейросеть не ответила за отведенное время, платформа возвращает ответ 408.

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

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

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

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

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

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

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

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

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

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