Örnek sorgular

Örnek sorgular ("birkaç deneme örneği" olarak da adlandırılır), Veri Aracısı'na öğrenmeniz gereken somut desenler verir. Bunlar örnek sorular ve oluşturucuların aracıya nasıl yanıt vermesi gerektiği konusunda yol gösteren ilgili sorgu mantığıdır. Bir kullanıcı bir veri kaynağına soru sorduğunda, Veri Aracısı en ilgili örnekleri (genellikle ilk dördü) otomatik olarak alır ve bunları kendi oluşturma sürecine aktarır. Aracı, bu örneklere başvurarak beklenen yapıyı, filtreleri ve birleşimleri daha iyi anlayabilir ve bu da daha doğru, tutarlı ve bağlama duyarlı sorgu sonuçları üretmesine yardımcı olur.

Örnek sorgular sağlama

Örnek sorgular sağlarken hem doğal dil sorusu hem de karşılık gelen sorgu yanıtını eklemeniz gerekir. Her soru, Veri Aracısı'na çeşitli başvuru noktaları sağlamak için benzersiz olmalıdır. Her örnek sorgu seçilen veri kaynağının şemasına göre doğrulanır; doğrulamayı geçmeyen sorgular aracıya gönderilmez. Örneklerinizin kullanıldığından emin olmak için bu doğrulama adımını geçtiklerini onaylamak önemlidir.

Tabloda, veri aracısında şu anda hangi veri kaynaklarının örnek sorguları desteklediği gösterilmektedir. Bu örnekler, desenler ve bağlam sağlayarak aracının sorgu oluşturma işlemine yol göstermeye yardımcı olur.

Veri Kaynağı Türü	Örnek Sorguları destekliyor mu?
Lakehouse	✅ Evet
Depo	✅ Evet
Eventhouse KQL Veritabanları	✅ Evet
Anlamsal Modeller	❌ Hayır
Ontoloji	❌ Hayır

Ayrıca, bir kullanıcının sorusuna hangi örnek sorguların alındığını ve uygulandığını ayıklamak için çalıştırma adımları görünümünü de kullanabilirsiniz. Bu görünüm özellikle doğru örneklerin kullanıldığını onaylamak ve belirli sonuçların neden oluşturulduğunu tanılamak için kullanışlıdır. Yanlış örnekler görünüyorsa, sorularınızı iyileştirmeyi veya daha net, daha hedefli örnekler eklemeyi deneyin.

Örnek sorgular yazmak için en iyi yöntemler

Veri Aracısı için örnek sorgular oluştururken, aşağıdaki en iyi yöntemler sorgu oluşturma sırasında net ve güvenilir rehberlik sağlamalarını sağlar. İyi hazırlanmış örnekler, aracının doğal dil sorularının SQL/KQL mantığına nasıl dönüştüğünü anlamasına, karmaşık birleşimleri veya hesaplamaları vurgulamasına ve sonuçlarının doğruluğunu iyileştirmesine yardımcı olur. Örneklerinizi daha etkili ve gerçek kullanıcı senaryolarını temsil eden hale getirmek için yönergeleri kullanın.

#	En İyi Yöntemler	Neden Önemlidir?
1	Soruların sorguyla net bir şekilde eşlediğinden emin olun	Veri Aracısı, soru ile sonuçta elde edilen SQL/KQL arasındaki deseni öğrenmek için bu örnekleri kullanır. Belirsizlik doğruluğu azaltır.
2	Aracıya kılavuzluk etmek için sorguya açıklama ekleme	Yorumlar ( -- substitute customer_id here) aracının değerlerin nereye yerleştirileceğini veya önemli mantığın nasıl uygulanacağını anlamasına yardımcı olur.
3	Birleştirme mantığını veya karmaşık desenleri vurgulama	Çok tablolu birleştirmelerin, toplamaların veya düz yönergelerde açıklanması zor olan diğer gelişmiş mantığın nasıl işleneceğini göstermek için örnek sorguları kullanın.
4	Çakışma veya çelişkilerden kaçının	Aracıya nasıl davranılacağına ilişkin temiz bir sinyal vermek için her örnek ayrı ve çakışmayan olmalıdır.
5	Hangi örneklerin geçtiğini ayıklamak için çalıştırma adımlarını kullanın	Çalıştırma adımları, belirli bir kullanıcı sorusu için hangi örneklerin alındığını görmenizi sağlar. Yanlış örnekler gösterildiyse, sorularınızı ayarlayın veya daha ayrıntılı örnekler ekleyin.
6	Gerçek kullanıcı davranışını yansıtma	Kullanıcılarınızın ilgi ve doğruluğu en üst düzeye çıkarmak için sorabilecekleri soru türlerini temsil eden örnek sorgular ekleyin.

Örnek sorguları doğrulama

Doku Veri Aracısı SDK'sı , örnek sorgularınızın kalitesini değerlendirmek ve geliştirmek için yerleşik araçlar sağlar. evaluate_few_shots işlevini kullanarak, her doğal dil/SQL çiftini doğrulayabilir ve veri kaynağı şemanızla uyumlu, açık ve doğru olduğunu onaylayabilirsiniz. SDK, her örneği Veri Aracısı'nın değerlendirme işlemi aracılığıyla çalıştırarak hangi örneklerin geçirildiğine ve hangilerinin iyileştirmeye ihtiyaç duyduğuna ilişkin ayrıntılı bir özet döndürür.

Örnek sorgular sağlama

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

SDK aracılığıyla değerlendirme

Veri Aracısı'nın daha yüksek kaliteli desenlerden ders çıkarması ve yeni sorular için daha doğru sonuçlar üretmesi için başarı oranını ve geri bildirimi gözden geçirerek örneklerinizi yinelemeli olarak ayarlayabilirsiniz. Bu sayede soruları netleştirebilir, SQL mantığını geliştirebilir veya yorum ekleyebilirsiniz.

# 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})")

Geri bildirimi izleme

Doğrulayıcıyı çalıştırdıktan sonra, hangi örneklerin geçtiğini ve hangilerinin başarısız olduğunu net bir şekilde döküm alırsınız. Bu geri bildirim, birkaç deneme örneğinizdeki güçlü ve zayıf noktaları belirlemenizi kolaylaştırır.

• Başarı Örnekleri: SQL'in beklenen yanıtlarla eşleştiği örnekler. Bu örnekler, daha sonra gelecek örnekleri modelleyebileceğiniz güçlü başvurulardır.
• Hata Durumları: SQL'in beklenen yanıtla eşleşmediği veya soru/sorgu çiftinin belirsiz veya geçersiz olabileceği örnekler. Bu durumlar gözden geçirilmeli ve incelenmelidir.

# 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

Örnek sorgularınızı yinelemek ve geliştirmek için bu geri bildirimi kullanın. Daha zayıf örnekleri düzenli olarak güçlendirmek, Veri Aracısı'nın zaman içinde daha doğru SQL ve yanıtlar üretmesine yardımcı olur.

Tam bir çalışma örneğini keşfetmek için Doku Veri Aracısı SDK'sı GitHub deposundaki örnek not defterine göz atabilirsiniz:

Uyarı

Bu değerlendirme yardımcı programı şu anda yalnızca SQL tabanlı örnek sorgular için kullanılabilir. KQL veya diğer sorgu türleri henüz desteklenmiyor.

Örnek sorgular arasındaki çakışmaları algılama

Kalite doğrulama tamamlandıktan sonra Değerlendirme SDK'sı, onaylanan örnek sorgularda veya birkaç denemede otomatik olarak çakışma algılama gerçekleştirir. Çakışma algılama, Veri Aracısı'nın öngörülemeyen veya yanlış sonuçlar üretmesine neden olabilecek tutarsızlıkları tanımlar.

İki veya daha fazla örnek olduğunda çakışma algılanır:

• Aynı amacı temsil eder (doğal dil sorusunun normalleştirilmiş bir sürümünü temel alır) ancak farklı tablolara veya görünümlere başvurur
• Farklı toplama mantığı veya farklı ayrıntı düzeyleri kullanarak aynı ölçümü hesaplama
• Aynı iş sorusu için önemli ölçüde farklı sonuçlar döndürecek SQL sorguları oluşturma

Bu çakışmalar, sağlanan birkaç çekim örneğinde belirsizliği veya tutarsızlığı gösterir. Bunları çözümlemek sorgu determinizminin, doğruluğun ve genel aracı davranışının geliştirilmesine yardımcı olur.

Çakışma ayrıntılarını gözden geçirme

Çakışmalar algılandığında SDK, her çakışmayı örnek satırlara genişleterek aşağıdakiler gibi ayrıntılı tanılamalar sağlar:

• Çakışmaya dahil olan örnekler
• Her örnek için doğal dil sorusu ve buna karşılık gelen SQL
• Örneklerin nasıl farklı olduğunu açıklayan çakışma açıklaması
• Çakışma algılamanın güvenilirliğini gösteren güvenilirlik puanı

Hangi örneklerin neden çakışdığını anlamak ve hangi örneklerin güncelleştirilmesi veya kaldırılması gerektiğini belirlemek için bu ayrıntılı görünümü kullanın.

# 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.")

Aşağıdaki örnek, çakışma algılama çıktısını, ilişkili sorularını ve SQL'i ve algılanan her çakışmanın güvenilirlik düzeyini gösterir.

Doğrulayıcı puanlarını anlama

Örnek sorgularınızda doğrulayıcıyı çalıştırdığınızda, her örnek için üç önemli puan oluşturur: Netlik, İlişkisellik ve Eşleme. Bu puanlar, doğal dil sorularınızın ve SQL sorgularınızın en iyi yöntemlerle ne kadar uyumlu olduğundan türetilir.

• Berraklık
  Doğal dil sorusunun açık ve net olup olmadığını ölçer. Sorular belirli olmalı, gerekli ölçümleri, zaman çerçevelerini ve filtreleri içermeli ve belirsiz veya çok amaçlı ifadelerden kaçınmalıdır.

  Örnek – İyi: "2024 için bölgeye göre toplam gelir."
  Örnek – İyileştirme gerekiyor: "Performansı göster."

• İlişkililik
  SQL sorgusunun doğal dil sorusunun amacına ne kadar yakın olduğunu değerlendirir. SQL doğru ölçümü döndürmeli, uygun filtreleri uygulamalı ve istenen ayrıntı düzeyiyle eşleşmelidir.

  Örnek – İyi:Mart 2025'te müşteri sayısını soran bir soru → SQL ile WHERE month='2025-03'müşterileri sayar.
  Örnek – İyileştirme gerekiyor: Bir soru sayıyı sorar, ancak SQL TOPLA(gelir) döndürür veya farklı bir dönemi filtreler.

• Haritalama
  Doğal dil sorusundaki tüm değişmez değerlerin SQL sorgusunda görünup görünmediğini denetler. Soruda belirtilen her sayı, tarih veya kategori SQL'de açıkça gösterilmelidir.

  Örnek – İyi: "Mart 2025'te 'Batı' için 100'ün üzerindeki siparişler" → SQL, > 100, 2025-03 ve 'West' içerir.
  Örnek – İyileştirme gerekiyor: SQL'de bu değişmez değerlerden biri eksik (örneğin, ay filtresi yok).

Örnek, yalnızca üç puanın da (Netlik, İlişkisellik ve Eşleme) pozitif olması durumunda yüksek kalite olarak kabul edilir. Örnek sorgularınızı iyileştirmek için şu puanları kullanın: Belirsiz soruları yeniden yazın, SQL'i soru amacıyla daha yakından hizalayın ve sorudaki her değişmez değerin SQL sorgusunda göründüğünden emin olun. Bu yinelemeli işlem, Veri Aracısı'nın daha iyi desenlerden öğrenmesine ve daha doğru sonuçlar üretmesine yardımcı olur.

Sonraki Adımlar

• Veri aracısı kavramı
• Veri aracısı senaryosu
• Örnek sorguları doğrulamak için örnek not defteri