Partage via

Compétence d’incorporations Azure OpenAI

  • Article

La compétence Incorporation Azure OpenAI se connecte à un modèle d’incorporation déployé sur votre ressource Azure OpenAI pour générer des incorporations pendant l’indexation. Vos données sont traitées dans l’emplacement géographique où votre modèle est déployé.

Prérequis

Votre service Azure OpenAI doit avoir un sous-domaine personnalisé associé. Si le service a été créé via le Portail Azure, ce sous-domaine est généré automatiquement dans le cadre de votre configuration de service. Vérifiez que votre service inclut un sous-domaine personnalisé avant de l’utiliser avec l’intégration d’Azure AI Search.

Les ressources azure OpenAI Service (avec accès aux modèles incorporés) qui ont été créées dans AI Studio ne sont pas prises en charge. Seules les ressources du service Azure OpenAI créées dans le Portail Azure sont compatibles avec l’intégration des compétences d’incorporation Azure OpenAI.

L’Assistant Importer et vectoriser des données sur le Portail Azure utilise la compétence Incorporation Azure OpenAI pour vectoriser le contenu. Vous pouvez exécuter l’Assistant et passer en revue l’ensemble de compétences généré pour voir comment l’Assistant génère la compétence pour incorporer des modèles.

Remarque

Cette compétence est liée à Azure OpenAI et est facturée au prix du paiement à l’utilisation d’Azure OpenAI.

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

Limites de données

La taille maximale d’une entrée de texte doit être de 8 000 jetons. Si l’entrée dépasse le maximum autorisé, le modèle renvoie une erreur de requête non valide. Pour plus d’informations, consultez le concept clé de jetons dans la documentation Azure OpenAI. Envisagez d’utiliser la compétence Fractionnement de texte si vous avez besoin d’une segmentation des données.

Paramètres de la compétence

Les paramètres respectent la casse.

Entrées Description
resourceUri URI du fournisseur de modèles, dans ce cas, une ressource Azure OpenAI. Ce paramètre prend uniquement en charge les URL avec un domaine openai.azure.com, par https://<resourcename>.openai.azure.comexemple . Si le point de terminaison Azure OpenAI a une URL avec un domaine cognitiveservices.azure.com, par https://<resourcename>.cognitiveservices.azure.comexemple, un sous-domaine personnalisé avec lequel openai.azure.com vous devez d’abord être créé pour la ressource Azure OpenAI et l’utiliser https://<resourcename>.openai.azure.com à la place.
apiKey La clé secrète utilisée pour accéder au modèle. Si vous fournissez une clé, laissez le champ authIdentity vide. Si vous définissez le apiKey et leauthIdentity, le apiKey est utilisé sur la connexion.
deploymentId Le nom du modèle d’incorporation Azure OpenAI déployé. Le modèle doit être un modèle d’incorporation, comme text-embedding-ada-002. Voir la Liste des modèles Azure OpenAI pour les modèles pris en charge.
authIdentity Une identité managée par l’utilisateur utilisée par le service de recherche pour la connexion à Azure OpenAI. Vous pouvez utiliser une identité managée par le système ou l’utilisateur. Pour utiliser une identité managée par le système, laissez apiKey et authIdentity vide. L’identité managée par le système est utilisée automatiquement. Une identité managée doit avoir les autorisations utilisateur OpenAI Cognitive Services pour envoyer du texte à Azure OpenAI.
modelName Cette propriété est requise si votre ensemble de compétences est créé à l’aide de l’API REST 2024-05-01-preview ou 2024-07-01. Définissez cette propriété sur le nom de déploiement d’un modèle d’incorporation Azure OpenAI déployé sur le fournisseur spécifié par resourceUri et identifié par deploymentId. Les valeurs actuellement prises en charge sont text-embedding-ada-002, text-embedding-3-large et text-embedding-3-small.
dimensions (Facultatif, introduit dans l’API REST 2024-05-01-preview). Les dimensions des incorporations que vous souhaitez générer si le modèle prend en charge la réduction des dimensions d’incorporation. Les plages prises en charge sont listées ci-dessous. Si elle n’est pas spécifiée, cette propriété correspond par défaut aux dimensions maximales pour chaque modèle. Pour les ensembles de compétences créés à l’aide de la version 2023-10-01-preview, les dimensions sont fixes à 1536.

Dimensions prises en charge par modelName

Les dimensions prises en charge pour une compétence Incorporation Azure OpenAI dépendent du modelName configuré.

modelName Dimensions minimales Dimensions maximales
text-embedding-ada-002 1536 1536
text-embedding-3-large 1 3 072
text-embedding-3-small 1 1536

Entrées de la compétence

Input Description
text Le texte d’entrée à vectoriser. Si vous utilisez la segmentation des données, la source peut être /document/pages/*.

Sorties de la compétence

Sortie Description
embedding Incorporation vectorisée pour le texte d’entrée.

Exemple de définition

Prenons l’exemple d’un enregistrement qui contient les champs suivants :

{
    "content": "Microsoft released Windows 10."
}

Votre définition de compétence peut se présenter comme suit :

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-eastus.openai.azure.com/",
  "deploymentId": "my-text-embedding-ada-002-model",
  "modelName": "text-embedding-ada-002",
  "dimensions": 1536,
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

Exemple de sortie

Pour le texte d’entrée donné, une sortie d’incorporation vectorisée est produite.

{
  "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... 
        0.021276434883475304,
      ]
}

La sortie réside dans la mémoire. Pour envoyer cette sortie à un champ dans l’index de recherche, vous devez définir un outputFieldMapping qui mappe la sortie d’incorporation vectorisée (qui est un tableau) à un champ vectoriel. En supposant que la sortie de la compétence se trouve dans le nœud incorporation du document et que content_vector est le champ de l’index de recherche, outputFieldMapping doit se présenter comme ceci dans l’indexeur :

  "outputFieldMappings": [
    {
      "sourceFieldName": "/document/embedding/*",
      "targetFieldName": "content_vector"
    }
  ]

Bonnes pratiques

Voici quelques meilleures pratiques à prendre en compte lors de l’utilisation de cette compétence :

  • Si vous atteignez votre limite de jetons par minute (TPM) Azure OpenAI, tenez compte des conseils sur les limites de quota afin de pouvoir répondre en conséquence. Pour plus d’informations sur les performances de votre instance Azure OpenAI, consultez la documentation Surveillance Azure OpenAI.

  • Le modèle de déploiement d’incorporations Azure OpenAI que vous utilisez pour cette compétence doit être idéalement distinct du déploiement utilisé pour d’autres cas d’usage, y compris le vectoriseur de requête. Cela permet à chaque déploiement d’être adapté à son cas d’usage spécifique, ce qui entraîne des performances optimisées et l’identification facile du trafic à partir de l’indexeur et des appels d’incorporation d’index.

  • Votre instance Azure OpenAI doit se trouver dans la même région ou au moins géographiquement proche de la région où votre service Recherche AI est hébergé. Cela réduit la latence et améliore la vitesse de transfert de données entre les services.

  • Si vous avez une limite de jetons par minute (TPM) Azure OpenAI supérieure à la valeur par défaut publiée dans la documentation Quotas et limites, ouvrez un cas de support avec l’équipe Recherche Azure AI, afin que cela puisse être ajusté en conséquence. Cela permet à votre processus d’indexation de ne pas être inutilement ralenti par la limite TPM par défaut documentée, si vous avez des limites plus élevées.

  • Pour obtenir des exemples d’utilisation de cette compétence, y compris des exemples de code, consultez les liens suivants :

Erreurs et avertissements

Condition Résultat
URI nul ou non valide Erreur
DeploymentID nul ou non valide Erreur
Le texte est vide Avertissement
Le texte est supérieur à 8 000 jetons Erreur

Voir aussi