Partager via

Informations de référence sur l’API REST Modèle de fondation

  • Article

Cet article fournit des informations générales sur les API pour les API Foundation Model Databricks et les modèles qu’elles 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 de paiement par jeton et de débit provisionné acceptent le même format de requête d’API REST.

Points de terminaison

Chaque modèle de paiement par jeton a un point de terminaison unique et les utilisateurs peuvent interagir avec ces points de terminaison à l’aide de requêtes HTTP POST. 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 également en charge plusieurs modèles par point de terminaison pour les tests A/B, tant que les deux modèles mis en service exposent le même format d’API. Par exemple, les deux modèles sont des modèles de conversation.

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 conversation et de saisie semi-automatique de texte prennent en charge les réponses de diffusion en continu.

Les charges de travail de paiement par jeton prennent en charge certains modèles, consultez Modèles pris en charge pour le paiement par jeton pour ces modèles et les formats d’API acceptés.

Utilisation

Les réponses incluent un sous-message usage qui signale le nombre de jetons dans la requête 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 Integer 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 tels que llama-2-70b-chat, 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. Chaque requête décrit la conversation jusqu’au point présent, où le champ messages doit alterner entre les rôles user et assistant se terminant par un message user. La réponse du modèle fournit le message assistant suivant dans la conversation.

Requête de conversation

Champ Par défaut Type Description
messages Liste ChatMessage Obligatoire. Liste des messages représentant la conversation actuelle.
max_tokens nil Entier supérieur à zéro ou nil, qui représente l’infini Nombre maximal de jetons à générer.
stream true Boolean Diffusez en continu les réponses à un client, afin d’autoriser les résultats partiels pour les requêtes. Si ce paramètre est inclus dans la requête, les réponses sont envoyées à l’aide de la norme Événements envoyés par le serveur.
temperature 1.0 Float en [0,2] La température d’échantillonnage. 0 est déterministe et les valeurs supérieures introduisent une tendance plus aléatoire.
top_p 1.0 Float en (0,1] Seuil de probabilité utilisé pour l’échantillonnage du noyau.
top_k nil Entier supérieur à zéro ou nil, qui représente l’infini 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 dans 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 approvisionnés.
tool_choice nil Chaîne ou ToolChoiceObject Peut seulement être utilisé 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 (le cas échéant) quel est l’outil approprié à utiliser. Avec auto, si le modèle considère que les outils de tools ne sont pas appropriés, il génère un message assistant standard au lieu d’un appel d’outil. required signifie que le modèle sélectionne l’outil le plus pertinent dans tools et qu’il 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 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 nil 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 peuvent être prises en charge.

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és 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é avec 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é par le modèle.
arguments Object 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, seul "function" est pris en charge.
function Object 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, seul function est pris 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 Object Obligatoire. Description détaillée de la fonction. Le modèle utilise cette description pour comprendre la pertinence de la fonction à l’invite et générer les appels d’outil avec une précision plus élevée.
parameters Object Paramètres acceptés par la fonction, décrits sous la forme d’un objet valide de schéma JSON. Si l’outil est appelé, l’appel de l’outil est donc 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.

Réponse de la 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 de saisie semi-automatique de texte et de bloc est presque identique : seul choices a un type différent.

Champ Type Description
id Chaîne Identificateur unique de la saisie semi-automatique de 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 aucune diffusion en continu ou "chat.completion.chunk" pour la diffusion en continu.
created Entier Heure de la génération de la saisie semi-automatique de texte 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 Integer Index du choix dans la liste des choix générés.
message ChatMessage Message de saisie semi-automatique de conversation 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 Integer 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 ceci rempli.

Tâche de saisie semi-automatique de texte

Les tâches de saisie semi-automatique de texte permettent de générer des réponses à une seule invite. Contrairement aux tâches de conversation, cette tâche prend en charge les entrées par lots : plusieurs invites indépendantes peuvent être envoyées dans une seule requête.

Requête de saisie semi-automatique de texte

Champ Par défaut Type Description
prompt String ou List[String] Obligatoire. Invite(s) pour le modèle.
max_tokens nil Entier supérieur à zéro ou nil, qui représente l’infini Nombre maximal de jetons à générer.
stream true Boolean Diffusez en continu les réponses à un client, afin d’autoriser les résultats partiels pour les requêtes. Si ce paramètre est inclus dans la requête, les réponses sont envoyées à l’aide de la norme Événements envoyés par le serveur.
temperature 1.0 Float en [0,2] La température d’échantillonnage. 0 est déterministe et les valeurs supérieures introduisent une tendance plus aléatoire.
top_p 1.0 Float en (0,1] Seuil de probabilité utilisé pour l’échantillonnage du noyau.
top_k nil Entier supérieur à zéro ou nil, qui représente l’infini 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 uniquement accepté 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 approvisionnés.
stop [] String ou List[String] Le modèle cesse de générer d’autres jetons lorsque l’une des séquences dans stop est rencontrée.
suffix "" Chaîne Chaîne ajoutée à la fin de chaque saisie semi-automatique.
echo false Booléen Retourne l’invite avec la saisie semi-automatique.
use_raw_prompt false Booléen Si true, passez 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 saisies semi-automatiques de texte. Pour chaque invite transmise, les choix n sont générés si n est spécifié. La valeur par défaut de n est 1.
object Chaîne Type d'objet. Égal à "text_completion"
created Entier Heure de la génération de la saisie semi-automatique en secondes.
usage Utilisation Métadonnées d’utilisation des jetons

CompletionChoice

Champ Type Description
index Integer Index de l’invite dans la requête.
text Chaîne Saisie semi-automatique 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.

Requête 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 suggèrent 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 de l’évènement.
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)

Ressources supplémentaires