Dokumentacja interfejsu API REST modelu podstawowego
Ten artykuł zawiera ogólne informacje o interfejsie API dla interfejsów API modelu usługi Databricks Foundation i modeli, które obsługują. 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 aprowizowaną przepływności akceptują ten sam format żądania interfejsu API REST.
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. Aprowizowanie punktów końcowych przepływności można utworzyć przy użyciu interfejsu API lub interfejsu użytkownika obsługującego. 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 przesyłania strumieniowego.
Obciążenia z płatnością za token obsługują niektóre modele, zobacz Obsługiwane modele dla tokenu płatności za token dla tych modeli i akceptowane formaty interfejsu API.
Użycie
Odpowiedzi obejmują usage komunikat podrzędny, 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 |
Integer | Liczba wygenerowanych tokenów. Nieuwzględnianie w odpowiedziach osadzania. |
prompt_tokens |
Integer | Liczba tokenów z monitów wejściowych. |
total_tokens |
Integer | Łą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 czatu
Zadania czatu są zoptymalizowane pod kątem konwersacji obejmujących wiele kolei przy użyciu modelu. Każde żądanie opisuje konwersację do tej pory, gdzie messages pole musi być alternatywne między rolami user i assistant kończące się komunikatem user . Odpowiedź modelu zawiera następny assistant komunikat w konwersacji. Zobacz POST /serving-endpoints/{name}/invocations w celu wykonywania zapytań dotyczących parametrów punktu końcowego.
Żądanie czatu
| Pole | Wartość domyślna | Typ | Opis |
|---|---|---|---|
messages |
Lista komunikatów czatu | Wymagany. 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 |
Wartość logiczna | Przesyłanie strumieniowe odpowiedzi z powrotem do klienta w celu umożliwienia częściowych wyników dla żądań. Jeśli ten parametr jest uwzględniony w żądaniu, odpowiedzi są wysyłane przy użyciu standardu Zdarzenia wysyłane przez serwer. |
temperature |
1.0 |
Zmiennoprzecinkowy w [0,2] | Temperatura próbkowania. Wartość 0 jest deterministyczna i wyższa wartość wprowadza większą losowość. |
top_p |
1.0 |
Liczba zmiennoprzecinkowa (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 dane wyjściowe deterministyczne. |
stop |
[] | Ciąg lub lista[ciąg] | Model przestaje generować kolejne tokeny, gdy napotkano jedną z sekwencji.stop |
n |
1 | Liczba całkowita większa niż zero | Interfejs API zwraca n niezależne ukończenie czatu, gdy n jest określony. 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 aprowizowanej przepływności. |
tool_choice |
none |
String 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 narzędzie (jeśli istnieje) ma zastosowanie. Jeśli auto model nie uważa, że jakiekolwiek narzędzia w programie tools są istotne, model generuje standardowy komunikat asystenta zamiast wywołania narzędzia.
required oznacza, że model wybiera najbardziej odpowiednie narzędzie i tools musi wygenerować 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 tools pole jest wypełnione tool_choice = "auto".
tools W przeciwnym razie pole jest domyślnie ustawione natool_choice = "none" |
tools |
null |
ToolObject | Lista, którą tools może wywołać model.
function Obecnie jest jedynym obsługiwanym tool typem, a maksymalna liczba funkcji 32 jest obsługiwana. |
response_format |
null |
ResponseFormatObject | Obiekt określający format, który musi zostać wygenerowany przez model. Akceptowane typy to text, json_schema lub json_objectUstawienie w celu { "type": "json_schema", "json_schema": {...} } włączenia danych wyjściowych ze strukturą, co zapewnia, że model jest zgodny z podanym schematem JSON.Ustawienie w celu { "type": "json_object" } zapewnienia odpowiedzi generowanych przez model jest prawidłowym kodem JSON, ale nie gwarantuje, że odpowiedzi są zgodne z określonym schematem. |
logprobs |
false |
Wartość logiczna | Ten parametr wskazuje, czy zapewnić prawdopodobieństwo dziennika próbkowanego tokenu. |
top_logprobs |
null |
Integer | Ten parametr steruje liczbą najbardziej prawdopodobnych kandydatów do tokenu w celu zwrócenia prawdopodobieństwa dziennika dla każdego kroku próbkowania. Może być 0–20.
logprobs musi być true używany w przypadku używania tego pola. |
ChatMessage
| Pole | Typ | Opis |
|---|---|---|
role |
String |
Wymagany. Rola autora wiadomości. Może to być "system", "user""assistant"lub "tool". |
content |
String | Zawartość wiadomości. Wymagane w przypadku zadań czatu, które nie obejmują wywołań narzędzi. |
tool_calls |
Lista NarzędziCall | Lista tool_calls wygenerowanych modeli. Musi mieć role wartość i "assistant" brak specyfikacji dla content pola. |
tool_call_id |
String | Gdy role ma "tool"wartość , identyfikator skojarzony z ToolCall tym, na który odpowiada komunikat. W przypadku innych role opcji musi być pusty. |
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 Wywoływanie funkcji w usłudze Azure Databricks.
| Pole | Typ | Opis |
|---|---|---|
id |
String | Wymagany. Unikatowy identyfikator tej sugestii wywołania narzędzia. |
type |
String |
Wymagany. Obsługiwany jest tylko warunek "function". |
function |
FunctionCallCompletion | Wymagany. Wywołanie funkcji sugerowane przez model. |
FunctionCallCompletion
| Pole | Typ | Opis |
|---|---|---|
name |
String | Wymagany. Nazwa funkcji zalecanej przez model. |
arguments |
Objekt | Wymagany. Argumenty funkcji jako serializowany słownik JSON. |
ToolChoiceObject
Zobacz Wywoływanie funkcji w usłudze Azure Databricks.
| Pole | Typ | Opis |
|---|---|---|
type |
String |
Wymagany. Typ narzędzia. Obecnie obsługiwane są tylko "function" te elementy. |
function |
Objekt |
Wymagany. Obiekt definiujący narzędzie do wywoływania formularza {"type": "function", "function": {"name": "my_function"}} , w którym "my_function jest nazwą obiektu FunctionObject w tools polu. |
ToolObject
Zobacz Wywoływanie funkcji w usłudze Azure Databricks.
| Pole | Typ | Opis |
|---|---|---|
type |
String |
Wymagany. Typ narzędzia. Obecnie obsługiwane są tylko function te elementy. |
function |
FunctionObject | Wymagany. Definicja funkcji skojarzona z narzędziem. |
FunctionObject
| Pole | Typ | Opis |
|---|---|---|
name |
String | Wymagany. Nazwa funkcji do wywołania. |
description |
Objekt | Wymagany. 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 |
Objekt | 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 kluczy jest ograniczona properties do 15 kluczy. |
strict |
Wartość logiczna | 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. Tylko podzbiór schematu JSON jest obsługiwany, gdy jest ściśle true |
ResponseFormatObject
Zobacz Dane wyjściowe ze strukturą w usłudze Azure Databricks.
| Pole | Typ | Opis |
|---|---|---|
type |
String |
Wymagany. Typ zdefiniowanego formatu odpowiedzi. W text przypadku tekstu bez struktury, json_object dla obiektów JSON bez struktury lub json_schema obiektów JSON przylegających do określonego schematu. |
json_schema |
JsonSchemaObject |
Wymagany. Schemat JSON zgodny z type ustawieniami json_schema |
JsonSchemaObject
Zobacz Dane wyjściowe ze strukturą w usłudze Azure Databricks.
| Pole | Typ | Opis |
|---|---|---|
name |
String | Wymagany. Nazwa formatu odpowiedzi. |
description |
String | Opis formatu odpowiedzi używany przez model do określenia sposobu reagowania w formacie. |
schema |
Objekt | Wymagany. Schemat formatu odpowiedzi opisany jako obiekt schematu JSON. |
strict |
Wartość logiczna | 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 jest ściśle true |
Odpowiedź na czat
W przypadku żądań nieprzesyłania strumieniowego odpowiedź jest pojedynczym obiektem uzupełniania czatu. W przypadku żądań przesyłania strumieniowego text/event-stream odpowiedź to miejsce, w którym każde zdarzenie jest obiektem fragmentu ukończenia. Struktura najwyższego poziomu uzupełniania i fragmentów jest prawie identyczna: ma tylko choices inny typ.
| Pole | Typ | Opis |
|---|---|---|
id |
String | Unikatowy identyfikator ukończenia czatu. |
choices |
List[ChatCompletionChoice] lub List[ChatCompletionChunk] (przesyłanie strumieniowe) | Lista tekstów ukończenia czatu.
n opcje są zwracane, jeśli n określono parametr. |
object |
String | Typ obiektu. Równe wartości "chat.completions" dla przesyłania strumieniowego lub "chat.completion.chunk" przesyłania strumieniowego. |
created |
Integer | Czas generowania ukończenia czatu w sekundach. |
model |
String | Wersja modelu używana do generowania odpowiedzi. |
usage |
Użycie | Metadane użycia tokenu. Może nie być obecny w odpowiedziach na przesyłanie strumieniowe. |
ChatCompletionChoice
| Pole | Typ | Opis |
|---|---|---|
index |
Integer | Indeks wybranego elementu na liście wygenerowanych wyborów. |
message |
ChatMessage | Komunikat ukończenia czatu zwrócony przez model. Rola będzie mieć assistantwartość . |
finish_reason |
String | Przyczyna, dla którego model przestał generować tokeny. |
ChatCompletionChunk
| Pole | Typ | Opis |
|---|---|---|
index |
Integer | Indeks wybranego elementu na liście wygenerowanych wyborów. |
delta |
ChatMessage | Część komunikatu ukończenia czatu wygenerowanych strumieniowo odpowiedzi z modelu. Zagwarantowano role wypełnienie tylko pierwszego fragmentu. |
finish_reason |
String | 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 | Wartość domyślna | Typ | Opis |
|---|---|---|---|
prompt |
Ciąg lub lista[ciąg] | Wymagany. Pytania do 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 |
Wartość logiczna | Przesyłanie strumieniowe odpowiedzi z powrotem do klienta w celu umożliwienia częściowych wyników dla żądań. Jeśli ten parametr jest uwzględniony w żądaniu, odpowiedzi są wysyłane przy użyciu standardu Zdarzenia wysyłane przez serwer. |
temperature |
1.0 |
Zmiennoprzecinkowy w [0,2] | Temperatura próbkowania. Wartość 0 jest deterministyczna i wyższa wartość wprowadza większą losowość. |
top_p |
1.0 |
Liczba zmiennoprzecinkowa (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 dane wyjściowe deterministyczne. |
error_behavior |
"error" |
"truncate" lub "error" |
W przypadku przekroczenia limitu czasu i przekroczenia długości kontekstu. Jeden z: "truncate" (zwraca jak najwięcej tokenów) i "error" (zwróć 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 ukończenie czatu, gdy n jest określony. 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 aprowizowanej przepływności. |
stop |
[] | Ciąg lub lista[ciąg] | Model przestaje generować kolejne tokeny, gdy napotkano jedną z sekwencji.stop |
suffix |
"" |
String | Ciąg, który jest dołączany na końcu każdego ukończenia. |
echo |
false |
Wartość logiczna | Zwraca monit wraz z ukończeniem. |
use_raw_prompt |
false |
Wartość logiczna | Jeśli trueelement , przekaż prompt bezpośrednio do modelu bez żadnych przekształceń. |
Odpowiedź na zakończenie
| Pole | Typ | Opis |
|---|---|---|
id |
String | Unikatowy identyfikator uzupełniania tekstu. |
choices |
ZakończenieChoice | Lista uzupełniania tekstu. Dla każdego przekazanego monitu opcje są generowane, n jeśli n jest określony. Wartość domyślna n to 1. |
object |
String | Typ obiektu. Równe "text_completion" |
created |
Integer | Czas wygenerowania ukończenia w sekundach. |
usage |
Użycie | Metadane użycia tokenu. |
CompletionChoice
| Pole | Typ | Opis |
|---|---|---|
index |
Integer | Indeks monitu w żądaniu. |
text |
String | Wygenerowane ukończenie. |
finish_reason |
String | Przyczyna, dla którego model przestał generować tokeny. |
Zadanie osadzania
Osadzanie zadań mapuje 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 lub lista[ciąg] | Wymagany. Tekst wejściowy do osadzenia. Może być ciągiem lub listą ciągów. |
instruction |
String | Opcjonalna instrukcja przekazywania do modelu osadzania. |
Instrukcje są opcjonalne i wysoce specyficzne dla modelu. Na przykład autorzy BGE nie zaleca żadnych instrukcji podczas indeksowania fragmentów i zalecamy użycie instrukcji "Represent this sentence for searching relevant passages:" do pobierania zapytań. Inne modele, takie jak Instructor-XL, obsługują szeroką gamę ciągów instrukcji.
Odpowiedź osadzania
| Pole | Typ | Opis |
|---|---|---|
id |
String | Unikatowy identyfikator osadzania. |
object |
String | Typ obiektu.
"list"Równe . |
model |
String | Nazwa modelu osadzania użytego do utworzenia osadzania. |
data |
Osadzanie obiektuObject | Obiekt osadzania. |
usage |
Użycie | Metadane użycia tokenu. |
EmbeddingObject
| Pole | Typ | Opis |
|---|---|---|
object |
String | Typ obiektu.
"embedding"Równe . |
index |
Integer | Indeks osadzania na liście osadzonych elementów wygenerowanych przez model. |
embedding |
List[Float] | Wektor osadzania. Każdy model zwróci wektor o stałym rozmiarze (1024 dla dużych BGE) |