Contoh pertanyaan

Contoh kueri (juga disebut "contoh beberapa bidikan") memberikan pola konkret Agen Data untuk dipelajari. Mereka adalah contoh pertanyaan dan logika kueri terkait yang disediakan pembuat untuk memandu bagaimana agen harus merespons. Saat pengguna mengajukan pertanyaan terhadap sumber data, Agen Data secara otomatis mengambil contoh yang paling relevan—biasanya empat besar—dan mengumpankannya ke dalam proses pembuatannya. Dengan mereferensikan contoh-contoh ini, agen dapat lebih memahami struktur, filter, dan gabungan yang diharapkan, yang membantu menghasilkan hasil kueri yang lebih akurat, konsisten, dan sadar konteks.

Berikan contoh kueri

Saat memberikan contoh kueri, Anda harus menyertakan pertanyaan bahasa alami dan jawaban kueri yang sesuai. Setiap pertanyaan harus unik untuk memberi Agen Data serangkaian titik referensi yang beragam. Setiap contoh kueri divalidasi terhadap skema sumber data yang dipilih—kueri yang tidak lulus validasi tidak dikirim ke agen. Untuk memastikan contoh Anda digunakan, penting untuk mengonfirmasi bahwa mereka melewati langkah validasi ini.

Tabel memperlihatkan sumber data mana yang saat ini mendukung contoh kueri di Agen Data. Contoh-contoh ini membantu memandu proses pembuatan kueri agen dengan menyediakan pola dan konteks.

Tipe Sumber Data	Mendukung Contoh Kueri?
Lakehouse	✅ Ya
Gudang	✅ Ya
Basis Data Eventhouse KQL	✅ Ya
Model Semantik	❌ Tidak
Ontologi	❌ Tidak

Anda juga dapat menggunakan tampilan langkah eksekusi untuk men-debug contoh kueri mana yang diambil dan diterapkan ke pertanyaan pengguna. Tampilan ini sangat berguna untuk mengonfirmasi bahwa contoh yang tepat sedang digunakan dan untuk mendiagnosis mengapa hasil tertentu dihasilkan. Jika contoh yang salah muncul, cobalah menyempurnakan pertanyaan Anda atau menambahkan contoh yang lebih jelas dan lebih ditargetkan.

Praktik terbaik untuk menulis contoh kueri

Dengan mengikuti praktik terbaik saat membuat contoh kueri untuk Agen Data, mereka memastikan memberikan panduan yang jelas dan andal selama pembuatan kueri. Contoh yang dibuat dengan baik membantu agen memahami bagaimana pertanyaan bahasa alami diterjemahkan ke dalam logika SQL/KQL, menyoroti gabungan atau perhitungan yang kompleks, dan meningkatkan akurasi hasilnya. Gunakan panduan untuk membuat contoh Anda lebih efektif dan mewakili skenario pengguna nyata.

#	Praktik Terbaik	Mengapa Penting
1	Pastikan pertanyaan secara jelas disesuaikan dengan permintaan	Agen Data menggunakan contoh-contoh ini untuk mempelajari pola antara pertanyaan dan SQL/KQL yang dihasilkan. Ambiguitas mengurangi akurasi.
2	Sertakan komentar dalam kueri untuk memandu agen	Komentar ( -- substitute customer_id here) membantu agen memahami di mana harus mengganti nilai atau menerapkan logika penting.
3	Menyoroti logika gabungan atau pola kompleks	Gunakan contoh kueri untuk memperlihatkan cara menangani gabungan multi-tabel, agregasi, atau logika tingkat lanjut lainnya yang sulit dijelaskan dalam instruksi biasa.
4	Hindari tumpang tindih atau kontradiksi	Setiap contoh harus berbeda dan tidak bertentangan untuk memberi agen sinyal bersih tentang cara bertingkah laku.
5	Gunakan langkah-langkah eksekusi untuk men-debug contoh mana yang diteruskan	Langkah-langkah eksekusi memungkinkan Anda melihat contoh mana yang diambil untuk pertanyaan pengguna tertentu — jika yang salah muncul, sesuaikan pertanyaan Anda, atau tambahkan contoh yang lebih spesifik.
6	Mencerminkan perilaku pengguna nyata	Tambahkan contoh kueri yang mewakili jenis pertanyaan yang diminta pengguna Anda untuk memaksimalkan relevansi dan akurasi.

Memvalidasi contoh kueri

Fabric Data Agent SDK menyediakan alat bawaan untuk mengevaluasi dan meningkatkan kualitas kueri contoh Anda. Dengan menggunakan fungsi ini evaluate_few_shots , Anda dapat memvalidasi setiap pasangan bahasa alami/SQL untuk mengonfirmasi bahwa pasangan tersebut jelas, benar, dan selaras dengan skema sumber data Anda. SDK menjalankan setiap contoh melalui proses evaluasi Agen Data, mengembalikan ringkasan terperinci tentang contoh mana yang diteruskan dan yang memerlukan penyempurnaan.

Berikan contoh kueri

examples_to_add = {
    "What was total revenue for Product Alpha in Q1 2024?": "SELECT SUM(amount) AS revenue FROM sales WHERE product = 'Alpha' AND fiscal_quarter = '2024-Q1';",
    "Show me average deal size in the North region during 2023.": "SELECT AVG(amount) AS avg_deal FROM deals WHERE region = 'North' AND YEAR(closed_date) = 2023;",
    "How many support tickets were closed in January 2024?": "SELECT COUNT(*) AS tickets_closed FROM support_tickets WHERE status = 'Closed' AND DATE_TRUNC('month', closed_at) = '2024-01-01';",
    "What is the total revenue for Product Alpha in the first quarter of 2024?": "SELECT COUNT(DISTINCT order_id) AS revenue FROM order_facts WHERE product = 'Alpha' AND fiscal_quarter = '2024-Q1';",
    "How many new leads were generated from the website in February 2024?": "SELECT COUNT(*) AS web_leads FROM leads WHERE source = 'Web' AND DATE_TRUNC('month', created_at) = '2024-02-01';",
    "List total marketing touches for campaign Ignite in March 2024.": "SELECT SUM(touches) AS total_touches FROM campaign_metrics WHERE campaign_name = 'Ignite' AND DATE_TRUNC('month', activity_date) = '2024-03-01';",
    "What was the average deal amount in the North region during 2023?": "SELECT SUM(amount) / COUNT(*) AS avg_deal FROM deal_summary WHERE region = 'North' AND YEAR(closed_date) = 2023;",
    "Which products exceeded 1M revenue in 2023?": "SELECT product FROM sales WHERE YEAR(order_date) = 2023 GROUP BY product HAVING SUM(amount) > 1000000;",
    "Show me how many support tickets were closed during January 2024.": "SELECT COUNT(ticket_id) AS tickets_closed FROM ticket_events WHERE event_type = 'Closed' AND MONTH(event_time) = 1 AND YEAR(event_time) = 2024;",
    "What is the churn rate for subscription tier Gold in 2024 so far?": "SELECT SUM(churned_accounts)::float / NULLIF(SUM(active_accounts), 0) AS churn_rate FROM subscription_health WHERE tier = 'Gold' AND YEAR(snapshot_date) = 2024;",
}

# Add the examples to the datasource
try:
    datasource.add_fewshots(examples_to_add)
    print(f"Added {len(examples_to_add)} few-shot examples to the datasource")
except Exception as e:
    print(f"Note: {e}")
    print("Few-shots may already exist in the datasource")

Mengevaluasi melalui SDK

Dengan meninjau tingkat keberhasilan dan umpan balik, Anda dapat secara berulang menyesuaikan contoh Anda—mengklarifikasi pertanyaan, meningkatkan logika SQL, atau menambahkan komentar—sehingga Agen Data belajar dari pola berkualitas lebih tinggi dan menghasilkan hasil yang lebih akurat untuk pertanyaan baru.

# Evaluate few-shot examples using the Data Agent SDK.
# This runs validation on your natural-language/SQL pairs and returns a summary of results.
result = datasource.evaluate_few_shots(batch_size=20)


# Print out the overall success rate of your examples.
# This shows how many examples passed validation vs. the total tested.
print(f"Success rate: {result.success_rate:.2f}% ({result.success_count}/{result.total_examples})")

Melacak umpan balik

Setelah menjalankan validator, Anda akan menerima perincian yang jelas tentang contoh mana yang lulus dan yang gagal. Umpan balik ini memudahkan untuk mengidentifikasi kekuatan dan kelemahan dalam beberapa contoh tembakan Anda.

• Kasus Keberhasilan: Contoh di mana SQL cocok dengan jawaban yang diharapkan. Contoh-contoh ini adalah referensi yang kuat, Anda dapat memodelkan contoh di masa mendatang setelahnya.
• Kasus Kegagalan: Contoh di mana SQL tidak cocok dengan jawaban yang diharapkan, atau di mana pasangan pertanyaan/kueri mungkin tidak jelas atau tidak valid. Kasus-kasus ini harus ditinjau dan disempurnakan.

# Access success and failure cases as pre-computed Pandas DataFrames
success_df = result.success_cases
failure_df = result.failure_cases

print("Success Cases:")
display(success_df)  # Shows examples where the SQL matched the user question

print("Failure Cases:")
display(failure_df)  # Shows examples that need review or improvement

Gunakan umpan balik ini untuk melakukan iterasi dan meningkatkan contoh kueri Anda. Memperkuat contoh yang lebih lemah secara teratur akan membantu Agen Data menghasilkan SQL dan jawaban yang lebih akurat dari waktu ke waktu.

Untuk menjelajahi contoh kerja lengkap, Anda dapat memeriksa contoh buku catatan di repositori GitHub Fabric Data Agent SDK:

Nota

Utilitas evaluasi ini saat ini hanya tersedia untuk kueri contoh berbasis SQL. Jenis kueri lainnya atau KQL belum bisa digunakan.

Mendeteksi konflik di antara contoh kueri

Setelah validasi kualitas selesai, SDK Evaluasi secara otomatis melakukan deteksi konflik pada contoh kueri yang disetujui atau contoh beberapa bidikan. Deteksi konflik mengidentifikasi inkonsistensi yang dapat menyebabkan Agen Data menghasilkan hasil yang tidak dapat diprediksi atau salah.

Konflik terdeteksi ketika dua contoh atau lebih:

• Mewakili niat yang sama (berdasarkan versi pertanyaan bahasa alami yang dinormalisasi) tetapi mereferensikan tabel atau tampilan yang berbeda
• Menghitung metrik yang sama menggunakan logika agregasi yang berbeda atau tingkat granularitas yang berbeda
• Hasilkan kueri SQL yang akan mengembalikan hasil yang berbeda secara material untuk pertanyaan bisnis yang sama

Konflik ini menunjukkan ambiguitas atau inkonsistensi dalam beberapa contoh bidikan yang disediakan. Mengatasinya membantu meningkatkan determinisme kueri, akurasi, dan perilaku agen secara keseluruhan.

Meninjau detail konflik

Ketika konflik terdeteksi, SDK memperluas setiap konflik ke dalam baris per contoh, memberikan diagnostik terperinci, termasuk:

• Contoh yang terlibat dalam konflik
• Pertanyaan bahasa alami dan SQL yang sesuai untuk setiap contoh
• Deskripsi konflik yang menjelaskan bagaimana contoh berbeda
• Skor keyakinan yang menunjukkan keandalan deteksi konflik

Gunakan tampilan terperinci ini untuk memahami contoh mana yang bertentangan dan mengapa, dan untuk menentukan contoh mana yang harus diperbarui atau dihapus.

# Display conflict summary
print(f"\nConflicts Detected: {result.conflict_count}")
print("Confidence Ratings: 5=High, 4=Medium, 3=Low, 2=Very Low, 1=Speculative\n")

# Access detailed conflict information as a pre-computed DataFrame
if result.conflict_count > 0:
    conflict_details_df = result.conflict_details
    display(conflict_details_df)
else:
    print("No conflict details to display.")

Contoh berikut menunjukkan output deteksi konflik, pertanyaan terkait dan SQL, dan tingkat keyakinan setiap konflik yang terdeteksi.

Memahami skor validator

Saat Anda menjalankan validator pada contoh kueri Anda, ini menghasilkan tiga skor utama untuk setiap contoh: Kejelasan, Kekaitan, dan Pemetaan. Skor ini berasal dari seberapa baik pertanyaan bahasa alami Anda dan kueri SQL selaras dengan praktik terbaik.

• Kejelasan
  Mengukur apakah pertanyaan bahasa alami jelas dan tidak ambigu. Pertanyaan harus spesifik, termasuk metrik, kerangka waktu, dan filter yang diperlukan, dan menghindari penggunaan frasa yang samar atau berbagai maksud.

  Contoh – Bagus: "Total pendapatan menurut wilayah untuk tahun 2024."
  Contoh – Perlu Penyempurnaan: "Tampilkan performa."

• Kekaitan
  Mengevaluasi seberapa dekat kueri SQL cocok dengan niat pertanyaan bahasa alami. SQL harus mengembalikan metrik yang benar, menerapkan filter yang tepat, dan mencocokkan granularitas yang diminta.

  Contoh – Bagus: Pertanyaan mengajukan jumlah pelanggan pada Maret 2025 → SQL menghitung pelanggan dengan WHERE month='2025-03'.
  Contoh – Perlu Penyempurnaan: Pertanyaan meminta hitungan, tetapi SQL mengembalikan SUM(pendapatan) atau memfilter periode yang berbeda.

• Pemetaan
  Memeriksa apakah semua literal dalam pertanyaan bahasa alami muncul dalam kueri SQL. Setiap angka, tanggal, atau kategori yang disebutkan dalam pertanyaan harus secara eksplisit diwakili dalam SQL.

  Contoh – Bagus: "Pesanan lebih dari 100 pada bulan Maret 2025 untuk 'Barat'" → SQL meliputi > 100, , 2025-03dan 'West'.
  Contoh – Perlu Penyempurnaan: SQL kehilangan salah satu literal tersebut (misalnya, tidak ada filter bulan).

Contoh dianggap berkualitas tinggi hanya jika ketiga skor—Clarity, Relatedness, dan Mapping—positif. Gunakan skor ini untuk menyempurnakan contoh kueri Anda: menulis ulang pertanyaan yang tidak jelas, selaraskan SQL lebih erat dengan niat pertanyaan, dan pastikan setiap literal dalam pertanyaan muncul dalam kueri SQL. Proses berulang ini membantu Agen Data belajar dari pola yang lebih baik dan menghasilkan hasil yang lebih akurat.

Langkah selanjutnya

• Konsep agen data
• Skenario agen data
• Contoh buku catatan untuk memvalidasi contoh kueri