Справочник по REST API модели Foundation
В этой статье содержатся общие сведения об API databricks Foundation Model и моделях, которые они поддерживают. API-интерфейсы модели Foundation разработаны так, чтобы быть похожими на REST API OpenAI, облегчая таким образом миграцию существующих проектов. Как конечные точки оплаты за токен, так и подготовленные конечные точки пропускной способности принимают один и тот же формат запроса REST API.
Конечные точки
API модельных платформ Foundation поддерживают конечные точки с оплатой за токен и конечные точки с гарантированной пропускной способностью.
Предварительно настроенная конечная точка доступна в рабочей области для каждой поддерживаемой модели с оплатой за токен, и пользователи могут взаимодействовать с этими конечными точками с помощью HTTP-запросов POST. См. "Оплата за токен" для поддерживаемых моделей.
Подготовленные конечные точки пропускной способности можно создать с помощью API или пользовательского интерфейса обслуживания. Эти конечные точки поддерживают несколько моделей на конечную точку для тестирования A/B, если обе обслуживаемые модели предоставляют один и тот же формат API. Например, обе модели являются моделями чата. Сведения о параметрах конфигурации конечной точки см. в POST /api/2.0/service-endpoints.
Запросы и ответы используют JSON, точная структура JSON зависит от типа задачи конечной точки. Конечные точки чата и завершения поддерживают потоковые ответы.
Употребление
Ответы включают в себя вложенное сообщение usage, которое сообщает количество токенов в запросе и ответе. Формат этого вложенного сообщения одинаков для всех типов задач.
| Поле | Тип | Описание |
|---|---|---|
completion_tokens |
Целое число | Количество сгенерированных токенов. Не включен в ответы на внедрение. |
prompt_tokens |
Целое число | Количество токенов из входных запросов. |
total_tokens |
Целое число | Общее количество токенов. |
Для таких моделей, как Meta-Llama-3.3-70B-Instruct запрос пользователя преобразуется с помощью шаблона запроса перед передачей в модель. Для конечных точек с оплатой за токен также может быть добавлен системный запрос.
prompt_tokens включает весь текст, добавленный нашим сервером.
задача чата
Задачи чата оптимизированы для многоходовых диалогов с моделью. Ответ модели предоставляет очередное сообщение 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 при использовании этого поля. |
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 |
ЗавершениеВызоваФункции | Обязательный. Вызов функции, предлагаемый моделью. |
FunctionCallCompletion
| Поле | Тип | Описание |
|---|---|---|
name |
Струна | Обязательно. Имя функции, которую рекомендовала модель. |
arguments |
Объект | Обязательно. Аргументы функции в виде сериализованного словаря JSON. |
ToolChoiceObject
См. функции, вызываемой в Azure Databricks.
| Поле | Тип | Описание |
|---|---|---|
type |
Струна |
Обязательный. Тип средства. В настоящее время поддерживается только "function". |
function |
Объект |
Обязательный. Объект, определяющий средство вызова формы {"type": "function", "function": {"name": "my_function"}}, где "my_function является именем FunctionObject в поле tools. |
ToolObject
См. функции, вызываемой в Azure Databricks.
| Поле | Тип | Описание |
|---|---|---|
type |
Струна |
Обязательный. Тип средства. В настоящее время поддерживается только function. |
function |
FunctionObject | Обязательный. Определение функции, связанное с инструментом. |
FunctionObject
| Поле | Тип | Описание |
|---|---|---|
name |
Струна | Обязательный. Имя вызываемой функции. |
description |
Объект | Обязательный. Подробное описание функции. Модель использует это описание для понимания релевантности функции в запросе и создания вызовов средства с более высокой точностью. |
parameters |
Объект | Параметры, которые принимает функция, описаны как объект, соответствующий допустимой схеме JSON. Если этот инструмент вызывается, вызов инструмента соответствует предоставленной схеме JSON. Опущение параметров определяет функцию без каких-либо параметров. Количество properties ограничено 15 ключами. |
strict |
Булев | Следует ли включить строгое соблюдение схемы при создании вызова функции. Если задано значение true, модель следует точной схеме, определенной в поле схемы. Поддерживается только подмножество схемы JSON, если строго true |
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 |
Струна | Причина, по которой модель перестала создавать токены. |
ChatCompletionChunk
| Поле | Тип | Описание |
|---|---|---|
index |
Целое число | Индекс выбора в списке созданных вариантов. |
delta |
СообщениеЧата | Сообщение об окончании сессии чата в составе потоковых ответов, сгенерированных моделью. Только первый фрагмент гарантированно содержит role. |
finish_reason |
Струна | Причина, по которой модель перестала создавать токены. Только последний блок будет заполнен. |
задача завершения
Задачи завершения текста предназначены для создания ответов на один запрос. В отличие от чата, эта задача поддерживает пакетные входные данные: несколько независимых запросов можно отправлять в одном запросе. Сведения о запросах параметров конечной точки см. в 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 |
Струна | Причина, по которой модель перестала создавать токены. |
задача внедрения
Задачи по встраиванию отображают входные строки в векторы встраивания. Многие входные данные можно пакетировать вместе в каждом запросе. Сведения о запросах параметров конечной точки см. в POST /serving-endpoints/{name}/invocations.
Запрос на внедрение
| Поле | Тип | Описание |
|---|---|---|
input |
Строка или список[строка] | Обязательный. Входной текст для встраивания. Может быть строкой или списком строк. |
instruction |
Струна | Необязательная инструкция для передачи в модель внедрения. |
Инструкции необязательны и зависят от модели. Например, авторы BGE рекомендуют обходиться без инструкций при индексировании блоков и использовать инструкцию "Represent this sentence for searching relevant passages:" для извлечения запросов. Другие модели, такие как Instructor-XL поддерживают широкий спектр строк инструкций.
Ответ векторного представления
| Поле | Тип | Описание |
|---|---|---|
id |
Струна | Уникальный идентификатор встраивания. |
object |
Струна | Тип объекта. Равно значению "list". |
model |
Струна | Имя модели внедрения, используемой для создания внедрения. |
data |
EmbeddingObject | Объект встраивания. |
usage |
Использование | Метаданные использования токенов. |
EmbeddingObject
| Поле | Тип | Описание |
|---|---|---|
object |
Струна | Тип объекта. Равно значению "embedding". |
index |
Целое число | Индекс внедрения в списке внедрений, создаваемых моделью. |
embedding |
Список[Float] | Вектор внедрения. Каждая модель возвращает вектор фиксированного размера (1024 для BGE-Large) |