Sdílet prostřednictvím

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

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 s platbou za token i zřízenou propustností přijímají požadavky ve stejném formátu rozhraní REST API.

koncové body

Rozhraní API základních modelů podporují koncové body s platbou za token a koncové body s garantovanou propustností.

Předkonfigurovaný koncový bod je k dispozici ve vašem pracovním prostoru pro každý model podporovaný s platbami za token a uživatelé můžou s těmito koncovými body pracovat pomocí požadavků HTTP POST. Viz Podporované základní modely na platformě Mosaic AI Model Serving pro seznam podporovaných modelů.

Koncové body zřízené propustnosti je možné vytvořit pomocí rozhraní API neboobslužného uživatelského rozhraní . Tyto koncové body 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. Parametry konfigurace koncového bodu najdete v POST /api/2.0/serving-endpoints.

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 generování dokončení podporují streamování odpovědí.

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ů
reasoning_tokens Celé číslo Počet myšlenkových tokenů Platí pouze pro modely odůvodnění.

U modelů, jako je databricks-meta-llama-3-3-70b-instruct, se výzva uživatele před předáním do modelu transformuje pomocí šablony výzvy. U koncových bodů s platbou za token může být přidána také systémová výzva. prompt_tokens obsahuje veškerý text přidaný naším serverem.

Chatový úkol

Úkoly chatu jsou optimalizované pro víceotáčkové konverzace s modelem. Odpověď modelu poskytuje následující assistant zprávu v konverzaci. Viz POST /serving-endpoints/{name}/invocations pro dotazování parametrů koncového bodu.

Žádost o chat

Pole Výchozí Typ Popis
messages ChatMessage seznam Požadované. Seznam zpráv představujících aktuální konverzaci
max_tokens null null, což znamená bez omezení nebo celé číslo větší než nula Maximální počet tokenů, které se mají vygenerovat.
stream true logický 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šší hodnoty představují větší náhodnost.
top_p 1.0 Float v intervalu (0,1] Prahová hodnota pravděpodobnosti použitá pro vzorkování jádra.
top_k null null, což znamená bez omezení nebo celé číslo větší než nula Definuje počet nejpravděpodobnějších k tokenů pro použití při filtrování top-k. Nastavte tuto hodnotu na hodnotu 1, aby byl výstup deterministický.
stop [] Řetězec nebo Seznam [Ř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čuje se pro úlohy, které generují více dokončení na stejném vstupu pro další efektivitu odvozování a úsporu 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 model nevěří, že některý z nástrojů tools je 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í vygenerovat volání nástroje. none znamená, že model negeneruje žádná volání nástrojů a místo toho musí vygenerovat 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 tool_choice = "auto". Jinak pole tools ve výchozím nastavení přebírá hodnotu tool_choice = "none".
tools null ToolObject Seznam 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 následuje za zadaným schématem JSON.
Nastavení { "type": "json_object" } zajišťuje, že odpovědi, které model vygeneruje, jsou platné JSON, ale nezajistí, aby odpovědi dodržovaly konkrétní schéma.
logprobs false logický Tento parametr určuje, jestli se má poskytnout logaritmická pravděpodobnost výběru tokenu.
top_logprobs null Celé číslo Tento parametr určuje počet nejpravděpodobnějších tokenů, pro které se v každém kroku vzorkování vrací logaritmované pravděpodobnosti. Může být 0–20. logprobs musí být true, pokud se používá toto pole.
reasoning_effort "medium" Řetězec Řídí úroveň odůvodnění, které by model měl použít při generování odpovědí. Přijaté hodnoty jsou "low", "medium"nebo "high". Vyšší úsilí může vést k promyšlenějším a přesným odpovědím, ale může zvýšit latenci a využití tokenů. Tento parametr je přijímán pouze omezenou sadou modelů, včetně databricks-gpt-oss-120b a databricks-gpt-oss-20b.

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 seznam ToolCall Seznam 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é ke ToolCall, na kterou zpráva odpovídá. Musí být prázdné pro ostatní možnosti role.

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 pro volání nástroje podle modelu. Viz volání funkce v Azure Databricks.

Pole Typ Popis
id Řetězec Požadované. Jedinečný identifikátor pro návrh na volání tohoto nástroje.
type Řetězec Požadované. Podporuje se jenom "function".
function FunctionCallCompletion Požadované. Volání funkce navrhované modelem
cache_control Řetězec Povolí ukládání do mezipaměti pro vaši žádost. Tento parametr přijímá pouze modely Claude hostované službou Databricks. Viz ukládání promptu do mezipaměti pro příklad.

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í nástroj pro volání formuláře {"type": "function", "function": {"name": "my_function"}}, kde "my_function je 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, aby lépe pochopil, jak je funkce relevantní k zadání, a mohl s vyšší přesností generovat volání nástrojů.
parameters Objekt Parametry, které funkce přijímá, jsou popsány jako platný objekt schématu JSON . Pokud je nástroj volán, pak volání nástroje odpovídá poskytnutému schématu JSON. Vynechání parametrů definuje funkci bez parametrů. Počet properties je omezený na 15 klíčů.
strict logický Zda povolit přísné dodržování schématu při generování volání funkce. Pokud je nastavená hodnota true, model se řídí přesným schématem definovaným v poli schématu. Pokud je striktní true, podporuje se pouze podmnožina schématu 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í schéma.
json_schema jsonSchemaObject Požadované. Schéma JSON, které se má dodržovat, pokud je type nastavená na 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é. Schéma pro formát odpovědi popsané jako objekt schématu JSON.
strict logický Zda povolit přísné dodržování schématu při generování výstupu. Pokud je nastavená hodnota true, model se řídí přesným schématem definovaným v poli schématu. Pokud je striktní true, podporuje se pouze podmnožina schématu JSON.

Odpověď na chat

U požadavků, které nejsou streamované, je odpovědí jeden objekt dokončení chatu. U požadavků na streamování je odpověď ve formátu text/event-stream, kde každá událost je objekt kompletního segmentu. Struktura objektů dokončení a dílčích objektů nejvyšší úrovně je téměř identická: pouze choices má jiný typ.

Pole Typ Popis
id Řetězec Jedinečný identifikátor dokončení chatu.
choices List[ChatCompletionChoice] nebo List[ChatCompletionChunk] (streamování) Seznam textových zpráv o 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í, nebo "chat.completion.chunk" pro streamování.
created Celé číslo Doba, za kterou bylo dokončení chatu vygenerováno, vyjádřená v sekundách.
model Řetězec Verze modelu použitá k vygenerování odpovědi.
usage Využití Metadata použití tokenů. Na streamovacích odpovědích nemusí být přítomen.

ChatCompletionChoice

Pole Typ Popis
index Celé číslo Index výběru v seznamu vygenerovaných možností.
message ChatMessage Zpráva o dokončení chatu vrácená modelem Úloha bude assistant.
finish_reason Řetězec Důvod, proč model přestal generovat tokeny
extra_fields Řetězec Při použití proprietárních modelů od externích poskytovatelů modelů můžou rozhraní API poskytovatele obsahovat do odpovědí další metadata. Databricks tyto odpovědi filtruje a vrací pouze podmnožinu původních polí poskytovatele. Toto safetyRating je jediné dodatečné pole podporované v tuto chvíli, další podrobnosti najdete v dokumentaci Gemini .

ChatCompletionChunk

Pole Typ Popis
index Celé číslo Index výběru v seznamu vygenerovaných možností.
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 Pouze poslední blok bude mít tuto informaci vyplněnou.

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í parametrů koncového bodu.

Žádost o dokončení

Pole Výchozí Typ Popis
prompt Řetězec nebo Seznam [Řetězec] Požadované. Výzvy pro model.
max_tokens null null, což znamená bez omezení nebo celé číslo větší než nula Maximální počet tokenů, které se mají vygenerovat.
stream true logický 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šší hodnoty představují větší náhodnost.
top_p 1.0 Float v intervalu (0,1] Prahová hodnota pravděpodobnosti použitá pro vzorkování jádra.
top_k null null, což znamená bez omezení nebo celé číslo větší než nula Definuje počet nejpravděpodobnějších k tokenů pro použití při filtrování top-k. Nastavte tuto hodnotu na hodnotu 1, aby byl výstup 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čuje se pro úlohy, které generují více dokončení na stejném vstupu pro další efektivitu odvozování a úsporu nákladů. K dispozici pouze pro koncové body s provisionovanou kapacitou propustnosti.
stop [] Řetězec nebo Seznam [Ř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 logický Vrátí výzvu k akci spolu s dokončením.
use_raw_prompt false logický Pokud true, předejte prompt přímo do modelu bez transformace.

Odpověď na dokončení úkolu

Pole Typ Popis
id Řetězec Jedinečný identifikátor pro dokončování textu.
choices Výběr dokončení Seznam dokončování textu. Při každém předání podnětu se vygenerují n volby, pokud je zadáno n. Výchozí n je 1.
object Řetězec Typ objektu. Rovná se "text_completion"
created Celé číslo Čas, kdy bylo dokončení vygenerováno, 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í parametrů koncového bodu.

Žádost o vložení

Pole Typ Popis
input Řetězec nebo Seznam [Řetězec] Požadované. Vstupní text, který chcete vložit. Může to být řetězec nebo seznam ř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žívat instrukce "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ý identifikátor pro vkládání.
object Řetězec Typ objektu. Rovná se "list".
model Řetězec Název modelu použitý k vytvoření vložení
data EmbeddingObject Embedující 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í v seznamu vložených objektů vygenerovaných modelem.
embedding Seznam[Float] Vektor vkládání. Každý model vrátí vektor pevné velikosti (1024 pro BGE-Large).

Další zdroje informací

  • Last updated on