Udostępnij za pośrednictwem

Dokumentacja interfejsu API REST modelu bazowego

  • Artykuł

Ten artykuł zawiera ogólne informacje o interfejsie API dla Databricks Foundation Model API i obsługiwanych modeli. Interfejsy API modelu foundation zostały zaprojektowane tak, aby były podobne do interfejsu API REST platformy OpenAI, aby ułatwić migrację istniejących projektów. Punkty końcowe z płatnością na zasadzie płatności za token i oprogramowaną przepustowością akceptują ten sam format żądania REST API.

punkty końcowe

Każdy model płatności za token ma jeden punkt końcowy, a użytkownicy mogą korzystać z tych punktów końcowych przy użyciu żądań HTTP POST. Punkty końcowe z zaprojektowaną przepustowością można utworzyć przy użyciu interfejsu API lub za pomocą interfejsu użytkownika usługi. Te punkty końcowe obsługują również wiele modeli na punkt końcowy na potrzeby testowania A/B, o ile oba obsługiwane modele uwidaczniają ten sam format interfejsu API. Na przykład oba modele są modelami czatów. Zobacz POST /api/2.0/serving-endpoints, aby uzyskać parametry konfiguracji punktu końcowego.

Żądania i odpowiedzi używają kodu JSON. Dokładna struktura JSON zależy od typu zadania punktu końcowego. Punkty końcowe czatu i uzupełniania obsługują odpowiedzi w formie strumieniowania.

Obciążenia rozliczane za token obsługują niektóre modele; zobacz Obsługiwane modele dla płatności za token, aby poznać te modele i akceptowane formaty interfejsu API.

Użycie

Odpowiedzi obejmują komunikat podrzędny usage, który zgłasza liczbę tokenów w żądaniu i odpowiedzi. Format tego komunikatu podrzędnego jest taki sam we wszystkich typach zadań.

Pole Typ Opis
completion_tokens Liczba całkowita Liczba wygenerowanych tokenów. Nie uwzględnianie w odpowiedziach z osadzaniem.
prompt_tokens Liczba całkowita Liczba tokenów z monitów wejściowych.
total_tokens Liczba całkowita Łączna liczba tokenów.

W przypadku modeli takich jak llama-2-70b-chat monit użytkownika jest przekształcany przy użyciu szablonu monitu przed przekazaniem go do modelu. W przypadku punktów końcowych płatności za token może zostać również dodany monit systemowy. prompt_tokens zawiera cały tekst dodany przez nasz serwer.

Zadanie czatowe

Zadania czatu są zoptymalizowane pod kątem wieloturnowych rozmów z użyciem modelu. Odpowiedź modelu zawiera następny komunikat assistant w konwersacji. Zobacz POST /serving-endpoints/{name}/invocations w celu wykonywania zapytań dotyczących parametrów punktu końcowego.

Żądanie czatu

Pole Domyślny Typ Opis
messages lista ChatMessage wymagane. Lista wiadomości reprezentujących bieżącą konwersację.
max_tokens null null, co oznacza brak limitu lub liczbę całkowitą większą niż zero Maksymalna liczba tokenów do wygenerowania.
stream true Boolean Przesyłanie odpowiedzi do klienta w celu umożliwienia uzyskania częściowych wyników dla żądań. Jeśli ten parametr jest uwzględniony w żądaniu, odpowiedzi są wysyłane przy użyciu standardu zdarzeń wysyłanych przez serwer .
temperature 1.0 Liczba zmiennoprzecinkowa w [0,2] Temperatura próbkowania. Wartość 0 jest deterministyczna i wyższa wartość wprowadza większą losowość.
top_p 1.0 Liczba zmiennoprzecinkowa w przedziale (0,1] Próg prawdopodobieństwa używany do próbkowania jądra.
top_k null null, co oznacza brak limitu lub liczbę całkowitą większą niż zero Definiuje liczbę k najbardziej prawdopodobnych tokenów używanych do filtrowania top-k. Ustaw tę wartość na 1, aby uczynić dane wyjściowe deterministycznymi.
stop [] String lub lista [string] Model przestaje generować kolejne tokeny, gdy napotkano jedną z sekwencji w stop.
n 1 Liczba całkowita większa niż zero Interfejs API zwraca n niezależnych uzupełnień czatu, gdy zostanie określony n. Zalecane w przypadku obciążeń, które generują wiele uzupełnień na tych samych danych wejściowych, aby uzyskać dodatkową wydajność wnioskowania i oszczędność kosztów. Dostępne tylko dla punktów końcowych przydzielonej przepustowości.
tool_choice none Ciąg lub ToolChoiceObject Używane tylko w połączeniu z polem tools. tool_choice obsługuje różne ciągi słów kluczowych, takie jak auto, requiredi none. auto oznacza, że pozwalasz modelowi zdecydować, które (jeśli istnieje) narzędzie ma zastosowanie do użycia. W przypadku auto, jeśli model nie wierzy, że jakiekolwiek narzędzia w tools są istotne, model generuje standardowy komunikat asystenta zamiast wywołania narzędzia. required oznacza, że model wybiera najbardziej odpowiednie narzędzie w tools i musi wykonać wywołanie narzędzia. none oznacza, że model nie generuje żadnych wywołań narzędzi i zamiast tego musi wygenerować standardowy komunikat asystenta. Aby wymusić wywołanie narzędzia za pomocą określonego narzędzia zdefiniowanego w tools, użyj ToolChoiceObject. Jeśli domyślnie pole tools zostanie wypełnione tool_choice = "auto". W przeciwnym razie pole tools przyjmuje wartość domyślną tool_choice = "none"
tools null ToolObject Zestawienie tools, które model może wywołać. Obecnie function jest jedynym obsługiwanym typem tool i obsługiwane są maksymalnie 32 funkcje.
response_format null ResponseFormatObject Obiekt określający format, który musi zostać wygenerowany przez model. Akceptowane typy to text, json_schema lub json_object

Ustawienie na { "type": "json_schema", "json_schema": {...} } włącza ustrukturyzowane dane wyjściowe, co zapewnia, że model jest zgodny z podanym schematem JSON.

Ustawienie wartości { "type": "json_object" } gwarantuje, że odpowiedzi generowane przez model są prawidłowe w formacie JSON, ale nie gwarantuje, że odpowiedzi są zgodne z określonym schematem.
logprobs false Boolean Ten parametr wskazuje, czy zapewniać informację o logarytmicznym prawdopodobieństwie próbkowanego tokenu.
top_logprobs null Liczba całkowita Ten parametr steruje liczbą najbardziej prawdopodobnych kandydatów na tokeny, dla których każde z kroków próbkowania zwraca logarytmiczne prawdopodobieństwa. Może być 0–20. logprobs musi być true, jeśli jest używane to pole.

ChatMessage

Pole Typ Opis
role Struna wymagane. Rola autora wiadomości. Może to być "system", "user", "assistant" lub "tool".
content Struna Zawartość wiadomości. Wymagane dla zadań czatu, które nie obejmują wywołań narzędzi.
tool_calls ToolCall - lista Lista tool_calls, którą wygenerował model. Musi mieć role jako "assistant" i nie może mieć specyfikacji dla pola content.
tool_call_id Struna Gdy role jest "tool", identyfikator skojarzony z ToolCall, na który odpowiada komunikat. Musi być pusty dla wszystkich innych opcji role.

Rola system może być używana tylko raz, jako pierwsza wiadomość w konwersacji. Zastępuje on domyślny monit systemowy modelu.

ToolCall

Sugestia akcji wywołania narzędzia przez model. Zobacz Funkcja wywołująca w usłudze Azure Databricks.

Pole Typ Opis
id Struna wymagane. Unikatowy identyfikator tej sugestii wywołania narzędzia.
type Struna wymagane. Tylko "function" jest obsługiwane.
function ZakończenieWywołaniaFunkcji wymagane. Wywołanie funkcji sugerowane przez model.

FunctionCallCompletion

Pole Typ Opis
name Struna Wymagane. Nazwa funkcji zalecanej przez model.
arguments Obiekt Wymagane. Argumenty funkcji jako serializowany słownik JSON.

ToolChoiceObject

Zobacz Funkcja wywołująca w usłudze Azure Databricks.

Pole Typ Opis
type Struna wymagane. Typ narzędzia. Obecnie obsługiwana jest tylko "function".
function Obiekt wymagane. Obiekt definiujący, które narzędzie wywołać w kontekście {"type": "function", "function": {"name": "my_function"}}, gdzie "my_function jest nazwą obiektu funkcji w polu tools.

ToolObject

Zobacz Funkcja wywołująca w usłudze Azure Databricks.

Pole Typ Opis
type Struna wymagane. Typ narzędzia. Obecnie obsługiwana jest tylko function.
function ObiektFunkcji wymagane. Definicja funkcji skojarzona z narzędziem.

FunctionObject

Pole Typ Opis
name Struna wymagane. Nazwa funkcji do wywołania.
description Obiekt wymagane. Szczegółowy opis funkcji. Model używa tego opisu, aby zrozumieć istotność funkcji monitu i wygenerować wywołania narzędzia z większą dokładnością.
parameters Obiekt Parametry akceptowane przez funkcję, opisane jako prawidłowy obiekt schematu JSON . Jeśli narzędzie jest wywoływane, wywołanie narzędzia pasuje do podanego schematu JSON. Pominięcie parametrów definiuje funkcję bez żadnych parametrów. Liczba properties jest ograniczona do 15 kluczy.
strict Boolean Czy włączyć ścisłe przestrzeganie schematu podczas generowania wywołania funkcji. Jeśli ustawiono wartość true, model jest zgodny z dokładnym schematem zdefiniowanym w polu schematu. Obsługiwany jest tylko podzbiór schematu JSON, gdy strict ma wartość true

ResponseFormatObject

Zobacz Strukturalne dane wyjściowe w usłudze Azure Databricks.

Pole Typ Opis
type Struna wymagane. Typ zdefiniowanego formatu odpowiedzi. text dla tekstu bez struktury, json_object dla obiektów JSON bez struktury lub json_schema dla obiektów JSON przylegających do określonego schematu.
json_schema JsonSchemaObject wymagane. Schemat JSON, do którego należy się stosować, jeśli type jest ustawiony na json_schema

JsonSchemaObject

Zobacz Strukturalne dane wyjściowe w usłudze Azure Databricks.

Pole Typ Opis
name Struna wymagane. Nazwa formatu odpowiedzi.
description Struna Opis formatu odpowiedzi używany przez model do określenia sposobu reagowania w tym formacie.
schema Obiekt wymagane. Schemat formatu odpowiedzi opisany jako obiekt schematu JSON.
strict Boolean Czy włączyć ścisłe przestrzeganie schematu podczas generowania danych wyjściowych. Jeśli ustawiono wartość true, model jest zgodny z dokładnym schematem zdefiniowanym w polu schematu. Tylko podzbiór schematu JSON jest obsługiwany, gdy strict jest ustawiony na true.

Odpowiedź na czat

Dla żądań bez przesyłania strumieniowego odpowiedzią jest pojedynczy obiekt zakończenia czatu. W przypadku żądań przesyłania strumieniowego odpowiedź jest text/event-stream, w którym każde zdarzenie jest obiektem fragmentu ukończenia. Struktura najwyższego poziomu obiektów uzupełniania i fragmentów jest prawie identyczna: tylko choices ma inny typ.

Pole Typ Opis
id Struna Unikatowy identyfikator dla ukończenia czatu.
choices List[ChatCompletionChoice] lub List[ChatCompletionChunk] (przesyłanie strumieniowe) Lista tekstów ukończenia czatu. n opcje są zwracane, jeśli parametr n został określony.
object Struna Typ obiektu. Równe "chat.completions" dla nie przesyłania strumieniowego lub "chat.completion.chunk" dla przesyłania strumieniowego.
created Liczba całkowita Moment wygenerowania ukończenia czatu w sekundach.
model Struna Wersja modelu używana do generowania odpowiedzi.
usage Użycie Metadane użycia tokenu. Może nie być obecny w odpowiedziach strumieniowych.

ChatCompletionChoice

Pole Typ Opis
index Liczba całkowita Indeks wyboru w wykazie wygenerowanych opcji.
message ChatMessage Komunikat ukończenia czatu zwrócony przez model. Rola będzie assistant.
finish_reason Struna Przyczyna, dla którego model przestał generować tokeny.

ChatCompletionChunk

Pole Typ Opis
index Liczba całkowita Indeks wybranego elementu na liście wygenerowanych wyborów.
delta ChatMessage Część komunikatu ukończenia czatu z wygenerowanych strumieniowo odpowiedzi przez model. Zagwarantowano, że tylko pierwszy fragment zostanie wypełniony role.
finish_reason Struna Przyczyna, dla którego model przestał generować tokeny. Zostanie wypełniony tylko ostatni fragment.

zadanie ukończenia

Zadania uzupełniania tekstu służą do generowania odpowiedzi na jeden monit. W przeciwieństwie do czatu to zadanie obsługuje dane wejściowe wsadowe: w jednym żądaniu można wysyłać wiele niezależnych monitów. Zobacz POST /serving-endpoints/{name}/invocations w celu wykonywania zapytań dotyczących parametrów punktu końcowego.

Żądanie ukończenia

Pole Domyślny Typ Opis
prompt Ciąg znaków lub lista[ciągów znaków] wymagane. Wskazówki dla modelu.
max_tokens null null, co oznacza brak limitu lub liczbę całkowitą większą niż zero Maksymalna liczba tokenów do wygenerowania.
stream true Boolean Przesyłanie odpowiedzi do klienta w celu umożliwienia uzyskania częściowych wyników dla żądań. Jeśli ten parametr jest uwzględniony w żądaniu, odpowiedzi są wysyłane przy użyciu standardu zdarzeń wysyłanych przez serwer .
temperature 1.0 Liczba zmiennoprzecinkowa w [0,2] Temperatura próbkowania. Wartość 0 jest deterministyczna i wyższa wartość wprowadza większą losowość.
top_p 1.0 Liczba zmiennoprzecinkowa w przedziale (0,1] Próg prawdopodobieństwa używany do próbkowania jądra.
top_k null null, co oznacza brak limitu lub liczbę całkowitą większą niż zero Definiuje liczbę k najbardziej prawdopodobnych tokenów używanych do filtrowania top-k. Ustaw tę wartość na 1, aby uczynić dane wyjściowe deterministycznymi.
error_behavior "error" "truncate" lub "error" W przypadku przekroczenia limitu czasu i przekroczenia długości kontekstu. Jeden z tych: "truncate" (zwraca jak najwięcej tokenów) i "error" (zwraca błąd). Ten parametr jest akceptowany tylko przez punkty końcowe płatności za token.
n 1 Liczba całkowita większa niż zero Interfejs API zwraca n niezależnych uzupełnień czatu, gdy zostanie określony n. Zalecane w przypadku obciążeń, które generują wiele uzupełnień na tych samych danych wejściowych, aby uzyskać dodatkową wydajność wnioskowania i oszczędność kosztów. Dostępne tylko dla punktów końcowych przydzielonej przepustowości.
stop [] Ciąg lub lista[ciąg] Model przestaje generować kolejne tokeny, gdy napotkano jedną z sekwencji w stop.
suffix "" Struna Ciąg, który jest dołączany na końcu każdego ukończenia.
echo false Boolean Zwraca monit wraz z ukończeniem.
use_raw_prompt false Boolean Jeśli true, przekaż prompt bezpośrednio do modelu bez żadnego przekształcenia.

Odpowiedź na zakończenie

Pole Typ Opis
id Struna Unikatowy identyfikator dokończenia tekstu.
choices CompletionChoice Lista uzupełniania tekstu. Dla każdego przekazanego monitu generowane są n opcje, gdy określono n. Domyślny n to 1.
object Struna Typ obiektu. Równe "text_completion"
created Liczba całkowita Czas wygenerowania ukończenia w sekundach.
usage Użycie Metadane użycia tokenu.

CompletionChoice

Pole Typ Opis
index Liczba całkowita Indeks monitu w żądaniu.
text Struna Wygenerowane ukończenie.
finish_reason Struna Przyczyna, dla którego model przestał generować tokeny.

Zadanie osadzania

Zadania osadzania mapują ciągi wejściowe na wektory osadzania. Wiele danych wejściowych można wsadować razem w każdym żądaniu. Zobacz POST /serving-endpoints/{name}/invocations w celu wykonywania zapytań dotyczących parametrów punktu końcowego.

Żądanie osadzania

Pole Typ Opis
input Ciąg znaków lub lista [ciągów znaków] wymagane. Tekst wejściowy do osadzenia. Może być ciągiem lub listą ciągów.
instruction Struna Opcjonalna instrukcja do przekazania do modelu osadzania.

Instrukcje są opcjonalne i wysoce specyficzne dla modelu. Na przykład autorzy BGE zalecają brak instrukcji podczas indeksowania fragmentów i zalecają użycie instrukcji "Represent this sentence for searching relevant passages:" na potrzeby zapytań pobierania. Inne modele, takie jak Instructor-XL obsługują szeroką gamę ciągów instrukcji.

Odpowiedź osadzania

Pole Typ Opis
id Struna Unikatowy identyfikator embeddingu.
object Struna Typ obiektu. Równe "list".
model Struna Nazwa modelu osadzania użytego do utworzenia osadzania.
data ObiektOsadzania Obiekt osadzania.
usage Użycie Metadane użycia tokenu.

EmbeddingObject

Pole Typ Opis
object Struna Typ obiektu. Równe "embedding".
index Liczba całkowita Indeks osadzenia na liście osadzeń wygenerowanych przez model.
embedding Lista[Liczba zmiennoprzecinkowa] Wektor osadzania. Każdy model zwróci wektor o stałym rozmiarze (1024 dla BGE-Large)

Dodatkowe zasoby