如使用代码解释器生成和执行 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.");
}
}
预测消息
该Predict消息在 Dataverse SDK for .NET 和 Web API 中都可用。
发送请求
无论如何发送请求, Predict 消息都需要三个参数:
- 记录的
msdyn_AIModelID。 设置此值的方式取决于是将 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 响应标头来建议应等待多长时间。