Informations de référence sur l’API REST du modèle Foundation
Cet article fournit des informations générales sur les API pour les API Databricks Foundation Model et les modèles qu’ils prennent en charge. Les API Foundation Model sont conçues pour être similaires à l’API REST d’OpenAI pour faciliter la migration de projets existants. Les points de terminaison "pay-per-token" et "provisioned throughput" acceptent le même format de requête d'API REST.
Points de terminaison
Les API Foundation Model prennent en charge les points de terminaison de paiement par jeton et les points de terminaison de débit approvisionnés.
Un point de terminaison préconfiguré est disponible dans votre espace de travail pour chaque modèle pris en charge par jeton de paiement et les utilisateurs peuvent interagir avec ces points de terminaison à l’aide de requêtes HTTP POST. Consultez le paiement par jeton pour les modèles pris en charge.
Les points de terminaison de débit approvisionnés peuvent être créés à l’aide de l’API ou de l’interface utilisateur de mise en service. Ces points de terminaison prennent en charge plusieurs modèles par point de terminaison pour les tests A/B, tant que les deux modèles servis exposent le même format d’API. Par exemple, les deux modèles sont des modèles de chat. Consultez POST /api/2.0/service-endpoints pour les paramètres de configuration de point de terminaison.
Les requêtes et les réponses utilisent JSON, la structure JSON exacte dépend du type de tâche d’un point de terminaison. Les points de terminaison de la conversation et de fin prennent en charge les réponses en continu.
Utilisation
Les réponses incluent un sous-message usage qui signale le nombre de jetons dans la demande et la réponse. Le format de ce sous-message est le même pour tous les types de tâches.
| Champ | Type | Description |
|---|---|---|
completion_tokens |
Entier | Nombre de jetons générés. Non inclus dans les réponses incorporées. |
prompt_tokens |
Entier | Nombre de jetons de la ou des invites d’entrée. |
total_tokens |
Entier | Nombre total de jetons. |
Pour les modèles comme Meta-Llama-3.3-70B-Instruct une invite utilisateur est transformée à l’aide d’un modèle d’invite avant d’être transmis au modèle. Pour les points de terminaison de paiement par jeton, une invite système peut également être ajoutée. prompt_tokens inclut tout le texte ajouté par notre serveur.
Tâche de conversation
Les tâches de conversation sont optimisées pour les invites multitour avec un modèle. La réponse du modèle fournit le message assistant suivant dans la conversation. Consultez POST /service-endpoints/{name}/invocations pour interroger les paramètres de point de terminaison.
Demande de conversation
| Champ | Par défaut | Type | Description |
|---|---|---|---|
messages |
Liste ChatMessage | Obligatoire. Liste des messages représentant la conversation actuelle. | |
max_tokens |
null |
null, ce qui signifie qu'il n'y a pas de limite ou qu'il s'agit d'un entier supérieur à zéro |
Nombre maximal de jetons à générer. |
stream |
true |
Booléen | Transmettez en flux continu les réponses au client afin de permettre les résultats partiels pour les demandes. Si ce paramètre est inclus dans la requête, les réponses sont envoyées à l’aide des événements envoyés par le serveur standard. |
temperature |
1.0 |
Float en [0,2] | Température d’échantillonnage. 0 est déterministe et les valeurs supérieures introduisent plus de randomité. |
top_p |
1.0 |
Float en (0,1] | Seuil de probabilité utilisé pour l’échantillonnage du noyau. |
top_k |
null |
null, ce qui signifie qu'il n'y a aucune limite, ou un entier supérieur à zéro |
Définit le nombre de jetons k les plus probables à utiliser pour le filtrage top-k. Définissez cette valeur sur 1 pour rendre les sorties déterministes. |
stop |
[] | String ou List[String] | Le modèle cesse de générer d’autres jetons lorsque l’une des séquences de stop est rencontrée. |
n |
1 | Entier supérieur à zéro | L’API retourne les achèvements de conversation indépendants n lorsque n est spécifié. Recommandé pour les charges de travail qui génèrent plusieurs achèvements sur la même entrée pour améliorer l’efficacité de l’inférence et réaliser des économies de coûts. Disponible uniquement pour les points de terminaison de débit provisionnés. |
tool_choice |
none |
Chaîne ou ToolChoiceObject | Utilisé uniquement conjointement avec le champ tools. tool_choice prend en charge une variété de chaînes de mots clés telles que auto, requiredet none. auto signifie que vous laissez le modèle décider si un outil est pertinent à utiliser. Avec auto si le modèle ne croit pas que les outils de tools sont pertinents, le modèle génère un message assistant standard au lieu d’un appel d’outil. required signifie que le modèle choisit l’outil le plus pertinent dans tools et doit générer un appel d’outil. none signifie que le modèle ne génère aucun appel d’outil et qu’il doit plutôt générer un message d’assistant standard. Pour forcer un appel d’outil avec un outil spécifique défini dans tools, utilisez un ToolChoiceObject. Valeur par défaut si le champ tools est renseigné tool_choice = "auto". Sinon, le champ tools est défini par défaut sur tool_choice = "none" |
tools |
null |
ToolObject | Liste d’outils de tools que le modèle peut appeler. Actuellement, function est le seul type de tool pris en charge et un maximum de 32 fonctions sont prises en charge. |
response_format |
null |
ResponseFormatObject | Objet spécifiant le format que le modèle doit générer. Les types acceptés sont text, json_schema ou json_objectLe paramètre sur { "type": "json_schema", "json_schema": {...} } active les sorties structurées, ce qui garantit que le modèle suit votre schéma JSON fourni.La définition de { "type": "json_object" } garantit que les réponses générées par le modèle sont valides JSON, mais ne garantit pas que les réponses suivent un schéma spécifique. |
logprobs |
false |
Booléen | Ce paramètre indique s'il faut fournir la probabilité logarithmique d'un jeton d'être échantillonné. |
top_logprobs |
null |
Entier | Ce paramètre contrôle le nombre de candidats de jetons les plus susceptibles de retourner des probabilités d’enregistrement pour chaque étape d’échantillonnage. Peut être 0-20. logprobs devez être true si vous utilisez ce champ. |
ChatMessage
| Champ | Type | Description |
|---|---|---|
role |
Chaîne | Obligatoire. Rôle de l’auteur du message. Peut être "system", "user", "assistant" ou "tool". |
content |
Chaîne | Contenu du message. Obligatoire pour les tâches de conversation qui n’impliquent pas d’appels d’outils. |
tool_calls |
Liste ToolCall | Liste des tool_calls générées par le modèle. Doit avoir role comme "assistant" et aucune spécification pour le champ content. |
tool_call_id |
Chaîne | Lorsque role est "tool", l’ID associé au ToolCall auquel le message répond. Doit être vide pour d’autres options role. |
Le rôle system ne peut être utilisé qu’une seule fois, comme premier message d’une conversation. Il remplace l’invite système par défaut du modèle.
ToolCall
Suggestion d’une action d’appel d’outil par le modèle. Consultez Appel de fonctions sur Azure Databricks.
| Champ | Type | Description |
|---|---|---|
id |
Chaîne | Obligatoire. Identificateur unique pour la suggestion d’appel d’outil. |
type |
Chaîne | Obligatoire. Seul "function" est pris en charge. |
function |
FunctionCallCompletion | Obligatoire. Suggestions d’appel de fonction par le modèle. |
FunctionCallCompletion
| Champ | Type | Description |
|---|---|---|
name |
Chaîne | Obligatoire. Nom de la fonction recommandée par le modèle. |
arguments |
Objet | Obligatoire. Arguments de la fonction en tant que dictionnaire JSON sérialisé. |
ToolChoiceObject
Consultez Appel de fonctions sur Azure Databricks.
| Champ | Type | Description |
|---|---|---|
type |
Chaîne | Obligatoire. Type de l’outil. Actuellement, seule "function" est prise en charge. |
function |
Objet | Obligatoire. Objet définissant l’outil à appeler du formulaire {"type": "function", "function": {"name": "my_function"}} où "my_function est le nom d’un FunctionObject dans le champ tools. |
ToolObject
Consultez Appel de fonctions sur Azure Databricks.
| Champ | Type | Description |
|---|---|---|
type |
Chaîne | Obligatoire. Type de l’outil. Actuellement, seule function est prise en charge. |
function |
FunctionObject | Obligatoire. Définition de fonction associée à l’outil. |
FunctionObject
| Champ | Type | Description |
|---|---|---|
name |
Chaîne | Obligatoire. Nom de la fonction à appeler. |
description |
Objet | Obligatoire. Description détaillée de la fonction. Le modèle utilise cette description pour comprendre la pertinence de la fonction par rapport à l’invite et générer les appels d'outils avec une plus grande précision. |
parameters |
Objet | Les paramètres que la fonction accepte, décrits comme un schéma JSON valide objet. Si l’outil est appelé, l’appel de l’outil est adapté au schéma JSON fourni. L’omission de paramètres définit une fonction sans aucun paramètre. Le nombre de properties est limité à 15 clés. |
strict |
Booléen | Indique s’il faut activer l’adhésion stricte au schéma lors de la génération de l’appel de fonction. Si la valeur est true, le modèle suit le schéma exact défini dans le champ de schéma. Seul un sous-ensemble de schéma JSON est pris en charge lorsque strict est true |
ResponseFormatObject
Consultez Sorties structurées sur Azure Databricks.
| Champ | Type | Description |
|---|---|---|
type |
Chaîne | Obligatoire. Type de format de réponse défini. Soit text pour le texte non structuré, json_object pour les objets JSON non structurés ou json_schema pour les objets JSON respectant un schéma spécifique. |
json_schema |
jsonSchemaObject | Obligatoire. Schéma JSON à respecter si type est défini sur json_schema |
JsonSchemaObject
Consultez Sorties structurées sur Azure Databricks.
| Champ | Type | Description |
|---|---|---|
name |
Chaîne | Obligatoire. Nom du format de réponse. |
description |
Chaîne | Une description de à quoi sert le format de réponse, utilisée par le modèle pour déterminer comment répondre dans ce format. |
schema |
Objet | Obligatoire. Schéma pour le format de réponse, décrit en tant qu’objet de schéma JSON. |
strict |
Booléen | Indique s’il faut activer l’adhésion stricte au schéma lors de la génération de la sortie. Si la valeur est true, le modèle suit le schéma exact défini dans le champ de schéma. Seul un sous-ensemble de schéma JSON est pris en charge lorsque strict est true |
Réponse de conversation
Pour les requêtes en non diffusion en continu, la réponse est un objet de saisie semi-automatique de conversation unique. Pour les requêtes de diffusion en continu, la réponse est text/event-stream où chaque événement est un objet de bloc de saisie semi-automatique de texte. La structure de niveau supérieur des objets d’achèvement et de morceaux est presque identique : seul choices a un type distinct.
| Champ | Type | Description |
|---|---|---|
id |
Chaîne | Identificateur unique pour l'achèvement de la conversation. |
choices |
List[ChatCompletionChoice] ou List[ChatCompletionChunk] (diffusion en continu) | Liste des textes de saisie semi-automatique de conversation. Les choix n sont retournés si le paramètre n est spécifié. |
object |
Chaîne | Type d’objet. Égal à "chat.completions" pour une utilisation hors diffusion en continu ou "chat.completion.chunk" pour la diffusion en continu. |
created |
Entier | Heure à laquelle l’achèvement de la conversation a été généré en secondes. |
model |
Chaîne | Version du modèle utilisée pour générer la réponse. |
usage |
Utilisation | Métadonnées d’utilisation des jetons. Peut ne pas être présent sur les réponses de diffusion en continu. |
ChatCompletionChoice
| Champ | Type | Description |
|---|---|---|
index |
Entier | Index du choix dans la liste des choix générés. |
message |
ChatMessage | Message de complétion de chat retourné par le modèle. Le rôle sera assistant. |
finish_reason |
Chaîne | Raison pour laquelle le modèle a cessé de générer des jetons. |
ChatCompletionChunk
| Champ | Type | Description |
|---|---|---|
index |
Nombre entier | Index du choix dans la liste des choix générés. |
delta |
ChatMessage | Une partie du message de saisie semi-automatique de conversation des réponses diffusées en continu générées à partir du modèle. Seul le premier bloc est garanti avec role rempli. |
finish_reason |
Chaîne | Raison pour laquelle le modèle a cessé de générer des jetons. Seul le dernier bloc aura ce remplissage. |
Tâche de fin
Les tâches de complétion de texte consistent à générer des réponses à partir d'une seule invite. Contrairement à Chat, cette tâche prend en charge les entrées par lots : plusieurs invites indépendantes peuvent être envoyées dans une seule requête. Consultez POST /service-endpoints/{name}/invocations pour interroger les paramètres de point de terminaison.
Demande d’achèvement
| Champ | Par défaut | Type | Description |
|---|---|---|---|
prompt |
String ou List[String] | Obligatoire. Les invites pour le modèle. | |
max_tokens |
null |
null, ce qui signifie qu'il n'y a pas de limite, ou un entier supérieur à zéro |
Nombre maximal de jetons à générer. |
stream |
true |
Booléen | Transmettez les réponses à un client pour permettre des résultats partiels pour les demandes. Si ce paramètre est inclus dans la requête, les réponses sont envoyées à l’aide des événements envoyés par le serveur standard. |
temperature |
1.0 |
Float en [0,2] | Température d’échantillonnage. 0 est déterministe et les valeurs supérieures introduisent plus de randomité. |
top_p |
1.0 |
Float en (0,1] | Seuil de probabilité utilisé pour l’échantillonnage du noyau. |
top_k |
null |
null, ce qui signifie qu'il n'y a pas de limite, ou un entier supérieur à zéro |
Définit le nombre de jetons k les plus probables à utiliser pour le filtrage top-k. Définissez cette valeur sur 1 pour rendre les sorties déterministes. |
error_behavior |
"error" |
"truncate" ou "error" |
Pour les délais d’expiration et les erreurs de longueur de contexte dépassées. Un des éléments suivants : "truncate" (renvoyer autant de jetons que possible) et "error" (renvoyer une erreur). Ce paramètre est accepté uniquement par les points de terminaison de paiement par jeton. |
n |
1 | Entier supérieur à zéro | L’API retourne les achèvements de conversation indépendants n lorsque n est spécifié. Recommandé pour les charges de travail qui génèrent plusieurs achèvements sur la même entrée pour améliorer l’efficacité de l’inférence et réaliser des économies de coûts. Disponible uniquement pour les points de terminaison de débit provisionnés. |
stop |
[] | String ou List[String] | Le modèle cesse de générer d’autres jetons lorsque l’une des séquences de stop est rencontrée. |
suffix |
"" |
Chaîne | Une chaîne qui est ajoutée à la fin de chaque complétion. |
echo |
false |
Booléen | Retourne l’invite avec la saisie semi-automatique. |
use_raw_prompt |
false |
Booléen | Si true, transmettez le prompt directement dans le modèle sans aucune transformation. |
Réponse de la saisie semi-automatique de texte
| Champ | Type | Description |
|---|---|---|
id |
Chaîne | Identificateur unique pour la saisie semi-automatique de texte. |
choices |
CompletionChoice | Liste des complétions de texte. Pour chaque invite transmise, les choix n sont générés si n est spécifié. La n par défaut est 1. |
object |
Chaîne | Type d’objet. Égal à "text_completion" |
created |
Entier | Heure à laquelle l’achèvement a été généré, exprimée en secondes. |
usage |
Utilisation | Métadonnées d’utilisation des jetons. |
CompletionChoice
| Champ | Type | Description |
|---|---|---|
index |
Entier | Index de l’invite dans la requête. |
text |
Chaîne | Saisie générée. |
finish_reason |
Chaîne | Raison pour laquelle le modèle a cessé de générer des jetons. |
tâche d’incorporation
Les tâches d’incorporation mappent les chaînes d’entrée dans des vecteurs d’incorporation. De nombreuses entrées peuvent être regroupées par lots dans chaque requête. Consultez POST /service-endpoints/{name}/invocations pour interroger les paramètres de point de terminaison.
Demande d’incorporation
| Champ | Type | Description |
|---|---|---|
input |
String ou List[String] | Obligatoire. Texte d’entrée à incorporer. Il peut s’agir d’une chaîne ou d’une liste de chaînes. |
instruction |
Chaîne | Instruction facultative à passer au modèle d’incorporation. |
Les instructions sont facultatives et hautement spécifiques au modèle. Par exemple, les auteurs BGE ne recommandent aucune instruction lors de l’indexation de blocs et recommandent d’utiliser l’instruction "Represent this sentence for searching relevant passages:" pour les requêtes de récupération. D’autres modèles comme Instructor-XL prennent en charge un large éventail de chaînes d’instructions.
Réponse des incorporations
| Champ | Type | Description |
|---|---|---|
id |
Chaîne | Identificateur unique pour l'intégration. |
object |
Chaîne | Type d’objet. Égal à "list". |
model |
Chaîne | Nom du modèle d’incorporation utilisé pour créer l’incorporation. |
data |
EmbeddingObject | Objet d’incorporation. |
usage |
Utilisation | Métadonnées d’utilisation des jetons. |
EmbeddingObject
| Champ | Type | Description |
|---|---|---|
object |
Chaîne | Type d’objet. Égal à "embedding". |
index |
Entier | Index de l’incorporation dans la liste des incorporations générées par le modèle. |
embedding |
List[Float] | Vecteur d’incorporation. Chaque modèle retourne un vecteur de taille fixe (1024 pour BGE-Large) |