Поделиться через

Справочник по REST API модели Foundation

В этой статье содержатся общие сведения об API databricks Foundation Model и моделях, которые они поддерживают. API моделей Foundation разработаны таким образом, чтобы быть похожими на REST API OpenAI, что облегчает перенос существующих проектов. Как конечные точки оплаты за токен, так и подготовленные конечные точки пропускной способности принимают один и тот же формат запроса REST API.

Конечные точки

API модельных платформ Foundation поддерживают конечные точки с оплатой за токен и конечные точки с гарантированной пропускной способностью.

Предварительно настроенная конечная точка доступна в рабочей области для каждой поддерживаемой модели с оплатой за токен, и пользователи могут взаимодействовать с этими конечными точками с помощью HTTP-запросов POST. См. Перечень поддерживаемых базовых моделей на платформе Mosaic AI Model Serving для получения информации о поддерживаемых моделях.

Подготовленные конечные точки пропускной способности можно создать с помощью API или пользовательского интерфейса обслуживания. Эти конечные точки поддерживают несколько моделей на конечную точку для тестирования A/B, если обе обслуживаемые модели предоставляют один и тот же формат API. Например, обе модели являются моделями чата. Сведения о параметрах конфигурации конечной точки см. в POST /api/2.0/service-endpoints.

Запросы и ответы используют JSON, точная структура JSON зависит от типа задачи конечной точки. Конечные точки чата и завершения поддерживают потоковые ответы.

Употребление

Ответы включают в себя вложенное сообщение usage, которое сообщает количество токенов в запросе и ответе. Формат этого вложенного сообщения одинаков для всех типов задач.

Поле Тип Описание
completion_tokens Целое число Количество сгенерированных токенов. Не включено в результаты встраивания.
prompt_tokens Целое число Количество токенов из входных подсказок.
total_tokens Целое число Общее количество токенов.
reasoning_tokens Целое число Количество токенов мышления. Это применимо только к моделям рассуждений.

Для таких моделей, как databricks-meta-llama-3-3-70b-instruct запрос пользователя преобразуется с помощью шаблона запроса перед передачей в модель. Для конечных точек с оплатой за токен также может быть добавлен системный запрос. prompt_tokens включает весь текст, добавленный нашим сервером.

API ответов

Это важно

API ответов совместим только с моделями OpenAI.

API Responses позволяет вести многоэтапные беседы с моделью. В отличие от Chat Completion, API ответов использует input вместо messages.

Запрос API ответов

Поле По умолчанию Тип Описание
model Струна Обязательный. Идентификатор модели, используемый для создания ответа.
input String или List[ResponsesInput] Обязательный. Входные данные, такие как текст, изображения или файлы, в модель, используемые для генерации ответа. В отличие от messagesэтого поля, используется input для указания содержимого беседы.
instructions null Струна Сообщение системы (или разработчика), вставленное в контекст модели.
max_output_tokens null null, что означает отсутствие ограничения или целое число больше нуля Верхняя граница для числа маркеров, которые можно создать для ответа, включая видимые выходные маркеры и маркеры причин.
temperature 1.0 Число с плавающей запятой в диапазоне от [0, 2] Температура выборки. 0 детерминировано и выше значения вводят больше случайности.
top_p 1.0 Плавать в (0,1] Порог вероятности, используемый для семплирования ядра.
stream false Булев Если задано значение true, данные ответа модели будут передаваться клиенту по мере его создания с помощью событий, отправляемых сервером.
stream_options null StreamOptions Параметры потоковых ответов. Этот параметр устанавливается только при установке stream: true.
text null TextConfig Параметры конфигурации для текстового ответа модели. Можно использовать обычный текст или структурированные данные JSON.
reasoning null ReasoningConfig Настройка логики для моделей gpt-5 и o-series.
tool_choice "auto" Строка или ToolChoiceObject Как модель должна выбрать средство (или инструменты), которое следует использовать при создании ответа. Просмотрите tools параметр, чтобы узнать, как указать, какие средства модель может вызывать.
tools null Список[ToolObject] Массив инструментов, которые модель может вызывать при создании ответа. Примечание. Интерпретатор кода и средства поиска в Интернете не поддерживаются Databricks.
parallel_tool_calls true Булев Следует ли разрешить модели запускать вызовы инструментов параллельно.
max_tool_calls null Целое число больше нуля Максимальное количество общих вызовов встроенных инструментов, которые могут обрабатываться в ответе.
metadata null Объект Набор из 16 пар "ключ-значение", которые могут быть присоединены к объекту.
prompt_cache_key null Струна Используется для кэширования ответов на аналогичные запросы с целью оптимизации частоты попадания в кэш. Заменяет user поле.
prompt_cache_retention null Струна Политика хранения кэша подсказок. Установите "24h" для включения расширенного кэширования подсказок, которое поддерживает кэшированные префиксы активными в течение более длительного времени, максимум до 24 часов.
safety_identifier null Струна Стабильный идентификатор, используемый для обнаружения пользователей приложения, которые могут нарушать политики использования.
user null Струна устаревшее. Взамен используйте safety_identifier и prompt_cache_key.
truncation null Струна Стратегия усечения, которую следует использовать для генерирования ответа модели.
top_logprobs null Целое число Целое число от 0 до 20, указывающее число наиболее вероятных маркеров, возвращаемых по каждой позиции маркера, каждый из которых имеет связанную вероятность журнала.
include null List[String] Укажите дополнительные выходные данные для включения в ответ модели.
prompt null Объект Ссылка на шаблон запроса и его переменные.

Неподдерживаемые параметры: следующие параметры не поддерживаются Databricks и возвращают ошибку 400, если задано:

  • background — фоновая обработка не поддерживается
  • store — сохраненные ответы не поддерживаются
  • conversation — API беседы не поддерживается
  • service_tier — Выбор уровня обслуживания управляется Databricks

ResponsesInput

Поле input принимает строку или список объектов входных сообщений с ролью и содержимым.

Поле Тип Описание
role Струна Обязательный. Роль автора сообщения. Может иметь значение "user" или "assistant".
content String или List[ResponsesContentBlock] Обязательный. Содержимое сообщения в виде строки или массива блоков содержимого.

ResponsesContentBlock

Блоки содержимого определяют тип содержимого в входных и выходных сообщениях. Тип блока содержимого определяется полем type .

InputText
Поле Тип Описание
type Струна Обязательный. Этот параметр должен содержать значение "input_text".
text Струна Обязательный. Текстовое содержимое.
OutputText
Поле Тип Описание
type Струна Обязательный. Этот параметр должен содержать значение "output_text".
text Струна Обязательный. Текстовое содержимое.
annotations Список[Объект] Необязательные аннотации к содержимому текста.
InputImage
Поле Тип Описание
type Струна Обязательный. Этот параметр должен содержать значение "input_image".
image_url Струна Обязательный. URL-адрес или URI данных в кодировке Base64 изображения.
InputFile
Поле Тип Описание
type Струна Обязательный. Этот параметр должен содержать значение "input_file".
file_id Струна Идентификатор файла при использовании отправленных файлов.
filename Струна Имя файла.
file_data Струна URI данных в кодировке Base64 с префиксом формата. Например, PDF-файлы используют формат data:application/pdf;base64,<base64 data>.
FunctionCall
Поле Тип Описание
type Струна Обязательный. Этот параметр должен содержать значение "function_call".
id Струна Обязательный. Уникальный идентификатор вызова функции.
call_id Струна Обязательный. Идентификатор вызова.
name Струна Обязательный. Имя вызываемой функции.
arguments Объект или строка Обязательный. Аргументы функции в виде объекта ИЛИ строки JSON.
FunctionCallOutput
Поле Тип Описание
type Струна Обязательный. Этот параметр должен содержать значение "function_call_output".
call_id Струна Обязательный. Идентификатор вызова, к которому относятся эти выходные данные.
output Строка/Объект Обязательный. Выходные данные функции в виде строки или объекта JSON.

StreamOptions

Конфигурация потоковых ответов. Используется, только если stream: true.

Поле Тип Описание
include_usage Булев Если значение true, включите сведения об использовании маркеров в потоке. По умолчанию — false.

TextConfig

Настройка выходных данных текста, включая структурированные выходные данные.

Поле Тип Описание
format ResponsesFormatObject Спецификация формата для выходных данных текста.

ResponsesFormatObject

Указывает выходной формат для текстовых ответов.

Поле Тип Описание
type Струна Обязательный. Тип формата: "text" для обычного текста, "json_object" для JSON или "json_schema" для структурированного JSON.
json_schema Объект Обязательный, если type имеет значение "json_schema". Объект схемы JSON, определяющий структуру выходных данных.

Объект json_schema имеет ту же структуру, что и JsonSchemaObject , документированную в API завершения чата.

ReasoningConfig

Настройка поведения рассуждений в моделях рассуждений (модели o-series и gpt-5).

Поле Тип Описание
effort Струна Уровень затраченных усилий: "low", "medium", или "high". По умолчанию — "medium".
encrypted_content Струна Зашифрованное содержимое рассуждений для статического режима. Предоставляется моделью в предыдущих ответах.

ToolObject

См. вызов функций в Azure Databricks.

Поле Тип Описание
type Струна Обязательный. Тип средства. В настоящее время поддерживается только function.
function FunctionObject Обязательный. Определение функции, связанное с инструментом.

FunctionObject

Поле Тип Описание
name Струна Обязательный. Имя вызываемой функции.
description Объект Обязательный. Подробное описание функции. Модель использует это описание для понимания релевантности функции в запросе и создания вызовов средства с более высокой точностью.
parameters Объект Параметры, которые принимает функция, описаны как объект, соответствующий допустимой схеме JSON. Если этот инструмент вызывается, вызов инструмента соответствует предоставленной схеме JSON. Опущение параметров определяет функцию без каких-либо параметров. Количество properties ограничено 15 ключами.
strict Булев Следует ли включить строгое соблюдение схемы при создании вызова функции. Если задано значение true, модель следует точной схеме, определенной в поле схемы. Поддерживается только подмножество схемы JSON, когда включен строгий режим true

ToolChoiceObject

См. вызов функций в Azure Databricks.

Поле Тип Описание
type Струна Обязательный. Тип средства. В настоящее время поддерживается только "function".
function Объект Обязательный. Объект, определяющий средство вызова формы {"type": "function", "function": {"name": "my_function"}}, где "my_function является именем FunctionObject в поле tools.

Ответы API ответов

Для запросов, отличных от потоковой передачи, ответ является одним объектом ответа. Для потоковых запросов ответ представляет собой text/event-stream, где каждое событие является частью ответа.

Поле Тип Описание
id Струна Уникальный идентификатор ответа. Примечание. Databricks шифрует этот идентификатор для обеспечения безопасности.
object Струна Тип объекта. Равно значению "response".
created_at Целое число Метка времени Unix (в секундах), когда был создан ответ.
status Струна Состояние ответа. Одно из следующих: completed, , failedin_progress, cancelledqueuedили incomplete.
model Струна Версия модели, используемая для создания ответа.
output Список[ResponsesMessage] Выходные данные, созданные моделью, обычно содержащие объекты сообщений.
usage Использование Метаданные использования токенов.
error Error Сведения об ошибке, если ответ завершился ошибкой.
incomplete_details НеполныеДетали Сведения о том, почему ответ является неполным, если применимо.
instructions Струна Инструкции, указанные в запросе.
max_output_tokens Целое число Максимальное количество токенов, указанное в запросе.
temperature Плавать Температура, используемая для генерации.
top_p Плавать Значение top_p, используемое для генерации.
tools Список[ToolObject] Средства, указанные в запросе.
tool_choice Строка или ToolChoiceObject Параметр tool_choice из запроса.
parallel_tool_calls Булев Включены ли параллельные вызовы инструментов.
store Булев Хранится ли ответ.
metadata Объект Метаданные, присоединенные к ответу.

ResponsesMessage

Объекты сообщений в поле output, содержащие содержание ответа модели.

Поле Тип Описание
id Струна Обязательный. Уникальный идентификатор сообщения.
role Струна Обязательный. Роль сообщения. "user" или "assistant".
content Список[ResponsesContentBlock] Обязательный. Блоки содержимого в сообщении.
status Струна Состояние обработки сообщений.
type Струна Обязательный. Тип объекта. Равно значению "message".

Error

Сведения об ошибке при сбое ответа.

Поле Тип Описание
code Струна Обязательный. Код ошибки.
message Струна Обязательный. Сообщение об ошибке, доступное для чтения человеком.
param Струна Параметр, вызвавшего ошибку, если применимо.
type Струна Обязательный. Тип ошибки.

IncompleteDetails

Сведения о том, почему ответ является неполным.

Поле Тип Описание
reason Струна Обязательный. Причина, по которой ответ является неполным.

API завершения чата

API завершения чата включает многоэтапные беседы с моделью. Ответ модели предоставляет следующее сообщение assistant в разговоре. Сведения о запросах параметров конечной точки см. в POST /serving-endpoints/{name}/invocations.

Запрос чата

Поле По умолчанию Тип Описание
messages ChatMessage список Обязательный. Список сообщений, представляющих текущую беседу.
max_tokens null null, что означает отсутствие ограничения или целое число больше нуля Максимальное количество генерируемых токенов.
stream true Булев Передавайте ответы обратно клиенту, чтобы предоставить частичные результаты для запросов. Если этот параметр включен в запрос, ответы отправляются в соответствии со стандартом событий, отправляемых сервером.
temperature 1.0 Число с плавающей запятой в диапазоне от [0, 2] Температура выборки. 0 детерминировано и выше значения вводят больше случайности.
top_p 1.0 Плавать в (0,1] Порог вероятности, используемый для семплирования ядра.
top_k null null, что означает отсутствие ограничения или целое число больше нуля Определяет количество наиболее вероятных токенов k, используемых для фильтрации по top-k. Задайте для этого значения значение 1, чтобы сделать выходные данные детерминированными.
stop [] Строка или список[строка] Модель перестает создавать дополнительные маркеры при обнаружении одной из последовательностей в stop.
n 1 Целое число больше нуля API возвращает n независимые завершения чата, когда указано n. Рекомендуется для рабочих нагрузок, которые создают несколько завершений для одного и того же входного значения, чтобы повысить эффективность вывода и сэкономить средства. Доступно только для конечных точек с выделенной пропускной способностью.
tool_choice none Строка или ToolChoiceObject Используется только в сочетании с полем tools. tool_choice поддерживает различные строки ключевых слов, такие как auto, requiredи none. auto означает, что вы позволяете модели самой решить, какой инструмент, если это применимо, следует использовать. Если модель auto не считает, что какие-либо инструменты в tools имеют отношение, она создает стандартное сообщение помощника вместо обращения к инструменту. required означает, что модель выбирает наиболее релевантный инструмент в tools и должна создавать вызов инструмента. none означает, что модель не создает вызовы инструментов и вместо этого должна создавать стандартное сообщение помощника. Для принудительного вызова инструмента с использованием определённого инструмента, заданного в tools, используйте ToolChoiceObject. По умолчанию, если поле tools заполнено tool_choice = "auto". В противном случае для поля tools по умолчанию используется значение tool_choice = "none"
tools null ToolObject Список tools, который модель может использовать. В настоящее время function является единственным поддерживаемым типом tool и поддерживается не более 32 функций.
response_format null ResponseFormatObject Объект, указывающий формат, который должен выводить модель. Допустимые типы: text, json_schema или json_object
Параметр { "type": "json_schema", "json_schema": {...} } включает структурированные выходные данные, которые гарантируют, что модель соответствует предоставленной схеме JSON.
Параметр { "type": "json_object" } гарантирует, что ответы, создаваемые моделью, являются допустимыми JSON, но не гарантирует, что ответы соответствуют определенной схеме.
logprobs false Булев Этот параметр указывает, следует ли предоставлять логарифмическую вероятность выборки токена.
top_logprobs null Целое число Этот параметр определяет количество наиболее вероятных кандидатов токенов, для которых возвращаются логарифмы вероятностей на каждом шаге выборки. Может быть 0–20. logprobs должен быть true при использовании этого поля.
reasoning_effort "medium" Струна Управляет уровнем усилий по созданию ответов, которые модель должна применять. Допустимые значения: "low", "medium"или "high". Более значительные усилия в рассуждениях могут привести к более задумчивым и точным ответам, но могут увеличить задержку и расход токенов. Этот параметр принимается только ограниченным набором моделей, включая databricks-gpt-oss-120b и databricks-gpt-oss-20b.

ChatMessage

Поле Тип Описание
role Струна Обязательный. Роль автора сообщения. Может быть "system", "user", "assistant" или "tool".
content Струна Содержимое сообщения. Обязательно для задач чата, которые не включают вызовы инструментов.
tool_calls список ToolCall Список tool_calls, который сгенерировала модель. Должно использоваться role как "assistant", и не должно быть спецификации для поля content.
tool_call_id Струна Когда role равно "tool", идентификатор связан с ToolCall, которому адресовано сообщение. Должен быть пустым для других опций role.

Роль system может использоваться только один раз, как первое сообщение в беседе. Она переопределяет системный запрос модели по умолчанию.

ToolCall

Предложение действия с использованием инструмента модели. См. вызов функций в Azure Databricks.

Поле Тип Описание
id Струна Обязательный. Уникальный идентификатор для рекомендации вызова этого инструмента.
type Струна Обязательный. Поддерживается только "function".
function Завершение вызова функции Обязательный. Вызов функции, предложенный моделью.
cache_control Струна Включает возможность кэширования для вашего запроса. Этот параметр принимается только моделями Claude, размещенными в Databricks. Пример кэширования запроса см. в разделе "Кэширование запросов ".

FunctionCallCompletion

Поле Тип Описание
name Струна Обязательно. Имя функции, которую рекомендовала модель.
arguments Объект Обязательно. Аргументы функции в виде сериализованного словаря JSON.

Примечание:ToolChoiceObject, ToolObject, и FunctionObject определены в разделе API ответов и используются обеими API.

ResponseFormatObject

См. структурированные выходные данные в Azure Databricks.

Поле Тип Описание
type Струна Обязательный. Тип определяемого формата ответа. Либо text для неструктурированного текста, json_object для неструктурированных объектов JSON или json_schema для объектов JSON, относящихся к определенной схеме.
json_schema JsonSchemaObject Обязательный. Схема JSON, соблюдаемая, если для type задано значение json_schema

JsonSchemaObject

См. структурированные выходные данные в Azure Databricks.

Поле Тип Описание
name Струна Обязательный. Имя формата ответа.
description Струна Описание формата ответа, которое используется моделью для определения того, как отвечать в этом формате.
schema Объект Обязательный. Схема формата ответа, описанная как объект схемы JSON.
strict Булев Следует ли включить строгое соблюдение схемы при создании выходных данных. Если задано значение true, модель следует точной схеме, определенной в поле схемы. Поддерживается только подмножество схемы JSON, когда включен строгий режим true

Ответ чата

Для запросов, не связанных с потоковой передачей, ответ представлен в виде одного объекта завершения чата. Для потоковых запросов ответ представляет собой text/event-stream, где каждое событие является объектом блока завершения. Структура объектов завершения и блока на верхнем уровне почти идентична: только choices имеет другой тип.

Поле Тип Описание
id Струна Уникальный идентификатор завершения чата.
choices List[ChatCompletionChoice] или List[ChatCompletionChunk] (потоковая передача) Список текстов завершения чата. n варианты возвращаются, если указан параметр n.
object Струна Тип объекта. Равно или "chat.completions" для не потоковой передачи, или "chat.completion.chunk" для потоковой передачи.
created Целое число Время, когда было сгенерировано завершение чата, в секундах.
model Струна Версия модели, используемая для создания ответа.
usage Использование Метаданные использования токенов. Может отсутствовать в потоковых ответах.

ChatCompletionChoice

Поле Тип Описание
index Целое число Индекс выбора в списке созданных вариантов.
message СообщениеЧата Сообщение о завершении чата, возвращаемое моделью. Роль будет assistant.
finish_reason Струна Причина, по которой модель перестала создавать токены.
extra_fields Струна При использовании собственных моделей от внешних поставщиков моделей API-интерфейсы поставщика могут включать дополнительные метаданные в ответы. Databricks фильтрует эти ответы и возвращает только подмножество исходных полей поставщика. Это safetyRating единственное дополнительное поле, поддерживаемое в настоящее время, см. документацию по Gemini для подробностей.

ChatCompletionChunk

Поле Тип Описание
index Целое число Индекс выбора в списке созданных вариантов.
delta СообщениеЧата Сообщение об окончании сессии чата в составе потоковых ответов, сгенерированных моделью. Только первый фрагмент гарантированно содержит role.
finish_reason Струна Причина, по которой модель перестала создавать токены. Только в последний блок будет внесено это содержимое.

API внедрения

Задачи по встраиванию отображают входные строки в векторы встраивания. Многие входные данные можно пакетировать вместе в каждом запросе. Сведения о запросах параметров конечной точки см. в POST /serving-endpoints/{name}/invocations.

Запрос на внедрение

Поле Тип Описание
input Строка или список[строка] Обязательный. Входной текст для встраивания. Может быть строкой или списком строк.
instruction Струна Необязательная инструкция для передачи в модель внедрения.

Инструкции необязательны и зависят от модели. Например, авторы BGE не рекомендуют инструкции при индексировании блоков и рекомендуется использовать инструкцию "Represent this sentence for searching relevant passages:" для получения запросов. Другие модели, такие как Instructor-XL поддерживают широкий спектр строк инструкций.

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

Поле Тип Описание
id Струна Уникальный идентификатор встраивания.
object Струна Тип объекта. Равно значению "list".
model Струна Имя модели внедрения, используемой для создания внедрения.
data ВстраиваемыйОбъект Встраиваемый объект.
usage Использование Метаданные использования токенов.

EmbeddingObject

Поле Тип Описание
object Струна Тип объекта. Равно значению "embedding".
index Целое число Индекс внедрения в списке внедрений, создаваемых моделью.
embedding Список[Float] Вектор внедрения. Каждая модель возвращает вектор фиксированного размера (1024 для BGE-Large)

API автодополнения

Задачи завершения текста предназначены для создания ответов на один запрос. В отличие от чата, эта задача поддерживает пакетные входные данные: несколько независимых запросов можно отправлять в одном запросе. Сведения о запросах параметров конечной точки см. в POST /serving-endpoints/{name}/invocations.

Запрос завершения

Поле По умолчанию Тип Описание
prompt Строка или список[строка] Обязательный. Запросы для модели.
max_tokens null null, что означает отсутствие ограничения или целое число больше нуля Максимальное количество генерируемых токенов.
stream true Булев Передавайте ответы обратно клиенту, чтобы предоставить частичные результаты для запросов. Если этот параметр включен в запрос, ответы отправляются в соответствии со стандартом событий, отправляемых сервером.
temperature 1.0 Число с плавающей запятой в диапазоне от [0, 2] Температура выборки. 0 детерминировано и выше значения вводят больше случайности.
top_p 1.0 Плавать в (0,1] Порог вероятности, используемый для семплирования ядра.
top_k null null, что означает отсутствие ограничения или целое число больше нуля Определяет количество наиболее вероятных токенов k, используемых для фильтрации по top-k. Задайте для этого значения значение 1, чтобы сделать выходные данные детерминированными.
error_behavior "error" "truncate" или "error" Для ошибок времени ожидания и превышения длины контекста. Одно из следующих: "truncate" (возвращать максимально возможное количество маркеров) и "error" (возвращать ошибку). Этот параметр принимается только конечными точками, работающими по схеме оплаты за токен.
n 1 Целое число больше нуля API возвращает n независимые завершения чата, когда указано n. Рекомендуется для рабочих нагрузок, которые создают несколько завершений для одного и того же входного значения, чтобы повысить эффективность вывода и сэкономить средства. Доступно только для конечных точек с выделенной пропускной способностью.
stop [] Строка или список[строка] Модель перестает создавать дополнительные маркеры при обнаружении одной из последовательностей в stop.
suffix "" Струна Строка, которая добавляется к окончанию каждого выполнения.
echo false Булев Возвращает запрос вместе с результатом.
use_raw_prompt false Булев Если true, передайте prompt непосредственно в модель без каких-либо преобразований.

Ответ на завершение задачи

Поле Тип Описание
id Струна Уникальный идентификатор завершения текста.
choices ЗавершениеВыбора Список дополнений текста. Если указан n, для каждого переданного запроса создается соответствующее количество вариантов n. Значение n по умолчанию — 1.
object Струна Тип объекта. Равно "text_completion"
created Целое число Время генерации завершения в секундах.
usage Использование Метаданные использования токенов.

CompletionChoice

Поле Тип Описание
index Целое число Индекс подсказки в запросе.
text Струна Созданное завершение.
finish_reason Струна Причина, по которой модель перестала создавать токены.

Дополнительные ресурсы

  • Last updated on