跟踪 AI 应用程序（预览版）

跟踪行为可以捕获每个执行步骤的详细遥测数据，从而帮助深入了解应用程序的执行。 这有助于通过识别不准确的工具调用、误导性提示、高延迟、低质量评估分数等问题来诊断问题并提高性能。

本文介绍如何使用 OpenTelemetry 和 Azure Monitor 在 AI 应用程序中实现跟踪，从而增强可观测性和调试能力。

下面是入门前关键概念的简要概述：

设置

若要使用 Azure AI Foundry 聊天完成或生成代理，请安装：

pip install azure-ai-projects azure-identity

若要检测跟踪，需要安装以下检测库：

pip install azure-monitor-opentelemetry opentelemetry-sdk

若要查看 Azure AI Foundry 中的跟踪，需要将 Application Insights 资源连接到 Azure AI Foundry 项目。

1. 在 Azure AI Foundry 门户的左侧导航窗格中导航到“跟踪”。
2. 如果还没有 Application Insights 资源，请创建新的 Application Insights 资源。
3. 将资源连接到 AI Foundry 项目。

检测代码中的跟踪

若要跟踪聊天消息的内容，请将 AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED 环境变量设置为 true（不区分大小写）。 请记住，这可能包含个人数据。 若要了解详细信息，请参阅适用于 Python 的 Azure Core Tracing OpenTelemetry 客户端库。

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true" # False by default

让我们开始使用 OpenTelemetry 跟踪来检测代理，首先使用 AIProjectClient 进行身份验证并连接到 Azure AI 项目。

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    endpoint=os.environ["PROJECT_ENDPOINT"],
)

接下来，从连接到项目的 Application Insights 资源中检索连接字符串，并设置 OTLP 导出程序以将遥测数据发送到 Azure Monitor。

from azure.monitor.opentelemetry import configure_azure_monitor
connection_string = project_client.telemetry.get_connection_string()

if not connection_string:
    print("Application Insights is not enabled. Enable by going to Tracing in your Azure AI Foundry project.")
    exit()

configure_azure_monitor(connection_string=connection_string) #enable telemetry collection

现在，跟踪在 Azure AI 项目中创建和执行代理和用户消息的代码，以便查看故障排除或监视的详细步骤。

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.create_thread()
    message = project_client.agents.create_message(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.create_run(thread_id=thread.id, agent_id=agent.id)

运行代理后，可以开始 在 Azure AI Foundry 门户中查看跟踪。

本地日志跟踪

若要连接到 Aspire 仪表板 或其他与 OpenTelemetry 兼容的后端，请安装 OpenTelemetry 协议 （OTLP） 导出程序。 这样，便可以将跟踪打印到控制台或使用本地查看器（如 Aspire 仪表板）。

pip install azure-core-tracing-opentelemetry opentelemetry-exporter-otlp opentelemetry-sdk

接下来，需要为应用程序配置跟踪。

from azure.core.settings import settings
settings.tracing_implementation = "opentelemetry"

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

# Setup tracing to console
span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

使用 enable_telemetry 开始收集遥测数据。

from azure.ai.projects import enable_telemetry
enable_telemetry(destination=sys.stdout)

# Logging to an OTLP endpoint, change the destination to
# enable_telemetry(destination="http://localhost:4317")

# Start tracing
from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.create_thread()
    message = project_client.agents.create_message(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.create_run(thread_id=thread.id, agent_id=agent.id)

跟踪自定义函数

若要跟踪自定义函数，请使用 OpenTelemetry SDK 检测代码。

1. 设置跟踪提供程序：初始化跟踪提供程序以管理和创建范围。
2. 创建范围：用范围包装要跟踪的代码。 每个跨度表示一个工作单元，可以嵌套以形成跟踪树。
3. 添加属性：使用属性扩充范围，以便为跟踪数据提供更多上下文。
4. 配置导出程序：将跟踪数据发送到后端进行分析和可视化。

下面是跟踪自定义函数的示例：

from opentelemetry import trace
from opentelemetry.trace import SpanKind

# Initialize tracer
tracer = trace.get_tracer(__name__)

def custom_function():
    with tracer.start_as_current_span("custom_function") as span:
        span.set_attribute("custom_attribute", "value")
        # Your function logic here
        print("Executing custom function")

custom_function()

有关详细说明和高级用法，请参阅 OpenTelemetry 文档。

将用户反馈附加到跟踪记录

为了在 Azure AI Foundry 门户中将用户反馈附加到跟踪并进行可视化，您可以使用 OpenTelemetry 的语义约定为您的应用程序进行仪器化，以实现跟踪功能和记录用户反馈。

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

若要记录用户反馈，请遵循以下格式：

仅当用户向 GenAI 模型响应提供响应时，才能捕获用户反馈评估事件。 在可能的情况下，应该将其挂载到描述此类响应的 GenAI 跨度。

用户反馈事件正文具有以下结构：

在跟踪数据中使用服务名称

若要通过 Application Insights 中的唯一 ID 标识你的服务，可以在跟踪数据中使用服务名称 OpenTelemetry 属性。 如果要将数据从多个应用程序记录到同一 Application Insights 资源，并且想要区分它们，这非常有用。

例如，假设你有两个应用程序： App-1 和 App-2，其中跟踪配置为将数据记录到同一 Application Insights 资源。 也许你希望设置 App-1，以便按“相关性”进行持续评估，并设置 App-2，以便按“相关性”进行持续评估。 在 AI Foundry 门户中监视应用程序时，可以使用服务名称按 Application 进行筛选。

若要设置服务名称属性，可以按照步骤直接在应用程序代码中执行此操作，请参阅对不同资源使用多个跟踪提供程序。 或者，可以在部署应用之前设置环境变量 OTEL_SERVICE_NAME 。 若要详细了解如何使用服务名称，请参阅 OTEL 环境变量和服务资源语义约定。

若要查询给定服务名称的跟踪数据，请查询 cloud_roleName 属性。

| where cloud_RoleName == "service_name"

为 Langchain 启用跟踪

你可以根据 opentelemetry-instrumentation-langchain 为遵循 OpenTelemetry 标准的 Langchain 启用跟踪。 若要为 Langchain 启用跟踪，请使用包管理器安装包 opentelemetry-instrumentation-langchain ，例如 pip：

pip install opentelemetry-instrumentation-langchain

安装必要的程序包后，可以轻松开始检测代码中的跟踪。

在 Azure AI Foundry 门户中查看跟踪

在你的项目中，转到 Tracing 以根据需要筛选跟踪。

通过选择跟踪，您可以逐步查看每个跨度并在观察应用程序响应的过程中识别问题。 这有助于调试和查明应用程序中的问题。

在 Azure Monitor 中查看跟踪

如果使用前面的代码片段记录了跟踪，就可以在 Azure Monitor Application Insights 中查看跟踪了。 可以从“管理数据源”的 Application Insights 中打开，并使用“端到端事务详细信息视图”进一步查看。

有关如何将 Azure AI 推理跟踪发送到 Azure Monitor 并创建 Azure Monitor 资源的详细信息，请参阅 Azure Monitor OpenTelemetry 文档。

相关内容

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