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. Журнал доступен только администратору инфраструктуры. Тела сообщений, аргументы инструментов и ключи не входят в новую диагностическую запись.
Тайм-ауты отдельных обращений к Модели зависят от настроек подключения. Проверка контекста и диагностика не задают лимит длительности работы внешнего Робота.