Visualización de los resultados de seguimiento de las aplicaciones de IA mediante el SDK de OpenAI

Nota:

Este documento hace referencia al portal de Microsoft Foundry (clásico).

🔍 Consulte la documentación de Microsoft Foundry (nuevo) para obtener información sobre el nuevo portal.

Obtenga información sobre cómo ver los resultados de seguimiento que proporcionan visibilidad sobre la ejecución de aplicaciones de IA. Utilice trazas para diagnosticar llamadas a herramientas inexactas, indicaciones engañosas, cuellos de botella de latencia y puntuaciones de evaluación de baja calidad.

En este artículo aprenderá a:

Habilite el seguimiento de un proyecto.
Implemente el SDK de OpenAI.
Capturar contenido del mensaje (opcional).
Ver escalas de tiempo e intervalos de seguimiento.
Conecte el seguimiento con bucles de evaluación.

En este artículo se explica cómo ver los resultados de seguimiento de las aplicaciones de inteligencia artificial mediante el SDK de OpenAI con OpenTelemetry en Microsoft Foundry.

Prerequisites

Necesita lo siguiente para completar este tutorial:

Se ha creado un proyecto de fundición.
Una aplicación de IA que usa el SDK de OpenAI para realizar llamadas a modelos hospedados en Foundry.

Habilitación del seguimiento en el proyecto

Foundry almacena seguimientos en Azure Application Insights mediante OpenTelemetry. Los nuevos recursos no aprovisionan Application Insights automáticamente. Asocie (o cree) un recurso una vez para cada recurso de Foundry.

Los pasos siguientes muestran cómo configurar el recurso:

Vaya al portal de Foundry y navegue hasta su proyecto.
En la barra de navegación lateral, seleccione Seguimiento.
Si un recurso de Azure Application Insights no está asociado al recurso Foundry, asocie uno. Si ya tiene un recurso de Application Insights asociado, no verá la página de habilitación siguiente y puede omitir este paso.
1. Para reutilizar una instancia de Azure Application Insights existente, use el nombre del recurso de Application Insights desplegable para buscar el recurso y seleccione Conectar.
  
  Tip
  
  Para conectarse a un Azure Application Insights existente, necesita al menos acceso de colaborador al recurso Foundry (o Hub).
2. Para conectarse a un nuevo recurso de Azure Application Insights, seleccione la opción Crear nuevo.
  1. Use el Asistente para configuración para configurar el nombre del nuevo recurso.
  2. De forma predeterminada, el nuevo recurso se crea en el mismo grupo de recursos donde se creó el recurso Foundry. Use la opción Configuración avanzada para configurar un grupo de recursos o una suscripción diferente.
    
    Tip
    
    Para crear un nuevo recurso de Azure Application Insights, también necesita un rol de colaborador en el grupo de recursos seleccionado (o el predeterminado).
  3. Seleccione Crear para crear el recurso y conectarlo al recurso Foundry.
3. Una vez configurada la conexión, estará listo para usar el seguimiento en cualquier proyecto del recurso.
Tip

Asegúrese de que tiene asignado el rol Lector de Log Analytics en el recurso de Application Insights. Para más información sobre cómo asignar roles, consulte Asignación de roles de Azure mediante Azure Portal. Use grupos de Microsoft Entra para administrar más fácilmente el acceso a los usuarios.
Vaya a la página de aterrizaje del proyecto y copie el URI del punto de conexión del proyecto. Lo necesitará más adelante.

Important

El uso del punto de conexión de un proyecto requiere la configuración de Microsoft Entra ID en la aplicación. Si no tiene configurado Entra ID, use la cadena de conexión de Azure Application Insights, como se indica en el paso 3 del tutorial.

Visualización de los resultados del seguimiento en el portal de Foundry

Una vez configurado el seguimiento y la aplicación esté instrumentada, puede ver los resultados de seguimiento en el portal de Foundry:

Vaya al portal de Foundry y navegue hasta su proyecto.
En la barra de navegación lateral, seleccione Seguimiento.
Verá una lista de los resultados de seguimiento de sus aplicaciones instrumentadas. Cada traza muestra:
- Identificador de rastreo: identificador único para el rastreo
- Hora de inicio: cuándo comenzó el seguimiento
- Duración: cuánto tiempo tardó la operación
- Estado: Estado de éxito o de fallo
- Operaciones: número de intervalos en la traza
Seleccione cualquier seguimiento para ver los resultados detallados del seguimiento, entre los que se incluyen:
- Escala de tiempo de ejecución completa
- Datos de entrada y salida para cada operación
- Métricas de rendimiento y tiempo
- Detalles del error si se ha producido alguno
- Atributos y metadatos personalizados

Instrumentación del SDK de OpenAI

Al desarrollar con el SDK de OpenAI, puede instrumentar el código para que los seguimientos se envíen a Foundry. Siga estos pasos para instrumentar el código:

Instale los paquetes:

pip install azure-ai-projects azure-monitor-opentelemetry opentelemetry-instrumentation-openai-v2

(Opcional) Captura del contenido del mensaje:
- PowerShell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
- Bash: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Obtenga la cadena de conexión para el recurso de Application Insights vinculado (Proyecto > Seguimiento > Gestión de origen de datos > Cadena de conexión):

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
     credential=DefaultAzureCredential(),
     endpoint="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>",
)
connection_string = project_client.telemetry.get_application_insights_connection_string()

Configure Azure Monitor e instrumente el SDK de OpenAI:

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

configure_azure_monitor(connection_string=connection_string)
OpenAIInstrumentor().instrument()

Enviar una solicitud:

client = project_client.get_openai_client()
response = client.chat.completions.create(
     model="gpt-4o-mini", 
     messages=[{"role": "user", "content": "Write a short poem on open telemetry."}],
)
print(response.choices[0].message.content)

Vuelva al Seguimiento en el portal para ver los nuevos seguimientos.
Puede ser útil capturar secciones del código que combinan lógica de negocios con modelos al desarrollar aplicaciones complejas. OpenTelemetry usa el concepto de intervalos para capturar secciones que le interesan. Para empezar a generar sus propios intervalos, obtenga una instancia del objeto de seguimiento actual.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

A continuación, use decoradores en el método para capturar escenarios específicos en el código que le interesen. Estos decoradores generan intervalos automáticamente. En el ejemplo de código siguiente se instrumenta un método denominado assess_claims_with_context que recorre en iteración una lista de notificaciones y se comprueba si el contexto admite la notificación mediante un LLM. Todas las llamadas realizadas en este método se capturan dentro del mismo intervalo:

def build_prompt_with_context(claim: str, context: str) -> str:
    return [{'role': 'system', 'content': "I will ask you to assess whether a particular scientific claim, based on evidence provided. Output only the text 'True' if the claim is true, 'False' if the claim is false, or 'NEE' if there's not enough evidence."},
            {'role': 'user', 'content': f"""
                The evidence is the following: {context}

                Assess the following claim on the basis of the evidence. Output only the text 'True' if the claim is true, 'False' if the claim is false, or 'NEE' if there's not enough evidence. Do not output any other text.

                Claim:
                {claim}

                Assessment:
            """}]

@tracer.start_as_current_span("assess_claims_with_context")
def assess_claims_with_context(claims, contexts):
    responses = []
    for claim, context in zip(claims, contexts):
        response = client.chat.completions.create(
            model="gpt-4.1",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Los resultados de seguimiento tienen el siguiente aspecto:

También puede agregar información adicional al intervalo actual. OpenTelemetry usa el concepto de atributos para eso. Use el trace objeto para acceder a ellos e incluir información adicional. Vea cómo se ha modificado el assess_claims_with_context método para incluir un atributo:

@tracer.start_as_current_span("assess_claims_with_context")
def assess_claims_with_context(claims, contexts):
    responses = []
    current_span = trace.get_current_span()

    current_span.set_attribute("operation.claims_count", len(claims))

    for claim, context in zip(claims, contexts):
        response = client.chat.completions.create(
            model="gpt-4.1",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Seguimiento a la consola

Puede resultar útil realizar un seguimiento de la aplicación y enviar los seguimientos a la consola de ejecución local. Este enfoque puede ser beneficioso al ejecutar pruebas unitarias o pruebas de integración en la aplicación mediante una canalización automatizada de CI/CD. Los seguimientos se pueden enviar a la consola y capturarlos mediante la herramienta CI/CD para su análisis posterior.

Configure el seguimiento de la manera siguiente:

Instrumente el SDK de OpenAI como de costumbre:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Configure OpenTelemetry para enviar seguimientos a la consola:

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

span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

Use el SDK de OpenAI como de costumbre:

response = client.chat.completions.create(
    model="deepseek-v3-0324",
    messages=[
        {"role": "user", "content": "Write a short poem on open telemetry."},
    ],
)

{
    "name": "chat deepseek-v3-0324",
    "context": {
        "trace_id": "0xaaaa0a0abb1bcc2cdd3d",
        "span_id": "0xaaaa0a0abb1bcc2cdd3d",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-06-13T00:02:04.271337Z",
    "end_time": "2025-06-13T00:02:06.537220Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.operation.name": "chat",
        "gen_ai.system": "openai",
        "gen_ai.request.model": "deepseek-v3-0324",
        "server.address": "my-project.services.ai.azure.com",
        "gen_ai.response.model": "DeepSeek-V3-0324",
        "gen_ai.response.finish_reasons": [
            "stop"
        ],
        "gen_ai.response.id": "aaaa0a0abb1bcc2cdd3d",
        "gen_ai.usage.input_tokens": 14,
        "gen_ai.usage.output_tokens": 91
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.31.1",
            "service.name": "unknown_service"
        },
        "schema_url": ""
    }
}

Seguimiento local con AI Toolkit

AI Toolkit ofrece una manera sencilla de realizar un seguimiento local en VS Code. Usa un recopilador compatible con OTLP local, lo que lo convierte en perfecto para el desarrollo y la depuración sin necesidad de acceso a la nube.

El kit de herramientas admite el SDK de OpenAI y otros marcos de inteligencia artificial a través de OpenTelemetry. Puede ver trazas al instante en su entorno de desarrollo.

Para obtener instrucciones de configuración detalladas y ejemplos de código específicos del SDK, consulte Seguimiento en AI Toolkit.

Agentes de seguimiento mediante el SDK de Microsoft Foundry

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-18