Udostępnij za pośrednictwem

Dokumentacja referencyjna 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ą za token i zapewnioną przepustowością akceptują ten sam format żądań REST API.

punkty końcowe

Interfejsy API modelu podstawowego obsługują punkty końcowe rozliczane za token oraz punkty końcowe o zapewnionej przepustowości.

Wstępnie skonfigurowany punkt końcowy jest dostępny w obszarze roboczym dla każdego obsługiwanego modelu płatności za token, a użytkownicy mogą wchodzić w interakcje z tymi punktami końcowymi przy użyciu żądań HTTP POST. Zobacz Płatność za Token w przypadku obsługiwanych modeli.

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ą wiele modeli na punkt końcowy na potrzeby testowania A/B, o ile oba obsługiwane modele udostępniają 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.

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 włączone w odpowiedzi dotyczące osadzania.
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 Meta-Llama-3.3-70B-Instruct 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 w postaci zmiennoprzecinkowej w przedziale [0,2] Temperatura próbkowania. Wartość 0 jest deterministyczna i wyższa wartość wprowadza większą losowość.
top_p 1.0 Liczba zmiennoprzecinkowa z zakresu (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. Domyślnie, jeśli 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", jest to identyfikator skojarzony z ToolCall, na który odpowiada komunikat. Musi być pusty dla 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 modelu dotycząca wywołania akcji narzędzia. Zobacz Wywoływanie funkcji na platformie 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. Sugerowane przez model wywołanie funkcji.

FunctionCallCompletion

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

ToolChoiceObject

Zobacz Wywoływanie funkcji na 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ć z formy {"type": "function", "function": {"name": "my_function"}}, gdzie "my_function jest nazwą obiekt funkcji w polu tools.

ToolObject

Zobacz Wywoływanie funkcji na platformie 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 dla monitu i wygenerować wywołania narzędzi 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 celu formatu odpowiedzi, który jest używany przez model do określenia, jak odpowiedzieć 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. Obsługiwany jest tylko podzbiór schematu JSON, gdy strict ma wartość true

Odpowiedź na czat

Dla żądań bez przesyłania strumieniowego odpowiedzią jest pojedynczy obiekt wyniku 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ówna się "chat.completions" dla transmisji niestreamowanej lub "chat.completion.chunk" dla transmisji strumieniowej.
created Liczba całkowita Czas wygenerowania ukończenia konwersacji w sekundach.
model Struna Wersja modelu używana do generowania odpowiedzi.
usage Użycie Metadane użycia tokenu. Może nie występować w odpowiedziach strumieniowych.

ChatCompletionChoice

Pole Typ Opis
index Liczba całkowita Indeks wyboru w wykazie wygenerowanych opcji.
message ChatMessage Wiadomość o zakończeniu czatu zwrócona 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 wyboru w wykazie wygenerowanych opcji.
delta ChatMessage Część komunikatu o ukończeniu czatu, będąca wynikiem wygenerowanych strumieniowo odpowiedzi modelu. 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ńczeniowe

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 String lub lista [string] 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 Zmiennoprzecinkowa w przedziale [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 limitów czasu i błędów związanych z przekroczeniem 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żne uzupełnienia czatu, gdy jest 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 [] String lub lista [string] Model przestaje generować kolejne tokeny, gdy napotkano jedną z sekwencji w stop.
suffix "" Struna Ciąg, który jest dodawany na końcu każdego dokoń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 zapytania generowane są n opcje, jeśli określono n. Domyślna wartość 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 podpowiedzi 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 string lub lista[string] wymagane. Tekst wejściowy, który ma zostać osadzony. 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[Float] Wektor osadzania. Każdy model zwróci wektor o stałym rozmiarze (1024 dla BGE-Large)

Dodatkowe zasoby