Eksempelspørringer

Eksempelspørringer (også kalt «few-shot examples») gir Data Agent konkrete mønstre å lære av. De er eksempelspørsmål og deres tilsvarende spørringslogikk som skapere leverer for å veilede hvordan agenten skal svare. Når en bruker stiller et spørsmål mot en datakilde, henter dataagenten automatisk de mest relevante eksemplene – vanligvis de fire beste – og mater dem inn i genereringsprosessen. Ved å referere til disse eksemplene kan agenten bedre forstå den forventede strukturen, filtrene og sammenføyningene, noe som hjelper den med å produsere mer nøyaktige, konsekvente og kontekstbevisste spørringsresultater.

Gi eksempelspørringer

Når du angir eksempelspørringer, må du inkludere både et spørsmål med naturlig språk og det tilsvarende spørringssvaret. Hvert spørsmål bør være unikt for å gi dataagenten et mangfoldig sett med referansepunkter. Hver eksempelspørring valideres mot skjemaet for den valgte datakilden – spørringer som ikke består validering, sendes ikke til agenten. For å sikre at eksemplene dine blir brukt, er det viktig å bekrefte at de består dette valideringstrinnet.

Skjermbilde av å legge til eksempelspørringer i dataagenten.

Tabellen viser hvilke datakilder som for øyeblikket støtter eksempelspørringer i Data Agent. Disse eksemplene hjelper til med å veilede agentens spørringsgenereringsprosess ved å gi mønstre og kontekst.

Type datakilde Støtter eksempelspørringer?
Lakehouse ✅ Ja
Warehouse ✅ Ja
Eventhouse KQL-databaser ✅ Ja
Semantiske modeller ❌ Nei
Ontologi ❌ Nei

Du kan også bruke visningen for å kjøre trinn for å feilsøke hvilke eksempelspørringer som ble hentet og brukt på brukerens spørsmål. Dette synet er spesielt nyttig for å bekrefte at de riktige eksemplene brukes og for å diagnostisere hvorfor visse resultater genereres. Hvis feil eksempler vises, kan du prøve å avgrense spørsmålene dine eller legge til tydeligere, mer målrettede eksempler.

Skjermbilde av de refererte eksempelspørringene i kjøretrinnene.

Anbefalte fremgangsmåter for å skrive eksempelspørringer

Når du oppretter eksempelspørringer for dataagenten, sikrer følgende anbefalte fremgangsmåter at de gir klar, pålitelig veiledning under spørringsgenerering. Godt utformede eksempler hjelper agenten med å forstå hvordan spørsmål med naturlig språk oversettes til SQL/KQL-logikk, fremheve komplekse sammenføyninger eller beregninger og forbedre nøyaktigheten til resultatene. Bruk retningslinjene for å gjøre eksemplene dine mer effektive og representative for reelle brukerscenarier.

# Beste praksis Hvorfor det er viktig
1 Sørg for at spørsmålene er tydelig tilordnet spørringen Data Agent bruker disse eksemplene til å lære mønsteret mellom spørsmålet og den resulterende SQL/KQL. Tvetydighet reduserer nøyaktigheten.
2 Inkluder kommentarer i spørringen for å veilede agenten Kommentarer ( -- substitute customer_id here) hjelper agenten å forstå hvor de skal erstatte verdier eller anvende viktig logikk.
3 Utheve sammenføyningslogikk eller komplekse mønstre Bruk eksempelspørringer for å vise hvordan man håndterer flertabell-joins, aggregeringer eller annen avansert logikk som er vanskelig å beskrive i enkle instruksjoner.
4 Unngå overlapping eller motsetninger Hvert eksempel bør være distinkt og ikke-motstridende for å gi agenten et rent signal om hvordan de skal oppføre seg.
5 Bruk kjøretrinn for å feilsøke hvilke eksempler som sendes Kjøretrinn lar deg se hvilke eksempler som ble hentet for et gitt brukerspørsmål – hvis feil dukker opp, juster spørsmålene dine eller legg til mer spesifikke eksempler.
6 Gjenspeiler reell brukeratferd Legg til eksempelspørringer som representerer typen spørsmål brukerne dine stiller for å maksimere relevans og nøyaktighet.

Validere eksempelspørringer

Fabric Data Agent SDK inneholder innebygde verktøy for å evaluere og forbedre kvaliteten på eksempelspørringene dine. Ved hjelp av evaluate_few_shots funksjonen kan du validere hvert naturlig språk/SQL-par for å bekrefte at det er klart, riktig og justert med datakildeskjemaet. SDK-en kjører hvert eksempel gjennom Data Agents evalueringsprosess, og returnerer en detaljert oppsummering av hvilke eksempler som har passert og hvilke som trenger forbedring.

Gi eksempelspørringer

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

Evaluer gjennom SDK

Ved å gå gjennom suksessraten og tilbakemeldingene kan du iterativt justere eksemplene dine – avklare spørsmål, forbedre SQL-logikk eller legge til kommentarer – slik at dataagenten lærer av mønstre av høyere kvalitet og gir mer nøyaktige resultater for nye spørsmål.

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

Tilbakemelding på sporet

Etter å ha kjørt validatoren, får du en klar oversikt over hvilke eksempler som bestod og hvilke som feilet. Denne tilbakemeldingen gjør det enkelt å identifisere styrker og svakheter i eksemplene dine med få skudd.

  • Suksess tilfeller: Eksempler der SQL samsvarte med de forventede svarene. Disse eksemplene er sterke referanser du kan modellere fremtidige eksempler etter.
  • Feilsaker: Eksempler der SQL-en ikke samsvarte med det forventede svaret, eller hvor spørsmål/spørringsparet kan være uklart eller ugyldig. Disse sakene bør gjennomgås og avgrenses.
# 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

Bruk denne tilbakemeldingen til å gjenta og forbedre eksempelspørringene dine. Regelmessig styrking av svakere eksempler vil hjelpe Data Agent med å produsere mer nøyaktig SQL og svar over tid.

Skjermbilde av eksempler på resultater fra spørringsvalidatorer.

Hvis du vil utforske et fullstendig fungerende eksempeleksempel, kan du se eksempelnotatblokken i GitHub-repositoriet for Fabric Data Agent SDK:

Note

Dette evalueringsverktøyet er for øyeblikket bare tilgjengelig for SQL-baserte eksempelspørringer. KQL eller andre spørringstyper støttes ikke ennå.

Oppdage konflikter mellom eksempelspørringer

Etter at kvalitetsvalidering er fullført, utfører Evaluation SDK automatisk konfliktdeteksjon på godkjente eksempelssøk eller få-shot-eksempler. Konfliktdeteksjon identifiserer inkonsistenser som kan føre til at Data Agent produserer uforutsigbare eller feilaktige resultater.

En konflikt oppdages når to eller flere eksempler:

  • Representere samme intensjon (basert på en normalisert versjon av det naturlige språkspørsmålet), men referere til forskjellige tabeller eller visninger
  • Beregn samme metrikk ved å bruke annen aggregeringslogikk eller ulike nivåer av granularitet
  • Generer SQL-spørringer som gir vesentlig forskjellige resultater for det samme forretningsspørsmålet

Disse konfliktene indikerer tvetydighet eller inkonsistens i de få eksemplene som er oppgitt. Å løse dem bidrar til å forbedre spørringsdeterminisme, nøyaktighet og generell agentadferd.

Gjennomgang av konfliktdetaljer

Når konflikter oppdages, utvider SDK-en hver konflikt til rader per eksempel, og gir detaljerte diagnostikk, inkludert:

  • Eksemplene involvert i konflikten
  • Spørsmålet om naturlig språk og tilhørende SQL for hvert eksempel
  • En beskrivelse av konflikten som forklarer hvordan eksemplene skiller lag
  • En konfidensscore som indikerer påliteligheten til konfliktdeteksjonen

Bruk denne detaljerte visningen for å forstå hvilke eksempler som er i konflikt og hvorfor, og for å avgjøre hvilke eksempler som bør oppdateres eller fjernes.

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

Følgende eksempel viser konfliktdeteksjonsresultatet, deres tilhørende spørsmål og SQL, samt konfidensnivået til hver oppdaget konflikt.

Skjermbilde av konfliktdeteksjon.

Forstå validatorpoeng

Når du kjører validatoren på eksempelspørringene, genererer den tre nøkkelpoengsummer for hvert eksempel: Klarhet, Slektskap og Tilordning. Disse poengsummene er avledet fra hvor godt spørsmålene og SQL-spørringene ditt stemmer overens med anbefalte fremgangsmåter.

  • Klarhet
    Måler om spørsmålet om naturlig språk er klart og entydig. Spørsmålene bør være spesifikke, inkludere nødvendige beregninger, tidsrammer og filtre, og unngå vage formuleringer eller formuleringer med flere intensjoner.

    Eksempel – Bra: "Total inntekt per region for 2024."
    Eksempel – Trenger forbedring: "Showforestilling."

  • Slektskap
    Evaluerer hvor nært SQL-spørringen samsvarer med hensikten med spørsmålet om naturlig språk. SQL skal returnere riktig metrikkverdi, bruke de riktige filtrene og samsvare med den forespurte detaljligheten.

    Eksempel – Bra: Et spørsmål spør om antall kunder i mars 2025 → SQL teller kunder med WHERE month='2025-03'.
    Eksempel – Trenger forbedring: Et spørsmål ber om antall, men SQL returnerer SUM(inntekt) eller filtrerer en annen periode.

  • tilordning
    Kontrollerer om alle litteraler i spørsmålet om naturlig språk vises i SQL-spørringen. Hvert tall, dato eller kategori nevnt i spørsmålet skal være eksplisitt representert i SQL.

    Eksempel – Bra: "Bestillinger over 100 i mars 2025 for 'West'" → SQL inkluderer > 100, 2025-03, og 'West'.
    Eksempel – Trenger forbedring: SQL mangler en av disse bokstavene (for eksempel ingen månedsfilter).

Et eksempel anses som høy kvalitet bare hvis alle tre poengsummene – Klarhet, Slektskap og Kartlegging – er positive. Bruk disse poengsummene til å avgrense eksempelspørringene: skriv uklare spørsmål på nytt, juster SQL tettere med spørsmålsintensjonen, og sørg for at hver litteral i spørsmålet vises i SQL-spørringen. Denne iterative prosessen hjelper dataagenten med å lære av bedre mønstre og produsere mer nøyaktige resultater.

Neste trinn

  • Last updated on