REST-API-Referenz für das Foundation Model
Dieser Artikel enthält allgemeine API-Informationen für Databricks Foundation Model-APIs und die modelle, die sie unterstützen. Die Foundation Model-APIs sind so konzipiert, dass sie mit der REST-API von OpenAI vergleichbar sind, um die Migration vorhandener Projekte zu vereinfachen. Sowohl die Pay-per-Token- als auch die bereitgestellten Durchsatzendpunkte akzeptieren das gleiche REST-API-Anforderungsformat.
Endpunkte
Foundation Model-APIs unterstützen Endpunkte mit tokenbasierter Bezahlung und Endpunkte mit bereitgestelltem Durchsatz.
Ein vorkonfigurierter Endpunkt steht in Ihrem Arbeitsbereich für jedes unterstützte Pay-per-Token-Modell zur Verfügung, und Benutzer können mit diesen Endpunkten mithilfe von HTTP POST-Anforderungen interagieren. Siehe Pay-per-Token- für unterstützte Modelle.
Endpunkte mit bereitgestelltem Durchsatz können mithilfe der API oder der Benutzeroberfläche für die Bereitstellung erstellt werden. Diese Endpunkte unterstützen mehrere Modelle pro Endpunkt für A/B-Tests, solange beide bereitgestellten Modelle das gleiche API-Format verfügbar machen. Beispielsweise sind beide Modelle Chatmodelle. Siehe POST /api/2.0/serving-endpoints für Endpunktkonfigurationsparameter.
Anforderungen und Antworten verwenden JSON, die genaue JSON-Struktur hängt vom Aufgabentyp eines Endpunkts ab. Chat- und Vervollständigungsendpunkte unterstützen Streaming-Antworten.
Verwendung
Antworten umfassen eine usage Unternachricht, die die Anzahl der Token in der Anforderung und Antwort meldet. Das Format dieser Unternachricht ist für alle Aufgabentypen identisch.
| Feld | Typ | Beschreibung |
|---|---|---|
completion_tokens |
Integer | Anzahl der generierten Token. Nicht in Einbettungsantworten enthalten. |
prompt_tokens |
Integer | Anzahl der Token aus den Eingabeaufforderungen. |
total_tokens |
Integer | Anzahl der Gesamttoken. |
Bei Modellen wie Meta-Llama-3.3-70B-Instruct wird eine Benutzeraufforderung mithilfe einer Eingabeaufforderungsvorlage transformiert, bevor sie an das Modell übergeben wird. Für Pay-per-Token-Endpunkte kann auch eine Systemaufforderung hinzugefügt werden. prompt_tokens enthält den gesamten von unserem Server hinzugefügten Text.
Chataufgabe
Die Chataufgaben sind für mehrstufige Unterhaltungen mit einem Modell optimiert. Die Modellantwort stellt die nächste assistant-Nachricht in der Unterhaltung bereit. Informationen zum Abfragen von Endpunktparametern finden Sie unter POST /serving-endpoints/{name}/invocations.
Chatanfrage
| Feld | Standard | Typ | Beschreibung |
|---|---|---|---|
messages |
ChatMessage-Liste | Erforderlich. Eine Liste der Nachrichten, die die aktuelle Unterhaltung darstellen. | |
max_tokens |
null |
null, was bedeutet, dass es keine Grenze gibt oder eine ganze Zahl größer als Null ist |
Die maximale Anzahl der zu generierenden Token. |
stream |
true |
Boolesch | Streamen Sie Antworten an einen Client zurück, um Teilergebnisse für Anfragen zuzulassen. Wenn dieser Parameter in der Anforderung enthalten ist, werden Antworten mithilfe des Standards Server-Sent Events gesendet. |
temperature |
1.0 |
Gleitkomma in [0,2] | Die Probenahmetemperatur. 0 ist deterministisch und höhere Werte führen zu mehr Zufallszahlen. |
top_p |
1.0 |
Gleitkomma in [0,1] | Die Wahrscheinlichkeitsschwelle, die für das Kernsampling verwendet wird. |
top_k |
null |
null, was bedeutet, dass keine Grenze besteht oder es sich um eine ganze Zahl größer als Null handelt |
Definiert die Anzahl der K-Höchstwahrscheinlichkeitstoken, die für die Top-k-Filterung verwendet werden sollen. Legen Sie diesen Wert auf 1 fest, um Ausgaben deterministisch zu machen. |
stop |
[] | Zeichenfolge oder Liste[string] | Das Modell beendet die Generierung weiterer Token, wenn eine der Sequenzen in stop gefunden wird. |
n |
1 | Integer größer 0 | Die API gibt von n unabhängige Chatvervollständigungen zurück, wenn n angegeben wird. Empfohlen für Workloads, die mehrere Abschlüsse auf demselben Input erzeugen, um die Effizienz zu steigern und Kosten zu sparen. Nur für bereitgestellte Durchsatzendpunkte verfügbar. |
tool_choice |
none |
Zeichenfolge oder ToolChoiceObject | Wird nur in Verbindung mit dem feld tools verwendet. tool_choice unterstützt eine Vielzahl von Schlüsselwortzeichenfolgen wie auto, requiredund none. auto bedeutet, dass Sie das Modell entscheiden lassen, welches Tool (falls vorhanden) für die Verwendung relevant ist. Wenn das Modell mit auto nicht der Meinung ist, dass eines der Tools in tools relevant ist, generiert das Modell anstelle eines Toolaufrufs eine Standard-Assistentennachricht. required bedeutet, dass das Modell das relevanteste Tool in tools auswählt und einen Toolaufruf generieren muss. none bedeutet, dass das Modell keine Toolaufrufe generiert und stattdessen eine Standard-Assistentennachricht generieren muss. Verwenden Sie ToolChoiceObject, um einen Toolaufruf mit einem bestimmten in tools definierten Tool zu erzwingen. Standardwert, wenn das Feld tools ausgefüllt ist: tool_choice = "auto". Andernfalls wird das Feld "tools" standardmäßig auf "tool_choice = "none"" gesetzt. |
tools |
null |
ToolObject | Eine Liste von tools, die das Modell aufrufen kann. Derzeit ist function der einzige unterstützte tool-Typ, und es werden maximal 32 Funktionen unterstützt. |
response_format |
null |
ResponseFormatObject | Ein Objekt, das das Format angibt, das das Modell ausgeben muss. Akzeptierte Typen sind text, json_schema oder json_objectDie Einstellung auf { "type": "json_schema", "json_schema": {...} } ermöglicht strukturierte Ausgaben, die sicherstellen, dass das Modell ihrem bereitgestellten JSON-Schema folgt.Das Festlegen auf { "type": "json_object" } stellt sicher, dass die vom Modell generierten Antworten gültiges JSON sind, garantiert jedoch nicht, dass die Antworten einem bestimmten Schema folgen. |
logprobs |
false |
Boolesch | Dieser Parameter gibt an, ob die Protokollwahrscheinlichkeit eines abgesampten Tokens bereitgestellt werden soll. |
top_logprobs |
null |
Integer | Dieser Parameter steuert die Anzahl der wahrscheinlichsten Tokenkandidaten, um Protokollwahrscheinlichkeiten für jeden Samplingschritt zurückzugeben. Kann 0-20 sein. logprobs muss bei Verwendung dieses Felds zu true werden. |
ChatMessage
| Feld | Typ | Beschreibung |
|---|---|---|
role |
Schnur | Erforderlich. Die Rolle des Autors der Nachricht. Kann "system", "user", "assistant" oder "tool"sein. |
content |
Schnur | Der Inhalt der Nachricht. Erforderlich für Chataufgaben, die keine Werkzeuganrufe umfassen. |
tool_calls |
ToolCall-Liste | Die Liste der tool_calls-Elemente, die das Modell generiert hat. Muss role als "assistant" und keine Spezifikation für das feld content aufweisen. |
tool_call_id |
Schnur | Wenn role gleich "tool" ist, die ID des ToolCall-Elements, auf das die Nachricht reagiert. Für andere Optionen von role muss der Wert leer sein. |
Die rolle system kann nur einmal verwendet werden, als erste Nachricht in einer Unterhaltung. Er setzt die Standardsystemaufforderung des Modells außer Kraft.
ToolCall
Ein Toolaufrufaktionsvorschlag durch das Modell. Weitere Informationen finden Sie unter Funktionsaufrufe für Azure Databricks.
| Feld | Typ | Beschreibung |
|---|---|---|
id |
Schnur | Erforderlich. Ein eindeutiger Bezeichner für diesen Toolaufrufvorschlag |
type |
Schnur | Erforderlich. Nur "function" wird unterstützt. |
function |
FunctionCallCompletion | Erforderlich. Ein Funktionsaufruf, der vom Modell vorgeschlagen wird. |
FunctionCallCompletion
| Feld | Typ | Beschreibung |
|---|---|---|
name |
Schnur | Erforderlich. Der Name der Funktion, die vom Modell empfohlen wird. |
arguments |
Objekt | Erforderlich. Argumente für die Funktion als serialisiertes JSON-Wörterbuch. |
ToolChoiceObject
Weitere Informationen finden Sie unter Funktionsaufrufe für Azure Databricks.
| Feld | Typ | Beschreibung |
|---|---|---|
type |
Schnur | Erforderlich. Der Typ des Tools. Derzeit wird nur "function" unterstützt. |
function |
Objekt | Erforderlich. Ein Objekt, das definiert, welches Tool aufgerufen werden soll, im Format {"type": "function", "function": {"name": "my_function"}}. Dabei ist "my_function der Name eines FunctionObject im Feld tools. |
ToolObject
Weitere Informationen finden Sie unter Funktionsaufrufe für Azure Databricks.
| Feld | Typ | Beschreibung |
|---|---|---|
type |
Schnur | Erforderlich. Der Typ des Tools. Derzeit wird nur function unterstützt. |
function |
FunctionObject | Erforderlich. Die dem Tool zugeordnete Funktionsdefinition. |
FunctionObject
| Feld | Typ | Beschreibung |
|---|---|---|
name |
Schnur | Erforderlich. Der Name der funktion, die aufgerufen werden soll. |
description |
Objekt | Erforderlich. Die detaillierte Beschreibung der Funktion. Das Modell verwendet diese Beschreibung, um die Relevanz der Funktion auf die Eingabeaufforderung zu verstehen und die Toolaufrufe mit höherer Genauigkeit zu generieren. |
parameters |
Objekt | Die Parameter, die die Funktion akzeptiert, die als gültiges JSON-Schema-Objekt beschrieben werden. Wenn das Tool aufgerufen wird, ist der Toolaufruf an das bereitgestellte JSON-Schema angepasst. Das Weglassen von Parametern definiert eine Funktion ohne Parameter. Die Anzahl von properties ist auf 15 Schlüssel beschränkt. |
strict |
Boolesch | Gibt an, ob die strikte Schematreue beim Generieren des Funktionsaufrufs aktiviert werden soll. Bei Festlegung auf truefolgt das Modell dem genauen Schema, das im Schemafeld definiert ist. Nur eine Teilmenge des JSON-Schemas wird unterstützt, wenn für „strict“ der Wert true festgelegt ist. |
ResponseFormatObject
Weitere Informationen finden Sie unter Strukturierte Ausgaben in Azure Databricks.
| Feld | Typ | Beschreibung |
|---|---|---|
type |
Schnur | Erforderlich. Der Typ des zu definierenden Antwortformats. Entweder text für unstrukturierten Text, json_object für unstrukturierte JSON-Objekte oder json_schema für JSON-Objekte, die einem bestimmten Schema entsprechen. |
json_schema |
JsonSchemaObject | Erforderlich. Das JSON-Schema, das eingehalten werden soll, wenn type auf json_schema festgelegt ist |
JsonSchemaObject
Weitere Informationen finden Sie unter Strukturierte Ausgaben in Azure Databricks.
| Feld | Typ | Beschreibung |
|---|---|---|
name |
Schnur | Erforderlich. Der Name des Antwortformats. |
description |
Schnur | Eine Beschreibung, wofür das Antwortformat gedacht ist, die vom Modell verwendet wird, um zu bestimmen, wie in dem Format geantwortet werden soll. |
schema |
Objekt | Erforderlich. Das Schema für das Antwortformat, das als JSON-Schemaobjekt beschrieben wird. |
strict |
Boolesch | Gibt an, ob die strikte Schematreue beim Generieren der Ausgabe aktiviert werden soll. Bei Festlegung auf truefolgt das Modell dem genauen Schema, das im Schemafeld definiert ist. Nur eine Teilmenge des JSON-Schemas wird unterstützt, wenn für „strict“ der Wert true festgelegt ist. |
Chatantwort
Bei Nicht-Streaming-Anforderungen ist die Antwort ein einzelnes Chat-Vervollständigungsobjekt. Bei Streaminganforderungen handelt es sich bei der Antwort um ein text/event-stream-Element, in dem jedes Ereignis ein Vervollständigungsblockobjekt ist. Die Struktur der obersten Ebene von Abschluss- und Blockobjekten ist fast identisch: nur bei choices gibt es einen anderen Typ.
| Feld | Typ | Beschreibung |
|---|---|---|
id |
Schnur | Eindeutiger Bezeichner für den Chatabschluss. |
choices |
List[ChatCompletionChoice] oder List[ChatCompletionChunk] (Streaming) | Liste der Chatabschlusstexte. n Auswahlmöglichkeiten werden zurückgegeben, wenn der n-Parameter angegeben wird. |
object |
Schnur | Der Objekttyp. Gleich dem "chat.completions" für Nichtstreaming oder dem "chat.completion.chunk" für Streaming. |
created |
Integer | Die Zeit, zu der der Chatabschluss in Sekunden generiert wurde. |
model |
Schnur | Die Modellversion, die zum Generieren der Antwort verwendet wird. |
usage |
Verwendung | Tokenverwendungsmetadaten. Möglicherweise in Streamingantworten nicht enthalten. |
ChatCompletionChoice
| Feld | Typ | Beschreibung |
|---|---|---|
index |
Integer | Der Index der Auswahl in der Liste der generierten Auswahlmöglichkeiten. |
message |
ChatMessage | Eine Chatabschlussnachricht, die vom Modell zurückgegeben wird. Die Rolle ist assistant. |
finish_reason |
Schnur | Der Grund, warum das Modell das Generieren von Token beendet hat. |
ChatCompletionChunk
| Feld | Typ | Beschreibung |
|---|---|---|
index |
Integer | Der Index der Auswahl in der Liste der generierten Optionen. |
delta |
ChatMessage | Ein Chatvervollständigungsnachrichtenteil der generierten gestreamten Antworten aus dem Modell. Nur im ersten Block ist role garantiert aufgefüllt. |
finish_reason |
Schnur | Der Grund, warum das Modell das Generieren von Token beendet hat. Dies wird nur im letzten Block aufgefüllt. |
Abschlussaufgabe
Textabschlussaufgaben dienen zum Generieren von Antworten auf eine einzelne Eingabeaufforderung. Im Gegensatz zu Chat unterstützt diese Aufgabe Batcheingaben: Mehrere unabhängige Eingabeaufforderungen können in einer Anforderung gesendet werden. Informationen zum Abfragen von Endpunktparametern finden Sie unter POST /serving-endpoints/{name}/invocations.
Abschlussanforderung
| Feld | Standard | Typ | Beschreibung |
|---|---|---|---|
prompt |
Zeichenfolge oder Liste[string] | Erforderlich. Die Aufforderungen für das Modell. | |
max_tokens |
null |
null, was entweder keine Grenze bedeutet oder eine ganze Zahl größer als Null |
Die maximale Anzahl der zu generierenden Token. |
stream |
true |
Boolesch | Antworten an einen Client streamen, um Teilergebnisse für Anfragen zu ermöglichen. Wenn dieser Parameter in der Anforderung enthalten ist, werden Antworten gemäß dem Server-gesendete Ereignisse Standard gesendet. |
temperature |
1.0 |
Gleitkomma in [0,2] | Die Probenahmetemperatur. 0 ist deterministisch und höhere Werte führen zu mehr Zufallszahlen. |
top_p |
1.0 |
Gleitkomma in [0,1] | Die Wahrscheinlichkeitsschwelle, die für das Nukleussampling verwendet wird. |
top_k |
null |
null, was bedeutet, dass es keine Grenze gibt oder eine ganze Zahl, die größer als Null ist |
Definiert die Anzahl der K-Höchstwahrscheinlichkeitstoken, die für die Top-k-Filterung verwendet werden sollen. Legen Sie diesen Wert auf 1 fest, um Ausgaben deterministisch zu machen. |
error_behavior |
"error" |
"truncate" oder "error" |
Für Timeouts und Fehler wegen überschrittener Kontextlänge. Einer von: "truncate" (so viele Token wie möglich zurückgeben) und "error" (Fehler zurückgeben). Dieser Parameter wird nur von Endpunkten akzeptiert, die nach dem Modell "Bezahlung pro Token" arbeiten. |
n |
1 | Integer größer 0 | Die API gibt von n unabhängige Chatvervollständigungen zurück, wenn n angegeben wird. Empfohlen für Workloads, die mehrere Vervollständigungen auf derselben Eingabe generieren, um die Effizienz zu steigern und Kosten zu sparen. Nur für bereitgestellte Durchsatzendpunkte verfügbar. |
stop |
[] | Zeichenfolge oder Liste[string] | Das Modell beendet die Generierung weiterer Token, wenn eine der Sequenzen in stop gefunden wird. |
suffix |
"" |
Schnur | Eine Zeichenfolge, die am Ende jeder Vervollständigung angefügt wird. |
echo |
false |
Boolesch | Gibt den Prompt zusammen mit der Vervollständigung zurück. |
use_raw_prompt |
false |
Boolesch | Bei true übergeben Sie prompt direkt und ohne Transformation an das Modell. |
Vervollständigungsantwort
| Feld | Typ | Beschreibung |
|---|---|---|
id |
Schnur | Eindeutiger Bezeichner für das Textvervollständigen. |
choices |
CompletionChoice | Eine Liste von Textvervollständigungen. Bei jedem übergebenen Prompt werden n Auswahlmöglichkeiten generiert, wenn n angegeben wird. Der Standardwert n ist 1. |
object |
Schnur | Der Objekttyp. Gleich "text_completion" |
created |
Integer | Die Zeit, zu der die Vervollständigung generiert wurde, in Sekunden. |
usage |
Verwendung | Tokenverwendungsmetadaten. |
CompletionChoice
| Feld | Typ | Beschreibung |
|---|---|---|
index |
Integer | Der Index des Prompts in der Anforderung. |
text |
Schnur | Die generierte Vervollständigung. |
finish_reason |
Schnur | Der Grund, warum das Modell das Generieren von Token beendet hat. |
Einbettungsaufgabe
Bei Einbettungsaufgaben werden Eingabezeichenfolgen in Einbettungsvektoren zugeordnet. In jeder Anforderung können viele Eingaben zusammengefasst werden. Informationen zum Abfragen von Endpunktparametern finden Sie unter POST /serving-endpoints/{name}/invocations.
Einbettungsanforderung
| Feld | Typ | Beschreibung |
|---|---|---|
input |
Zeichenfolge oder Liste[string] | Erforderlich. Der einzubettende Eingabetext. Kann eine Zeichenfolge oder eine Liste von Zeichenfolgen sein. |
instruction |
Schnur | Eine optionale Anweisung zum Übergeben an das Einbettungsmodell. |
Anweisungen sind optional und hochmodellspezifisch. Beispielsweise empfehlen die BGE-Autoren, beim Indizieren von Chunks keine Anweisung zu geben, sondern stattdessen die Anweisung "Represent this sentence for searching relevant passages:" für Abrufabfragen zu verwenden. Andere Modelle wie Instructor-XL unterstützen eine vielzahl von Anweisungszeichenfolgen.
Einbettungsantwort
| Feld | Typ | Beschreibung |
|---|---|---|
id |
Schnur | Eindeutiger Bezeichner für die Einbettung. |
object |
Schnur | Der Objekttyp. Gleich "list" |
model |
Schnur | Der Name des Einbettungsmodells, das zum Erstellen der Einbettung verwendet wird. |
data |
EmbeddingObject | Das Einbettungsobjekt. |
usage |
Verwendung | Tokenverwendungsmetadaten. |
EmbeddingObject
| Feld | Typ | Beschreibung |
|---|---|---|
object |
Schnur | Der Objekttyp. Gleich "embedding" |
index |
Integer | Der Index der Einbettung in der Liste der vom Modell generierten Einbettungen. |
embedding |
List[Float] | Der Einbettungsvektor. Jedes Modell gibt einen Vektor mit fester Größe zurück (1024 für BGE-Large) |