Yapay zeka aracısı çerçeveleri için izlemeyi yapılandırma (önizleme)

Önemli

Bu makalede işaretlenen (önizleme) öğeler şu anda genel önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Uygun Kullanım Koşulları.

Not

İzleme genelde sadece hızlı ajanlar için kullanılabilir. İş akışı, barındırılan ve özel aracılar önizleme aşamasındadır.

Yapay zeka aracıları üretimde beklenmedik şekilde davrandığında, izleme size kök nedeni hızla tanımlamak için görünürlük sağlar. İzleme; LLM çağrıları, araç çağrıları ve aracı karar akışları dahil olmak üzere ayrıntılı telemetriyi yakalar; böylece sorunlarda hata ayıklayabilir, gecikme süresini izleyebilir ve istekler arasında aracı davranışını anlayabilirsiniz.

Microsoft Foundry, en az kod değişikliği gerektiren popüler aracı çerçeveleri için izleme tümleştirmeleri sağlar. Bu makalede şunların nasıl yapılacağını öğreneceksiniz:

  • Microsoft Agent Framework için otomatik izlemeyi yapılandırma
  • LangChain ve LangGraph için langchain-azure-ai izleyiciyi ayarla
  • OpenTelemetry ile OpenAI Ajanları SDK'sını entegre etme
  • İzlemelerin Dökümhane portalında göründüğünü doğrulayın
  • Yaygın izleme sorunlarını giderme

Önkoşullar

  • Azure İzleyici Application Insights'e bağlı izlemeli bir Foundry projesi.
  • İzleme alımı amacıyla Application Insights kaynağında "Katkıda Bulunan" veya daha yüksek bir role sahip olunması.
  • İzlemeleri görüntülemek için bağlı Application Insights kaynağına erişim. Günlük tabanlı sorgular için ilişkili Log Analytics çalışma alanına da erişmeniz gerekebilir.
  • Python 3.10 veya üzeri (bu makaledeki tüm kod örnekleri için gereklidir).
  • Paket langchain-azure-ai sürümü 0.1.0 veya üzeri (LangChain ve LangGraph örnekleri için gereklidir).
  • LangChain veya LangGraph kullanıyorsanız pip yüklü bir Python ortamı.

Telemetriyi görüntüleyebildiğinizi onaylayın

İzleme verilerini görüntülemek için hesabınızın bağlı Application Insights kaynağına erişimi olduğundan emin olun.

  1. Azure portalında, Foundry projenize bağlı Application Insights kaynağını açın.

  2. Erişim denetimi (IAM) öğesini seçin.

  3. Kullanıcınıza veya grubunuz için uygun bir rol atayın.

    Günlük tabanlı sorgular kullanıyorsanız, Log Analytics Okuyucu rolü vererek başlayın.

Güvenlik ve gizlilik

İzleme hassas bilgileri (örneğin, kullanıcı girişleri, model çıkışları ve araç bağımsız değişkenleri ve sonuçları) yakalayabilir.

  • Tam istek ve yanıt verilerini görmek için geliştirme ve hata ayıklama sırasında içerik kaydını etkinleştirin. Hassas verileri korumak için üretim ortamlarında içerik kaydını devre dışı bırakın. Bu makaledeki örneklerde, içerik kaydı, enable_content_recording ve OTEL_RECORD_CONTENT gibi ayarlar tarafından denetlenir.
  • Gizli bilgileri, kimlik doğrulama bilgilerini veya belirteçleri istemlerde ya da araç argümanlarında depolamayın.

Daha fazla rehberlik için bkz . Güvenlik ve gizlilik.

Not

Application Insights'ta depolanan izleme verileri, çalışma alanınızın veri saklama ayarlarına ve Azure İzleyici fiyatlandırmasına tabidir. Maliyet yönetimi için, üretimde örnekleme oranlarını veya saklama sürelerini ayarlamayı göz önünde bulundurun. Bkz. Azure İzleyici pricing ve Veri saklama ve arşivi yapılandırma.

Microsoft Aracı Çerçevesi için izlemeyi yapılandırma

Microsoft Foundry, her iki Microsoft Agent Framework ile yerel tümleştirmelere sahiptir. Her iki çerçeveyle oluşturulan ajanlar, Foundry projeniz için izleme etkinleştirildiği zaman izleri otomatik olarak yayar; ek kod veya paket gerekmez.

İzlemenin çalıştığını doğrulamak için:

  1. Temsilcinizi en az bir kez çalıştırın.
  2. Dökümhane portalında Gözlemlenebilirlik>İzler sekmesine gidin.
  3. Aracınızın operasyonları için parçalar içeren yeni bir iz'in göründüğünü onaylayın.

İzlemeler genellikle ajanı yürütmeden sonraki 2 ila 5 dakika içerisinde görünür. Gelişmiş yapılandırma için çerçeveye özgü belgelere bakın:

LangChain ve LangGraph için izlemeyi yapılandırma

Not

LangChain ve LangGraph için izleme tümleştirmesi şu anda yalnızca Python'da kullanılabilir.

langchain-azure-ai paketini kullanarak LangChain ve LangGraph işlemleri için OpenTelemetry uyumlu izler oluşturun. Bu izlemeler, Dökümhane portalındaki Gözlemlenebilirlik>İzlemeleri görünümünde görünür.

Örnek: Azure yapay zeka izleme özelliğine sahip LangChain v1 aracısı

Bu uçtan uca örneği kullanarak langchain-azure-ai izleyicisini entegre etmek için bir LangChain v1 (önizleme) temsilcisini araçlandırın. Bu tracer (izleyici) en son OpenTelemetry (OTel) semantik kurallarını uyguladığından, Foundry gözlemlenebilirlik görünümünde zengin izlemeleri görüntüleyebilirsiniz.

LangChain v1: Paketleri yükleme

pip install \
  langchain-azure-ai \
  langchain \
  langgraph \
  langchain-openai \
  azure-identity \
  python-dotenv \
  rich

LangChain v1: Ortamı yapılandırma

  • APPLICATION_INSIGHTS_CONNECTION_STRING: İzleme için izleme bağlantı dizesi Azure İzleyici Application Insights.
  • AZURE_OPENAI_ENDPOINT: Azure OpenAI uç nokta URL'niz.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: Sohbet modeli dağıtım adı.
  • AZURE_OPENAI_VERSION: API sürümü, örneğin 2024-08-01-preview.
  • SDK, ortam değişkenlerini, yönetilen kimliği ve VS Code oturum açmayı destekleyen DefaultAzureCredential kullanarak Azure kimlik bilgilerini çözümler.

Bu değerleri yerel geliştirme için bir .env dosyada depolayın.

LangChain v1: İzleme kurulumu

from dotenv import load_dotenv
import os
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Weather information agent",
    id="weather_info_agent_771929",
)

tracers = [azure_tracer]

LangChain v1: Model kurulumu (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
)

LangChain v1: Araçları ve istemi tanımlama

from dataclasses import dataclass
from langchain_core.tools import tool

system_prompt = """You are an expert weather forecaster, who speaks in puns.

You have access to two tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location.
If you can tell from the question that they mean wherever they are,
use the get_user_location tool to find their location."""

# Mock user locations keyed by user id (string)
USER_LOCATION = {
    "1": "Florida",
    "2": "SF",
}

@dataclass
class UserContext:
    user_id: str

@tool
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

LangChain v1: Çalışma zamanı bağlamı kullanma ve kullanıcı bilgilendirme aracı tanımlama

from langgraph.runtime import get_runtime
from langchain_core.runnables import RunnableConfig

@tool
def get_user_info(config: RunnableConfig) -> str:
    """Retrieve user information based on user ID."""
    runtime = get_runtime(UserContext)
    user_id = runtime.context.user_id
    return USER_LOCATION[user_id]

LangChain v1: Aracıyı oluşturma

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from dataclasses import dataclass

@dataclass
class WeatherResponse:
    conditions: str
    punny_response: str

checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    prompt=system_prompt,
    tools=[get_user_info, get_weather],
    response_format=WeatherResponse,
    checkpointer=checkpointer,
)

LangChain v1: aracıyı izleme ile çalıştırın

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
    context = UserContext(user_id="1")

    r1 = agent.invoke(
        {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
        config=config,
        context=context,
    )
    print(r1.get("structured_response"))

    r2 = agent.invoke(
        {"messages": [{"role": "user", "content": "Thanks"}]},
        config=config,
        context=context,
    )
    print(r2.get("structured_response"))

if __name__ == "__main__":
    main()

Etkinleştirildiğinde langchain-azure-ai, tüm LangChain v1 işlemleri (LLM çağrıları, araç kullanımları, aracı adımları) en son anlamsal kuralları kullanarak OpenTelemetry spans yayar. Bu izlemeler, Foundry portalındaki Gözlemlenebilirlik>İzlemeleri görünümünde görünür ve Application Insights kaynağınıza bağlanır.

Ipucu

Ajanı çalıştıktan sonra izlerin görünmesi için birkaç dakika bekleyin. İzlemeleri görmüyorsanız Application Insights bağlantı dizesi doğru olduğundan emin olun ve Yaygın sorunları giderme bölümünü denetleyin.

LangChain v1 izlemelerinizi doğrulayın

Aracıyı çalıştırdıktan sonra:

  1. İzlemelerin yayılması için 2-5 dakika bekleyin.
  2. Dökümhane portalında Gözlemlenebilirlik>İzler sekmesine gidin.
  3. Belirttiğiniz ada sahip bir iz arayın (örneğin, "Hava durumu bilgileri aracısı").
  4. LLM çağrıları, araç kullanımları ve aracı adımları için kapsamları görebilmek amacıyla izlemeyi genişletin.

İzlemeleri görmüyorsanız Yaygın sorunları giderme bölümünü gözden geçirin.

Örnek: Azure yapay zeka izleme özelliğine sahip LangGraph aracısı

Bu örnek, grafik adımları, araç çağrıları ve model çağrıları için langchain-azure-ai ile izlenen basit bir LangGraph aracısını gösterir ve OpenTelemetry uyumlu izlemeleri yayar.

LangGraph: Paketleri yükleme

pip install \
  langchain-azure-ai \
  langgraph>=1.0.0 \
  langchain>=1.0.0 \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: Ortamı yapılandırma

  • APPLICATION_INSIGHTS_CONNECTION_STRING: İzleme için izleme bağlantı dizesi Azure İzleyici Application Insights.
  • AZURE_OPENAI_ENDPOINT: Azure OpenAI uç nokta URL'niz.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: Sohbet modeli dağıtım adı.
  • AZURE_OPENAI_VERSION: API sürümü, örneğin 2024-08-01-preview.

Bu değerleri yerel geliştirme için bir .env dosyada depolayın.

LangGraph izleme kurulumu

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=os.getenv("OTEL_RECORD_CONTENT", "true").lower() == "true",
    name="Music Player Agent",
)

LangGraph: Araçlar

from langchain_core.tools import tool

@tool
def play_song_on_spotify(song: str):
    """Play a song on Spotify"""
    # Integrate with Spotify API here.
    return f"Successfully played {song} on Spotify!"

@tool
def play_song_on_apple(song: str):
    """Play a song on Apple Music"""
    # Integrate with Apple Music API here.
    return f"Successfully played {song} on Apple Music!"

tools = [play_song_on_apple, play_song_on_spotify]

LangGraph: Model kurulumu (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
).bind_tools(tools, parallel_tool_calls=False)

LangGraph iş akışını oluşturma

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver

tool_node = ToolNode(tools)

def should_continue(state: MessagesState):
    messages = state["messages"]
    last_message = messages[-1]
    return "continue" if getattr(last_message, "tool_calls", None) else "end"

def call_model(state: MessagesState):
    messages = state["messages"]
    response = model.invoke(messages)
    return {"messages": [response]}

workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)

workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",
        "end": END,
    },
)
workflow.add_edge("action", "agent")

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

LangGraph: İzleme ile çalıştırma

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
input_message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
    event["messages"][-1].pretty_print()

langchain-azure-ai Etkin olduğunda, LangGraph yürütmeniz model çağrıları, araç çağrıları ve grafik geçişleri için OpenTelemetry uyumlu yayılma alanları gösterir. Bu izlemeler Application Insights'a akar ve Foundry portalındaki Gözlemlenebilirlik>İzlemeleri görünümünde görünür.

Ipucu

Her grafik düğümü ve kenar geçişi ayrı bir yayılma alanı oluşturarak aracının karar akışını görselleştirmeyi kolaylaştırır.

LangGraph izlemelerinizi doğrulama

Aracıyı çalıştırdıktan sonra:

  1. İzlemelerin yayılması için 2-5 dakika bekleyin.
  2. Dökümhane portalında Gözlemlenebilirlik>İzler sekmesine gidin.
  3. Belirttiğiniz isme sahip bir iz arayın (örneğin, "Music Player Aracısı").
  4. Graf düğümleri, araç çağrıları ve model çağrıları için aralıkları görmek amacıyla iz kaydını genişletin.

İzlemeleri görmüyorsanız Yaygın sorunları giderme bölümünü gözden geçirin.

Örnek: Azure yapay zeka izleme ile LangChain 0.3 kurulumu

Bu minimum kurulum, langchain-azure-ai izleyicisi ve AzureChatOpenAI kullanarak LangChain 0.3 uygulamasında Azure yapay zeka izlemeyi etkinleştirmeyi gösterir.

LangChain 0.3: Paketleri yükleme

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  langchain-azure-ai \
  python-dotenv

LangChain 0.3: Ortamı yapılandırma

  • APPLICATION_INSIGHTS_CONNECTION_STRING: İzleme için Application Insights bağlantı dizesi. Bu değeri bulmak için Azure portalında Application Insights kaynağınızı açın, Overview öğesini seçin ve Bağlantı Dizesi kopyalayın.
  • AZURE_OPENAI_ENDPOINT: Azure OpenAI uç noktası URL'si.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: Sohbet modeli dağıtım adı.
  • AZURE_OPENAI_VERSION: API sürümü, örneğin 2024-08-01-preview.
  • AZURE_OPENAI_API_KEY: Azure OpenAI API anahtarı.

Not

Bu örnekte kolaylık sağlamak için API anahtarı kimlik doğrulaması kullanılmaktadır. Üretim iş yükleri için, LangChain v1 ve LangGraph örneklerinde gösterildiği gibi, DefaultAzureCredential ile get_bearer_token_provider kullanın.

LangChain 0.3: İzleme ve model kurulumu

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Tracer: emits spans conforming to updated OTel spec
azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Trip Planner Orchestrator",
    id="trip_planner_orchestrator_v3",
)
tracers = [azure_tracer]

# Model: Azure OpenAI with callbacks for tracing
llm = AzureChatOpenAI(
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    temperature=0.2,
    callbacks=tracers,
)

LangChain 0.3 işlemlerinin izlendiğinden emin olmak için callbacks=[azure_tracer] 'yi zincirlerinize, araçlarınıza veya aracılarınıza ekleyin. Zincirinizi veya aracınızı çalıştırdıktan sonra, izler 2-5 dakika içinde Dökümhane portalındaki Gözlemlenebilirlik>İzler görünümünde görüntülenir.

OpenAI Aracıları SDK'sı için izlemeyi yapılandırma

OpenAI Aracıları SDK'sı OpenTelemetry enstrümantasyonunu destekler. İzleme ve dışarı aktarma aralıklarını Azure İzleyici yapılandırmak için aşağıdaki kod parçacığını kullanın. Eğer APPLICATION_INSIGHTS_CONNECTION_STRING ayarlanmadıysa, dışa aktarıcı yerel hata ayıklama için otomatik olarak konsola geçer.

Örneği çalıştırmadan önce gerekli paketleri yükleyin:

pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter

import os
from opentelemetry import trace
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

# Configure tracer provider + exporter
resource = Resource.create({
    "service.name": os.getenv("OTEL_SERVICE_NAME", "openai-agents-app"),
})
provider = TracerProvider(resource=resource)

conn = os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING")
if conn:
    from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
    provider.add_span_processor(
        BatchSpanProcessor(AzureMonitorTraceExporter.from_connection_string(conn))
    )
else:
    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

trace.set_tracer_provider(provider)

# Instrument the OpenAI Agents SDK
OpenAIAgentsInstrumentor().instrument(tracer_provider=trace.get_tracer_provider())

# Example: create a session span around your agent run
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_session[openai.agents]"):
    # ... run your agent here
    pass

Foundry Portalı'nda izleri doğrulayın

  1. Microsoft Foundry oturum açın. Yeni Dökümhane anahtarının açık olduğundan emin olun. Bu adımlar Foundry (yeni)'ye atıfta bulunur.
  2. Projeniz için izlemenin bağlı olduğunu kontrol edin. Gerekirse, Microsoft Foundry içinde izlemeyi ayarlamayı takip edin.
  3. Temsilcinizi en az bir kez çalıştırın.
  4. Dökümhane portalında Gözlemlenebilirlik>İzler sekmesine gidin.
  5. Aracınızın operasyonları için parçalar içeren yeni bir iz'in göründüğünü onaylayın.

İzlemeler genellikle ajanı yürütmeden sonraki 2 ila 5 dakika içerisinde görünür. İzlemeler bu süreden sonra hala görünmüyorsa bkz. Yaygın sorunları giderme.

Yaygın sorunları giderme

Sorunu Neden Çözünürlük
Foundry'de izleri görmüyorsunuz İzleme bağlantısı kurulmadı, son zamanlarda trafik yok veya veri alma gecikiyor Application Insights bağlantısını onaylayın, yeni trafik oluşturun ve 2-5 dakika sonra yenileyin.
LangChain veya LangGraph spans'ı görmüyorsunuz İzleme geri çağırmaları çalışmaya eklenmemiş İzlemek istediğiniz çalıştırma için callbacks (örneğin, config = {"callbacks": [azure_tracer]}) içine izleyiciyi yerleştirdiğinizden emin olun.
LangChain aralıkları görünüyor ancak araç çağrıları eksik. Araçlar modele bağlı değil veya araç düğümü yapılandırılmadı Modelde araçların bind_tools() üzerinde kullanıldığını ve araç düğümlerinin grafiğinize eklendiğini doğrulayın.
İzler görünür, ancak eksiktir veya bazı aralıklar kayıptır. İçerik kaydı devre dışı bırakıldı veya bazı işlemler enstrümanlanmadı Tam telemetri için etkinleştirin enable_content_recording=True . Özel işlemler için OpenTelemetry SDK'sını kullanarak manuel spanlar ekleyin.
Telemetriyi sorguladığınızda yetkilendirme hataları görürsünüz RBAC izinlerinin Application Insights veya Log Analytics üzerinde eksik olması Bağlı kaynaklar için Erişim denetiminde (IAM) erişimi onaylayın. Günlük sorguları için Log Analytics Okuyucu rolünü atayın.
İzlerde hassas içerik görünür İçerik kaydı etkinleştirildiğinde istemler, araç parametreleri veya çıkışlar hassas verileri içerebilir. Üretimde içerik kaydını devre dışı bırakın ve hassas verileri telemetriye girmeden önce yeniden işlemden geçirin.

Sonraki adımlar

  • Last updated on