Chat Completions: контекст, инструменты и ошибки#

Для интеграции с Моделью через Sherpa AI Server необходимо использовать POST /api/v1/threads/chat/completions. Метод выполняет один запрос без создания Чата или Запуска. История сообщений передается клиентом.

Авторизация и выбор Модели#

Необходим действующий API-токен с правом создания в разделе Чат. Для POST /api/v1/threads/chat/preflight необходимо право чтения. Аккаунт определяется по авторизации, account_guid передавать не требуется.

В model необходимо указать имя карточки Модели текущего Аккаунта. Сервер выбирает активный экземпляр этой карточки. Поддерживается также прежний выбор по имени активного экземпляра в том же Аккаунте. Неизвестное или чужое имя возвращает 404 model_not_found. Карточка без активного экземпляра возвращает 503 model_unavailable.

Явно переданное значение параметра имеет приоритет над карточкой Модели и настройками окружения сервера. Если параметр отсутствует, используются настройки карточки, затем окружения. Объект chat_template_kwargs заменяется целиком. Значения null, {} и отсутствие поля различаются. Необходимо передавать только одно поле бюджета ответа: max_tokens либо max_completion_tokens.

Проверка контекста перед генерацией#

Необходимо отправить полный будущий запрос на /api/v1/threads/chat/preflight с заголовками Authorization: Bearer <API_TOKEN> и Content-Type: application/json. В примере необходимо заменить Support model на имя доступной карточки:

{
  "model": "Support model",
  "messages": [{"role": "user", "content": "Read the test file"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "read_file",
      "parameters": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"],
        "additionalProperties": false
      }
    }
  }],
  "max_tokens": 512,
  "chat_template_kwargs": {"enable_thinking": false}
}

Preflight не запускает генерацию и инструменты, не создает историю. Ответ находится в data:

Поле Значение
prompt_tokens Размер входа с учетом сообщений, схем инструментов и резерва для изображений и формата ответа.
output_tokens Бюджет ответа. null, если бюджет неизвестен.
context_limit Известное окно контекста. null, если лимит не настроен.
fits Помещается ли запрос с бюджетом ответа. null, если данных недостаточно.
exact, count_method Точный подсчет tokenizer либо оценка. Изображения и формат ответа могут добавлять оценочный резерв.
would_reject Будет ли запрос отклонен по достоверно известной границе. Одна приблизительная оценка не блокирует генерацию.
fallback_reason Причина приблизительного подсчета, например недоступный tokenizer или облачный провайдер без него.
allowed_max_output Остаток контекста после рассчитанного входа. При оценке это ориентир.

При would_reject=true необходимо сократить историю, схемы или бюджет ответа и повторить проверку. После подготовки необходимо отправить тот же запрос на /api/v1/threads/chat/completions. Сервер повторно проверяет бюджет для фактически выбранного экземпляра, в том числе после переключения. Разные экземпляры могут иметь разные лимиты. Preflight не закрепляет экземпляр для следующего запроса.

Вызовы инструментов#

Внешний API-клиент исполняет полученные вызовы самостоятельно. В tools описываются функции и JSON Schema их аргументов. Дополнительные входные поля необходимо включать в схему и function.arguments.

В следующем запросе необходимо сохранить сообщение Ассистента с tool_calls и добавить ответы role=tool. function.arguments и tool.content являются строками. Каждый ответ связан с вызовом через tool_call_id. Прикладные статусы, ошибки, артефакты и метаданные передаются JSON внутри строки content:

[
  {"role":"assistant","content":null,"tool_calls":[{"id":"call_1","type":"function","function":{"name":"read_file","arguments":"{\"path\":\"sample.txt\"}"}}]},
  {"role":"tool","tool_call_id":"call_1","content":"{\"status\":\"ok\",\"data\":\"Example text\",\"artifacts\":[]}"}
]

Идентификатор нового вызова должен быть уникальным в истории. Ответы инструментов должны идти после соответствующего сообщения Ассистента и до следующего сообщения другой роли. Ошибочные аргументы необходимо сохранить вместе с ответом об ошибке, чтобы Модель могла исправить вызов. Успешные действия с побочными эффектами повторять нельзя.

Во внутреннем режиме Агента исправимые аргументы возвращаются Модели для исправления. Число таких ошибок само по себе не завершает задачу. Повтор одинакового неверного вызова переводит Запуск в waiting с continuation.required=true. После исправления причины необходимо явно продолжить Запуск через обычный метод выполнения. Контекст и результаты выполненных действий сохраняются. Отмена и реальные ограничения доступа продолжают действовать.

Метод /api/v1/threads/responses использует отдельный формат Responses. Нельзя смешивать его элементы с сообщениями Chat Completions.

Ошибки и повтор запроса#

Ответ об ошибке содержит error.code, repairable, retryable, request_id и безопасные details. При repairable=true необходимо исправить запрос по деталям. При retryable=true допускается повтор с задержкой и учетом Retry-After. Эти признаки не разрешают повторять уже выполненные действия инструмента.

Код Действие
invalid_arguments, invalid_tool_history Исправить параметры, схему или пары вызовов и ответов.
context_limit Сократить вход или бюджет. Проверить числовые сведения в details.
model_not_found, model_unavailable Проверить имя, Аккаунт и активные экземпляры.
access_denied Проверить токен, права и доступ сервера к провайдеру.
upstream_rate_limited Учитывать Retry-After.
upstream_timeout, upstream_unavailable, invalid_upstream_response Проверить retryable и повторить позже при допустимости повтора.

Для SSE требуется stream=true. Необходимо читать поток до завершения и обрабатывать event: error. HTTP 200 означает начало потока и не гарантирует успешное завершение. При ошибке чтения или обрыве сервер передает машинную ошибку с тем же request_id.

Диагностика запроса#

Клиенту рекомендуется передавать X-Request-ID: от 1 до 128 символов A-Z, a-z, 0-9, ., _, :, -. При отсутствии или неверном формате сервер создает новый ID.

Ответ JSON и SSE содержит X-Request-ID и X-Sherpa-Attempt-Count. При наличии выбранной карточки доступны X-Sherpa-Model-Guid, X-Sherpa-Model-Instance-Guid, X-Sherpa-Configuration-Revision. Ревизия позволяет отличить изменения эффективных настроек. JSON также содержит request_meta.request_id. Для ошибки до выбора Модели сведения об экземпляре отсутствуют.

Для обращения к администратору необходимо сохранить ID, время, код ошибки и диагностические заголовки. В существующем серверном журнале по ID сопоставляются попытки, причины отказов, время, usage и завершение потока. Фоновые Запуски связываются по GUID Запуска и ID вида run:<GUID>. Событие постановки в очередь связывает внешний ID с GUID. Журнал доступен только администратору инфраструктуры. Тела сообщений, аргументы инструментов и ключи не входят в новую диагностическую запись.

Тайм-ауты отдельных обращений к Модели зависят от настроек подключения. Проверка контекста и диагностика не задают лимит длительности работы внешнего Робота.