Partager via

plug-in ai_embed_text (préversion)

  • Article

S’applique à : ✅Azure Data Explorer

Le ai_embed_text plug-in permet l’incorporation de texte à l’aide de modèles de langage, ce qui permet d’activer différents scénarios liés à l’IA, tels que les applications DE génération augmentée de récupération (RAG) et la recherche sémantique. Le plug-in prend en charge les modèles d’incorporation du service Azure OpenAI accessibles à l’aide de l’identité managée.

Prérequis

Syntaxe

evaluateai_embed_text (text, connectionString [, options [, IncludeErrorMessages]])

En savoir plus sur les conventions de syntaxe.

Paramètres

Nom Type Requise Description
texte string ✔️ Texte à incorporer. La valeur peut être une référence de colonne ou une scalaire constante.
connectionString string ✔️ Les chaîne de connexion pour le modèle de langage au format <ModelDeploymentUri>;<AuthenticationMethod>; remplacez <ModelDeploymentUri> et <AuthenticationMethod> par l’URI de déploiement du modèle IA et la méthode d’authentification respectivement.
options dynamic Options qui contrôlent les appels au point de terminaison du modèle d’incorporation. Consultez Options.
IncludeErrorMessages bool Indique s’il faut générer des erreurs dans une nouvelle colonne de la table de sortie. Valeur par défaut : false.

Options

Le tableau suivant décrit les options qui contrôlent la façon dont les requêtes sont adressées au point de terminaison du modèle incorporé.

Nom Type Description
RecordsPerRequest int Spécifie le nombre d’enregistrements à traiter par requête. Valeur par défaut : 1.
CharsPerRequest int Spécifie le nombre maximal de caractères à traiter par requête. Valeur par défaut : 0 (illimité). Azure OpenAI compte des jetons, chaque jeton se traduit approximativement en quatre caractères.
RetriesOnThrottling int Spécifie le nombre de nouvelles tentatives lors de la limitation. Valeur par défaut : 0.
GlobalTimeout timespan Spécifie la durée maximale d’attente d’une réponse du modèle d’incorporation. Valeur par défaut : null
ModelParameters dynamic Paramètres spécifiques au modèle d’incorporation, tels que les dimensions d’incorporation ou les identificateurs utilisateur à des fins de surveillance. Valeur par défaut : null.
ReturnSuccessfulOnly bool Indique s’il faut retourner uniquement les éléments traités avec succès. Valeur par défaut : false. Si le paramètre IncludeErrorMessages est défini truesur , cette option est toujours définie sur false.

Configurer des stratégies d’identité managée et de légende

Pour utiliser le ai_embed_text plug-in, vous devez configurer les stratégies suivantes :

  • identité managée : autorisez l’identité managée affectée par le système à s’authentifier auprès des services Azure OpenAI.
  • légende : autorisez le domaine de point de terminaison du modèle IA.

Pour configurer ces stratégies, utilisez les commandes dans les étapes suivantes :

  1. Configurez l’identité managée :

    .alter-merge cluster policy managed_identity
```
[
  {
    "ObjectId": "system",
    "AllowedUsages": "AzureAI"
  }
]
```

  2. Configurez la stratégie de légende :

    .alter-merge cluster policy callout
```
[
    {
        "CalloutType": "azure_openai",
        "CalloutUriRegex": "https://[A-Za-z0-9\\-]{3,63}\\.openai\\.azure\\.com/.*",
        "CanCall": true
    }
]
```

Retours

Retourne les nouvelles colonnes d’incorporation suivantes :

  • Colonne avec le suffixe _embedding qui contient les valeurs d’incorporation
  • S’il est configuré pour retourner des erreurs, une colonne avec le suffixe _embedding_error , qui contient des chaînes d’erreur ou est laissée vide si l’opération réussit.

Selon le type d’entrée, le plug-in retourne des résultats différents :

  • Référence de colonne : retourne un ou plusieurs enregistrements avec des colonnes supplémentaires sont précédés du nom de colonne de référence. Par exemple, si la colonne d’entrée est nommée TextData, les colonnes de sortie sont nommées TextData_embedding et, si elles sont configurées pour retourner des erreurs, TextData_embedding_error.
  • Scalaire constante : retourne un enregistrement unique avec des colonnes supplémentaires qui ne sont pas préfixées. Les noms de colonnes sont _embedding et, s’ils sont configurés pour retourner des erreurs, _embedding_error.

Exemples

L’exemple suivant incorpore le texte Embed this text using AI à l’aide du modèle d’incorporation Azure OpenAI.

let expression = 'Embed this text using AI';
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
evaluate ai_embed_text(expression, connectionString)

L’exemple suivant incorpore plusieurs textes à l’aide du modèle d’incorporation Azure OpenAI.

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
let options = dynamic({
    "RecordsPerRequest": 10,
    "CharsPerRequest": 10000,
    "RetriesOnThrottling": 1,
    "GlobalTimeout": 2m
});
datatable(TextData: string)
[
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
]
| evaluate ai_embed_text(TextData, connectionString, options , true)

Bonnes pratiques

Les modèles d’incorporation Azure OpenAI sont soumis à une limitation importante et les appels fréquents à ce plug-in peuvent rapidement atteindre des limites de limitation.

Pour utiliser efficacement le ai_embed_text plug-in tout en réduisant la limitation et les coûts, suivez les bonnes pratiques suivantes :

  • Taille de la demande de contrôle : ajustez le nombre d’enregistrements (RecordsPerRequest) et les caractères par requête (CharsPerRequest).
  • Contrôlez le délai d’expiration de la requête : définissez GlobalTimeout sur une valeur inférieure au délai d’expiration de la requête pour vous assurer que la progression n’est pas perdue lors des appels réussis jusqu’à ce point.
  • Gérer les limites de débit plus normalement : définissez les nouvelles tentatives sur la limitation (RetriesOnThrottling).

Contenu connexe