Sdílet prostřednictvím

Referenční informace k rozhraní REST API základního modelu

  • Článek

Tento článek obsahuje obecné informace o rozhraní API pro rozhraní API modelu Databricks Foundation a modely, které podporují. Rozhraní API základního modelu jsou navržená tak, aby byla podobná rozhraní REST API OpenAI, aby se usnadnila migrace stávajících projektů. Koncové body na základě platby za token i zřízenou propustnost přijímají stejný formát požadavku rozhraní REST API.

koncové body

Každý model plateb za token má jeden koncový bod a uživatelé můžou s těmito koncovými body pracovat pomocí požadavků HTTP POST. Koncové body zřízené propustnosti je možné vytvořit pomocí rozhraní API neboobslužného uživatelského rozhraní . Tyto koncové body také podporují více modelů na koncový bod pro testování A/B, pokud oba obsluhované modely zpřístupňují stejný formát rozhraní API. Oba modely jsou například modely chatu. Viz POST /api/2.0/serving-endpoints pro konfiguraci koncového bodu parameters.

Požadavky a odpovědi používají JSON, přesná struktura JSON závisí na typu úlohy koncového bodu. Koncové body pro chat a auto-dokončování podporují proudové odpovědi.

Úlohy účtované za token podporují určité modely, vizte Podporované modely pro platbu za token pro tyto modely a přijímané formáty API.

Použití

Odpovědi zahrnují dílčí zprávu usage, která hlásí počet tokenů v požadavku a odpovědi. Formát této dílčí zprávy je stejný pro všechny typy úkolů.

Pole Typ Popis
completion_tokens Celé číslo Počet vygenerovaných tokenů Není zahrnuto ve vkládání odpovědí.
prompt_tokens Celé číslo Počet tokenů ze vstupních výzev
total_tokens Celé číslo Počet celkového počtu tokenů

U modelů, jako je llama-2-70b-chat, se výzva uživatele před předáním do modelu transformuje pomocí šablony výzvy. U koncových bodů s platbami za token se může přidat také výzva systému. prompt_tokens obsahuje veškerý text přidaný naším serverem.

Chat – úloha

Úkoly chatu jsou optimalizované pro vícekrokové konverzace pomocí modelu. Odpověď modelu přináší další assistant zprávu v konverzaci. Viz POST /serving-endpoints/{name}/invocations pro dotazování koncového bodu parameters.

Žádost o chat

Pole Výchozí Typ Popis
messages ChatMessagelist Požadované. list zpráv představujících aktuální konverzaci.
max_tokens null null, což znamená žádné limitnebo celé číslo větší než nula Maximální počet tokenů pro generate.
stream true Boolean Umožněte streamování odpovědí zpět klientovi, aby bylo možné poskytnout částečné výsledky pro požadavky. Pokud je tento parametr součástí požadavku, odpovědi se posílají pomocí standardu pro události zasílané serverem.
temperature 1.0 Plovoucí v [0,2] Teplota vzorkování. Hodnota 0 je deterministická a vyšší values představuje větší náhodnost.
top_p 1.0 Float in (0,1] Prahová hodnota pravděpodobnosti použitá pro vzorkování jádra.
top_k null null, což znamená, že buď neexistuje žádná limit, nebo že je to celé číslo větší než nula Definuje počet nejpravděpodobnějších k tokenů pro použití při filtrování top-k. Set tuto hodnotu na 1, aby výstupy byly deterministické.
stop [] Řetězec nebo List[Řetězec] Model přestane generovat další tokeny, když dojde k nějaké sekvenci v stop.
n 1 Celé číslo větší než nula Rozhraní API vrátí n nezávislé dokončování chatu při zadání n. Doporučeno pro úlohy, které generate více dokončení na stejném vstupu pro zvýšení efektivity a úspory nákladů. K dispozici pouze pro koncové body s provisionovanou kapacitou propustnosti.
tool_choice none String nebo ToolChoiceObject Používá se pouze ve spojení s polem tools. tool_choice podporuje různé řetězce klíčových slov, jako jsou auto, requireda none. auto znamená, že necháte model rozhodnout, který nástroj je vhodné použít, pokud vůbec existuje. Pokud auto, pokud model nevěří žádnému z nástrojů v tools jsou relevantní, model místo volání nástroje vygeneruje standardní zprávu asistenta. required znamená, že model vybere nejrelevavantnější nástroj v tools a musí generate volání nástroje. none znamená, že model generate žádná volání nástrojů a místo toho musí generate standardní zprávu asistenta. Chcete-li vynutit volání nástroje s konkrétním nástrojem definovaným v tools, použijte ToolChoiceObject. Ve výchozím nastavení, pokud je pole tools vyplněno, je to tool_choice = "auto". Jinak pole tools ve výchozím nastavení přebírá hodnotu tool_choice = "none".
tools null ToolObject list tools, které model může volat. V současné době je function jediným podporovaným typem tool a podporuje se maximálně 32 funkcí.
response_format null responseFormatObject Objekt určující formát, který musí model vypíše. Akceptované typy jsou text, json_schema nebo json_object

Nastavení { "type": "json_schema", "json_schema": {...} } umožňuje strukturované výstupy, které zajistí, že model je v souladu s vaším zadaným JSON schema.

Nastavení { "type": "json_object" } zajišťuje, že odpovědi, které model vygeneruje, jsou platné JSON, ale nezajistí, aby odpovědi dodržovaly konkrétní schema.
logprobs false Boolean Tento parametr určuje, jestli se má poskytnout logaritmická pravděpodobnost výběru tokenu.
top_logprobs null Celé číslo Tento parametr řídí počet nejpravděpodobnějších tokenů, pro každý krok vzorkování vrátí logaritmované pravděpodobnosti. Může být 0–20. logprobs musí být true, pokud se používá toto pole.

ChatMessage

Pole Typ Popis
role Řetězec Požadované. Role autora zprávy Může být "system", "user", "assistant" nebo "tool".
content Řetězec Obsah zprávy. Požadované pro úlohy chatu, které nezahrnují volání nástrojů.
tool_calls ToolCalllist Výsledek list z tool_calls, který model vygeneroval. Musí mít role jako "assistant" a žádné specifikace pro pole content.
tool_call_id Řetězec Když je role"tool", jedná se o ID přidružené k ToolCall, na kterou zpráva odpovídá. Pro ostatní možnosti role musí být prázdné.

Roli system lze použít jenom jednou, jako první zprávu v konverzaci. Přepíše výchozí systémovou výzvu modelu.

ToolCall

Návrh akce volání nástroje podle modelu. Viz volání funkce v Azure Databricks.

Pole Typ Popis
id Řetězec Požadované. Jedinečný identifier pro tento návrh volání nástroje.
type Řetězec Požadované. Podporuje se jenom "function".
function FunctionCallCompletion Požadované. Volání funkce navrhované modelem

FunctionCallCompletion

Pole Typ Popis
name Řetězec Povinné. Název funkce, kterou model doporučil.
arguments Objekt Povinné. Argumenty pro funkci ve formě serializovaného JSON slovníku.

ToolChoiceObject

Viz volání funkce v Azure Databricks.

Pole Typ Popis
type Řetězec Požadované. Typ nástroje. V současné době se podporuje pouze "function".
function Objekt Požadované. Objekt definující, který nástroj volat, má ve formě {"type": "function", "function": {"name": "my_function"}}where"my_function název FunctionObject v poli tools.

ToolObject

Viz volání funkce v Azure Databricks.

Pole Typ Popis
type Řetězec Požadované. Typ nástroje. V současné době se podporuje pouze function.
function FunctionObject Požadované. Definice funkce přidružená k nástroji.

FunctionObject

Pole Typ Popis
name Řetězec Požadované. Název funkce, která se má volat.
description Objekt Požadované. Podrobný popis funkce. Model používá tento popis k pochopení relevance funkce pro výzvu a generate volání nástroje s vyšší přesností.
parameters Objekt parameters funkce přijímá, popsaná jako platný JSON objekt schema. Pokud je nástroj volán, jeho volání odpovídá poskytnutému schema JSON. Vynechání parameters definuje funkci bez jakéhokoli parameters. Počet properties je omezený na 15 klíčů.
strict Boolean Zda povolit přísné dodržování schema při generování volání funkce. Pokud set do true, model se řídí přesným schema definovaným v poli schema. Pokud je true striktní, je podporována pouze podmnožina schema JSON.

ResponseFormatObject

Viz část Strukturované výstupy ve službě Azure Databricks.

Pole Typ Popis
type Řetězec Požadované. Typ formátu odpovědi, který se definuje. Buď text pro nestrukturovaný text, json_object pro nestrukturované objekty JSON, nebo json_schema pro objekty JSON, které dodržují konkrétní schema.
json_schema jsonSchemaObject Požadované. JSON schema se má dodržovat, pokud type je set k json_schema

JsonSchemaObject

Viz část Strukturované výstupy ve službě Azure Databricks.

Pole Typ Popis
name Řetězec Požadované. Název formátu odpovědi.
description Řetězec Popis formátu odpovědi, který model používá k určení způsobu reakce v tomto formátu.
schema Objekt Požadované. Formát odpovědi schema, popsaný jako objekt JSON schema.
strict Boolean Zda povolit striktní schema dodržování při generování výstupu. Pokud je set do true, model se řídí přesným schema definovaným v poli schema. Když je strict true, podporuje se jen podmnožina schema JSON.

Odpověď na chat

V případě požadavků, které nejsou streamované, je odpovědí jeden objekt dokončení chatu. U požadavků na streamování je odpověď text/event-streamwhere, každá událost je objekt dokončovacího bloku. Struktura objektů dokončení a bloků dat nejvyšší úrovně je téměř identická: pouze choices má jiný typ.

Pole Typ Popis
id Řetězec Jedinečné identifier pro dokončení chatu.
choices List[ChatCompletionChoice] nebo List[ChatCompletionChunk] (streamování) List textu dokončení chatu. Volby n se vrátí, pokud je zadán parametr n.
object Řetězec Typ objektu. Rovná se buď "chat.completions" pro nestreamování, a "chat.completion.chunk" pro streamování.
created Celé číslo Čas vygenerování dokončení chatu v sekundách.
model Řetězec Verze modelu použitá k generate odpovědi.
usage Využití Metadata použití tokenů. Na streamovací odpovědi nemusí být přítomno.

ChatCompletionChoice

Pole Typ Popis
index Celé číslo Index výběru v rámci list z vygenerovaných možností.
message ChatMessage Zpráva o dokončení chatu vrácená modelem Role bude assistant.
finish_reason Řetězec Důvod, proč model přestal generovat tokeny

ChatCompletionChunk

Pole Typ Popis
index Celé číslo Index výběru v rámci generovaných voleb v list.
delta ChatMessage Zpráva o dokončení chatu, která je součástí vygenerovaných streamovaných odpovědí z modelu Je zaručeno, že pouze první blok dat bude mít role naplněno.
finish_reason Řetězec Důvod, proč model přestal generovat tokeny Tuto hodnotu bude mít naplněnou pouze poslední blok dat.

Dokončení úkolu

Úkoly dokončování textu slouží k generování odpovědí na jednu výzvu. Na rozdíl od chatu tato úloha podporuje dávkové vstupy: v jedné žádosti lze odeslat několik nezávislých výzev. Viz POST /serving-endpoints/{name}/invocations pro dotazování koncového bodu parameters.

Žádost o dokončení

Pole Výchozí Typ Popis
prompt Řetězec nebo List[Řetězec] Požadované. Výzvy pro model.
max_tokens null null, což znamená žádnou limit, nebo celé číslo větší než nula Maximální počet tokenů pro generate.
stream true Boolean Umožněte streamování odpovědí zpět klientovi, aby bylo možné poskytnout částečné výsledky pro požadavky. Pokud je tento parametr součástí požadavku, odpovědi se posílají pomocí standardu pro události zasílané serverem.
temperature 1.0 Plovoucí v [0,2] Teplota vzorkování. Hodnota 0 je deterministická a vyšší values představuje větší náhodnost.
top_p 1.0 Float in (0,1] Prahová hodnota pravděpodobnosti použitá pro vzorkování jádra.
top_k null null, které znamená žádné limitani žádné celé číslo větší než nula Definuje počet nejpravděpodobnějších k tokenů pro použití při filtrování top-k. Set tuto hodnotu na 1, aby výstupy byly deterministické.
error_behavior "error" "truncate" nebo "error" Chyby překročení časového limitu a chyby překročení délky kontextu. Jedna z těchto možností: "truncate" (vrácení co nejvíce tokenů) a "error" (vrácení chyby). Tento parametr je přijímán pouze koncovými body s platbou za token.
n 1 Celé číslo větší než nula Rozhraní API vrátí n nezávislé dokončování chatu při zadání n. Doporučeno pro úlohy, které generate více dokončení na stejném vstupu, aby se další efektivita odvozování a úspora nákladů. K dispozici pouze pro koncové body s provisionovanou kapacitou propustnosti.
stop [] Řetězec nebo List[Řetězec] Model přestane generovat další tokeny, když dojde k nějaké sekvenci v stop.
suffix "" Řetězec Řetězec, který je připojen na konec každého dokončení.
echo false Boolean Vrátí výzvu k akci spolu s dokončením.
use_raw_prompt false Boolean Pokud true, předejte prompt přímo do modelu bez transformace.

Odpověď na dokončení

Pole Typ Popis
id Řetězec Jedinečné identifier pro dokončení textu.
choices DokončeníVýběr list dokončení textu. Při každém předání výzvy se vygenerují n volby, pokud je určeno n. Výchozí n je 1.
object Řetězec Typ objektu. Rovná se "text_completion"
created Celé číslo Čas vygenerování dokončení v sekundách.
usage Využití Metadata použití tokenů.

CompletionChoice

Pole Typ Popis
index Celé číslo Index výzvy v požadavku.
text Řetězec Vygenerované dokončení.
finish_reason Řetězec Důvod, proč model přestal generovat tokeny

Úloha vkládání

Úkoly vkládání mapují vstupní řetězce na vektory vkládání. V každém požadavku je možné dosát dohromady mnoho vstupů. Viz POST /serving-endpoints/{name}/invocations pro dotazování koncového bodu parameters.

Žádost o vložení

Pole Typ Popis
input Řetězec nebo List[Řetězec] Požadované. Vstupní text, který chcete vložit. Může to být řetězec nebo list řetězců.
instruction Řetězec Volitelná instrukce, která se má předat modelu vkládání.

Pokyny jsou volitelné a vysoce specifické pro model. Autoři BGE například při indexování bloků dat nedoporučují žádné instrukce a doporučují použití pokynů "Represent this sentence for searching relevant passages:" pro načítání dotazů. Další modely, jako je Instructor-XL, podporují širokou škálu instrukčních řetězců.

Odpověď vkládání

Pole Typ Popis
id Řetězec Jedinečné identifier pro vkládání.
object Řetězec Typ objektu. Rovná se "list".
model Řetězec Název modelu vložení použitého k vytvoření vkládání
data EmbeddingObject Vložený objekt.
usage Využití Metadata použití tokenů.

EmbeddingObject

Pole Typ Popis
object Řetězec Typ objektu. Rovná se "embedding".
index Celé číslo Index vkládání do list vkládání generovaných modelem.
embedding List[Float] Vektor vkládání. Každý model vrátí vektor pevné velikosti (1024 pro BGE-Large).

Další zdroje informací