Veri aracınızı değerlendirme (önizleme)

Fabric SDK'yı değerlendirme için kullanarak, veri ajanınızın doğal dil sorularına ne kadar iyi yanıt verdiğini programlı olarak test edebilirsiniz. Basit bir Python arayüzü kullanarak, temel gerçek örnekleri tanımlayabilir, değerlendirmeler yapabilir ve sonuçları analiz edebilirsiniz—tüm bunlar not defteriniz ortamında. Bu süreç, ajanınızı üretime göndermeden önce doğruluğu doğrulamanıza, hataları ayıklamanıza ve ajanınızı güvenle geliştirmenize yardımcı olur.

Önemli

Bu özellik önizleme aşamasındadır.

Önkoşullar

• F2 veya üstü ücretli bir Fabric kapasitesi veya Microsoft Fabric etkin kapasiteye sahip bir Power BI Premium kapasitesi (P1 veya üzeri).
• Fabric veri aracısı kiracı ayarlarında açıklanan gereksinimlere göre yapay zeka için coğrafi bölgeler arası işleme ve depolama işlevlerini etkinleştirin.
• Veri içeren bu veri kaynaklarından en az biri: Ambar, göl evi, Power BI anlam modeli, KQL veritabanı, yansıtılmış veritabanı veya ontoloji. Veri kaynağına okuma erişiminiz olmalıdır.

Veri aracısı SDK'sını yükleme

Fabric veri ajanınızı programatik olarak değerlendirmeye başlamak için Fabric veri ajanı Python SDK'yı kurun. Bu SDK, veri aracınızla etkileşime geçmek, değerlendirmeleri çalıştırmak ve sonuçları günlüğe kaydetmek için gereken araçları ve yöntemleri sağlar. Not defterinizde aşağıdaki komutu çalıştırarak en son sürümü yükleyin:

%pip install -U fabric-data-agent-sdk

Bu adım, SDK'da en up-togüncel özelliklere ve düzeltmelere sahip olduğunuzdan emin olunmasını sağlar.

Temel gerçeklik veri kümenizi yükleme

Fabric veri ajanınızı değerlendirmek için beklenen cevaplarla birlikte bir dizi örnek soru almanız gerekir. Bu soruları, ajanın gerçek dünya sorularına ne kadar doğru yanıt verdiğini doğrulamak için kullanın.

Bu soruları doğrudan kodunuzda pandas DataFrame kullanarak tanımlayın:

import pandas as pd

# Define a sample evaluation set with user questions and their expected answers.
# You can modify the question/answer pairs to match your scenario.
df = pd.DataFrame(
    columns=["question", "expected_answer"],
    data=[
        ["Show total sales for Canadian Dollar for January 2013", "46,117.30"],
        ["What is the product with the highest total sales for Canadian Dollar in 2013", "Mountain-200 Black, 42"],
        ["Total sales outside of the US", "19,968,887.95"],
        ["Which product category had the highest total sales for Canadian Dollar in 2013", "Bikes (Total Sales: 938,654.76)"]
    ]
)

Alternatif olarak, mevcut bir değerlendirme veri kümeniz varsa, question ve expected_answer sütunlarını içeren bir CSV dosyasından yükleyin:

# Load questions and expected answers from a CSV file
input_file_path = "/lakehouse/default/Files/Data/Input/curated_2.csv"
df = pd.read_csv(input_file_path)

Bu veri kümesi, doğruluğu ve kapsamı değerlendirmek için veri aracınızda otomatik değerlendirmeler çalıştırmaya yönelik giriş görevi görür.

Veri aracınızı değerlendirin ve inceleyin

Sonraki adım, değerlendirmeyi evaluate_data_agent işlevini kullanarak çalıştırmaktır. Bu işlev, aracının yanıtlarını beklediğiniz sonuçlarla karşılaştırır ve değerlendirme ölçümlerini depolar.

Note

Bu adım, değerlendirme yaptığınız ortamda zaten yayımlanmış bir veri aracısı gerektirir (production veya sandbox). Henüz bir Fabric veri aracınız yoksa, Fabric veri aracısı oluşturma bölümüne bakın.

from fabric.dataagent.evaluation import evaluate_data_agent

# Name of your data agent
data_agent_name = "AgentEvaluation"

# (Optional) Name of the workspace if the data agent is in a different workspace
workspace_name = None

# (Optional) Name of the output table to store evaluation results (default: "evaluation_output")
# Two tables will be created:
# - "<table_name>": contains summary results (e.g., accuracy)
# - "<table_name>_steps": contains detailed reasoning and step-by-step execution
table_name = "demo_evaluation_output"

# Specify the data agent stage: "production" (default) or "sandbox"
data_agent_stage = "production"

# Run the evaluation and get the evaluation ID
try:
    evaluation_id = evaluate_data_agent(
        df,
        data_agent_name,
        workspace_name=workspace_name,
        table_name=table_name,
        data_agent_stage=data_agent_stage
    )
    print(f"Unique ID for the current evaluation run: {evaluation_id}")
except Exception as e:
    print(f"Evaluation failed: {e}")

Çalışma bittikten sonra, aşağıdaki metne benzer bir çıktı görürsünüz:

Unique ID for the current evaluation run: <evaluation-id>

Değerlendirme özetini alma

Değerlendirmeyi yaptıktan sonra, fonksiyonu get_evaluation_summary kullanarak sonuçların yüksek seviyeli bir özetini elde edebilirsiniz. Bu fonksiyon, veri ajanınızın genel olarak ne kadar iyi performans gösterdiğine dair içgörüler sağlar; örneğin kaç yanıtın beklenen yanıtlarla eşleştiği gibi metrikler de var.

from fabric.dataagent.evaluation import get_evaluation_summary

# Retrieve a summary of the evaluation results
summary_df = get_evaluation_summary(table_name)

Varsayılan olarak, bu fonksiyon . evaluation_outputadlı bir tablo arar. Değerlendirme sırasında özel bir tablo adı belirttiyseniz (örneğin demo_evaluation_output), bu ismi argüman table_name olarak aktarın.

Döndürülen DataFrame doğru, yanlış veya belirsiz yanıt sayısı gibi toplu ölçümleri içerir. Bu sonuç, etkenin doğruluğunu hızlı bir şekilde değerlendirmenize ve iyileştirme alanlarını belirlemenize yardımcı olur.

Ayrıntılı değerlendirme sonuçlarını inceleme

Veri ajanınızın her bir soruya nasıl yanıt verdiğine daha derinlemesine inmek için fonksiyonu get_evaluation_details kullanın. Bu fonksiyon, ajan yanıtları, beklenen yanıtla eşleşip eşleşmediği ve değerlendirme dizisinin bağlantısı dahil olmak üzere değerlendirme çalıştırmasının ayrıntılı dökümünü döndürür (yalnızca değerlendirmeyi yürüten kullanıcı tarafından görülebilir).

from fabric.dataagent.evaluation import get_evaluation_details

# Table name used during evaluation
table_name = "demo_evaluation_output"

# Whether to return all evaluation rows (True) or only failures (False)
get_all_rows = False

# Whether to print a summary of the results
verbose = True

# Retrieve evaluation details for a specific run
eval_details = get_evaluation_details(
    evaluation_id,
    table_name,
    get_all_rows=get_all_rows,
    verbose=verbose
)

Değerlendirme isteminizi özelleştirme

Varsayılan olarak, Fabric SDK, veri ajanının gerçek cevabının beklenen cevapla eşleşip eşleşmediğini değerlendirmek için yerleşik bir istem kullanır. Ancak, parametreyi critic_prompt kullanarak daha nüanslı veya alana özgü değerlendirmeler için kendi promptunuzu sağlayabilirsiniz.

Özel isteminiz {query}, {expected_answer} ve {actual_answer} yer tutucularını içermelidir. Değerlendirme süreci, her soru için bu yer tutucuları dinamik olarak değiştirir.

from fabric.dataagent.evaluation import evaluate_data_agent

# Define a custom prompt for evaluating agent responses
critic_prompt = """
    Given the following query, expected answer, and actual answer, please determine if the actual answer is equivalent to expected answer. If they are equivalent, respond with 'yes'.

    Query: {query}

    Expected Answer:
    {expected_answer}

    Actual Answer:
    {actual_answer}

    Is the actual answer equivalent to the expected answer?
"""

# Name of the data agent
data_agent_name = "AgentEvaluation"

# Run evaluation using the custom critic prompt
evaluation_id = evaluate_data_agent(df, data_agent_name, critic_prompt=critic_prompt)

Bu özellik özellikle aşağıdaki durumlarda kullanışlıdır:

• Eşleşme sayılan şeyler için daha esnek veya daha katı kriterler uygulamak istersiniz.
• Beklediğiniz ve gerçek cevaplarınız format olarak değişebilir ama yine de anlamsal olarak eşdeğer olabilir.
• Yanıtların nasıl değerlendirileceği konusunda etki alanına özgü nüansları yakalamanız gerekir.

Tanı düğmesi

Tanı butonu ise veri ajanınızın yapılandırma ve çalıştırma adımlarının tam bir anlık görüntüsünü indirmenize olanak tanır. Bu dışa aktarma, veri kaynağı ayarları, uygulanan talimatlar, kullanılan örnek sorgular ve veri ajanının yanıtını oluşturmak için attığı temel adımlar gibi detayları içerir.

Bu özelliği Microsoft Desteği ile çalışırken veya beklenmedik davranışları sorun giderken kullanın. İndirilen dosyayı inceleyerek, veri ajanının talebinizi nasıl işlediğini, hangi yapılandırmaların uygulandığını ve olası sorunların nerede ortaya çıktığını tam olarak görebilirsiniz. Bu şeffaflık seviyesi, veri ajanınızın performansını hata ayıklamayı ve optimize etmeyi kolaylaştırır.

Troubleshooting

Issue	Cause	Çözünürlük
Veri ajanı bulunamadı	data_agent_name veya workspace_name yanlış ya da aracı yayımlanmamış.	Ajan adını ve çalışma alanını doğrulayın ve ajanın belirtilen data_agent_stage'da yayınlandığından emin olun.
Boş veya eksik sonuçlar	Tablo adı, evaluate_data_agent sırasında kullanılan adla eşleşmiyor.	Aynı table_name öğesini get_evaluation_summary ve get_evaluation_details öğelerine iletin.
message_url erişilebilir değil	Değerlendirme iş parçacıklarını yalnızca değerlendirmeyi yürüten kullanıcı görebilir.	İleti dizisi bağlantılarına erişmek için değerlendirmeyi kendi hesabınızla yeniden çalıştırın.
Özel istemin hiçbir etkisi veya hatası yoktur	critic_prompt, gerekli yer tutucuları içermiyor.	İsteminize {expected_answer}, {actual_answer} ve {query} ekleyin.
İzin veya kapasite hatası	F2 veya daha yüksek kapasite eksik, ya da veri kaynağına okuma erişimi eksik.	Kapasite ve veri kaynağı okuma erişimi dahil olmak üzere ön koşulları onaylayın.

Sonraki Adımlar

• Fabric veri aracısı oluşturun
• Fabric veri aracısı SDK'sını kullanın
• Veri aracısı SDK'sını kullanma hakkında örnek not defterlerine erişme