Azure OpenAI Embedded skill

La compétence Azure OpenAI Embedding se connecte à un modèle d’embedding déployé sur votre projet Azure OpenAI dans Foundry Models ou Microsoft Foundry pour générer des embeddings pendant l’indexation. Vos données sont traitées dans la géo où votre modèle est déployé.

L’assistant Import data du portail Azure utilise la compétence Azure OpenAI Embedding pour vectoriser le contenu. Vous pouvez lancer l’assistant et revoir les compétences générées pour voir comment l’assistant construit la compétence d’intégration de modèles.

Prerequisites

• Un Azure OpenAI dans Foundry Models ressource ou Foundry.

  • Votre ressource OpenAI Azure doit avoir un sous-domaine personnalisé, comme https://<resource-name>.openai.azure.com. Vous pouvez trouver ce point de terminaison sur la page Keys et Endpoint dans le portail Azure et l’utiliser pour la propriété resourceUri dans cette compétence.

  • La ressource mère de votre projet Foundry offre l’accès à plusieurs points de terminaison, notamment https://<resource-name>.openai.azure.com, https://<resource-name>.services.ai.azure.com, et https://<resource-name>.cognitiveservices.azure.com. Vous pouvez trouver ces points de terminaison sur la page Keys et Endpoint du portail Azure et utiliser n’importe lequel d’entre eux pour la propriété resourceUri dans cette compétence.

• Un modèle d’intégration Azure OpenAI déployé sur votre ressource ou projet. Pour les modèles pris en charge, voir la section Paramètres de compétence .

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

Limites des données

La taille maximale d’une saisie texte devrait être de 8 000 jetons. Si l’entrée dépasse le maximum autorisé, le modèle génère une erreur de requête invalide. Pour plus d’informations, consultez le concept clé tokens dans la documentation Azure OpenAI. Envisagez d’utiliser la compétence Text Split si vous avez besoin de fragmentation de données.

Paramètres de compétence

Les paramètres sont sensibles à la casse.

Dimensions supportées par modelName

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

Données de compétences

Résultats des compétences

Exemple de définition

Considérons un enregistrement qui possède les champs suivants :

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

Alors ta définition de compétence pourrait ressembler à ceci :

{
  "@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 résultat

Pour le texte d’entrée donné, une sortie d’intégration vectorielle est produite.

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

La sortie réside en mémoire. Pour envoyer cette sortie à un champ dans l’index de recherche, vous devez définir une sortieFieldMapping qui mappe la sortie d’embedding vectorisée (qui est un tableau) sur un champ vectoriel. En supposant que la sortie de compétence réside dans le nœud d’intégration du document, et que content_vector soit le champ dans l’index de recherche, le outputFieldMapping dans l’indexeur devrait ressembler à :

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

Bonnes pratiques

Voici quelques bonnes pratiques à considérer lorsque vous utilisez cette compétence :

• Si vous atteignez votre Azure limite OpenAI TPM (Tokens par minute), considérez le conseil quota limits afin de pouvoir vous y adresser en conséquence. Consultez la documentation Azure OpenAI monitoring pour plus d’informations sur la performance de votre instance OpenAI Azure.

• Le déploiement du modèle d’embeddings OpenAI Azure que vous utilisez pour cette compétence devrait idéalement être séparé de celui utilisé pour d’autres cas d’usage, y compris le vectoriseur requête. Cela permet d’adapter chaque déploiement à son cas d’usage spécifique, ce qui permet d’optimiser les performances et d’identifier facilement le trafic provenant de l’indexeur et des appels d’intégration de l’indice.

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

• Pour éviter de rencontrer souvent des codes d’erreur 429, envisagez d’implémenter l’équilibrage de charge via Gestion des API en implémentant une passerelle devant plusieurs déploiements de modèles d’incorporation OpenAI Azure.

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

• Pour des exemples et des exemples de code fonctionnels utilisant cette compétence, voir les liens suivants :

  • Vectorisation intégrée (Python)
  • Vectorisation intégrée (C#)
  • Vectorisation intégrée (Java)

Erreurs et avertissements

Considérations relatives à la sécurité pour l’authentification d’identité managée

Lorsque la compétence d’incorporation OpenAI Azure utilise l’authentification d’identité managée, Recherche Azure AI obtient un jeton d’accès Microsoft Entra pour l’audience des outils de recherche (https://cognitiveservices.azure.com) et l’inclut dans les demandes envoyées au point de terminaison spécifié par resourceUri. L’authentification d’identité managée s’applique quand authIdentity elle est définie, ou lorsque les deux apiKey sont vides et authIdentity que le service utilise l’identité affectée par le système.

Le point de terminaison référencé par resourceUri est censé être votre propre ressource OpenAI ou Foundry Tools Azure. Les domaines pris en charge sont :

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

les points de terminaison Gestion des API Azure (APIM) sont*.azure-api.net également pris en charge. Étant donné qu'un nom d'hôte APIM ne peut pas être vérifié à partir de son nom seul, Recherche Azure AI valide ces points de terminaison avec une vérification de connectivité dynamique au moment de la configuration plutôt que par correspondance de domaine. Vous êtes responsable de la configuration et de la maintenance de la relation entre le point de terminaison APIM et la ressource Azure OpenAI ou Foundry Tools derrière elle.

Un jeton d’identité managée émis pour l’audience Des outils Foundry est valide sur n’importe quel outil Foundry Tools ou Azure ressource OpenAI sur laquelle l’identité est autorisée. L’envoi à un point de terminaison non approuvé peut exposer le jeton.

Pratiques de sécurité recommandées

Pour faciliter la maintenance d’un déploiement sécurisé, suivez les pratiques suivantes :

• Définissez uniquement les points de terminaison que vous possédez resourceUri et approuvez. Préférez les domaines Des outils de découverte répertoriés précédemment. Si vous utilisez un point de terminaison APIM, confirmez-le devant votre propre ressource avant d’activer l’identité managée. Un nom d’hôte de recherche fiable n’est pas une preuve de propriété.
• Appliquez le principe du privilège minimum à l’identité managée utilisée par le service de recherche. La Azure compétence d’incorporation OpenAI nécessite uniquement le rôle utilisateur OpenAI Cognitive Services sur la ressource cible. Évitez d’accorder des rôles plus larges.
• Utilisez le périmètre de sécurité réseau (NSP) et les points de terminaison privés ou l’intégration de réseau virtuel pour restreindre les points de terminaison auxquels le service de recherche peut accéder et les sources à partir de lesquelles la ressource cible accepte les demandes.
• Si vous utilisez un point de terminaison APIM, vérifiez que la passerelle valide les demandes entrantes et les transfère uniquement au serveur principal prévu. Vous devez également passer en revue régulièrement ses stratégies d’accès.
• Préférer l’identité managée par rapport apiKeyà . Si vous utilisez apiKey, stockez et faites-le pivoter en toute sécurité et ne l’incorporez pas dans le contrôle de code source. Le service rejette les configurations qui définissent à la fois apiKey et authIdentity.
• Passez régulièrement en revue les définitions d’ensemble de compétences, les attributions de rôles d’identité managée et les configurations APIM pour vérifier que resourceUri les valeurs, les contrôles d’accès et les autorisations d’identité restent actuels et appropriés. Passez en revue les modifications de configuration par le biais de vos processus de gestion des modifications et de révision de sécurité établis.
• Surveillez Azure journaux de connexion OpenAI et Foundry Tools, les événements d’authentification et les journaux d’accès pour une activité inattendue ou non autorisée.
• Supprimez les compétences inutilisées, les points de terminaison, les attributions de rôles et les clés API qui ne sont plus nécessaires.

Restreindre l’accès à la configuration de l’ensemble de compétences

Les utilisateurs qui peuvent créer, modifier ou exécuter des ensembles de compétences contrôlent à la fois le point de terminaison de destination (resourceUri) et la configuration d’authentification utilisée par la compétence. Étant donné que la compétence envoie un jeton d’identité managée pour l’audience Des outils Foundry à ce point de terminaison, limitez ces autorisations aux administrateurs approuvés et suivez vos processus standard de gestion des modifications et de révision de sécurité lors de la configuration des compétences avec l’identité managée.

Voir aussi

• Compétences intégrées
• Comment définir un ensemble de compétences
• Comment définir les correspondances des champs de sortie