Azure AI 유추 SDK를 사용하여 애플리케이션을 추적하는 방법

Important

이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

이 문서에서는 Python, JavaScript 또는 C#을 사용하는 중에서 선택한 Azure AI 유추 SDK를 사용하여 애플리케이션을 추적하는 방법을 알아봅니다. Azure AI 유추 클라이언트 라이브러리는 OpenTelemetry를 사용하여 추적을 지원합니다.

애플리케이션에서 추적 사용

필수 구성 요소

• Azure 구독.
• Azure AI 프로젝트는 Azure AI Foundry 포털에서 프로젝트 만들기를 참조 하세요.
• AI Foundry를 통해 배포된 Azure AI 모델 유추 API 를 지원하는 AI 모델입니다.
• Python을 사용하는 경우 pip를 포함하여 Python 3.8 이상을 설치해야 합니다.
• JavaScript를 사용하는 경우 지원되는 환경은 Node.js LTS 버전입니다.

설치

Python

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를 통한 추적을 참조하세요.

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#

OpenTelemetry를 사용하는 분산 추적 및 메트릭은 실험적 모드에서 Azure AI 유추에서 지원되며 다음 단계 중 하나를 통해 사용하도록 설정할 수 있습니다.

• 환경 변수를 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() 

또한 제거 호출을 사용하여 Azure AI 추론 API를 제거할 수도 있습니다. 이 호출 후에는 계측이 다시 호출될 때까지 Azure AI 추론 API에서 추적을 더 이상 내보내지 않습니다.

AIInferenceInstrumentor().uninstrument() 

JavaScript

Azure SDK에 계측을 사용하려면 다음과 같은 @azure-rest/ai-inference종속성을 @azure/core-tracing가져오기 전에 등록해야 합니다.

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 패키지 설치: 콘솔 및 OTLP 내보내기뿐만 아니라 HTTP 추적 및 메트릭 계측에 대한 다음 종속성을 설치합니다.

      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의 의미 체계 규칙을 사용하여 AI Foundry 포털에서 추적에 사용자 피드백을 첨부하고 시각화하려면 사용자 피드백을 추적하고 로깅할 수 있도록 애플리케이션을 계측할 수 있습니다. 응답 ID를 사용하여 피드백 추적과 해당 채팅 요청 추적의 상관 관계를 지정하면 AI Foundry 포털에서 이러한 추적을 보고 관리할 수 있습니다. OpenTelemetry의 사양을 사용하면 AI Foundry 포털에서 성능 최적화 및 사용자 환경 인사이트를 분석할 수 있는 표준화되고 보강된 추적 데이터를 사용할 수 있습니다. 이 방법을 사용하면 애플리케이션에서 향상된 가시성을 위해 OpenTelemetry의 모든 기능을 사용할 수 있습니다.

관련 콘텐츠

• 동기 및 비동기 클라이언트를 사용하여 추적하기 위해 완전히 실행 가능한 Python 코드를 포함하는 Python 샘플 입니다.
• 동기 및 비동기 클라이언트를 사용하여 추적하기 위해 완전히 실행 가능한 JavaScript 코드를 포함하는 JavaScript 샘플 입니다.
• 동기 및 비동기 메서드를 사용하여 유추를 수행하기 위해 완전히 실행 가능한 C# 코드를 포함하는 C# 샘플 입니다.