Rastrear aplicativos de IA usando o SDK do OpenAI

2025-06-17

O rastreamento fornece visibilidade profunda da execução do aplicativo capturando telemetria detalhada em cada etapa de execução. Isso ajuda a diagnosticar problemas e melhorar o desempenho identificando problemas como chamadas de ferramenta 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:

Um projeto do Azure AI Foundry foi criado.
Um aplicativo de IA que usa o SDK do OpenAI para fazer chamadas a 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 o OpenTelemetry. Por padrão, 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:

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

Dica

Para se conectar a um Azure Application Insights existente, você precisa de pelo menos acesso de colaborador ao recurso do Azure AI Foundry (ou Hub).
Para se conectar a um novo recurso do Azure Application Insights, selecione a opção Criar nova.
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 uma assinatura diferente.
  
  Dica
  
  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 do 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 inicial do projeto e copie o URI do endpoint do projeto. Você precisará dele mais tarde no tutorial.

Importante

Usar um endpoint de projeto requer configurar o 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.

Instrumentar o SDK do OpenAI

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

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

Instrumentar 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 de IA do Azure, 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()
```
Dica

As strings de conexão do Azure Application Insights são como 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á-las. Verifique se essa variável de ambiente está configurada no nível do ambiente em que o código está em execução.

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 da Fábrica de IA do Azure, deverá ver o rastreamento exibido:
Pode ser útil capturar seções do código que misturam lógica de negócios com modelos ao desenvolver aplicativos complexos. O OpenTelemetry usa o conceito de intervalos para capturar seções nas quais você está interessado. Para começar a gerar seus próprios intervalos, obtenha uma instância do objeto tracer atual.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Em seguida, use decoradores no seu método para capturar cenários específicos no seu código que lhe interessam. Esses decoradores geram spans automaticamente. O exemplo de código a seguir instrui um método chamado assess_claims_with_context que percorre uma lista de declarações e verifica se a declaração tem suporte no contexto usando um LLM. Todas as chamadas feitas neste método são capturadas no mesmo 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.5-preview",
            messages=build_prompt_with_context(claim=claim, context=context),
        )
        responses.append(response.choices[0].message.content.strip('., '))

    return responses

Os traços são os seguintes:

Talvez você também queira adicionar informações extras ao intervalo atual. O OpenTelemetry usa o conceito de atributos para isso. Use o objeto trace 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

Rastreamento para console

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

Configure o rastreamento da seguinte maneira:

Implemente o SDK do OpenAI como de costume.

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Configure o OpenTelemetry para enviar rastreamentos 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 SDK do OpenAI 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óximas etapas

Rastrear agentes usando o SDK do Azure AI Foundry