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 dla konfiguracji punktu końcowego parameters.

Żą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 punktu końcowego parameters.

Żądanie czatu

Pole Domyślny Typ Opis
messages ChatMessagelist wymagane. Liczba list wiadomości reprezentujących bieżącą konwersację.
max_tokens null null, co oznacza brak limitlub liczbę całkowitą większą niż zero Maksymalna liczba tokenów do generate.
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 values 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 limitlub liczbę całkowitą większą niż zero Definiuje liczbę k najbardziej prawdopodobnych tokenów używanych do filtrowania top-k. Set tę wartość do 1, aby dane wyjściowe deterministyczne.
stop [] Ciąg lub List[ciąg] 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 generate wielu uzupełnień na tych samych danych wejściowych w celu uzyskania dodatkowej wydajności wnioskowania i oszczędności 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 z tools i powinien generate wywołać narzędzie. none oznacza, że model nie generate żadnych wywołań narzędzi i zamiast tego musi wykonać generate 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 list 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 schemaJSON.

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 schema.
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 ToolCalllist list dla tool_calls wygenerowany przez 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. Unikatowa identifier dla 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 do wywołania formularza {"type": "function", "function": {"name": "my_function"}}where"my_function jest nazwą FunctionObject 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 generate wywołania narzędzia z większą dokładnością.
parameters Obiekt Funkcja parameters akceptuje opisany jako prawidłowy obiekt JSON schema. Jeśli narzędzie jest wywoływane, to jego wywołanie odpowiada podanemu JSON schema. Pominięcie parameters definiuje funkcję bez żadnych parameters. Liczba properties jest ograniczona do 15 kluczy.
strict Boolean Czy włączyć przestrzeganie schema w sposób ścisły podczas generowania wywołania funkcji. Jeśli set do true, model jest zgodny z dokładnym schema zdefiniowanym w polu schema. Obsługiwany jest tylko podzbiór JSON schema, gdy tryb rygorystyczny jest true.

ResponseFormatObject

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

Pole Typ Opis
type Struna wymagane. Typ zdefiniowanego formatu odpowiedzi. Albo 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 schema.
json_schema JsonSchemaObject wymagane. JSON schema, które należy przestrzegać, jeśli type jest set do 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. schema dla formatu odpowiedzi, opisane jako obiekt schema JSON.
strict Boolean Czy włączyć przestrzeganie ścisłe schema podczas generowania wyników. Jeśli set do true, model jest zgodny z dokładnym schema zdefiniowanym w polu schema. Obsługiwany jest tylko podzbiór JSON schema, gdy tryb rygorystyczny jest true.

Odpowiedź na czat

Dla żądań bez przesyłania strumieniowego odpowiedzią jest pojedynczy obiekt zakończenia czatu. W przypadku żądań przesyłania strumieniowego odpowiedzią jest kombinacja text/event-streamwhere, w której 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 Unikalne identifier dla zakończenia czatu.
choices List[ChatCompletionChoice] lub List[ChatCompletionChunk] (przesyłanie strumieniowe) List 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 generate 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 list wygenerowanych wyborów.
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 wyboru w list 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 punktu końcowego parameters.

Żądanie ukończenia

Pole Domyślny Typ Opis
prompt Ciąg lub List[ciąg] wymagane. Wskazówki dla modelu.
max_tokens null null, co oznacza brak limitlub liczbę całkowitą większą niż zero Maksymalna liczba tokenów do generate.
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 values 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 limitlub liczbę całkowitą większą niż zero Definiuje liczbę k najbardziej prawdopodobnych tokenów używanych do filtrowania top-k. Set tę wartość do 1, aby dane wyjściowe deterministyczne.
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 generate wielu uzupełnień na tych samych danych wejściowych w celu uzyskania dodatkowej wydajności wnioskowania i oszczędności kosztów. Dostępne tylko dla punktów końcowych przydzielonej przepustowości.
stop [] Ciąg lub List[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 Unikalne identifier do uzupełniania tekstu.
choices CompletionChoice list 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 punktu końcowego parameters.

Żądanie osadzania

Pole Typ Opis
input Ciąg lub List[ciąg] 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 Unikatowe identifier osadzania.
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 embedingu w list generowanych przez model.
embedding List[zmiennoprzecinkowa] Wektor osadzania. Każdy model zwróci wektor o stałym rozmiarze (1024 dla BGE-Large)

Dodatkowe zasoby