Condividi tramite

Informazioni di riferimento sull'API REST del modello fondamentale

  • Articolo

Questo articolo fornisce informazioni generali sulle API per le API di Databricks Foundation Model e i modelli supportati. Le API del modello foundation sono progettate per essere simili all'API REST di OpenAI per semplificare la migrazione di progetti esistenti. Gli endpoint con pagamento in base al token e attraverso il throughput riservato accettano lo stesso formato di richiesta dell'API REST.

Endpoint

Le API del modello di base supportano gli endpoint con pagamento per token e gli endpoint con velocità effettiva provisionati.

Un endpoint preconfigurato è disponibile nell'area di lavoro per ogni modello supportato con pagamento in base al token e gli utenti possono interagire con questi endpoint usando richieste HTTP POST. Vedi Pagamento-per-token per i modelli supportati.

Gli endpoint di velocità effettiva con provisioning possono essere creati usando l'API o l'interfaccia utente di gestione. Questi endpoint supportano più modelli per endpoint per i test A/B, purché entrambi i modelli serviti espongono lo stesso formato API. Ad esempio, entrambi i modelli sono modelli di chat. Vedere post /api/2.0/serving-endpoints per i parametri di configurazione degli endpoint.

Le richieste e le risposte usano JSON, la struttura JSON esatta dipende dal tipo di attività di un endpoint. Gli endpoint di chat e completamento supportano le risposte di streaming.

Uso

Le risposte includono un usage sottomessaggio che segnala il numero di gettoni nella richiesta e nella risposta. Il formato di questo sotto-messaggio è lo stesso in tutti i tipi di attività.

Campo Digitare Descrizione
completion_tokens Numero intero Numero di token generati. Non incluso nelle risposte di incorporamento.
prompt_tokens Numero intero Numero di token dei prompt forniti.
total_tokens Numero intero Numero totale di token.

Per modelli come Meta-Llama-3.3-70B-Instruct, un prompt dell'utente viene convertito usando un template del prompt prima di essere passato al modello. Per gli endpoint con pagamento in base al token, potrebbe essere aggiunta anche una richiesta di sistema. prompt_tokens include tutto il testo aggiunto dal nostro server.

attività Chat

Le attività di chat sono ottimizzate per le conversazioni a più turni con un modello. La risposta del modello fornisce il prossimo messaggio assistant nella conversazione. Vedere POST /serving-endpoints/{name}/invocazioni per eseguire query sui parametri dell'endpoint.

Richiesta di chat

Campo Impostazione Predefinita Digitare Descrizione
messages elenco di ChatMessage Obbligatorio. Elenco di messaggi che rappresentano la conversazione corrente.
max_tokens null null, ovvero nessun limite o un numero intero maggiore di zero Numero massimo di token da generare.
stream true Booleano Trasmettere le risposte a un client per consentire risultati parziali per le richieste. Se questo parametro è incluso nella richiesta, le risposte vengono inviate usando gli eventi inviati dal server standard.
temperature 1.0 Numero in virgola mobile in [0, 2] Temperatura di campionamento. 0 è deterministico e valori più elevati introducono maggiore casualità.
top_p 1.0 Numero decimale in (0,1] Soglia di probabilità utilizzata per il campionamento del nucleo.
top_k null null, ovvero nessun limite o un numero intero maggiore di zero Definisce il numero di k token più probabili da usare per il filtro top-k. Impostare questo valore su 1 per rendere deterministici gli output.
stop [] Stringa o Lista[String] Il modello smette di generare altri token quando viene rilevata una delle sequenze in stop.
n 1 Intero maggiore di zero L'API restituisce n completamenti di chat indipendenti quando viene specificato n. Consigliato per i carichi di lavoro che generano più completamenti sullo stesso input per un'ulteriore efficienza di inferenza e risparmi sui costi. Disponibile solo per gli endpoint a throughput fornito.
tool_choice none Stringa o ToolChoiceObject Utilizzato solo in combinazione con il campo tools. tool_choice supporta un'ampia gamma di stringhe di parole chiave, ad esempio auto, requirede none. auto significa che si consente al modello di decidere quale strumento (se presente) è rilevante per l'uso. Con auto se il modello non ritiene che nessuno degli strumenti in tools sia rilevante, il modello genera un messaggio di assistente standard anziché una chiamata allo strumento. required significa che il modello seleziona lo strumento più rilevante in tools e deve generare una chiamata allo strumento. none significa che il modello non genera chiamate agli strumenti e deve invece generare un messaggio di assistente standard. Per forzare una chiamata di strumento con uno strumento specifico definito in tools, usare un ToolChoiceObject. Per impostazione predefinita, se il campo tools viene popolato tool_choice = "auto". In caso contrario, il campo tools viene impostato su tool_choice = "none" per impostazione predefinita.
tools null ToolObject Elenco di tools che il modello può chiamare. Attualmente, function è l'unico tipo di tool supportato e sono supportate al massimo 32 funzioni.
response_format null ResponseFormatObject Oggetto che specifica il formato che il modello deve restituire. I tipi accettati sono text, json_schema o json_object

L'impostazione su { "type": "json_schema", "json_schema": {...} } abilita output strutturati che garantisce che il modello segua lo schema JSON fornito.

L'impostazione su { "type": "json_object" } garantisce che le risposte generate dal modello siano JSON valide, ma non garantisce che le risposte seguano uno schema specifico.
logprobs false Booleano Questo parametro indica se fornire il logaritmo della probabilità di un token essere campionato.
top_logprobs null Numero intero Questo parametro controlla il numero di candidati token più probabili per restituire le probabilità logaritmiche a ciascun passaggio di campionamento. Può essere 0-20. logprobs deve essere true se si usa questo campo.

ChatMessage

Campo Digitare Descrizione
role Stringa Obbligatorio. Ruolo dell'autore del messaggio. Può essere "system", "user", "assistant" o "tool".
content Stringa Contenuto del messaggio. Necessario per le attività di chat che non comportano chiamate agli strumenti.
tool_calls Elenco ToolCall Elenco di tool_calls generato dal modello. Deve avere role come "assistant" e nessuna specificazione per il campo content.
tool_call_id Stringa Quando role è "tool", l'ID associato al ToolCall a cui il messaggio risponde. Deve essere vuoto per le altre opzioni di role.

Il ruolo system può essere usato una sola volta, come primo messaggio in una conversazione. Esegue l'override del prompt di sistema predefinito del modello.

ToolCall

Suggerimento dell'azione di chiamata di uno strumento da parte del modello. Consulta Chiamata di funzioni in Azure Databricks.

Campo Digitare Descrizione
id Stringa Obbligatorio. Identificatore univoco per questo suggerimento di chiamata dello strumento.
type Stringa Obbligatorio. È supportato solo "function".
function FunctionCallCompletion Obbligatorio. Chiamata di funzione suggerita dal modello.

FunctionCallCompletion

Campo Digitare Descrizione
name Stringa Obbligatorio. Nome della funzione consigliata dal modello.
arguments Oggetto Obbligatorio. Argomenti per la funzione come dizionario JSON serializzato.

ToolChoiceObject

Consulta Chiamata di funzioni in Azure Databricks.

Campo Digitare Descrizione
type Stringa Obbligatorio. Tipo dello strumento. Attualmente è supportato solo "function".
function Oggetto Obbligatorio. Oggetto che definisce quale strumento chiamare il modulo {"type": "function", "function": {"name": "my_function"}} in cui "my_function è il nome di un FunctionObject nel campo tools.

ToolObject

Consulta Chiamata di funzioni in Azure Databricks.

Campo Digitare Descrizione
type Stringa Obbligatorio. Tipo dello strumento. Attualmente è supportato solo function.
function FunctionObject Obbligatorio. Definizione della funzione associata allo strumento.

FunctionObject

Campo Digitare Descrizione
name Stringa Obbligatorio. Nome della funzione da chiamare.
description Oggetto Obbligatorio. Descrizione dettagliata della funzione. Il modello usa questa descrizione per comprendere la pertinenza della funzione al prompt e generare le chiamate degli strumenti con un'accuratezza maggiore.
parameters Oggetto I parametri accettati dalla funzione, descritti come uno schema JSON valido oggetto. Se lo strumento viene chiamato, la chiamata allo strumento è adatta allo schema JSON fornito. L'omissione di parametri definisce una funzione senza parametri. Il numero di properties è limitato a 15 chiavi.
strict Booleano Indica se abilitare una rigorosa conformità allo schema durante la generazione della chiamata di funzione. Se impostato su true, il modello segue lo schema esatto definito nel campo dello schema. Solo un subset di schema JSON è supportato quando strict è true

ResponseFormatObject

Vedere output strutturati in Azure Databricks.

Campo Digitare Descrizione
type Stringa Obbligatorio. Tipo di formato di risposta definito. text per il testo non strutturato, json_object per gli oggetti JSON non strutturati o json_schema per gli oggetti JSON aderendo a uno schema specifico.
json_schema JsonSchemaObject Obbligatorio. Schema JSON da rispettare se type è impostato su json_schema

JsonSchemaObject

Vedere output strutturati in Azure Databricks.

Campo Digitare Descrizione
name Stringa Obbligatorio. Nome del formato della risposta.
description Stringa Descrizione del formato di risposta, utilizzato dal modello per determinare come rispondere.
schema Oggetto Obbligatorio. Schema per il formato di risposta, descritto come oggetto schema JSON.
strict Booleano Indica se abilitare una rigorosa conformità allo schema durante la generazione dell'output. Se impostato su true, il modello segue lo schema esatto definito nel campo dello schema. Solo un subset di schema JSON è supportato quando strict è true

Risposta di chat

Per le richieste non in streaming, la risposta è un singolo oggetto per completare la chat. Per le richieste di streaming, la risposta è un text/event-stream in cui ogni evento è un oggetto blocco di completamento. La struttura di primo livello degli oggetti di completamento e frammenti è quasi identica: l'unica differenza è che choices ha un tipo diverso.

Campo Digitare Descrizione
id Stringa Identificatore univoco per il completamento della chat.
choices Lista[ChatCompletionChoice] o Lista[ChatCompletionChunk] (in streaming) Elenco dei testi di completamento della chat. Vengono restituite le scelte n se il parametro n è specificato.
object Stringa Tipo di oggetto. Uguale a "chat.completions" per non in streaming o a "chat.completion.chunk" per lo streaming.
created Numero intero Il tempo in cui è stato generato il completamento della chat, misurato in secondi.
model Stringa Versione del modello usata per generare la risposta.
usage utilizzo Metadati di utilizzo dei token. Potrebbe non essere presente nelle risposte in streaming.

ChatCompletionChoice

Campo Digitare Descrizione
index Numero intero Indice della scelta nell'elenco delle scelte generate.
message MessaggioDiChat Messaggio di completamento della chat restituito dal modello. Il ruolo sarà assistant.
finish_reason Stringa Motivo per cui il modello ha interrotto la generazione di token.

ChatCompletionChunk

Campo Digitare Descrizione
index Numero intero Indice della scelta nell'elenco delle scelte generate.
delta MessaggioDiChat Parte del messaggio di completamento della chat tra le risposte generate in streaming dal modello. È garantito che solo il primo blocco sarà popolato con role.
finish_reason Stringa Motivo per cui il modello ha interrotto la generazione di token. Solo l'ultimo blocco sarà popolato.

Attività di completamento

Le attività di completamento del testo sono per generare risposte a un singolo prompt. A differenza di Chat, questa attività supporta input in batch: più richieste indipendenti possono essere inviate in una sola richiesta. Vedere POST /serving-endpoints/{name}/invocazioni per eseguire query sui parametri dell'endpoint.

Richiesta di completamento

Campo Impostazione Predefinita Digitare Descrizione
prompt Stringa o Lista[String] Obbligatorio. I suggerimenti per il modello.
max_tokens null null, ovvero nessun limite o un numero intero maggiore di zero Numero massimo di token da generare.
stream true Booleano Trasmettere le risposte a un client per consentire risultati parziali per le richieste. Se questo parametro è incluso nella richiesta, le risposte vengono inviate usando gli eventi inviati dal server standard.
temperature 1.0 Numero in virgola mobile in [0, 2] Temperatura di campionamento. 0 è deterministico e valori più elevati introducono maggiore casualità.
top_p 1.0 Numero decimale in (0,1] Soglia di probabilità utilizzata per il campionamento del nucleo.
top_k null null, ovvero nessun limite o un numero intero maggiore di zero Definisce il numero di k token più probabili da usare per il filtro top-k. Impostare questo valore su 1 per rendere deterministici gli output.
error_behavior "error" "truncate" o "error" Per i timeout e gli errori di superamento della lunghezza del contesto. Uno dei seguenti: "truncate" (restituire il maggior numero possibile di token) e "error" (restituisce un errore). Questo parametro viene accettato solo dagli endpoint a pagamento per token.
n 1 Intero maggiore di zero L'API restituisce n completamenti di chat indipendenti quando viene specificato n. Consigliato per i carichi di lavoro che generano più completamenti sullo stesso input per un'ulteriore efficienza di inferenza e risparmi sui costi. Disponibile solo per gli endpoint a throughput fornito.
stop [] Stringa o Lista[String] Il modello smette di generare altri token quando viene rilevata una delle sequenze in stop.
suffix "" Stringa Una stringa che viene aggiunta alla fine di ogni completamento.
echo false Booleano Restituisce il prompt insieme al completamento.
use_raw_prompt false Booleano Se true, passa il prompt direttamente nel modello senza alcuna trasformazione.

Risposta di completamento

Campo Digitare Descrizione
id Stringa Identificatore univoco per il completamento del testo.
choices SceltaCompletamento Elenco di completamenti di testo. Per ogni richiesta passata, vengono generate n scelte se viene specificato n. Il n predefinito è 1.
object Stringa Tipo di oggetto. Uguale a "text_completion"
created Numero intero Ora di generazione del completamento in secondi.
usage utilizzo Metadati di utilizzo dei token.

CompletionChoice

Campo Digitare Descrizione
index Numero intero Indice del prompt nella richiesta.
text Stringa Completamento generato.
finish_reason Stringa Motivo per cui il modello ha interrotto la generazione di token.

Attività di embedding

Le attività di embedding eseguono il mapping delle stringhe di input in vettori di embedding. Molti input possono essere raggruppati in batch in ogni richiesta. Vedere POST /serving-endpoints/{name}/invocazioni per eseguire query sui parametri dell'endpoint.

Richiesta di incorporamento

Campo Digitare Descrizione
input Stringa o Lista[String] Obbligatorio. Testo di input da incorporare. Può essere una stringa o un elenco di stringhe.
instruction Stringa Istruzione facoltativa da passare al modello di embedding.

Le istruzioni sono facoltative ed estremamente specifiche del modello. Ad esempio, gli autori di BGE raccomandano di non fornire alcuna istruzione durante l'indicizzazione dei blocchi e consigliano di usare l'istruzione "Represent this sentence for searching relevant passages:" per le query di recupero. Altri modelli come Instructor-XL supportano un'ampia gamma di stringhe di istruzioni.

Risposta di incorporamento

Campo Digitare Descrizione
id Stringa Identificatore univoco per l'incorporamento.
object Stringa Tipo di oggetto. Uguale a "list".
model Stringa Nome del modello di incorporamento utilizzato per creare l'incorporamento.
data EmbeddingObject Oggetto incorporato.
usage utilizzo Metadati di utilizzo dei token.

EmbeddingObject

Campo Digitare Descrizione
object Stringa Tipo di oggetto. Uguale a "embedding".
index Numero intero Indice dell'incorporamento nell'elenco di incorporamenti generati dal modello.
embedding Lista[Float] Vettore di incorporamento. Ogni modello restituirà un vettore a dimensione fissa (1024 per BGE-Large)

Risorse aggiuntive