Compétence Prompt GenAI

La compétence GenAI (IA générative) Prompt exécute une requête chat completion contre un grand modèle de langage (LLM) déployé dans Azure OpenAI dans Foundry Models ou Microsoft Foundry. Utilisez cette compétence pour créer de nouvelles informations pouvant être indexées et stockées comme contenus consultables.

Voici quelques exemples de la façon dont la compétence de l’invite GenAI peut vous aider à créer du contenu :

• Décrire verbalement des images
• Résumez de grands textes
• Simplifier le contenu complexe
• Effectuez toute autre tâche que vous pouvez exprimer dans une consigne

La compétence GenAI Prompt est généralement disponible dans l’API REST du Service de recherche 2026-04-01 ainsi que dans SDK Azure qui ciblent cette version. Cette compétence prend en charge le texte, l’image et le contenu multimodal, tels que des images avec des visuels et du texte extrait de fichiers PDF.

Modèles pris en charge

• Vous pouvez utiliser n’importe quel modèle d’inférence de saisie semi-automatique de conversation déployé dans Foundry, comme les modèles GPT, DeepSeek-R#, Llama-4-Maverick et Cohere-command-r. Pour les modèles GPT spécifiquement, seuls les terminaux API de complétions de chat sont pris en charge. Les points de terminaison utilisant l'API Azure OpenAI Responses (contenant /openai/responses dans l'URI) ne sont pas actuellement compatibles.

• Pour la verbalisation d’image, le modèle utilisé pour analyser l’image détermine quels formats d’image sont pris en charge.

• Pour les modèles GPT-5, le paramètre n’est temperature pas pris en charge de la même manière que les modèles précédents. Si défini, il doit être fixé à 1.0, car d’autres valeurs entraîneront des erreurs.

• La facturation dépend du prix du modèle que vous utilisez.

Prerequisites

• Un Azure OpenAI dans Foundry Models ressource ou Foundry.

• Un modèle supporté déployé dans votre ressource ou projet.

  • Pour Azure OpenAI, copiez le point d’extrémité avec le domaine openai.azure.com depuis la page Keys et Endpoint du portail Azure. Utilisez ce point de terminaison pour le Uri paramètre de cette compétence.

  • Pour Foundry, copiez l’URI cible pour le déploiement depuis la page Modèles du portail Foundry. Utilisez ce point de terminaison pour le Uri paramètre de cette compétence.

• L’authentification peut être basée sur une clé avec une clé API provenant de votre ressource OpenAI Foundry ou Azure. Cependant, nous recommandons un accès basé sur le rôle en utilisant une identité gérée par service de recherche attribuée à un rôle.

  • Sur Azure OpenAI, assignez Cognitive Services OpenAI User à l’identité gérée.

  • Sur Foundry, affectez l’utilisateur Foundry à l’identité managée.

    Important

    Les rôles RBAC Foundry ont été récemment renommés. Foundry User, Foundry Owner, Propriétaire du compteFoundry et Foundry Project Manager ont été précédemment nommés Azure utilisateur IA, Azure propriétaire d’IA, propriétaire Azure compte IA et Azure gestionnaire Project IA. Vous pouvez toujours voir les noms précédents à certains endroits pendant le déploiement du renommage. Les ID de rôle et les autorisations de base sont inchangés par le renommage.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Limites des données

Paramètres de compétence

* Exactement une des apiKey, authIdentity, ou l’identité assignée au système du service doit être utilisée.

commonModelParameters Paramètres par défaut

Données de compétences

Résultats des compétences

Exemples de définitions.

Résumé en mode texte uniquement.

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "inputs": [
    { "name": "text", "source": "/document/content" },
    { "name": "systemMessage", "source": "='You are a concise AI assistant.'" },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

Description texte + image

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Image Describer",
  "context": "/document/normalized_images/*",
  "inputs": [
    { "name": "image", "source": "/document/normalized_images/*/data" },
    { "name": "imageDetail", "source": "=high" },
    { "name": "systemMessage", "source": "='You are a useful AI assistant.'" },
    { "name": "userMessage", "source": "='Describe this image:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "authIdentity": "11111111-2222-3333-4444-555555555555",
  "responseFormat": { "type": "text" }
}

Recherche de faits numérique structurée

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "NumericalFactFinder",
  "context": "/document",
  "inputs": [
    { "name": "systemMessage", "source": "='You are an AI assistant that helps people find information.'" },
    { "name": "userMessage", "source": "='Find all the numerical data and put it in the specified fact format.'"}, 
    { "name": "text", "source": "/document/content" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "responseFormat": {
    "type": "json_schema",
    "jsonSchemaProperties": {
      "name": "NumericalFactObj",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": "{\"facts\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"number\":{\"type\":\"number\"},\"fact\":{\"type\":\"string\"}},\"required\":[\"number\",\"fact\"]}}}",
        "required": [ "facts" ],
        "additionalProperties": false
      }
    }
  }
}

Sortie d’échantillon (tronquée)

{
  "response": {
    "facts": [
      { "number": 32.0, "fact": "Jordan scored 32 points per game in 1986-87." },
      { "number": 6.0,  "fact": "He won 6 NBA championships." }
    ]
  },
  "usageInformation": {
    "usage": {
      "completion_tokens": 203,
      "prompt_tokens": 248,
      "total_tokens": 451
    }
  }
}

Bonnes pratiques

• Faites des blocs longs avec la compétence Text Split pour rester dans la fenêtre contextuelle du modèle.
• Pour une indexation à haut volume, dédiez un déploiement de modèle séparé à cette compétence afin que les quotas de jetons pour les charges de travail RAG au moment de la requête restent intacts.
• Pour minimiser la latence, co-localisez le modèle et votre service Recherche Azure AI dans la même région Azure.
• Utilisez responseFormat.json_schema avec GPT-4o pour une extraction structurée fiable et un mappage plus facile vers les champs d’index.
• Surveillez l’utilisation des tokens et soumettez des demandes d’augmentation de quota si l’indexeur atteint vos limites de Tokens par Minute (TPM).

Erreurs et avertissements

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

Lorsque la compétence d’invite GenAI utilise l’authentification d’identité managée, Recherche Azure AI obtient un jeton d’accès Microsoft Entra pour l’audience foundry Tools (https://cognitiveservices.azure.com) et l’inclut dans les requêtes envoyées au point de terminaison spécifié par uri. 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 uri est censé être votre propre Azure ressource OpenAI ou Foundry. Les domaines pris en charge sont :

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

les points de terminaison Gestion des API Azure (*.azure-api.netAPIM) et les domaines personnalisés qui font face à ces ressources sont également pris en charge. Étant donné qu'un domaine personnalisé ou 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 et la ressource OpenAI ou Foundry Azure derrière elle.

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 uri 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 ou de domaine personnalisé, 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 :
  • Sur Azure OpenAI, affectez uniquement l’utilisateur OpenAI de Cognitive Services.
  • Sur Foundry, affectez uniquement Foundry User. É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 ou de domaine personnalisé, 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’ensembles de compétences, les attributions de rôles d’identité managée et les configurations APIM et de domaine personnalisé pour vérifier que uri les valeurs, les contrôles d’accès et les autorisations d’identité restent actuelles et appropriées. 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, Foundry Tools et Foundry, 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 (uri) 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

• Recherche Azure AI >
• Vectorisation intégrée
• Comment définir un ensemble de compétences
• Comment générer des complétions de chat avec Azure inférence de modèle IA (Foundry)
• Sorties structurées dans Azure OpenAI