如何使用 Azure AI 推斷 SDK 追蹤您的應用程式

重要

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。 此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。 可能不支援特定功能，或可能已經限制功能。 如需詳細資訊，請參閱 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，支持的環境是 LTS 版本的 Node.js。

安裝

Python

使用套件管理員安裝套件 azure-ai-inference，例如 pip：

  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 進行追蹤。

JavaScript

使用 npm 安裝 JavaScript 的套件 @azure-rest/ai-inference ：

    npm install @azure-rest/ai-inference

若要深入瞭解適用於 JavaScript 的 Azure AI 推斷 SDK 和可觀察性，請參閱 透過適用於 JavaScript 的推斷 SDK 進行追蹤。

C#

使用 NuGet 安裝適用於 .NET 的 Azure AI 推斷用戶端連結庫：

    dotnet add package Azure.AI.Inference --prerelease

若要深入瞭解適用於 C# 和可觀察性的 Azure AI 推斷 SDK，請參閱 透過適用於 C# 的推斷 SDK 進行追蹤。

若要深入瞭解，請參閱 推斷 SDK 參考。

組態

Python

您必須根據使用案例新增下列組態設定：

• 若要擷取提示和完成內容，請將 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 追蹤 OpenTelemetry 用戶端連結庫。

JavaScript

只有聊天完成才支持檢測，而不進行串流處理。 若要啟用檢測，您必須註冊匯出工具。。 以下是如何新增主控台匯出工具的範例。

主控台匯出工具：

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

const provider = new NodeTracerProvider(); 

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

provider.register(); 

C#

在實驗模式的 Azure AI 推斷中支援使用 OpenTelemetry 的分散式追蹤和計量，並可透過下列步驟之一來啟用：

• 將 AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE 環境變數設定為 true。
• 在應用程式程式代碼中，將 Azure.Experimental.EnableActivitySource 內容切換為 true。

啟用檢測

Python

最後一個步驟是使用下列代碼段啟用 Azure AI 推斷檢測：

from azure.ai.inference.tracing import AIInferenceInstrumentor 

# Instrument AI Inference API 

AIInferenceInstrumentor().instrument() 

您也可以使用 Uninstrument 呼叫來取消入侵 Azure AI 推斷 API。 在此呼叫之後，Azure AI 推斷 API 將不再發出追蹤，直到再次呼叫檢測為止：

AIInferenceInstrumentor().uninstrument() 

JavaScript

若要使用 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() } 

}); 

C#

若要設定 OpenTelemetry 並啟用 Azure AI 推斷追蹤，請遵循下列步驟：

1. 安裝 OpenTelemetry 套件：安裝下列 HTTP 追蹤和計量檢測的相依性，以及控制台和 OTLP 匯出工具：

      dotnet add package OpenTelemetry.Instrumentation.Http 
   
      dotnet add package OpenTelemetry.Exporter.Console 
   
      dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol 
   

2. 啟用實驗性 Azure SDK 可觀察性：設定內容切換以啟用實驗性 Azure SDK 可檢視性：

      AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true); 
   

3. 啟用內容錄製：根據預設，檢測會擷取沒有內容的聊天訊息。 若要啟用內容錄製，請設定下列內容切換：

    AppContext.SetSwitch("Azure.Experimental.TraceGenAIMessageContent", true);
   

4. 設定追蹤提供者：設定追蹤提供者，以視需要將追蹤和計量匯出至主控台和本機 OTLP 目的地。

追蹤您自己的函式

若要追蹤您自己的自定義函式，您可以利用 OpenTelemetry，您必須使用 OpenTelemetry SDK 來檢測程式代碼。 這牽涉到設定追蹤提供者，以及建立您想要追蹤的程式代碼範圍。 每個範圍都代表工作單位，而且可以巢狀形成追蹤樹狀結構。 您可以將屬性新增至範圍，以使用其他內容擴充追蹤數據。 檢測之後，請設定導出工具，將追蹤數據傳送至後端以進行分析和視覺效果。 如需詳細指示和進階使用方式，請參閱 OpenTelemetry 檔。 這可協助您監視自定義函式的效能，並深入瞭解其執行。

將使用者意見反應附加至追蹤

若要使用 OpenTelemetry 的語意慣例，將使用者意見反應附加至追蹤，並在 Azure AI Foundry 入口網站中將其可視化，您可以檢測您的應用程式，以啟用追蹤和記錄使用者意見反應。 藉由使用回應標識碼將意見反應追蹤與其各自的聊天要求追蹤相互關聯，您可以在 Azure AI Foundry 入口網站中使用檢視及管理這些追蹤。 OpenTelemetry 的規格允許標準化和擴充的追蹤數據，其可在 Azure AI Foundry 入口網站中進行分析，以取得效能優化和用戶體驗深入解析。 此方法可協助您使用 OpenTelemetry 的完整功能，以增強應用程式中的可檢視性。

相關內容

• 包含使用同步和異步客戶端進行追蹤的完整可執行 Python 程式代碼的 Python 範例 。
• JavaScript 範例 包含可完整執行的 JavaScript 程式代碼，以使用同步和異步客戶端進行追蹤。
• C# 範例 ，包含可完全執行的 C# 程式代碼，以使用同步和異步方法來進行推斷。