Informazioni di riferimento sull'API REST del modello fondamentale
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 , required e 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
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
Modelli supportati per con pagamento in base al token