Microsoft Foundry ve Azure İzleyici ile LangChain ve LangGraph uygulamalarını izleme

LangChain ve LangGraph uygulamalarından OpenTelemetry izlemeleri yaymak ve bunları Azure Uygulaması Insights'a eklemek için langchain-azure-ai tümleştirme paketini kullanın. Bu makalede, AzureAIOpenTelemetryTracer yapılandırın, çalıştırılabilir programa iliştirin ve Azure İzleyici'deki izleri inceleyin.

İzleyici, ajan yürütme, model çağrıları, araç yürütme ve bilgi getirme işlemleri için spans oluşturur. Tamamen yerel, Foundry Aracısı Hizmeti'ni çağıran karma akışlar veya çok aracılı LangGraph çözümleri çalıştıran uygulamalar için kullanabilirsiniz.

Önkoşullar

  • Azure aboneliği. Ücretsiz bir tane oluşturun.
  • Dökümhane projesi.
  • Dağıtılmış Azure OpenAI sohbet modeli (örneğin, gpt-4.1).
  • Python 3.10 veya üzeri.
  • Azure CLI oturum açtı (az login) böylece DefaultAzureCredential kimlik doğrulaması yapabilir.

Ortamınızı yapılandırma

Gerekli paketleri yükleyin:

pip install -U "langchain-azure-ai[opentelemetry]" azure-identity

Bu makalede kullanılan ortam değişkenlerini ayarlayın:

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"
os.environ["APPLICATION_INSIGHTS_CONNECTION_STRING"] = "InstrumentationKey=0ab1c2d3..."

İletilerden ve araç çağrılarından gelen içeriğin iz sürümüne kaydedilip kaydedilmediğini denetlemek için enable_content_recording öğesini AzureAIOpenTelemetryTracer yapıcısına geçirin. İçerik kaydı varsayılan olarak etkindir.

Ipucu

oluşturucuda enable_content_recording=False izlerdeki ileti içeriğini ve araç çağrısı bağımsız değişkenlerini gizlemek için ayarlayın AzureAIOpenTelemetryTracer.

İzlemeyi oluşturma

Bir izleyici örneği oluşturun ve iş akışınızda yeniden kullanabilirsiniz.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

tracer = AzureAIOpenTelemetryTracer(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	name="langchain-tracing-sample",
	agent_id="support-bot",
	trace_all_langgraph_nodes=True,
)

Bu kod parçacığının yaptığı iş: Foundry proje uç noktanızdan ilişkili Application Insights bağlantı dizesini çözen ve LangGraph düğümleri için izlemeyi etkinleştiren bir izleyici yapılandırır. Aracıları çağırırken agent_id parametresini kullanarak gen_ai.agent.id özniteliğini ayarlayın. name parametresi OpenTelemetry izleyici adını ayarlar.

İzleme, üretim iş akışları için yaygın denetimleri destekler:

  • Belirli bir Application Insights kaynağını hedeflemek için connection_string geçir veya APPLICATION_INSIGHTS_CONNECTION_STRING ortam değişkenini yapılandır.
  • trace_all_langgraph_nodes=True varsayılan olarak tüm düğümleri izlemek için ayarlayın.
  • Belirli düğümleri dahil etmek veya atlamak için otel_trace: True veya otel_trace: False gibi düğüm meta verilerini kullanın.
  • İletileriniz özel bir durum şekli altında iç içe geçtiğinde message_keys ve message_paths kullanın, örneğin chat_history.

Referans:

Ajanı izleme

İzlemeyi hızla doğrulayabilmeniz için en düşük Düzeyde Bir LangChain aracısı ile başlayın. LangGraph için, derlenmiş grafta with_config ile izleyiciyi ekleyin.

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
).with_config(
    {"callbacks": [tracer]}
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()

================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

Bu kod parçacığının yaptığı iş: Basit bir LangGraph aracısı oluşturur, iz sürücüsünü ekler ve aracı bir iletiyle çağırır.

Referans:

LangChain işletilebilirini takip etme

İzlemeyi hızla doğrulayabilmeniz için minimal LangChain akışıyla başlayabilirsiniz.

import os

from azure.identity import DefaultAzureCredential
from langchain_core.prompts import ChatPromptTemplate
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
	endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
)

prompt = ChatPromptTemplate.from_template(
	"You are concise. Answer in one sentence: {question}"
)
chain = prompt | model

response = chain.invoke(
	{"question": "What does OpenTelemetry help me do?"},
	config={"callbacks": [tracer]},
)

print(response.content)

OpenTelemetry helps you observe requests, latency, dependencies, and failures across your AI workflow.

Bu kod parçacığının yaptığı iş: Standart bir LangChain işlem hattı çalıştırır ve aracılığıyla AzureAIOpenTelemetryTracerOpenTelemetry'ye sohbet aralıkları gönderir.

Referans:

LangGraph grafiğini izleme

LangGraph için, derlenmiş grafta with_config ile izleyiciyi ekleyin. Bu kod parçacığı, önceki örneklerden model ve tracer'i yeniden kullanır.

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver
from langchain_core.tools import tool
from langchain_azure_ai.utils.agents import pretty_print

@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!"

tool_node = ToolNode([play_song_on_apple, play_song_on_spotify])
model_with_tools = model.bind_tools([play_song_on_apple, play_song_on_spotify])

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_with_tools.invoke(messages)
    return {"messages": [response]}

memory = MemorySaver()
workflow = (
    StateGraph(MessagesState)
    .add_node("agent", call_model)
    .add_node("action", tool_node)
    .add_edge(START, "agent")
    .add_conditional_edges(
        "agent",
        should_continue,
        {
            "continue": "action",
            "end": END,
        },
    )
    .add_edge("action", "agent")
    .compile(checkpointer=memory)
)

Ardından grafiği her zamanki gibi çalıştırabilirsiniz:

from langchain_core.messages import HumanMessage

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

result = workflow.invoke({"messages": [message]}, config)
pretty_print(result)

================================ Human Message =================================

Can you play Taylor Swift's most popular song?
================================== Ai Message ==================================
Tool Calls:
  play_song_on_spotify (call_xxx)
 Call ID: call_xxx
  Args:
    song: Anti-Hero
================================= Tool Message =================================
Name: play_song_on_spotify

Successfully played Anti-Hero on Spotify!
================================== Ai Message ==================================

I played Taylor Swift's popular song "Anti-Hero" on Spotify.

Bu kod parçacığının işlevi: Basit bir LangGraph uygulaması oluşturur, düğümü takip için işaretler ve aynı izlemeye model/araç aralıklarını ekler.

Referans:

İzleme yapısını anlama

Tracer, OpenTelemetry GenAI semantik kurallarına uygun olarak spanler oluşturur. Her span türü belirli gen_ai.operation.name bir değer kullanır:

Span türü gen_ai.operation.name Açıklama
Ajan/zincir çağrısı invoke_agent Her LangGraph düğümü veya zincir adımı. Span adı şeklindedir invoke_agent {gen_ai.agent.name}.
Sohbet modeli çağrısı chat LLM tahmin istekleri. Span adı şeklindedir chat {gen_ai.request.model}.
Metin tamamlama text_completion Sohbet dışı LLM çağrıları.
Araç çalıştırma execute_tool Model tarafından tetiklenen araç çağrıları. Span adı şeklindedir execute_tool {gen_ai.tool.name}.
Arayıcı execute_tool Vektör depolarından veya aramadan alma işlemleri.

Span'lar şu temel öznitelikleri de taşır:

  • gen_ai.agent.name — Aracı veya düğüm adı.
  • gen_ai.agent.id — Oluşturucu parametresinden agent_id ayarlayın.
  • gen_ai.agent.description — Ajanın açıklaması.
  • gen_ai.provider.name — Model sağlayıcısı (örneğin, openai, azure.ai.inference).
  • gen_ai.request.model — Çıkarım için kullanılan model adı.
  • gen_ai.conversation.id — Kullanılabilir olduğunda iş parçacığı veya oturum tanımlayıcısı.
  • gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Model yanıtlarından belirteç sayısı.
  • gen_ai.input.messages / gen_ai.output.messages — İleti içeriği (içerik kaydı etkinleştirildiğinde).

İzleyici nasıl çözümlenebilir? gen_ai.agent.name

İzsürücü, aracı adını ilk boş olmayan değerden şu sırayla çözümleyerek belirler:

  1. agent_name düğüm meta verileri içinde.
  2. langgraph_node düğüm meta verilerinde (LangGraph tarafından otomatik olarak ayarlanır).
  3. agent_type düğüm meta verileri içinde.
  4. name LangChain geri çağırmasından anahtar sözcük bağımsız değişkeni.
  5. langgraph_path (son öğe) yukarıdakiler genel yer tutucular ise.
  6. Serileştirilmiş zincir kimliği veya sınıf adı.
  7. name oluşturucunun AzureAIOpenTelemetryTracer parametresi (geri dönüş varsayılanı).

İzleyici nasıl çözümlenebilir? gen_ai.agent.id

İzleme aracı kimliğini şu kaynaktan çözümler:

  1. agent_id düğüm meta verilerinde (düğüm başına geçersiz kılma).
  2. agent_id Oluşturucu parametresi (tüm yayılma alanları için varsayılan).

Düğüm meta verileriyle öznitelikleri özelleştirme

LangGraph meta verilerini kullanarak her düğüm için agent_name, agent_id ve agent_description ayarlayabilirsiniz. ile gen_ai. başlayan tüm meta veri anahtarları da span özniteliği olarak iletilir.

config = {
    "callbacks": [tracer],
    "metadata": {
        "agent_name": "support-bot",
        "agent_id": "support-bot-v2",
        "agent_description": "Handles customer support requests",
        "thread_id": "session-abc-123",
    },
}
result = graph.invoke({"messages": [message]}, config)

LangGraph kullanırken, grafik tanımında düğüm başına meta verileri de ayarlayabilirsiniz:

workflow = StateGraph(MessagesState)
workflow.add_node(
    "planner",
    planner_fn,
    metadata={
        "agent_name": "PlannerAgent",
        "agent_id": "planner-v1",
        "otel_agent_span": True,
    },
)

Referans:

Azure İzleyici'de izleri görüntüleme

İzlemeler Azure Uygulaması Insights'a gönderilir ve Azure İzleyici kullanılarak sorgulanabilir:

  1. Azure portalına gidin.

  2. Yapılandırdığınız Azure Uygulaması İçgörüleri'ne gidin.

  3. Sol gezinti çubuğunu kullanarak İncele>Aracılar (Önizleme)'yi seçin.

  4. Ajan, model ve araç yürütmelerini gösteren bir pano görürsünüz. Aracılarınızın genel etkinliğini anlamak için bu görünümü kullanın.

  5. Aracı Çalıştırmaları ile İzlemeleri Görüntüle'yi seçin. Yan panel, ajan çalıştırmalarından oluşturulan tüm izleri gösterir.

    Birden çok çalıştırmayı görüntüleyen Azure İzleyici Aracılar (Önizleme) bölümünü gösteren ekran görüntüsü.

  6. İzlemelerden birini seçin. Ayrıntıları görmeniz gerekir.

    Seçili çalıştırmanın izleme ayrıntılarını gösteren ekran görüntüsü.

DökümHane Denetim Düzlemi'nde izleri görüntüleme

LangGraph veya LangChain çözümünüzü dağıttıysanız, görünürlük ve idare elde etmek için bu dağıtımı DökümHane Denetim Düzlemi'ne kaydedebilirsiniz.

Foundry portalında izlemeleri görüntülemek için uygulamanızı Dökümhane Denetim Düzlemi'ne kaydedin.

Şu adımları izleyin:

  1. Foundry Kontrol Düzlemi özel ajan yeteneğini kullanmak için gereksinimleri karşıladığınızdan emin olun:

    • Foundry kaynağınızda yapılandırılmış bir yapay zeka ağ geçidi. Foundry, aracıları API'ler olarak kaydetmek için Azure API Management kullanır.

    • Erişilebilir bir uç nokta aracılığıyla dağıttığınız ve kullanıma eklediğiniz bir aracı. Uç nokta genel bir uç nokta veya Foundry kaynağını dağıttığınız ağdan erişilebilen bir uç nokta olabilir.

  2. Projede gözlemlenebilirliğin yapılandırıldığından emin olun.

  3. sınıfını AzureAIOpenTelemetryTraceryapılandırırken, aracının kaydedilmesini istediğiniz projenin uç noktasını kullandığınızdan emin olun. agent_id öğesini yapılandırdığınızdan emin olun.

  4. Foundry portalına gidin.

  5. Araç çubuğunda çalıştır'ı seçin.

  6. Genel Bakış bölmesinde Aracıyı Kaydet'i seçin.

  7. Kayıt sihirbazı görüntülenir. İlk olarak, kaydetmek istediğiniz aracıyla ilgili ayrıntıları tamamlayın.

    • Aracı URL'si: Aracınızın çalıştırıldığı ve istekleri aldığı uç nokta (URL).
    • Protokol: Aracınızın desteklediği iletişim protokolü.
    • OpenTelemetry Ajansı Kimliği: AzureAIOpenTelemetryTracer sınıfında yapılandırdığınız agent_id parametresi.
    • Project: AzureAIOpenTelemetryTracer sınıfında izlemeleri almak için yapılandırdığınız project.
    • Aracı adı: Aracının adı (agent_id ile aynı olabilir).

  8. Aracının çalıştığından emin olmak için onu çağırın.

  9. Araç çubuğunda çalıştır'ı seçin.

  10. Sol bölmede Varlıklar'ı seçin.

  11. Oluşturduğunuz aracıyı seçin.

  12. İzlemeler bölümünde, ajanın uç noktasındaki her HTTP çağrısı için bir giriş gösterilir.

    Ayrıntıları görmek için bir girdi seçin.

    Çalıştırmalar ve akışlar rotası altındaki ajanın uç noktasına yapılan çağrının ekran görüntüsü.

Sorun Giderme

  • Hiçbir iz görünmüyorsa, connection_string yapılandırılmış veya proje uç noktanızın telemetriyi ortaya koyduğunu doğrulayın.
  • İleti içeriği kapatılmış olarak görünüyorsa, enable_content_recording=True öğesini AzureAIOpenTelemetryTracer oluşturucuda ayarlayın.
  • Bazı LangGraph düğümleri eksikse düğüm meta verilerini trace_all_langgraph_nodes=Trueayarlayın otel_trace: True veya ekleyin.

LangChain ve LangGraph ile Döküm Belleği Kullanma

İlgili içerik

  • Last updated on