Справочник по REST API модели Foundation
В этой статье содержатся общие сведения об API databricks Foundation Model и моделях, которые они поддерживают. API-интерфейсы модели Foundation разработаны так, чтобы быть похожими на REST API OpenAI, облегчая таким образом миграцию существующих проектов. Как конечные точки оплаты за токен, так и подготовленные конечные точки пропускной способности принимают один и тот же формат запроса REST API.
Конечные точки
Каждая модель оплаты за токен имеет одну конечную точку, и пользователи могут взаимодействовать с этими конечными точками с помощью HTTP-запросов POST. Подготовленные конечные точки пропускной способности можно создать с помощью API или пользовательского интерфейса обслуживания. Эти конечные точки также поддерживают несколько моделей для каждой конечной точки для тестирования A/B, если обе обслуживаемые модели предоставляют один и тот же формат API. Например, обе модели являются моделями чата. Смотрите POST /api/2.0/обслуживающие конечные точки для конфигурации обслуживающих конечных точек parameters.
Запросы и ответы используют JSON, точная структура JSON зависит от типа задачи конечной точки. Конечные точки чата и завершения поддерживают потоковые ответы.
Рабочие нагрузки с оплатой за токен поддерживают определенные модели, см. в разделе Поддерживаемые модели для оплаты за токен для этих моделей и принятых форматов API.
Употребление
Ответы включают в себя вложенное сообщение usage, которое сообщает количество токенов в запросе и ответе. Формат этого вложенного сообщения одинаков для всех типов задач.
| Поле | Тип | Описание |
|---|---|---|
completion_tokens |
Целое число | Количество сгенерированных токенов. Не включен в ответы на внедрение. |
prompt_tokens |
Целое число | Количество токенов из входных запросов. |
total_tokens |
Целое число | Общее количество токенов. |
Для таких моделей, как llama-2-70b-chat запрос пользователя преобразуется с помощью шаблона запроса перед передачей в модель. Для конечных точек с оплатой за токен также может быть добавлен системный запрос.
prompt_tokens включает весь текст, добавленный нашим сервером.
задача чата
Задачи чата оптимизированы для многоходовых диалогов с моделью. Ответ модели предоставляет очередное сообщение assistant в разговоре. См. POST /сервинг-эндпоинты/{name}/invocations для запроса конечной точки parameters.
Запрос чата
| Поле | По умолчанию | Тип | Описание |
|---|---|---|---|
messages |
ChatMessagelist | Обязательный. list сообщений, представляющих текущую беседу. | |
max_tokens |
null |
null, что означает отсутствие limitили целое число больше нуля |
Максимальное число токенов для generate. |
stream |
true |
Булев | Передавайте ответы обратно клиенту, чтобы предоставить частичные результаты для запросов. Если этот параметр включен в запрос, ответы отправляются в соответствии со стандартом событий, отправляемых сервером. |
temperature |
1.0 |
Плавать в [0,2] | Температура выборки. 0 детерминировано, и более высокие values вводят больше случайности. |
top_p |
1.0 |
Плавать в (0,1] | Порог вероятности, используемый для семплирования ядра. |
top_k |
null |
null, что означает отсутствие limitили целое число больше нуля |
Определяет количество наиболее вероятных токенов k, используемых для фильтрации по top-k. Set это значение равно 1, чтобы сделать выходные данные детерминированными. |
stop |
[] | Строка или List[Строка] | Модель перестает создавать дополнительные маркеры при обнаружении одной из последовательностей в stop. |
n |
1 | Целое число больше нуля | API возвращает n независимых завершений чата при указании n. Рекомендуется для рабочих нагрузок, которые generate несколько завершений на одни и те же входные данные для дополнительной эффективности вывода и экономии затрат. Доступно только для конечных точек с выделенной пропускной способностью. |
tool_choice |
none |
Строка или ToolChoiceObject | Используется только в сочетании с полем tools.
tool_choice поддерживает различные строки ключевых слов, такие как auto, requiredи none.
auto означает, что вы позволяете модели самой решить, какой инструмент, если это применимо, следует использовать. Если auto модель считает, что никакие из средств в tools не подходят, модель генерирует стандартное сообщение помощника вместо вызова средства.
required означает, что модель выбирает наиболее релевантный инструмент в tools и должна generate выполнить вызов инструмента.
none означает, что модель не generate вызовы инструментов и вместо этого должна generate стандартное сообщение помощника. Для принудительного вызова инструмента с использованием инструмента, определенного в tools, используйте ToolChoiceObject. По умолчанию, если поле tools заполняется tool_choice = "auto". В противном случае для поля tools по умолчанию используется значение tool_choice = "none" |
tools |
null |
ToolObject | Некоторое listtools, которые модель может вызывать. В настоящее время function является единственным поддерживаемым типом tool и поддерживается не более 32 функций. |
response_format |
null |
ResponseFormatObject | Объект, указывающий формат, который должен выводить модель. Допустимые типы: text, json_schema или json_objectПараметр { "type": "json_schema", "json_schema": {...} } активирует структурированные выходные данные, которые гарантируют, что модель следует предоставленному JSON schema.Настройка на { "type": "json_object" } обеспечивает, что ответы, создаваемые моделью, являются допустимым JSON, однако это не гарантирует соответствие ответов определённому schema. |
logprobs |
false |
Булев | Этот параметр указывает, следует ли предоставлять логарифмическую вероятность выборки токена. |
top_logprobs |
null |
Целое число | Этот параметр определяет количество наиболее вероятных кандидатов токенов для возврата логарифмов вероятностей на каждом шаге выборки. Может быть 0–20.
logprobs должен быть true при использовании этого поля. |
ChatMessage
| Поле | Тип | Описание |
|---|---|---|
role |
Струна |
Обязательный. Роль автора сообщения. Может быть "system", "user", "assistant" или "tool". |
content |
Струна | Содержимое сообщения. Обязательно для задач чата, которые не включают вызовы инструментов. |
tool_calls |
ToolCalllist |
list из tool_calls, которые были сгенерированы моделью. Должно быть role в качестве "assistant" и отсутствует спецификация для поля content. |
tool_call_id |
Струна | Когда role равно "tool", идентификатор связан с ToolCall, на который отвечает сообщение. Должен быть пустым для других опций role. |
Роль system может использоваться только один раз, как первое сообщение в беседе. Она переопределяет системный запрос модели по умолчанию.
ToolCall
Предложение действия вызова инструментом модели. См. функции, вызываемой в Azure Databricks.
| Поле | Тип | Описание |
|---|---|---|
id |
Струна | Обязательный. Уникальный identifier для рекомендации вызова этого инструмента. |
type |
Струна |
Обязательный. Поддерживается только "function". |
function |
ЗавершениеВызоваФункции | Обязательный. Вызов функции, предлагаемый моделью. |
FunctionCallCompletion
| Поле | Тип | Описание |
|---|---|---|
name |
Струна | Обязательно. Имя функции, которую рекомендовала модель. |
arguments |
Объект | Обязательно. Аргументы функции в виде сериализованного словаря JSON. |
ToolChoiceObject
См. функции, вызываемой в Azure Databricks.
| Поле | Тип | Описание |
|---|---|---|
type |
Струна |
Обязательный. Тип средства. В настоящее время поддерживается только "function". |
function |
Объект |
Обязательный. Объект, определяющий, какой инструмент формы {"type": "function", "function": {"name": "my_function"}}where"my_function следует вызвать, является именем FunctionObject в поле tools. |
ToolObject
См. функции, вызываемой в Azure Databricks.
| Поле | Тип | Описание |
|---|---|---|
type |
Струна |
Обязательный. Тип средства. В настоящее время поддерживается только function. |
function |
FunctionObject | Обязательный. Определение функции, связанное с инструментом. |
FunctionObject
| Поле | Тип | Описание |
|---|---|---|
name |
Струна | Обязательный. Имя вызываемой функции. |
description |
Объект | Обязательный. Подробное описание функции. Модель использует это описание для понимания релевантности функции к запросу, а generate обеспечивает вызовы инструмента с более высокой точностью. |
parameters |
Объект |
parameters функция принимает объект JSON schema, описанный как допустимый. Если инструмент вызывается, то вызов инструмента соответствует предоставленному schema JSON. Пропуск parameters задаёт функцию без какого-либо parameters. Количество properties ограничено 15 ключами. |
strict |
Булев | Следует ли включить строгое соблюдение schema при создании вызова функции. Если set до true, модель следует точному schema, определенному в поле schema. Поддерживается только подмножество JSON schema, если строго true |
ResponseFormatObject
См. структурированные выходные данные в Azure Databricks.
| Поле | Тип | Описание |
|---|---|---|
type |
Струна |
Обязательный. Тип определяемого формата ответа. Либо text для неструктурированного текста, json_object для неструктурированных объектов JSON или json_schema для объектов JSON, которые относятся к определенной schema. |
json_schema |
JsonSchemaObject |
Обязательный. JSON schema, которому должно соответствовать, если type является set к json_schema |
JsonSchemaObject
См. структурированные выходные данные в Azure Databricks.
| Поле | Тип | Описание |
|---|---|---|
name |
Струна | Обязательный. Имя формата ответа. |
description |
Струна | Описание формата ответа, которое используется моделью для определения того, как отвечать в этом формате. |
schema |
Объект | Обязательный. schema для формата ответа, описанного как объект JSON schema. |
strict |
Булев | Следует ли включить строгое соблюдение schema при создании выходных данных. Если set до true, модель следует точному schema, определенному в поле schema. Поддерживается только подмножество JSON schema, если строго true |
Ответ чата
Для запросов, не связанных с потоковой передачей, ответ представлен в виде одного объекта завершения чата. Для потоковых запросов ответ представляет собой text/event-streamwhere каждое событие является объектом блока завершения. Структура завершения и объектов блока верхнего уровня почти идентична: только choices имеет другой тип.
| Поле | Тип | Описание |
|---|---|---|
id |
Струна | Уникальный identifier для завершения беседы. |
choices |
List[ChatCompletionChoice] или List[ChatCompletionChunk] (потоковая передача) |
List текста завершения чата.
n выборы возвращаются, если указан параметр n. |
object |
Струна | Тип объекта. Равно "chat.completions" для неподключенной передачи или "chat.completion.chunk" для потоковой передачи. |
created |
Целое число | Время, когда было сгенерировано завершение чата, в секундах. |
model |
Струна | Версия модели, использованная для ответа generate. |
usage |
Использование | Метаданные использования токенов. Может отсутствовать в потоковых ответах. |
ChatCompletionChoice
| Поле | Тип | Описание |
|---|---|---|
index |
Целое число | Индекс выбора в list сгенерированных вариантов. |
message |
СообщениеЧата | Сообщение о завершении чата, возвращаемое моделью. Роль будет assistant. |
finish_reason |
Струна | Причина, по которой модель перестала создавать токены. |
ChatCompletionChunk
| Поле | Тип | Описание |
|---|---|---|
index |
Целое число | Индекс выбора в list сгенерированных вариантов. |
delta |
СообщениеЧата | Сообщение об окончании сессии чата в составе потоковых ответов, сгенерированных моделью. Только первый фрагмент гарантированно содержит role. |
finish_reason |
Струна | Причина, по которой модель перестала создавать токены. Только последний блок будет заполнен. |
задача завершения
Задачи завершения текста предназначены для создания ответов на один запрос. В отличие от чата, эта задача поддерживает пакетные входные данные: несколько независимых запросов можно отправлять в одном запросе. См. POST /сервинг-эндпоинты/{name}/invocations для запроса конечной точки parameters.
Запрос завершения
| Поле | По умолчанию | Тип | Описание |
|---|---|---|---|
prompt |
Строка или List[Строка] | Обязательный. Запросы для модели. | |
max_tokens |
null |
null, что означает отсутствие limitили целое число больше нуля |
Максимальное число токенов для generate. |
stream |
true |
Булев | Передавайте ответы обратно клиенту, чтобы предоставить частичные результаты для запросов. Если этот параметр включен в запрос, ответы отправляются в соответствии со стандартом событий, отправляемых сервером. |
temperature |
1.0 |
Плавать в [0,2] | Температура выборки. 0 детерминировано, и более высокие values вводят больше случайности. |
top_p |
1.0 |
Плавать в (0,1] | Порог вероятности, используемый для семплирования ядра. |
top_k |
null |
null, что означает отсутствие limitили целое число больше нуля |
Определяет количество наиболее вероятных токенов k, используемых для фильтрации по top-k. Set это значение равно 1, чтобы сделать выходные данные детерминированными. |
error_behavior |
"error" |
"truncate" или "error" |
Для ошибок времени ожидания и превышения длины контекста. Одно из следующих: "truncate" (возвращать максимально возможное количество маркеров) и "error" (возвращать ошибку). Этот параметр принимается только конечными точками, работающими по схеме оплаты за токен. |
n |
1 | Целое число больше нуля | API возвращает n независимых завершений чата при указании n. Рекомендуется для рабочих нагрузок, которые generate несколько завершений на одни и те же входные данные для дополнительной эффективности вывода и экономии затрат. Доступно только для конечных точек с выделенной пропускной способностью. |
stop |
[] | Строка или List[Строка] | Модель перестает создавать дополнительные маркеры при обнаружении одной из последовательностей в stop. |
suffix |
"" |
Струна | Строка, которая добавляется к концу каждого завершения. |
echo |
false |
Булев | Возвращает запрос вместе с завершением. |
use_raw_prompt |
false |
Булев | Если true, передайте prompt непосредственно в модель без каких-либо преобразований. |
Ответ на завершение
| Поле | Тип | Описание |
|---|---|---|
id |
Струна | Уникальный identifier для завершения текста. |
choices |
ЗавершениеВыбор |
list — количество завершений текста. При указании n для каждого переданного запроса создается n выборов. Значение n по умолчанию — 1. |
object |
Струна | Тип объекта. Равно "text_completion" |
created |
Целое число | Время генерации завершения в секундах. |
usage |
Использование | Метаданные использования токенов. |
CompletionChoice
| Поле | Тип | Описание |
|---|---|---|
index |
Целое число | Индекс подсказки в запросе. |
text |
Струна | Созданное завершение. |
finish_reason |
Струна | Причина, по которой модель перестала создавать токены. |
задача внедрения
Задачи по встраиванию отображают входные строки в векторы встраивания. Многие входные данные можно пакетировать вместе в каждом запросе. См. POST /сервинг-эндпоинты/{name}/invocations для запроса конечной точки parameters.
Запрос на внедрение
| Поле | Тип | Описание |
|---|---|---|
input |
Строка или List[Строка] | Обязательный. Входной текст для встраивания. Может быть строкой или набором строк list. |
instruction |
Струна | Необязательная инструкция для передачи в модель внедрения. |
Инструкции необязательны и зависят от модели. Например, авторы BGE рекомендуют обходиться без инструкций при индексировании блоков и использовать инструкцию "Represent this sentence for searching relevant passages:" для извлечения запросов. Другие модели, такие как Instructor-XL поддерживают широкий спектр строк инструкций.
Ответ векторного представления
| Поле | Тип | Описание |
|---|---|---|
id |
Струна | Уникальный identifier для встраивания. |
object |
Струна | Тип объекта. Равно значению "list". |
model |
Струна | Имя модели внедрения, используемой для создания внедрения. |
data |
EmbeddingObject | Объект встраивания. |
usage |
Использование | Метаданные использования токенов. |
EmbeddingObject
| Поле | Тип | Описание |
|---|---|---|
object |
Струна | Тип объекта. Равно значению "embedding". |
index |
Целое число | Индекс встраивания в list встраиваний, созданных моделью. |
embedding |
List[Float] | Вектор внедрения. Каждая модель возвращает вектор фиксированного размера (1024 для BGE-Large) |