Partager via

Interpréteur de code pour les développeurs

Comme décrit dans Utiliser l’interpréteur de code pour générer et exécuter du code Python, l’interpréteur de code permet aux agents d’exécuter du code Python pour l’analyse des données, Word, Excel, PowerPoint et le traitement PDF et les visualisations. Reportez-vous à cet article pour comprendre :

  • Exigences en matière de licences et régions prises en charge
  • Fonctionnalités générales de l’interpréteur de code
  • Comment activer l’interpréteur de code pour une invite
  • Comment utiliser les capacités de l’interpréteur de code avec une invite

Cet article explique comment les développeurs peuvent utiliser le message Dataverse Predict pour passer des paramètres à des invites compatibles avec l'interpréteur de code et traiter les réponses.

Note

Un scénario courant pour les invites activées par l’interpréteur de code consiste à générer des expériences d’interface utilisateur pour les applications basées sur des modèles à l’aide de composants PCF (Power Apps Component). Reportez-vous à l’exemple de composant PCF de l’interpréteur de code pour obtenir un exemple.

Activer l’interpréteur de code pour l’environnement

L’interpréteur de code doit être activé pour chaque environnement avant de pouvoir l’utiliser. La valeur par défaut est Désactivé. Découvrez comment activer l’interpréteur de code à l’aide du Centre d’administration Power Platform

Les développeurs peuvent utiliser les API des paramètres de gestion de l’environnement Power Platform pour lire ou définir la propriété booléenne pour activer l’interpréteur CopilotStudio_CodeInterpreter de code pour un environnement.

Invites de l'interpréteur de code activées

Chaque invite créée à l’aide de Microsoft Copilot Studio ou d’AI Builder crée un enregistrement dans la table Dataverse AI Model (msdyn_AIModel). Vous avez besoin de l’ID de la ligne lorsque vous appelez le message Predict.

Vous ne pouvez pas créer une invite de commande en ajoutant une nouvelle ligne dans le msdyn_AIModel. Les invites sont créées et mises à jour à l’aide du message AIModelPublish. Ce message public est destiné uniquement à une utilisation interne. Vous devez utiliser l’interface utilisateur pour créer des invites activées par l’interpréteur de code. Vous devez également vous assurer que chaque invite de commande est activée pour un interpréteur de code. L’activation d’une invite est légèrement différente selon que vous modifiez l’invite dans Power Apps ou Copilot Studio. Consultez ces instructions :

Vous pouvez interroger la table msdyn_AIModel à l’aide de la valeur de colonne msdyn_Name pour identifier les invites activées par l’interpréteur de code par nom. La msdyn_AIModel propriété ne peut pas être utilisée pour filtrer uniquement les invites activées par l’interpréteur de code.

Récupérer des données de modèle IA

Utilisez des requêtes comme celles-ci pour récupérer des données de la msdyn_AIModel table à l’aide du nom du modèle en tant que filtre.

/// <summary>
/// Retrieves AI models from Dataverse that match the specified model name pattern.
/// </summary>
/// <param name="service">The IOrganizationService instance used to connect to Dataverse</param>
/// <param name="modelName">The model name prefix to search for (uses BeginsWith matching)</param>
/// <remarks>
/// This method queries the msdyn_aimodel table using a BeginsWith condition, which means it will find
/// models whose names start with the specified modelName string. The search is case-insensitive.
/// If no matching models are found, a message is displayed to the console.
/// </remarks>
/// <example>
/// <code>
/// RetrieveAIModelsExample(service, "GPT");
/// // This will find all AI models whose names start with "GPT"
/// </code>
/// </example>
static void RetrieveAIModelsExample(IOrganizationService service, string modelName)
{
    var query = new QueryExpression("msdyn_aimodel")
    {
        ColumnSet = new ColumnSet("msdyn_name", "msdyn_aimodelid"),
        Criteria = new FilterExpression(LogicalOperator.And)
        {
            Conditions = {
                new ConditionExpression(
                    attributeName:"msdyn_name",
                    conditionOperator: ConditionOperator.BeginsWith,
                    value: modelName
                 )
            }
        }
    };

    var results = service.RetrieveMultiple(query);

    if (results.Entities.Any())
    {
        foreach (var entity in results.Entities)
        {
            Console.WriteLine($"Model Name: {entity["msdyn_name"]}, ID: {entity["msdyn_aimodelid"]}");
        }
    }
    else
    {
        Console.WriteLine($"No model with a name starting with '{modelName}' was found.");
    }
}

Découvrez comment interroger des données à l’aide de QueryExpression

Prédire le contenu du message

Le Predict message est disponible dans le Kit de développement logiciel (SDK) Dataverse pour .NET et l’API web.

Envoi de la requête

Quel que soit le mode d’envoi de la requête, le Predict message nécessite trois paramètres :

  • L'identifiant de l’enregistrement msdyn_AIModel. La façon dont vous définissez cette valeur dépend de l’utilisation du Kit de développement logiciel (SDK) pour .NET ou l’API web.
  • Les données contenant les paramètres que l'invite est configurée pour accepter. Il est passé en tant que paramètre nommé requestv2. En savoir plus sur le requestv2 paramètre
  • Le paramètre version. La valeur est toujours "2.0".

Paramètre requestv2

Ce paramètre est configuré en tant que type ouvert. En savoir plus sur l’utilisation des types ouverts en général

Un type ouvert est un dictionnaire qui contient des clés et des valeurs. Les valeurs peuvent également être des dictionnaires. Il est donc possible d’envoyer des données complexes et hiérarchiques à l’aide d’un paramètre de type ouvert.

Avec le Kit de développement logiciel (SDK) pour .NET, utilisez la classe Entity et définissez la collection Attributes avec les valeurs. La principale différence dans ce scénario est que l’instance Entity n’a pas de LogicalName défini, elle ne fait donc pas référence à une table Dataverse spécifique.

L’exemple de méthode suivant PredictActionExample utilise la classe OrganizationRequest pour utiliser le Predict message, comme décrit dans Utiliser des messages avec le Kit de développement logiciel (SDK) pour .NET. Vous pouvez également générer une paire de classes typées PredictRequest et PredictResponse. Découvrez comment générer des classes à liaison anticipée pour le Kit de développement logiciel (SDK) pour .NET

Cet exemple montre également comment définir le paramètre Target à l'aide d'une EntityReference qui se réfère à msdyn_AIModel l’enregistrement en utilisant l’ID.

static PredictActionExample (IOrganizationService service, Guid yourAiModelId)
{
 // Create the nested 'patient' entity
 var patientEntity = new Entity
 {
     Attributes =
     {
         { "firstname", "John" },
         { "lastname", "Smith" }
     }
 };
 
 // Create the main 'requestv2' entity
 var requestV2Entity = new Entity
 {
     Attributes =
     {
         { "pai_sex", 1 },
         { "pai_age", 10 },
         { "patient", patientEntity }
     }
 };
 
 // Create the Predict action request
 var predictRequest = new OrganizationRequest("Predict")
 {
     Parameters = new ParameterCollection
     {
         { "version", "2.0" },
         { "requestv2", requestV2Entity },
         { "Target", new EntityReference("msdyn_aimodel", new Guid(yourAiModelId)) }
     }
 };
 
 // Execute the request
 var response = service.Execute(predictRequest);
 
 Console.WriteLine("Prediction Result:");
 Console.WriteLine(response.Results);
}

Traitement de la réponse

Le type complexe PredictResponse contient la réponse du message dans l'API Web Predict. Le Kit de développement logiciel (SDK) pour .NET a des propriétés de réponse similaires. Pour plus d’informations, reportez-vous à l’exemple de réponse de l’API web précédente.

Propriété Type Descriptif
overrideHttpStatusCode Chaîne Si la prévision n’est pas terminée, 202 indique qu’une interrogation est nécessaire, sinon null.
overrideLocation Chaîne Null sauf si ce overrideHttpStatusCode n’est pas null. Emplacement de l’interrogation. Envoyez une requête GET à cet emplacement pour consulter le résultat.
overrideRetryAfter Chaîne Null sauf si ce overrideHttpStatusCode n’est pas null. Suggestion sur le moment où essayer d’interroger.
response Chaîne Cette propriété est obsolète depuis l’introduction de la responsev2 propriété et doit toujours être null.
responsev2 Entité/expando Voir les propriétés PredictResponse responsev2

Propriétés de PredictResponse responsev2

La responsev2 propriété a deux propriétés :

  • operationStatus: valeur de chaîne indiquant si l’opération a réussi. La valeur attendue est Success.

  • predictionOutput: dictionnaire avec les propriétés suivantes :

    Propriété Type Descriptif
    text ficelle Contenu généré principal. Le contenu dépend du type de valeur retourné par l’invite.
    mimetype ficelle Type MIME de texte.
    textMimeType ficelle Dupliquer/confirmer le type MIME
    finishReason ficelle La raison pour laquelle le raisonnement s’est terminé. Il s’agit généralement de stop.
    code ficelle Code source Python ou espace réservé décrivant le code exécuté.
    signature ficelle un jeton d’intégrité et de métadonnées codés en base64, avec version
    logs ficelle Sortie du log d’exécution de code Python (le cas échéant).
    codeThinking objet Objet d’espace réservé vide/interne.
    files choix d’objets Artefacts de fichier générés avec file_name, content_typeet base64_content propriétés.
    structuredOutput objet Forme canonique de sortie principale avec mimetype et text de propriétés.
    artifacts objet Carte des identificateurs d’artefacts vers les métadonnées et le contenu en base64. Cet objet contient des propriétés spécifiques à la sortie et ces propriétés sont des objets qui ont les propriétés suivantes : artifactName, mimeTypeet base64Content

Résolution des problèmes

Voici quelques erreurs que vous pouvez rencontrer lors de l’utilisation de l’action Predict avec les invites activées de l'interpréteur de code.

Capacité insuffisante

Lorsque vous n’avez pas de capacité AI Builder restante, vous obtenez cette 403 ForbiddenEntitlementNotAvailable erreur :

{ 
   "error": { 
       "code": "0x80048d06", 
       "message": "{\"operationStatus\":\"Error\",\"error\":{\"type\":\"Error\",\"code\":\"EntitlementNotAvailable\",\"innerErrors\":[{\"scope\":\"Generic\",\"target\":null,\"code\":\"NoCapacity\",\"type\":\"Error\",\"message\":\"No capacity was found.\"}]},\"predictionId\":null}" 
   } 
}

Un contrôle PCF qui rencontre cette erreur affiche ce message : Accès refusé. Vous n’êtes pas autorisé à utiliser ce modèle.

La résolution de cette erreur consiste à acheter plus de capacité AI Builder. En savoir plus sur la façon d’obtenir le droit aux crédits AI Builder

Nombre maximal d'appels simultanés atteints

Lorsque vous envoyez trop de requêtes simultanément par environnement ou locataire, vous obtenez cette 500 Internal Server ErrorMaxConcurrentPlexCallsReachedException erreur :

{ 
   "error": { 
       "code": "0x80048d0a", 
       "message": "{\"operationStatus\":\"Error\",\"error\":{\"type\":\"Error\",\"code\":\"Unknown\",\"message\":\"Unhandled exception: Microsoft.PowerAI.MiddleEarth.HttpService.CodeInterpreter.Exceptions.MaxConcurrentPlexCallsReachedException\"},\"predictionId\":null}" 
   } 
}

Un contrôle PCF qui rencontre cette erreur affiche ce message : Erreur serveur. Réessayez ultérieurement ou contactez l’administrateur.

La résolution de cette erreur consiste à envoyer moins de demandes. Patientez un peu et réessayez. Il n’existe aucun RetryAfter en-tête de réponse pour recommander la durée pendant laquelle vous devez attendre.

Plus d’informations

Exemple de composant PCF de l’interpréteur de code

  • Last updated on