Dağıtılmış aracı ve model etkileşimlerini değerlendirin

Important

Bu makalede işaretlenen (önizleme) öğeler şu anda genel önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Orijinal istekleri yeniden oynatmadan, dağıtıma alınan aracılar ve modellerden elde edilen depolanmış yanıtları veya OpenTelemetry izlerini değerlendirin.

Prerequisites

• Bulut değerlendirme önkoşullarını ve istemci kurulumunu tamamlayın.
• Yanıt değerlendirmesi için depolanmış yanıt kimlikleri veya iz değerlendirmesi için Foundry projenize bağlı bir Application Insights kaynağı.
• İzleri değerlendirirken iz verisi gereksinimlerini karşılayan OpenTelemetry spans.

Örneklerde SDK istemcisini ayarlama bölümünde yapılandırılan SDK istemcisi kullanılır.

Etkileşimleri yanıt kimliğine göre değerlendirme

azure_ai_responses veri kaynağı türünü kullanarak yanıt kimliklerine göre Foundry aracısı yanıtlarını alın ve değerlendirin. Bu senaryoyu, belirli agent etkileşimlerini gerçekleştikten sonra değerlendirmek için kullanın.

Tip

Başlamadan önce istemci kurulumunu tamamlayın.

Yanıt kimliği, Bir Foundry aracısı her yanıt oluşturduğunda döndürülen benzersiz bir tanımlayıcıdır. Yanıtlar API'sini kullanarak veya uygulamanızın izleme günlüklerinden aracı etkileşimlerinden yanıt kimlikleri toplayabilirsiniz. ID'leri doğrudan dosya içeriğinde sağlayın.

Important

Aracı yanıtı değerlendirmeleri (azure_ai_responses), yanıt kimlikleri sağlamak için yalnızca file_content destekler. file_id Kaynak türü desteklenmez ve bir 400 Bad Request hata döndürür.

Yanıt kimliklerini topla

Yanıtlar API'sine yapılan her çağrı, benzersiz id bir alana sahip bir yanıt nesnesi döndürür. Uygulamanızın etkileşimlerinden bu kimlikleri toplayın veya doğrudan oluşturun:

# Generate response IDs by calling a model through the Responses API
response = openai_client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

Ayrıca, uygulamanızın izleme günlüklerindeki veya izleme işlem hattındaki aracı etkileşimlerinden yanıt kimlikleri de toplayabilirsiniz. Her yanıt kimliği, değerlendirme hizmetinin alabildiği depolanmış yanıtı benzersiz olarak tanımlar.

Değerlendirme oluşturma ve çalıştırma

Python

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"model": model_deployment_name},
    ),
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
    ),
]

eval_object = openai_client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

JavaScript/TypeScript

const evalObject = await openaiClient.evals.create({
    name: "Agent Response Evaluation",
    data_source_config: { type: "azure_ai_source", scenario: "responses" },
    testing_criteria: [
        {
            type: "azure_ai_evaluator",
            name: "coherence",
            evaluator_name: "builtin.coherence",
            initialization_parameters: { model: modelDeploymentName },
        },
        {
            type: "azure_ai_evaluator",
            name: "violence",
            evaluator_name: "builtin.violence",
        },
    ],
});

const responseEvalRun = await openaiClient.evals.runs.create(evalObject.id, {
    name: "agent-response-evaluation",
    data_source: {
        type: "azure_ai_responses",
        item_generation_params: {
            type: "response_retrieval",
            data_mapping: { response_id: "{{item.resp_id}}" },
            source: {
                type: "file_content",
                content: [
                    { item: { resp_id: "resp_abc123" } },
                    { item: { resp_id: "resp_def456" } },
                ],
            },
        },
    },
});
console.log(`Evaluation run created: ${responseEvalRun.id}`);

cURL

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-response-evaluation",
    "data_source": {
      "type": "azure_ai_responses",
      "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
          "type": "file_content",
          "content": [
            {"item": {"resp_id": "resp_abc123"}},
            {"item": {"resp_id": "resp_def456"}}
          ]
        }
      }
    }
  }'

Tam bir çalıştırılabilir örnek için bkz. GitHub üzerinde sample_agent_response_evaluation.py. Tamamlanma durumunu denetlemek ve sonuçları yorumlamak için bkz. Bulut değerlendirme sonuçlarını alma.

İzleri değerlendirme (önizleme)

Application Insights'ın zaten yakaladığı aracı etkileşimlerini değerlendirin. azure_ai_traces Veri kaynağı türünü kullanın. Bu senaryo, gerçek üretim trafiğinin dağıtım sonrası değerlendirmesi için kullanışlıdır. İzleme işlem hattınızdan izleri seçer ve herhangi bir isteği yeniden yürütmeden bunlar üzerinde değerlendiriciler çalıştırırsınız.

Important

Microsoft Foundry Agent Service ile oluşturulmayan aracıları (LangChain ve özel çerçeveler dahil) değerlendirmek için önerilen yaklaşım, iz değerlendirmesidir. Ajanınız, Application Insights’a GenAI semantik kurallarına uygun OpenTelemetry span’leri gönderdiği sürece, iz değerlendirmesi etkileşimlerini Foundry ajanları için kullanılabilen aynı değerlendiricileri kullanarak değerlendirebilir.

İzleme değerlendirmesi iki modu destekler:

• İzleme kimliklerine göre - Application Insights’taki operation_Id değerlerini sağlayarak belirli aracı etkileşimlerini değerlendirin.
• Aracı filtresine göre - İzleme kimliklerini el ile toplamadan belirli bir aracı için son izlemeleri otomatik olarak bulun ve değerlendirin.

Tip

Başlamadan önce istemci kurulumunu tamamlayın. Bu senaryo ayrıca , Foundry projenize bağlı bir Application Insights kaynağı gerektirir.

Akıllı örnekleme

İzleme değerlendirmesi, yakalanan her izlemenin değerlendirilmesi yerine değerlendirme için izlemelerin temsili bir alt kümesini seçen akıllı örneklemeyi destekler. İzleme değerlendirmesi çalıştırmasını yapılandırırken Foundry portalında Akıllı örnekleme geçişini açın. Akıllı örnekleme, izleme çeşitliliğini korurken değerlendirme maliyetini azaltır; uç servis taleplerinin, hata yollarının ve çeşitli konuşma desenlerinin değerlendirilen kümeye dahil edilmesini sağlar.

Akıllı örnekleme nasıl çalışır?

Örnekleme algoritması, birden çok aşamada çalışan MinHash en uzak-öncelikli çeşitlilik yaklaşımını kullanır:

1. Tam yinelenenlerin kaldırılması - Havuzdaki yinelenen izleri kaldırır.
2. Katı filtreler - Değerlendirme için uygun olmayan bozuk oturumları, kırpılmış izleri ve hatalı biçimlendirilmiş araç çağrılarını kaldırır.
3. Toplama - İzleme düzeyi sinyallerini birleşik bir gösterimde birleştirir.
4. MinHash en uzak ilk seçim - İzlemeler arasındaki benzerliği tahmin etmek için kullanıcı metninin yerelliğe duyarlı karmalarını (MinHash imzaları) hesaplar, ardından kalan havuzdan en benzer olmayan izlemeyi yinelemeli olarak seçer. Her bir sonraki seçim, daha önce seçilmiş tüm izlerden olan mesafeyi en üst düzeye çıkarır.

Bu yaklaşım rastgele örneklemeye kıyasla önemli ölçüde daha yüksek sözcük çeşitliliği ve daha geniş sözlük kapsamı üretir. Bu, değerlendirilen kümenin rastgele örneklemenin kaçırma eğiliminde olduğu nadir, zor ve yeni durumlar dahil olmak üzere tüm aracı etkileşimlerini daha iyi temsil ettiği anlamına gelir.

Akıllı örnekleme özellikle şu alanlarda etkilidir:

• Değerlendirme ve karşılaştırmalar - Değerlendirme puanlarının gerçek dünyadaki çeşitliliği yansıtması için giriş dağılımının kapsamını en üst düzeye çıkarır.
• Dereceli puanlama anahtarı oluşturma - Çeşitli konuşma kalıplarını ortaya çıkararak daha odaklı ve uygulanabilir dereceli puanlama anahtarları üretir.
• Veri kümesi kürasyonunda ince ayarlama - Modellerin daha verimli bir şekilde öğrenmelerine yardımcı olan izlemeleri seçer.

Algoritma, ek API çağrıları olmadan tamamen yerel işlem üzerinde çalışır, bu nedenle değerlendirmenin kendisi dışında ek model çıkarım maliyetlerine neden olmaz.

Akıllı örnekleme örneği

# Eval group for trace-based evaluations
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

print("Creating trace-based evaluation group")
eval_object = client.evals.create(
    name="Trace Evaluation (Agent Smart Filter)",
    data_source_config=data_source_config,  # type: ignore
    testing_criteria=testing_criteria,
)
print(f"Evaluation created (id: {eval_object.id})")

# Compute time window in unix seconds
# Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
now_unix = int(time.time())
end_time = now_unix + 600
start_time = now_unix - (args.lookback_hours * 3600)

# Build trace_source based on mode
trace_source: dict = {
    "type": "agent_filter",
    "start_time": start_time,
    "end_time": end_time,
    "max_traces": args.max_traces,
    "filter_strategy": "smart_filtering"
}

# Add agent name/version or agent id
trace_source["agent_name"] = agent_name
trace_source["agent_version"] = agent_version
## trace_source["agent_id"] = args.agent_id

data_source = {
    "type": "azure_ai_trace_data_source_preview",
    "trace_source": trace_source,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="trace-evaluation-agent-smart-filter-run",
    data_source=data_source,  # type: ignore
)

Veri gereksinimlerini izleme

İz değerlendirmesi, aracınızın üretken yapay zeka için OpenTelemetry semantik kurallarını izleyen span'ler üretmesini gerektirir. Değerlendirme hizmeti, özellikle Application Insights'tan izlekleri okurinvoke_agent ve özniteliklerinden konuşma verilerini ayıklar.

Aşağıdaki span öznitelikleri kullanılır:

Özellik	Zorunlu	Description
gen_ai.operation.name	Yes	"invoke_agent" eşit olmalıdır. Hizmet diğer tüm aralıkları görmezden gelir.
gen_ai.agent.id	Aracı filtre modu için	Benzersiz ajan tanımlayıcı (biçim: agent-name:version).
gen_ai.agent.name	Aracı filtre modu için	İnsan tarafından okunabilir ajan adı.
gen_ai.input.messages	Değerlendiriciler için sorgu girişleri	GenAI anlam kuralları ileti biçimini izleyen giriş iletilerinin JSON dizisi. Rolü user veya system olan iletiler, query ile eşlenir. Rolü assistant veya tool olan iletiler, response ile eşlenir.
gen_ai.output.messages	Değerlendiriciler için sorgu girişleri	Model tarafından oluşturulan çıkış iletilerinin JSON dizisi. Tüm çıkış iletileri response ile eşleştirilir. Çıkış ayrıca type: tool_result veya type: tool_call içeriyorsa, tool_calls ile eşlenir.
gen_ai.tool.definitions	İsteğe bağlı	Aracın kullanabileceği araç şemalarının JSON dizisi. Yoksa, hizmet araç çağrı iletilerinden araç tanımlarını çıkarsamaya çalışır, ancak çıkarsanan şemalar eksik olabilir.
gen_ai.conversation.id	İsteğe bağlı	Konuşma tanımlayıcısı, bağıntı için değerlendirme sonuçlarına geçirilir.

Note

gen_ai.input.messages ve gen_ai.output.messages boşsa veya eksikse, kalite değerlendiricileri (tutarlılık, akıcılık, ilgili olma, niyet çözümleme) score=None döndürür. Güvenlik değerlendiricileri (şiddet, kendine zarar verme, cinsel, nefret/adaletsizlik) kısmi verilerle puan üretebilir ancak anlamlı sonuçlar üretmeyebilir.

Azure AI Agent Server SDK ile geliştirilen Python aracılar için otomatik span yayını etkinleştirmek üzere [tracing] extrasını ekleyin.

pip install "azure-ai-agentserver-core[tracing]"

İzleme değerlendirmesi için önkoşullar

Genel önkoşullara ek olarak izleme değerlendirmesi şunları gerektirir:

• Foundry projenize bağlı bir Application Insights kaynağı . bkz. Microsoft Foundry'da izlemeyi ayarlama.
• Projenin yönetilen kimliği hem Application Insights kaynağında hem de bağlı Log Analytics çalışma alanında Log Analytics Reader rolüne sahip olmalıdır. İzlemelerinizi depolayan tablolar korunuyorsa (koruma düzeyleri Korumalı olarak ayarlanmışsa), hizmetin korumalı izleme tablolarını okuyabilmesi için aynı kapsamlarda Privileged Monitord Monitoring Data Reader rolünü de atayın.
• azure-monitor-query Python paketi (yalnızca izleme kimliklerini el ile topluyorsanız gereklidir).

pip install "azure-ai-projects>=2.2.0" azure-monitor-query

Şu ortam değişkenlerini ayarlayın:

• APPINSIGHTS_RESOURCE_ID — Application Insights kaynak kimliği (örneğin, /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
• AGENT_ID — İzleme tümleştirmesi (gen_ai.agent.id özniteliği) tarafından yayılan ajan tanımlayıcısı, izlemeleri filtrelemek için kullanılır. Biçim: agent-name:version.
• TRACE_LOOKBACK_HOURS — (İsteğe bağlı) İzlemeleri sorgularken geriye bakılması gereken saat sayısı. Varsayılan değer 1’dır.

Seçenek A: Temsilci filtresine göre değerlendirme

En basit yaklaşım, hizmetin belirli bir aracı için son izlemeleri otomatik olarak bulmasına ve değerlendirmesine izin vermektir. İzleme kimliklerini el ile toplamanız gerekmez.

import os

agent_id = os.environ["AGENT_ID"]  # e.g., "my-weather-agent:1"
trace_lookback_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by agent)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run — the service queries App Insights for matching traces
data_source = {
    "type": "azure_ai_traces",
    "agent_id": agent_id,
    "max_traces": 50,           # Maximum number of traces to evaluate
    "lookback_hours": trace_lookback_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Hizmet, invoke_agent etiketine göre gen_ai.agent.id aralıkları filtreler, max_traces benzersiz izleme kimliğine kadar örnekler ve bu izlemelerden gelen tüm aralıkları değerlendirir.

Seçenek B: İzleme kimliklerine göre değerlendirme

Daha fazla denetim için Application Insights'tan belirli izleme kimliklerini toplayın ve değerlendirin. Bu yöntem, uyarılar tarafından işaretlenen veya kalite incelemesi için örneklenen izlemeler gibi seçilmiş bir etkileşim kümesini değerlendirmek istediğinizde kullanışlıdır.

Application Insights'ten izleme kimliklerini toplayın

Aracınızın izlemelerindeki operation_Id değerleri için Application Insights'i sorgulayın. Her operation_Id biri, tam bir ajan etkileşimini temsil eder.

import os
from datetime import datetime, timedelta, timezone
from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, LogsQueryStatus

appinsights_resource_id = os.environ["APPINSIGHTS_RESOURCE_ID"]
agent_id = os.environ["AGENT_ID"]
trace_query_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=trace_query_hours)

query = f"""dependencies
| where timestamp between (datetime({start_time.isoformat()}) .. datetime({end_time.isoformat()}))
| extend agent_id = tostring(customDimensions["gen_ai.agent.id"])
| where agent_id == "{agent_id}"
| distinct operation_Id"""

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
response = logs_client.query_resource(
    appinsights_resource_id,
    query=query,
    timespan=None,  # Time range is specified in the query itself
)

trace_ids = []
if response.status == LogsQueryStatus.SUCCESS:
    for table in response.tables:
        for row in table.rows:
            trace_ids.append(row[0])

print(f"Found {len(trace_ids)} trace IDs")

İzleme kimlikleriyle değerlendirme oluştur ve çalıştır

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by trace IDs)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run using the collected trace IDs
data_source = {
    "type": "azure_ai_traces",
    "trace_ids": trace_ids,
    "lookback_hours": trace_query_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    metadata={
        "agent_id": agent_id,
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
    },
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Değerlendiricileri ve veri eşlemelerini ayarlama

İzlemeleri değerlendirdiğinizde, hizmet konuşma verilerini OpenTelemetry span özniteliklerinden otomatik olarak ayıklar. Bu alan adlarını doğrudan data_mapping içinde kullanın (diğer senaryolarda kullanılan item. veya sample. ön ekleri olmadan).

Değişken	Kaynak özniteliği	Description
{{item.query}}	gen_ai.input.messages (kullanıcı/sistem rolleri)	İz kaydından çıkarılan kullanıcı sorgusu.
{{item.response}}	gen_ai.input.messages (yardımcı/araç rolleri) + gen_ai.output.messages	Ajandanın yanıtı iz kaydından ayıklanır.
{{item.tool_definitions}}	gen_ai.tool.definitions	Ajan tarafından kullanılabilen araç şemaları. Yalnızca araçla ilgili değerlendiriciler için gereklidir.
{{item.tool_calls}}	Yardımcı mesajlardan ayıklanan gen_ai.input.messages / gen_ai.output.messages	Etkileşim sırasında aracı tarafından yapılan araç çağrıları. Araç değerlendiricileri tarafından kullanılır. Yalnızca araçla ilgili değerlendiriciler için gereklidir.

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    # Quality evaluators — require query and response from trace data
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="intent_resolution",
        evaluator_name="builtin.intent_resolution",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        initialization_parameters={"model": model_deployment_name},
    ),
    # Tool evaluators — assess tool usage quality
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="tool_call_accuracy",
        evaluator_name="builtin.tool_call_accuracy",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        initialization_parameters={"model": model_deployment_name},
    ),
    # Safety evaluators — work even with partial trace data
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        initialization_parameters={"threshold": 4},
    ),
]

Sonraki Adımlar

• Tamamlanma durumunu denetlemek ve sonuçları yorumlamak için bkz. Bulut değerlendirme sonuçlarını alma.
• Tam bir çalıştırılabilir örnek için bkz. GitHub üzerinde sample_evaluations_builtin_with_traces.py.