Melihat hasil pelacakan untuk aplikasi AI menggunakan OpenAI SDK (klasik)

Nota

Dokumen ini mengacu pada portal Microsoft Foundry (klasik ).

🔍 Lihat dokumentasi Microsoft Foundry (baru) untuk mempelajari tentang portal baru.

Pelajari cara melihat hasil pelacakan yang memberikan visibilitas ke dalam eksekusi aplikasi AI. Gunakan jejak untuk mendiagnosis panggilan alat yang tidak akurat, perintah yang menyesatkan, penyempitan latensi, dan skor evaluasi berkualitas rendah.

Dalam artikel ini, Anda akan mempelajari cara:

Aktifkan pelacakan untuk proyek.
Instrumen OpenAI SDK.
Mengambil konten pesan (opsional).
Lihat garis waktu dan rentang pelacakan.
Sambungkan penelusuran dengan lingkaran evaluasi.

Artikel ini menjelaskan cara melihat hasil pelacakan untuk aplikasi AI menggunakan OpenAI SDK dengan OpenTelemetry di Microsoft Foundry.

Prasyarat

Anda memerlukan hal berikut untuk menyelesaikan tutorial ini:

Sebuah proyek Foundry dibuat.
Aplikasi AI yang menggunakan OpenAI SDK untuk melakukan panggilan ke model yang dihosting di Foundry.

Mengaktifkan pelacakan di proyek Anda

Foundry menyimpan jejak di Azure Application Insights menggunakan OpenTelemetry. Sumber daya baru tidak menyediakan Application Insights secara otomatis. Kaitkan (atau buat) sumber daya sekali per sumber daya Foundry.

Langkah-langkah berikut menunjukkan cara mengonfigurasi sumber daya Anda:

Buka Foundry portal dan buka proyek Anda.
Di bilah navigasi samping, pilih Pelacakan.
Jika sumber daya Azure Application Insights tidak terkait dengan sumber daya Foundry Anda, kaitkan sumber daya tersebut. Jika Anda sudah memiliki sumber daya Application Insights yang terkait, Anda tidak akan melihat halaman aktifkan di bawah ini dan Anda dapat melewati langkah ini.

cuplikan layar yang memperlihatkan cara mengonfigurasi Azure Application Insights ke sumber daya Foundry.
1. Untuk menggunakan kembali Azure Application Insights yang ada, gunakan nama sumber daya drop-down Application Insights untuk menemukan sumber daya dan pilih Connect.
  
  Petunjuk / Saran
  
  Untuk menyambungkan ke Azure Application Insights yang ada, Anda memerlukan setidaknya akses kontributor ke sumber daya Foundry (atau Hub).
2. Untuk menyambungkan ke sumber daya Azure Application Insights baru, pilih opsi Buat baru.
  1. Gunakan wizard konfigurasi untuk mengonfigurasi nama sumber daya baru.
  2. Secara default, sumber daya baru dibuat dalam grup sumber daya yang sama tempat sumber daya Foundry dibuat. Gunakan opsi Pengaturan lanjutan untuk mengonfigurasi grup sumber daya atau langganan yang berbeda.
    
    Petunjuk / Saran
    
    Untuk membuat sumber daya Azure Application Insights baru, Anda juga memerlukan peran kontributor ke grup sumber daya yang Anda pilih (atau yang default).
  3. Pilih Buat untuk membuat sumber daya dan menyambungkannya ke sumber daya Foundry.
3. Setelah koneksi dikonfigurasi, Anda siap untuk menggunakan pelacakan di project apa pun dalam sumber daya.
Petunjuk / Saran

Pastikan Anda memiliki peran Log Analytics Reader yang ditetapkan di sumber daya Application Insights Anda. Untuk mempelajari selengkapnya tentang cara menetapkan peran, lihat Assign Azure roles using the Azure portal. Gunakan grup Microsoft Entra untuk mengelola access pengguna dengan lebih mudah.
Buka halaman landing proyek Anda dan salin URI titik akhir proyek. Anda akan membutuhkannya nanti.

cuplikan layar yang menunjukkan cara menyalin URI titik akhir proyek.

Penting

Penggunaan titik akhir proyek memerlukan konfigurasi Microsoft Entra ID dalam aplikasi Anda. Jika Anda tidak memiliki ID Entra yang dikonfigurasi, gunakan Azure Application Insights connection string seperti yang ditunjukkan pada langkah 3 tutorial.

Menampilkan hasil pelacakan di portal Foundry

Setelah pelacakan dikonfigurasi dan aplikasi Anda diinstrumentasikan, Anda dapat melihat hasil pelacakan di portal Foundry:

Pergi ke Foundry portal dan buka proyek Anda.
Di bilah navigasi samping, pilih Pelacakan.
Anda akan melihat daftar hasil pelacakan dari aplikasi berinstrumentasi Anda. Setiap jejak menunjukkan:
- ID Pelacakan: Pengidentifikasi unik untuk pelacakan
- Waktu mulai: Ketika jejak dimulai
- Durasi: Berapa lama operasi berlangsung
- Status: Status keberhasilan atau kegagalan
- Operasi: Jumlah rentang dalam pelacakan
Pilih jejak apa pun untuk melihat hasil pelacakan terperinci termasuk:
- Garis waktu eksekusi lengkap
- Data input dan output untuk setiap operasi
- Metrik dan waktu performa
- Detail kesalahan jika terjadi
- Atribut dan metadata kustom

Menerapkan OpenAI SDK

Saat mengembangkan dengan OpenAI SDK, Anda dapat mengonfigurasi kode Anda sehingga jejak dapat dikirim ke Foundry. Ikuti langkah-langkah berikut untuk menginstrumentasi kode Anda:

Instal paket:

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

(Opsional) Mengambil konten pesan:
- Powershell: setx OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
- Bash: export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Dapatkan connection string untuk sumber daya Application Insights yang terhubung (Project > Tracing > Kelola sumber data > Connection string):

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()

Konfigurasikan Azure Monitor dan instrumen OpenAI SDK:

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

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

Kirim permintaan:

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)

Kembali ke Pelacakan di portal untuk melihat jejak baru.
Mungkin berguna untuk mengambil bagian kode Anda yang mencampur logika bisnis dengan model saat mengembangkan aplikasi yang kompleks. OpenTelemetry menggunakan konsep span untuk merekam bagian yang Anda minati. Untuk mulai menghasilkan span Anda sendiri, dapatkan instance objek pelacak saat ini.
```
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
```

Kemudian, gunakan dekorator dalam metode Anda untuk mengambil skenario tertentu dalam kode yang Anda minati. Dekorator ini menghasilkan rentang secara otomatis. Contoh kode berikut melengkapi metode yang disebut assess_claims_with_context yang mengulangi daftar klaim dan memverifikasi apakah klaim didukung oleh konteks menggunakan LLM. Semua panggilan yang dilakukan dalam metode ini diambil dalam rentang yang sama:

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

Hasil pelacakan terlihat sebagai berikut:

Anda mungkin juga ingin menambahkan informasi tambahan ke rentang saat ini. OpenTelemetry menggunakan konsep atribut untuk itu. Gunakan objek trace untuk access objek tersebut dan sertakan informasi tambahan. Lihat bagaimana assess_claims_with_context metode telah dimodifikasi untuk menyertakan atribut:

@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

Cetak ke konsol

Mungkin berguna untuk juga melacak aplikasi Anda dan mengirim jejak ke konsol eksekusi lokal. Pendekatan ini mungkin bermanfaat saat menjalankan pengujian unit atau pengujian integrasi di aplikasi Anda menggunakan alur CI/CD otomatis. Jejak dapat dikirim ke konsol dan diambil oleh alat CI/CD Anda untuk analisis lebih lanjut.

Konfigurasikan pelacakan sebagai berikut:

Gunakan OpenAI SDK seperti biasa:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

Konfigurasikan OpenTelemetry untuk mengirim jejak ke konsol:

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)

Gunakan OpenAI SDK seperti biasa:

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

Lacak secara lokal dengan Toolkit AI

AI Toolkit menawarkan cara sederhana untuk melacak alur secara lokal di VS Code. Ini menggunakan kolektor yang kompatibel dengan OTLP setempat, membuatnya sempurna untuk pengembangan dan debugging tanpa memerlukan akses cloud.

Toolkit mendukung OpenAI SDK dan kerangka kerja AI lainnya melalui OpenTelemetry. Anda dapat melihat jejak secara instan di lingkungan pengembangan Anda.

Untuk instruksi penyiapan terperinci dan contoh kode khusus SDK, lihat Melacak di AI Toolkit.

Melacak agen menggunakan Microsoft Foundry SDK

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-10