Exempel på förfrågningar

Exempelfrågor (kallas även "few-shot examples") ger Data Agent konkreta mönster att använda för lärande. De är exempelfrågor och deras motsvarande frågelogik som skaparna tillhandahåller för att vägleda hur agenten ska svara. När en användare ställer en fråga mot en datakälla hämtar dataagenten automatiskt de mest relevanta exemplen – vanligtvis de fyra främsta – och matar in dem i genereringsprocessen. Genom att referera till de här exemplen kan agenten bättre förstå den förväntade strukturen, filtren och kopplingarna, vilket hjälper den att skapa mer exakta, konsekventa och kontextmedvetna frågeresultat.

Ange exempelfrågor

När du tillhandahåller exempelfrågor måste du inkludera både en fråga med naturligt språk och motsvarande frågesvar. Varje fråga bör vara unik för att ge dataagenten en mängd olika referenspunkter. Varje exempelfråga verifieras mot schemat för den valda datakällan – frågor som inte klarar valideringen skickas inte till agenten. För att säkerställa att dina exempel används är det viktigt att bekräfta att de godkänns i det här valideringssteget.

Tabellen visar vilka datakällor som för närvarande stöder exempelfrågor i dataagenten. De här exemplen hjälper till att vägleda agentens frågegenereringsprocess genom att tillhandahålla mönster och kontext.

Typ av datakälla	Har du stöd för exempelfrågor?
Lakehouse	✅ Ja
Lager	✅ Ja
Eventhouse KQL-databaser	✅ Ja
Semantiska modeller	❌ Nej
Ontologi	❌ Nej

Du kan också använda körningsstegvyn för att felsöka vilka exempelfrågor som hämtades och tillämpades på en användares fråga. Den här vyn är särskilt användbar för att bekräfta att rätt exempel används och för att diagnostisera varför vissa resultat genereras. Om fel exempel visas kan du försöka förfina dina frågor eller lägga till tydligare, mer riktade exempel.

Metodtips för att skriva exempelfrågor

När du skapar exempelfrågor för dataagenten säkerställer följande metodtips att de ger tydlig och tillförlitlig vägledning under frågegenereringen. Väl utformade exempel hjälper agenten att förstå hur frågor om naturligt språk översätts till SQL/KQL-logik, markerar komplexa kopplingar eller beräkningar och förbättrar precisionen i dess resultat. Använd riktlinjerna för att göra dina exempel mer effektiva och representativa för verkliga användarscenarier.

#	Bästa praxis	Varför det spelar roll
1	Se till att frågorna tydligt mappas till frågan	Dataagenten använder dessa exempel för att lära sig mönstret mellan frågan och den resulterande SQL/KQL:n. Tvetydighet minskar noggrannheten.
2	Inkludera kommentarer i frågan för att vägleda agenten	Kommentarer ( -- substitute customer_id here) hjälper agenten att förstå var du kan ersätta värden eller tillämpa viktig logik.
3	Markera kopplingslogik eller komplexa mönster	Använd exempelfrågor för att visa hur du hanterar kopplingar med flera tabeller, sammansättningar eller annan avancerad logik som är svår att beskriva i vanliga instruktioner.
4	Undvik överlappning eller motsägelser	Varje exempel bör vara distinkt och icke-motstridigt för att ge agenten en ren signal om hur man beter sig.
5	Använd körningssteg för att felsöka vilka exempel som skickas	Genom att köra steg för steg kan du se vilka exempel som identifierades för en viss användarfråga – om felaktiga visas, kan du justera dina förfrågningar eller tillföra mer specifika exempel.
6	Återspegla verkligt användarbeteende	Lägg till exempelfrågor som representerar de typer av frågor som användarna ställer för att maximera relevans och noggrannhet.

Validera exempelfrågor

Fabric Data Agent SDK innehåller inbyggda verktyg för att utvärdera och förbättra kvaliteten på dina exempelfrågor. Med hjälp av evaluate_few_shots funktionen kan du verifiera varje naturligt språk/SQL-par för att bekräfta att det är tydligt, korrekt och justerat efter datakällschemat. SDK:t kör varje exempel genom dataagentens utvärderingsprocess och returnerar en detaljerad sammanfattning av vilka exempel som har skickats och vilka som behöver förfinas.

Ange exempelfrågor

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

Utvärdera via SDK

Genom att granska framgångsfrekvensen och feedbacken kan du iterativt justera dina exempel – klargöra frågor, förbättra SQL-logiken eller lägga till kommentarer – så att dataagenten lär sig av mönster av högre kvalitet och ger mer exakta resultat för nya frågor.

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

Spåra feedback

När du har kört validatorn får du en tydlig uppdelning av vilka exempel som har skickats och vilka som misslyckades. Den här feedbacken gör det enkelt att identifiera styrkor och svagheter i dina exempel med få skott.

• Lyckade fall: Exempel där SQL matchade de förväntade svaren. De här exemplen är starka referenser som du kan modellera framtida exempel efter.
• Felfall: Exempel där SQL inte matchade det förväntade svaret eller där frågeparet kan vara oklart eller ogiltigt. Dessa fall bör ses över och förfinas.

# 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

Använd den här feedbacken för att iterera och förbättra dina exempelfrågor. Genom att regelbundet stärka svagare exempel kan dataagenten producera mer exakta SQL- och svar över tid.

Om du vill utforska ett fullständigt fungerande exempel kan du kolla in exempelanteckningsboken på GitHub-lagringsplatsen för Fabric Data Agent SDK:

Anmärkning

Det här utvärderingsverktyget är för närvarande endast tillgängligt för SQL-baserade exempelfrågor. KQL eller andra frågetyper stöds ännu inte.

Identifiera konflikter mellan exempelfrågor

När kvalitetsverifieringen har slutförts utför Utvärderings-SDK automatiskt konfliktidentifiering på godkända exempelfrågor eller exempel med få skott. Konfliktidentifiering identifierar inkonsekvenser som kan orsaka att dataagenten ger oförutsägbara eller felaktiga resultat.

En konflikt identifieras när två eller flera exempel:

• Representera samma avsikt (baserat på en normaliserad version av frågan om naturligt språk) men referera till olika tabeller eller vyer
• Beräkna samma mått med hjälp av olika aggregeringslogik eller olika detaljnivåer
• Generera SQL-frågor som returnerar väsentligt olika resultat för samma affärsfråga

Dessa konflikter tyder på tvetydighet eller inkonsekvens inom några få skottexempel. Genom att lösa dem kan du förbättra frågans determinism, noggrannhet och övergripande agentbeteende.

Granska konfliktinformation

När konflikter identifieras expanderar SDK:n varje konflikt till rader per exempel, vilket ger detaljerad diagnostik, inklusive:

• Exemplen som är inblandade i konflikten
• Frågan om naturligt språk och motsvarande SQL för varje exempel
• En beskrivning av konflikten som förklarar hur exemplen skiljer sig åt
• En konfidenspoäng som anger tillförlitligheten för konfliktidentifieringen

Använd den här detaljerade vyn för att förstå vilka exempel som är i konflikt och varför, och för att avgöra vilka exempel som ska uppdateras eller tas bort.

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

I följande exempel visas utdata för konfliktidentifiering, deras associerade frågor och SQL samt konfidensnivån för varje identifierad konflikt.

Förstå validatorpoäng

När du kör validatorn i dina exempelfrågor genererar den tre nyckelpoäng för varje exempel: Klarhet, relateradhet och mappning. Dessa poäng härleds från hur väl dina frågor om naturligt språk och SQL-frågor överensstämmer med bästa praxis.

• Klarhet
  Mäter om frågan om naturligt språk är tydlig och entydig. Frågorna bör vara specifika, inkludera nödvändiga mått, tidsramar och filter och undvika vaga fraser eller fraser med flera avsikter.

  Exempel – Bra: "Totala intäkter per region för 2024."
  Exempel – Behöver förbättras: "Visa prestanda."

• Samband
  Utvärderar hur nära SQL-frågan matchar avsikten med frågan om naturligt språk. SQL ska returnera rätt mått, tillämpa rätt filter och matcha den begärda kornigheten.

  Exempel – Bra: En fråga frågar efter antalet kunder i mars 2025 → SQL räknar kunder med WHERE month='2025-03'.
  Exempel – Behöver förbättras: En fråga frågar efter antal, men SQL returnerar SUM(revenue) eller filtrerar en annan period.

• Kartläggning
  Kontrollerar om alla literaler i frågan om naturligt språk visas i SQL-frågan. Varje tal, datum eller kategori som nämns i frågan ska uttryckligen representeras i SQL.

  Exempel – Bra: "Beställningar över 100 i mars 2025 för "West" → SQL innehåller > 100, 2025-03och 'West'.
  Exempel – Behöver förbättras: SQL saknar en av dessa literaler (till exempel inget månadsfilter).

Ett exempel anses endast vara av hög kvalitet om alla tre poängen – Tydlighet, Relateradhet och Mappning – är positiva. Använd dessa poäng för att förfina dina exempelfrågor: skriv om oklara frågor, justera SQL närmare med fråge avsikten och se till att varje literal i frågan visas i SQL-frågan. Den här iterativa processen hjälper dataagenten att lära sig av bättre mönster och ge mer exakta resultat.

Nästa steg

• Koncept för dataagent
• Scenario för dataagent
• Exempel på notebook-fil för att validera exempelfrågor