Codedolmetscher für Entwickler

Wie unter Verwenden des Code Interpreter zum Generieren und Ausführen von Python-Code beschrieben, bietet der Code Interpreter eine Möglichkeit für Agenten, Python-Code für Datenanalyse, die Verarbeitung von Word-, Excel-, PowerPoint- und PDF-Dateien sowie für Visualisierungen auszuführen. Lesen Sie diesen Artikel, um Folgendes zu verstehen:

  • Lizenzierungsanforderungen und unterstützte Regionen
  • Allgemeine Funktionen des Codedolmetschers
  • Aktivieren des Code-Interpreters für eine Eingabeaufforderung
  • Verwendung von Code-Interpreter-Funktionen mit einer Eingabeaufforderung

In diesem Artikel wird beschrieben, wie Entwickler die Dataverse-Nachricht Predict verwenden können, um Parameter an Codedolmetscher aktivierte Eingabeaufforderungen zu übergeben und die Antworten zu verarbeiten.

Hinweis

Ein häufiges Szenario für Code-Interpreter-aktivierte Eingabeaufforderungen besteht darin, Benutzeroberflächen für modellgesteuerte Anwendungen mithilfe von Power Apps Component Framework (PCF)-Komponenten zu generieren. Ein Beispiel finden Sie im Codedolmetscher-PCF-Komponentenbeispiel .

Aktivieren des Codedolmetschers für die Umgebung

Der Codedolmetscher muss für jede Umgebung aktiviert sein, bevor Sie ihn verwenden können. Die Standardeinstellung ist Aus. Erfahren Sie, wie Sie Code Interpreter über das Power Platform Admin Center aktivieren.

Entwickler können die Power Platform Environment Management Settings APIs verwenden, um die CopilotStudio_CodeInterpreter boolesche Eigenschaft zu lesen oder festzulegen, um Codedolmetscher für eine Umgebung zu aktivieren.

Vom Code-Interpreter aktivierte Eingabeaufforderungen

Jede Aufforderung, die Sie mithilfe von Microsoft Copilot Studio oder AI Builder erstellen, erstellt einen neuen Datensatz in der Dataverse AI Model (msdyn_AIModel)-Tabelle. Sie benötigen die ID der Zeile, wenn Sie die Predict Nachricht aufrufen.

Sie können keinen Prompt erstellen, indem Sie eine neue Zeile in der msdyn_AIModel Tabelle erstellen. Sie erstellen und aktualisieren Prompts mithilfe der AIModelPublish-Nachricht. Diese öffentliche Nachricht ist nur für die interne Verwendung vorgesehen. Sie müssen die Benutzeroberfläche verwenden, um Codedolmetscher-aktivierte Eingabeaufforderungen zu erstellen. Außerdem müssen Sie sicherstellen, dass jeder Prompt für den Code-Interpreter aktiviert ist. Der Prozess zum Aktivieren eines Prompts unterscheidet sich je nachdem, ob Sie den Prompt in Power Apps oder Copilot Studio bearbeiten. Lesen Sie die folgenden Anweisungen:

Sie können die msdyn_AIModel Tabelle abfragen, indem Sie den msdyn_Name Spaltenwert verwenden, um Eingabeaufforderungen mit aktiviertem Code Interpreter anhand des Namens zu identifizieren. Die msdyn_AIModel Tabelle verfügt nicht über eine Eigenschaft, mit der Sie nur die Prompts filtern können, für die der Code Interpreter aktiviert ist.

Abrufen von KI-Modelldaten

Verwenden Sie Abfragen wie die folgende, um Daten aus der msdyn_AIModel Tabelle abzurufen, indem Sie den Namen des Modells als Filter verwenden.

/// <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.");
    }
}

Informationen zum Abfragen von Daten mithilfe von QueryExpression

Nachricht vorhersehen

Die Predict Nachricht ist sowohl im Dataverse SDK für .NET als auch in der Web-API verfügbar.

Senden der Anforderung

Unabhängig davon, wie Sie die Anforderung senden, erfordert die Predict Nachricht drei Parameter:

  • Die ID des msdyn_AIModel-Datensatzes. Wie Sie diesen Wert festlegen, hängt davon ab, ob Sie das SDK für .NET oder Die Web-API verwenden.
  • Die Daten, die die Parameter enthalten, die von der Eingabeaufforderung akzeptiert werden sollen. Übergeben Sie diese Daten als Parameter mit dem Namen requestv2. Erfahren Sie mehr über den requestv2-Parameter.
  • Der version-Parameter. Der Wert ist immer "2.0".

requestv2 Parameter

Konfigurieren Sie diesen Parameter als offenen Typ. Erfahren Sie mehr darüber, wie Open Types im Allgemeinen verwendet werden.

Ein geöffneter Typ ist ein Wörterbuch, das Schlüssel und Werte enthält. Die Werte können auch Wörterbücher sein, sodass Sie komplexe, hierarchische Daten mithilfe eines offenen Typparameters senden können.

Verwenden Sie mithilfe des SDK für .NET die Entity-Klasse, und legen Sie die Attributes-Auflistung mit den Werten fest. Der Hauptunterschied in diesem Szenario besteht darin, dass die Entity Instanz keinen LogicalName-Satz hat, sodass sie nicht auf eine bestimmte Dataverse-Tabelle verweist.

Die folgende PredictActionExample Beispielmethode verwendet die OrganizationRequest-Klasse , um die Predict Nachricht zu verwenden, wie unter Verwenden von Nachrichten mit dem SDK für .NET beschrieben. Alternativ können Sie ein Paar von Typ PredictRequest und PredictResponse-Klassen generieren. Erfahren Sie, wie Sie früh gebundene Klassen für das SDK für .NET generieren.

In diesem Beispiel wird auch gezeigt, wie Sie den Target Parameter mithilfe einer EntityReference festlegen, die auf den msdyn_AIModel Datensatz mithilfe der ID verweist.

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);
}

Antwort der Predict-Nachricht verarbeiten

Der komplexe Typ "PredictResponse" enthält die Antwort von der Predict Nachricht in der Web-API. Das SDK für .NET verfügt über ähnliche Antworteigenschaften. Ausführliche Informationen finden Sie im vorherigen Web-API-Antwortbeispiel.

Eigentum Typ Description
overrideHttpStatusCode String Wenn die Vorhersage nicht abgeschlossen ist, zeigt 202 an, dass die Abfrage erforderlich ist. Andernfalls ist der Wert null.
overrideLocation String null außer wenn overrideHttpStatusCode nicht null ist. Der Ort für die regelmäßige Abfrage. Senden Sie eine GET Anfrage an diesen Speicherort, um das Ergebnis abzufragen.
overrideRetryAfter String null es sei denn, overrideHttpStatusCode ist nicht null. Vorschlag, wann das Polling versucht werden sollte.
response String Diese Eigenschaft ist seit der Einführung der responsev2 Eigenschaft veraltet und sollte immer null sein.
responsev2 Entität/expando Siehe PredictResponse responsev2-Eigenschaften

PredictResponse responsev2-Eigenschaften

Die responsev2 Eigenschaft besitzt zwei Attribute.

  • operationStatus: Ein Zeichenfolgenwert, der anzeigt, ob der Vorgang erfolgreich war. Erwarteter Wert ist Success.

  • predictionOutput: Ein Wörterbuch mit den folgenden Eigenschaften:

    Eigentum Typ Description
    text Schnur Primär generierter Inhalt. Der Inhalt hängt vom Typ des werts ab, der von der Eingabeaufforderung zurückgegeben wird.
    mimetype Schnur Text-MIME-Typ.
    textMimeType Schnur Mime-Typ duplizieren/bestätigen
    finishReason Schnur Der Grund, warum die Begründung beendet wurde. Dieser Wert ist in der Regel stop.
    code Schnur Python-Quellcode oder ein Platzhalter, der ausgeführten Code beschreibt.
    signature Schnur Ein Base64-codiertes, versionsbasiertes Metadaten- und Integritätstoken.
    logs Schnur Ausgabe des Python-Codeausführungsprotokolls (sofern angegeben).
    codeThinking Objekt Leeres/internes Platzhalterobjekt.
    files Array von Objekten Generierte Dateiartefakte mit file_name, content_typeund base64_content Eigenschaften.
    structuredOutput Objekt Kanonische Form des primären Ergebnisses mit mimetype und text Attributen.
    artifacts Objekt Zuordnung von Artefakt-IDs zu Metadaten und Base64-Inhalten. Dieses Objekt enthält spezifische Eigenschaften für die Ausgabe. Diese Eigenschaften sind Objekte mit den folgenden Eigenschaften: artifactName, mimeType und base64Content.

Problembehandlung

In den folgenden Abschnitten werden Fehler beschrieben, die auftreten können, wenn Sie die Predict Aktion mit aktiviertem Code Interpreter in Prompts verwenden.

Unzureichende Kapazität

Wenn Sie keine verbleibenden AI Builder Kapazität haben, erhalten Sie diesen 403 ForbiddenEntitlementNotAvailable Fehler:

{ 
   "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}" 
   } 
}

Ein PCF-Steuerelement, das auf diesen Fehler stößt, zeigt diese Meldung an: Zugriff verweigert. Sie sind nicht berechtigt, dieses Modell zu verwenden.

Um diesen Fehler zu beheben, kaufen Sie mehr AI Builder Kapazität. Erfahren Sie mehr darüber, wie Sie Anspruch auf AI Builder-Credits erhalten.

Maximale Anzahl gleichzeitiger Anrufe erreicht

Wenn Sie zu viele Anforderungen gleichzeitig pro Umgebung oder Mandant senden, wird dieser 500 Internal Server ErrorMaxConcurrentPlexCallsReachedException Fehler angezeigt:

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

Ein PCF-Steuerelement, das auf diesen Fehler stößt, zeigt diese Meldung an: Serverfehler. Versuchen Sie es später erneut, oder wenden Sie sich an den Administrator.

Um diesen Fehler zu beheben, senden Sie weniger Anfragen. Warten Sie eine kurze Zeit, und versuchen Sie es erneut. Es gibt keinen RetryAfter Antwortheader, um zu empfehlen, wie lange Sie warten sollten.

Mehr Informationen

Beispiel für Codedolmetscher-PCF-Komponenten