Condividi tramite

Informazioni di riferimento sulle API REST del modello Di base

  • 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 alla velocità effettiva con provisioning accettano lo stesso formato di richiesta dell'API REST.

Endpoint

Ogni modello con pagamento in base al token ha un singolo endpoint e gli utenti possono interagire con questi endpoint usando richieste HTTP POST. È possibile creare endpoint di velocità effettiva con provisioning usando l'API o l'interfaccia utente di gestione. Questi endpoint supportano anche 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.

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.

I carichi di lavoro con pagamento in base al token supportano determinati modelli, vedere Modelli supportati per il pagamento in base al token per tali modelli e formati API accettati.

Utilizzo

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

Campo Tipo Descrizione
completion_tokens Intero Numero di token generati. Non incluso nelle risposte di incorporamento.
prompt_tokens Intero Numero di token nel prompt.
total_tokens Intero Numero totale di chiamate token.

Per i modelli come llama-2-70b-chat un prompt degli utenti viene trasformato usando un modello di richiesta 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 server.

Attività chat

Le attività di chat sono ottimizzate per le conversazioni a più turni con un modello. Ogni richiesta descrive finora la conversazione, in cui il messages campo deve alternarsi tra user e assistant ruoli, terminando con un user messaggio. La risposta del modello fornisce il messaggio successivo assistant nella conversazione.

Richiesta di chat

Campo Predefiniti Tipo Descrizione
messages Elenco ChatMessage Obbligatorio. Elenco di messaggi che rappresentano la conversazione corrente.
max_tokens null null, che significa nessun limite o un numero intero maggiore di zero Numero massimo di token da generare nella risposta.
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 lo standard degli eventi inviati dal server.
temperature 1.0 Float in [0,2] Temperatura di campionamento. 0 è deterministico e valori più elevati introducono maggiore casualità.
top_p 1.0 Float in (0,1] Soglia di probabilità utilizzata per il campionamento del nucleo.
top_k null null, che significa 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 [] String o List[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 n viene specificato. 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 di velocità effettiva con provisioning.
tool_choice none String o ToolChoiceObject Utilizzato solo in combinazione con il tools campo . tool_choice supporta un'ampia gamma di stringhe di parole chiave, ad autoesempio , requirede none. auto significa che si consente al modello di decidere quale strumento (se presente) è rilevante per l'uso. Se auto 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ù pertinente 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 ToolChoiceObject. Per impostazione predefinita, se il tools campo viene popolato tool_choice = "auto". In caso contrario, per impostazione predefinita il tools campo è tool_choice = "none"
tools null ToolObject Un elenco di tools che il modello può chiamare. Attualmente, function è l'unico tipo supportato tool 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": {...} } consente 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 la probabilità di log di un token campionato.
top_logprobs null Intero Questo parametro controlla il numero di candidati token più probabili per restituire le probabilità di log per ogni passaggio di campionamento. Può essere 0-20. logprobs deve essere true se si usa questo campo.

ChatMessage

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

Il system ruolo 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. Vedere Chiamata di funzioni in Azure Databricks.

Campo Tipo 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 Tipo Descrizione
name Stringa Obbligatorio. Nome della funzione consigliata dal modello.
arguments Object Obbligatorio. Argomenti per la funzione come dizionario JSON serializzato.

ToolChoiceObject

Vedere Chiamata di funzioni in Azure Databricks.

Campo Tipo Descrizione
type Stringa Obbligatorio. Tipo dello strumento. Attualmente è supportato solo "function".
function Object 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 tools campo.

ToolObject

Vedere Chiamata di funzioni in Azure Databricks.

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

FunctionObject

Campo Tipo Descrizione
name Stringa Obbligatorio. Nome della funzione che deve essere chiamata.
description Object Obbligatorio. Descrizione 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 Object I parametri accettati dalla funzione, descritti come un oggetto schema JSON valido. 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 massimo 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 Tipo Descrizione
type Stringa Obbligatorio. Tipo di formato di risposta definito. Sia text per il testo non strutturato, json_object per gli oggetti JSON non strutturati o json_schema per gli oggetti JSON che 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 Tipo Descrizione
name Stringa Obbligatorio. Nome del formato della risposta.
description String Descrizione del formato di risposta, usato dal modello per determinare come rispondere nel formato.
schema Object 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 di completamento della chat. Per le richieste di streaming, la risposta è un text/event-stream oggetto in cui ogni evento è un oggetto blocco di completamento. La struttura di primo livello degli oggetti di completamento e blocchi è quasi identica: ha solo choices un tipo diverso.

Campo Tipo Descrizione
id Stringa Identificatore univoco per il completamento della chat.
choices List[ChatCompletionChoice] o List[ChatCompletionChunk] (streaming) Elenco di scelte di completamento della chat. n le scelte vengono restituite se viene specificato il n parametro .
object String Tipo dell'oggetto. Uguale a "chat.completions" per il non streaming o "chat.completion.chunk" per lo streaming.
created Intero Ora in cui il completamento della chat è stato generato in secondi.
model String 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 Tipo Descrizione
index Intero Indice della scelta nell'elenco di scelte.
message ChatMessage Messaggio di completamento della chat generato dal modello. Il ruolo sarà assistant.
finish_reason String Il motivo per cui il modello ha interrotto la generazione di token.

ChatCompletionChunk

Campo Tipo Descrizione
index Intero Indice della scelta nell'elenco di scelte.
delta ChatMessage Parte del messaggio di completamento della chat delle risposte generate in streaming dal modello. È garantito role che solo il primo blocco sia popolato.
finish_reason String Il motivo per cui il modello ha interrotto la generazione di token. Solo l'ultimo blocco avrà questo popolamento.

Completamento dell’attività

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.

Completamento richiesto

Campo Predefiniti Tipo Descrizione
prompt String o List[String] Obbligatorio. Prompt/i per il modello.
max_tokens null null, che significa nessun limite o un numero intero maggiore di zero Numero massimo di token da generare nella risposta.
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 lo standard degli eventi inviati dal server.
temperature 1.0 Float in [0,2] Temperatura di campionamento. 0 è deterministico e valori più elevati introducono maggiore casualità.
top_p 1.0 Float in (0,1] Soglia di probabilità utilizzata per il campionamento del nucleo.
top_k null null, che significa 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" oppure "error" Per i timeout e gli errori di lunghezza del contesto superati. Uno di: "truncate" (restituisce il maggior numero possibile di token) e "error" (restituisce un errore). Questo parametro viene accettato solo con pagamento per endpoint di token.
n 1 Intero maggiore di zero L'API restituisce n completamenti di chat indipendenti quando n viene specificato. 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 di velocità effettiva con provisioning.
stop [] String o List[String] Il modello smette di generare altri token quando viene rilevata una delle sequenze in stop .
suffix "" String Stringa aggiunta alla fine di ogni completamento.
echo false Booleano Restituisce il prompt insieme al completamento.
use_raw_prompt false Booleano Se true, passare direttamente nel prompt modello senza alcuna trasformazione.

Risposta di completamento

Campo Tipo Descrizione
id Stringa Identificatore univoco per il completamento.
choices CompletionChoice Elenco di completamenti di testo. Per ogni richiesta passata, n le scelte vengono generate se n specificato. Il valore predefinito n è 1.
object String Tipo dell'oggetto. Uguale a "text_completion"
created Intero Ora di generazione del completamento in secondi.
usage Utilizzo Metadati di utilizzo dei token.

CompletionChoice

Campo Tipo Descrizione
index Intero Indice del prompt nella richiesta.
text String Completamento generato.
finish_reason String Il motivo per cui il modello ha interrotto la generazione di token.

Incorporamento dell’attività

Le attività di incorporamento eseguono il mapping delle stringhe di input in vettori di incorporamento. Molti input possono essere raggruppati in batch in ogni richiesta.

Incorporamento dei report

Campo Tipo Descrizione
input String o List[String] Obbligatorio. Testo di input da incorporare. Può essere una stringa o un elenco di stringhe.
instruction String Istruzione facoltativa da passare al modello di incorporamento.

Le istruzioni sono facoltative ed estremamente specifiche del modello. Ad esempio, gli autori di BGE non consigliano alcuna istruzione durante l'indicizzazione dei blocchi e consigliano l'uso dell'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 Tipo Descrizione
id Stringa Identificatore univoco per l'incorporamento.
object String Tipo dell'oggetto. Uguale a "list".
model String Il nome del modello di incorporamento del testo richiamato per creare l'incorporamento.
data EmbeddingObject Il vettore di incorporamento.
usage Utilizzo Metadati di utilizzo dei token.

EmbeddingObject

Campo Tipo Descrizione
object Stringa Tipo dell'oggetto. Uguale a "embedding".
index Intero Indice dell'incorporamento nell'elenco di incorporamenti.
embedding list[float] Il vettore di incorporamento. Ogni modello restituirà un vettore a dimensione fissa (1024 per BGE-Large)

Risorse aggiuntive