Rastreie aplicativos de IA usando o OpenAI SDK

2025-06-16

O rastreamento fornece visibilidade profunda da execução de seu aplicativo, capturando telemetria detalhada em cada etapa de execução. Isso ajuda a diagnosticar problemas e melhorar o desempenho, identificando problemas como chamadas de ferramentas imprecisas, prompts enganosos, alta latência, pontuações de avaliação de baixa qualidade e muito mais.

Este artigo explica como implementar o rastreamento para aplicativos de IA usando o SDK do OpenAI com o OpenTelemetry no Azure AI Foundry.

Pré-requisitos

Você precisa do seguinte para concluir este tutorial:

Foi criado um projeto do Azure AI Foundry.
Um aplicativo de IA que usa o SDK do OpenAI para fazer chamadas para modelos hospedados no Azure AI Foundry.

Habilitar o rastreamento em seu projeto

O Azure AI Foundry armazena rastreamentos nos recursos do Azure Application Insight usando OpenTelemetry. Por padrão, os novos recursos do Azure AI Foundry não provisionam esses recursos. Você pode conectar projetos a um recurso existente do Azure Application Insights ou criar um novo de dentro do projeto. Você faz essa configuração uma vez por cada recurso do Azure AI Foundry.

As etapas a seguir mostram como configurar seu recurso:

Vá para o portal do Azure AI Foundry e navegue até o seu projeto.
Na barra de navegação lateral, selecione Rastreamento.
Se um recurso do Azure Application Insights não estiver associado ao seu recurso do Azure AI Foundry, associe um.
Para reutilizar um recurso do Azure Application Insights existente, use o menu suspenso nome do recurso Application Insights para localizar o recurso e selecione Conectar.

Sugestão

Para se conectar a um Azure Application Insights existente, você precisa de pelo menos acesso de colaborador ao recurso (ou Hub) do Azure AI Foundry.
Para se conectar a um novo recurso do Azure Application Insights, selecione a opção Criar novo.
1. Use o assistente de configuração para configurar o nome do novo recurso.
2. Por padrão, o novo recurso é criado no mesmo grupo de recursos em que o recurso Azure AI Foundry foi criado. Use a opção Configurações avançadas para configurar um grupo de recursos ou assinatura diferente.
  
  Sugestão
  
  Para criar um novo recurso do Azure Application Insight, você também precisa da função de colaborador para o grupo de recursos selecionado (ou o padrão).
3. Selecione Criar para criar o recurso e conectá-lo ao recurso Azure AI Foundry.
Depois que a conexão estiver configurada, você estará pronto para usar o rastreamento em qualquer projeto dentro do recurso.
Vá para a página de destino do seu projeto e copie o URI do ponto de extremidade do projeto. Você precisa dele mais tarde no tutorial.

Importante

Usar o ponto de extremidade de um projeto requer a configuração do Microsoft Entra ID em seu aplicativo. Se você não tiver a ID do Entra configurada, use a cadeia de conexão do Azure Application Insights, conforme indicado na etapa 3 do tutorial.

Configurar o SDK da OpenAI

Ao desenvolver com o SDK do OpenAI, você pode instrumentar seu código para que os rastreamentos sejam enviados para o Azure AI Foundry. Siga estas etapas para instrumentar seu código:

Instale azure-ai-projects, azure-monitor-opentelemetry e opentelemetry-instrumentation-openai-v2 no seu ambiente. O exemplo a seguir usa pip:
```
pip install azure-ai-projects azure-monitor-opentelemetry opentelemetry-instrumentation-openai-v2
```

Implemente o SDK do OpenAI usando OpenAIInstrumentor():

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Obtenha a cadeia de conexão para o recurso do Azure Application Insights associado ao seu projeto. A linha a seguir usa o cliente do Projeto Azure AI, que requer o uso da ID do Microsoft Entra para autenticação:
```
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_connection_string()
```
Sugestão

As cadeias de conexão do Azure Application Insights têm o seguinte formato: InstrumentationKey=aaaa0a0a-bb1b-cc2c-dd3d-eeeee4e4e4e;.... Você também pode acessar a cadeia de conexão usada em seu projeto na seção Rastreamento no portal do Azure AI Foundry. Na barra de navegação superior, selecione Gerenciar fonte de dados e copie a Cadeia de conexão. Configure sua cadeia de conexão em uma variável de ambiente.

Configure o OpenTelemetry para enviar rastreamentos para o Azure Application Insights:

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(connection_string=connection_string)

Por padrão, o OpenTelemetry não captura entradas e saídas. Use a variável OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true de ambiente para capturá-los. Verifique se essa variável de ambiente está configurada no nível de ambiente em que o código está sendo executado.

Use o SDK do OpenAI como de costume:

client = project_client.get_azure_openai_client()

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

Se você voltar ao portal do Azure AI Foundry, verá o rastreamento exibido:
Pode ser útil capturar seções do seu código que misturam lógica de negócios com modelos ao desenvolver aplicativos complexos. O OpenTelemetry usa o conceito de extensões para capturar seções nas quais você está interessado. Para começar a gerar os seus próprios spans, obtenha uma instância do objeto rastreador atual.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Em seguida, utilize decoradores no seu método para capturar cenários específicos no seu código nos quais está interessado. Tais decoradores geram intervalos automaticamente. O exemplo de código a seguir instrumenta um método chamado assess_claims_with_context com iterações sobre uma lista de declarações e verifica se a declaração é suportada pelo contexto usando um LLM. Todas as chamadas feitas neste método são capturadas dentro do mesmo período:

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.5-preview",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Os vestígios têm a seguinte aparência:

Você também pode adicionar informações extras ao intervalo atual. OpenTelemetry usa o conceito de atributos para isso. Use o trace objeto para acessá-los e incluir informações extras. Veja como o assess_claims_with_context método foi modificado para incluir um 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.5-preview",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Rastrear para o console

Pode ser útil também rastrear seu aplicativo e enviar os rastreamentos para o console de execução local. Essa abordagem pode resultar benéfica ao executar testes de unidade ou testes de integração em seu aplicativo usando um pipeline automatizado de CI/CD. Os vestígios podem ser enviados para o console e capturados pela sua ferramenta CI/CD para análise posterior.

Configure o rastreamento da seguinte maneira:

Instrua o SDK da OpenAI como de costume.

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Configurar OpenTelemetry para enviar traços para o console:

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 o OpenAI SDK como de costume:

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": ""
    }
}

Próximos passos

Agentes de rastreamento usando o SDK do Azure AI Foundry