你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何使用 Azure AI 推理 SDK 跟踪应用程序

项目
12/25/2024

重要

本文中标记了“（预览版）”的项目目前为公共预览版。此预览版未提供服务级别协议，不建议将其用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

在本文中，你将了解如何使用 Azure AI 推理 SDK 跟踪应用程序，你可以选择使用 Python、JavaScript 或 C#。 Azure AI 推理客户端库支持使用 OpenTelemetry 进行跟踪。

在应用中启用跟踪

先决条件

一个 Azure 订阅。
一个 Azure AI 项目，请参阅在 Azure AI Foundry 门户中创建项目。
通过 Azure AI Foundry 部署的支持 Azure AI 模型推理 API 的 AI 模型。
如果使用 Python，则需要安装 Python 3.8 或更高版本，包括 pip。
如果使用 JavaScript，则支持的环境是 Node.js 的 LTS 版本。

安装

使用包管理器（例如 pip）安装包 azure-ai-inference：

  pip install azure-ai-inference[opentelemetry]

安装 Azure Core OpenTelemetry 跟踪插件、OpenTelemetry 和 OTLP 导出程序，以便将遥测数据发送到可观测性后端。若要安装 Python 所需的包，请使用以下 pip 命令：

pip install opentelemetry 

pip install opentelemetry-exporter-otlp

要详细了解适用于 Python 的 Azure AI 推理 SDK 以及可观测性，请参阅通过适用于 Python 的推理 SDK 进行跟踪。

使用 npm 安装适用于 JavaScript 的包 @azure-rest/ai-inference：

    npm install @azure-rest/ai-inference

若要详细了解适用于 JavaScript 的 Azure AI 推理 SDK 和可观测性，请参阅通过适用于 JavaScript 的推理 SDK 进行跟踪。

使用 NuGet 安装适用于 .NET 的 Azure AI 推理客户端库：

    dotnet add package Azure.AI.Inference --prerelease

要详细了解适用于 C# 的 Azure AI 推理 SDK 以及可观测性，请参阅通过适用于 C# 的推理 SDK 进行跟踪。

若要了解详细信息，请参阅推理 SDK 参考。

配置

需要根据你的用例添加以下配置设置：

若要捕获提示和补全内容，请将 AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED 环境变量设置为 true（不区分大小写）。默认情况下，不会记录提示、补全内容、函数名称、参数或输出。
若要启用 Azure SDK 跟踪，请将 AZURE_SDK_TRACING_IMPLEMENTATION 环境变量设置为 opentelemetry。或者，可以使用以下代码片段在代码中对其进行配置：
```
from azure.core.settings import settings 

settings.tracing_implementation = "opentelemetry" 
```
若要了解详细信息，请参阅适用于 Python 的 Azure Core Tracing OpenTelemetry 客户端库。

仅支持对无流式处理的聊天补全进行检测。若要启用检测，需要注册导出程序。下面是有关如何添加控制台导出程序的示例。

控制台导出程序：

import { ConsoleSpanExporter, NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node"; 

const provider = new NodeTracerProvider(); 

provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); 

provider.register();

启用检测

最后一步是使用以下代码片段启用 Azure AI 推理检测：

from azure.ai.inference.tracing import AIInferenceInstrumentor 

# Instrument AI Inference API 

AIInferenceInstrumentor().instrument()

也可以通过使用解除检测调用对 Azure AI 推理 API 进行解除检测操作。此调用后，Azure AI 推理 API 将不再发出跟踪，直到再次调用检测：

AIInferenceInstrumentor().uninstrument()

若要对 Azure SDK 使用检测，你需要在从 @azure/core-tracing 导入任何依赖项（例如 @azure-rest/ai-inference）之前注册它。

import { registerInstrumentations } from "@opentelemetry/instrumentation"; 

import { createAzureSdkInstrumentation } from "@azure/opentelemetry-instrumentation-azure-sdk"; 


registerInstrumentations({ 

  instrumentations: [createAzureSdkInstrumentation()], 

}); 

import ModelClient from "@azure-rest/ai-inference";

进行聊天补全调用时，需要将 tracingOptions 包含在活动跟踪上下文中：


import { context } from "@opentelemetry/api"; 

client.path("/chat/completions").post({ 

      body: {...}, 

      tracingOptions: { tracingContext: context.active() } 

});

若要配置 OpenTelemetry 并启用 Azure AI 推理跟踪，请执行以下步骤：

安装 OpenTelemetry 包：安装以下依赖项以用于 HTTP 跟踪和指标检测以及控制台和 OTLP 导出程序：

   dotnet add package OpenTelemetry.Instrumentation.Http 

   dotnet add package OpenTelemetry.Exporter.Console 

   dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

启用试验性 Azure SDK 可观测性：设置上下文开关以启用试验性 Azure SDK 可观测性：
```
   AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true); 
```
启用内容录制：默认情况下，检测会捕获不包含内容的聊天消息。若要启用内容录制，请设置以下上下文开关：
```
 AppContext.SetSwitch("Azure.Experimental.TraceGenAIMessageContent", true);
```
配置跟踪提供程序：将跟踪提供程序配置为根据需要将跟踪和指标导出到控制台和本地 OTLP 目标。

跟踪自己的函数

若要跟踪自己的自定义函数，可以利用 OpenTelemetry，需要使用 OpenTelemetry SDK 检测代码。这涉及设置跟踪提供程序，并围绕要跟踪的代码创建跨度。每个跨度表示一个工作单元，可以嵌套以形成跟踪树。可以为跨度添加属性，从而通过额外的上下文来扩充跟踪数据。检测后，将导出程序配置为将跟踪数据发送到后端进行分析和可视化。有关详细说明和高级用法，请参阅 OpenTelemetry 文档。这有助于监视自定义函数的性能并深入了解其执行情况。

将用户反馈附加到跟踪

要将用户反馈附加到跟踪并使用 OpenTelemetry 的语义约定在 Azure AI Foundry 门户中将其可视化，可以对应用程序进行检测，以启用跟踪和记录用户反馈。通过使用响应 ID 将反馈跟踪与其相应的聊天请求跟踪相关联，可以在 Azure AI Foundry 门户中查看和管理这些跟踪。 OpenTelemetry 规范可实现标准化且丰富的跟踪数据，这些数据可以在 Azure AI Foundry 门户中进行分析，以优化性能并获取用户体验见解。这种方法可帮助你充分利用 OpenTelemetry 的强大功能，增强应用程序的可观测性。

Python 示例，包含完全可运行的 Python 代码，以便使用同步和异步客户端进行跟踪。
JavaScript 示例包含完全可运行的 JavaScript 代码，以便使用同步和异步客户端进行跟踪。
C# 示例，包含完全可运行的 C# 代码，以便使用同步和异步客户端进行推理。

通过