「 コード インタープリターを使用して Python コードを生成して実行する」で説明されているように、コード インタープリターは、エージェントがデータ分析、Word、Excel、PowerPoint、PDF 処理、視覚化のために Python コードを実行する方法を提供します。 理解するには、その記事を参照してください。
- ライセンス要件とサポートされているリージョン
- 一般的なコード インタープリター機能
- プロンプトのコード インタープリターを有効にする方法
- プロンプトでコード インタープリター機能を使用する方法
この記事では、開発者が Dataverse Predict メッセージを使用して、コード インタープリターが有効なプロンプトにパラメーターを渡し、応答を処理する方法について説明します。
注
コード インタープリターが有効なプロンプトの一般的なシナリオは、Power Apps コンポーネント (PCF) コンポーネントを使用してモデル駆動型アプリケーションの UI エクスペリエンスを生成することです。 例については、 コード インタープリター PCF コンポーネントのサンプル を参照してください。
環境のコード インタープリターを有効にする
コード インタープリターを使用する前に、各環境でコード インタープリターを有効にする必要があります。 既定の設定は [オフ] です。 Power Platform 管理センターを使用してコード インタープリターを有効にする方法について説明します
開発者は、Power Platform Environment Management Settings API を使用して、 CopilotStudio_CodeInterpreter ブール型プロパティの読み取りまたは設定を行って、環境のコード インタープリターを有効にすることができます。
コード インタープリターが有効なプロンプト
Microsoft Copilot Studio または AI Builder を使用して作成されたすべてのプロンプトは、Dataverse AI Model (msdyn_AIModel) テーブルに新しいレコードを作成します。
Predict メッセージを呼び出すときは、行の ID が必要です。
msdyn_AIModelに新しい行を作成してプロンプトを作成することはできません。 プロンプトは、 AIModelPublish メッセージを使用して更新されて作成されます。 このパブリック メッセージは内部でのみ使用されます。 UI を使用して、コード インタープリターが有効なプロンプトを作成する必要があります。 また、各プロンプトがコード インタープリターに対して有効になっていることを確認する必要もあります。 プロンプトの有効化は、Power Apps と Copilot Studio のどちらでプロンプトを編集するかによって若干異なります。 次の手順を参照してください。
msdyn_AIModel列の値を使用してmsdyn_Name テーブルに対してクエリを実行し、コード インタープリターが有効なプロンプトを名前で識別できます。
msdyn_AIModelには、コード インタープリターが有効になっているプロンプトのみをフィルター処理するために使用できるプロパティはありません。
AI モデル のデータを取得する
次のようなクエリを使用して、モデルの名前をフィルターとして使用して msdyn_AIModel テーブルからデータを取得します。
/// <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.");
}
}
メッセージを予測する
Predict メッセージは、Dataverse SDK for .NET と Web API の両方で使用できます。
要求の送信
要求の送信方法に関係なく、 Predict メッセージには次の 3 つのパラメーターが必要です。
-
msdyn_AIModelレコードの ID。 この値の設定方法は、SDK for .NET と Web API のどちらを使用するかによって異なります。 - プロンプトが受け入れるように構成されているパラメーターを含むデータ。 これは、
requestv2という名前のパラメーターとして渡されます。requestv2パラメーターの詳細 -
versionパラメーター。 値は常に"2.0"。
requestv2 パラメーター
このパラメーターは、 開いている型として構成されます。 オープン型の一般的な使用方法の詳細
開いている型は、キーと値を含むディクショナリです。 値はディクショナリにすることもできます。そのため、オープン型パラメーターを使用して複雑な階層データを送信できます。
SDK for .NET では、 Entity クラス を使用し、値を使用して Attributes コレクションを設定します。 このシナリオの主な違いは、 Entity インスタンスに LogicalName が設定されていないため、特定の Dataverse テーブルを参照していない点です。
次のPredictActionExampleサンプル メソッドでは、「SDK for .NET でメッセージを使用する」の説明に従って、OrganizationRequest クラスを使用してPredict メッセージを使用します。 または、型指定された PredictRequest クラスと PredictResponse クラスのペアを生成することもできます。
SDK for .NET の早期バインド クラスを生成する方法について説明します
この例では、ID を使用してTarget レコードを参照する EntityReference でmsdyn_AIModel パラメーターを設定する方法も示します。
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);
}
応答の処理
PredictResponse 複合型には、Web API のPredict メッセージからの応答が含まれています。 SDK for .NET にも同様の応答プロパティがあります。 詳細については、前の Web API 応答の例を参照してください。
| プロパティ | タイプ | Description |
|---|---|---|
overrideHttpStatusCode |
String | 予測が完了しなかった場合、202 はポーリングが必要であることを示し、それ以外の場合は null を示します。 |
overrideLocation |
String |
overrideHttpStatusCodeが null でない場合を除き、null。 ポーリングの場所。 結果をポーリングするために GET 要求をこの場所に送信しました。 |
overrideRetryAfter |
String |
overrideHttpStatusCodeが null でない場合を除き、null。 ポーリングを試すタイミングに関する提案。 |
response |
String | このプロパティは、 responsev2 プロパティの導入により廃止され、常に null にする必要があります。 |
responsev2 |
エンティティ/expando | PredictResponse responsev2 プロパティを参照してください |
PredictResponse responsev2 プロパティ
responsev2 プロパティには、次の 2 つのプロパティがあります。
operationStatus: 操作が成功したかどうかを示す文字列値。 予期される値はSuccess。predictionOutput: 次のプロパティを持つディクショナリ。プロパティ タイプ Description text文字列 プライマリで生成されたコンテンツ。 コンテンツは、プロンプトによって返される値の種類によって異なります。 mimetype文字列 テキスト MIME の種類。 textMimeType文字列 MIME の種類の複製/確認 finishReason文字列 理由の検討が終わった理由。 通常、これは stopになります。code文字列 実行されたコードを記述する Python ソース コードまたはプレースホルダー。 signature文字列 Base64 でエンコードされたバージョン管理されたメタデータと整合性トークン logs文字列 Python コード実行ログ出力 (指定されている場合)。 codeThinkingオブジェクト 空、内部プレースホルダーオブジェクト。 filesオブジェクトの配列 file_name、content_type、およびbase64_contentプロパティを使用して生成されたファイル成果物。structuredOutputオブジェクト mimetypeプロパティとtextプロパティを持つメイン出力の正規形式。artifactsオブジェクト アーティファクト識別子をメタデータと base64 コンテンツにマップします。 このオブジェクトには出力に固有のプロパティが含まれます。これらのプロパティは、 artifactName、mimeType、およびbase64Content
トラブルシューティング
コード インタープリターが有効なプロンプトで Predict アクションを使用しているときに発生する可能性のあるエラーを次に示します。
Insufficient capacity (容量の不足)
残りの AI Builder 容量がない場合は、次の 403 ForbiddenEntitlementNotAvailable エラーが発生します。
{
"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}"
}
}
このエラーが発生した PCF コントロールには、次のメッセージが表示されます: アクセスが拒否されました。このモデルを使用する権限がありません。
このエラーの解決策は、より多くの AI Builder 容量を購入することです。 AI Builder クレジットの権利を取得する方法の詳細を確認する
最大同時実行呼び出しに達しました
環境またはテナントごとに同時に送信される要求が多すぎると、次の 500 Internal Server ErrorMaxConcurrentPlexCallsReachedException エラーが発生します。
{
"error": {
"code": "0x80048d0a",
"message": "{\"operationStatus\":\"Error\",\"error\":{\"type\":\"Error\",\"code\":\"Unknown\",\"message\":\"Unhandled exception: Microsoft.PowerAI.MiddleEarth.HttpService.CodeInterpreter.Exceptions.MaxConcurrentPlexCallsReachedException\"},\"predictionId\":null}"
}
}
このエラーが発生した PCF コントロールには、サーバー エラーというメッセージが表示されます 。後でもう一度やり直すか、管理者に問い合わせてください。
このエラーの解決策は、送信する要求の数を減らすることです。 しばらく待ってから、もう一度やり直してください。 待機する必要がある時間を推奨する RetryAfter 応答ヘッダーはありません。