面向开发人员的代码解释器

如使用代码解释器生成和执行 Python 代码中所述,代码解释器提供了一种方法,以供智能体执行用于数据分析、Word、Excel、PowerPoint 和 PDF 处理以及可视化的 Python 代码。 请参阅该文章以了解:

  • 许可证要求和受支持的地区
  • 常规代码解释器功能
  • 如何为提示启用代码解释器
  • 如何通过提示使用代码解释器功能

本文介绍了开发人员如何使用 Dataverse Predict 消息将参数传递给启用了代码解释器的提示并处理响应。

Note

已启用代码解释器的提示的常见应用场景是使用 Power Apps Component (PCF) 组件为模型驱动应用程序生成 UI 体验。 有关示例,请参阅 代码解释器 PCF 组件示例 。

为环境启用代码解释器

必须先为每个环境启用代码解释器,然后才能使用它。 默认设置为“关”。 了解如何使用 Power Platform 管理中心启用代码解释器。

开发人员可以使用 Power Platform 环境管理设置 API 读取或设置 CopilotStudio_CodeInterpreter 布尔属性,以为环境启用代码解释器。

已启用代码解释器的提示

使用 Microsoft Copilot Studio 或 AI Builder 创建的每个提示都会在 Dataverse AI 模型 (msdyn_AIModel) 表中创建一条新记录。 调用 Predict 消息时,需要行的 ID。

无法通过在 msdyn_AIModel 表中创建新行来创建提示。 使用 AIModelPublish 消息创建和更新提示。 此公开消息仅供内部使用。 必须使用 UI 创建启用代码解释器的提示。 还必须确保为代码解释器启用每个提示。 启用提示词的过程因是在 Power Apps 还是 Copilot Studio 中编辑提示词而异。 请参阅以下说明:

可以使用 msdyn_Name 列值查询 msdyn_AIModel 表,以按名称标识启用了代码解释器的提示。 该 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.");
    }
}

了解如何使用 QueryExpression 查询数据

预测消息

该Predict消息在 Dataverse SDK for .NET 和 Web API 中都可用。

发送请求

无论如何发送请求, Predict 消息都需要三个参数:

  • 记录的 msdyn_AIModel ID。 设置此值的方式取决于是将 SDK 用于.NET还是 Web API。
  • 包含提示配置为接受的参数的数据。 将此数据作为名为 requestv2 的参数传递。 详细了解 requestv2 参数。
  • version 参数。 该值始终为"2.0"。

requestv2 参数

将此参数配置为开放类型。 了解有关一般如何使用开放类型的详细信息。

开放类型是包含键和值的字典。 这些值也可以是字典,因此可以使用开放类型的参数发送复杂的分层数据。

通过使用 SDK for .NET,使用 Entity 类,并为 Attributes 集合设置这些值。 此方案中的主要区别在于,Entity 实例未设置 LogicalName,因此它不会引用特定的 Dataverse 表。

以下 PredictActionExample 示例方法使用 OrganizationRequest 类来使用 Predict 消息,如将消息与适用于 .NET 的 SDK 配合使用中所述。 或者,可以生成一对类型化的 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 响应示例。

Property 类型 Description
overrideHttpStatusCode String 如果预测未完成, 202 则表示需要轮询。 否则,值为 null。
overrideLocation String null,除非 overrideHttpStatusCode 不是 null。 投票地点。 GET向此位置发送请求以轮询结果。
overrideRetryAfter String null,除非 overrideHttpStatusCode 不是 null。 有关何时尝试轮询的建议。
response String 此属性自引入 responsev2 属性以来已过时,并且应始终为 null。
responsev2 Entity/expando 请参阅 PredictResponse responsev2 属性

PredictResponse responsev2 属性

该 responsev2 属性有两个属性:

  • operationStatus:一个字符串值,该值显示操作是否成功。 预期值为 Success.

  • predictionOutput:具有以下属性的字典

    Property 类型 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。

Troubleshooting

以下部分介绍使用启用了代码解释器的提示时配合 Predict 操作可能会遇到的错误。

容量不足

如果没有任何剩余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 响应标头来建议应等待多长时间。

更多信息

代码解释器 PCF 组件示例