Informations de référence sur l’API REST Modèle de fondation
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 |
null |
null, ce qui signifie aucune limite, ou un entier supérieur à zéro |
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 |
null |
null, ce qui signifie 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 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 |
none |
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 |
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 peuvent être 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 permettant { "type": "json_schema", "json_schema": {...} } d’activer les sorties structurées qui garantit que le modèle suit votre schéma JSON fourni.Le paramètre pour { "type": "json_object" } garantir 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 |
Boolean | Ce paramètre indique s’il faut fournir la probabilité de journal d’un jeton échantillonné. |
top_logprobs |
null |
Integer | Ce paramètre contrôle le nombre de candidats de jetons les plus susceptibles de renvoyer des probabilités de journal pour chaque étape d’échantillonnage. Peut être compris entre 0 et 20. logprobs doit être true en cas d’utilisation de 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é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 | Les paramètres que la fonction accepte, décrits comme un objet de schéma JSON valide. 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 |
Boolean | 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 définie 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 quand strict est true |
ResponseFormatObject
Consultez les 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, soit json_schema pour les objets JSON conformes à un schéma spécifique. |
json_schema |
JsonSchemaObject | Obligatoire. Schéma JSON à respecter s’il type est défini sur json_schema |
JsonSchemaObject
Consultez les sorties structurées sur Azure Databricks.
| Champ | Type | Description |
|---|---|---|
name |
Chaîne | Obligatoire. Nom du format de réponse. |
description |
Chaîne | Description du rôle du format de réponse, qui permet au modèle de déterminer comment répondre dans le format. |
schema |
Object | Obligatoire. Schéma pour le format de réponse, décrit en tant qu’objet de schéma JSON. |
strict |
Boolean | 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 définie 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 quand strict est true |
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 |
null |
null, ce qui signifie aucune limite, ou un entier supérieur à zéro |
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 |
null |
null, ce qui signifie 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. |
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) |