Eksempelforespørgsler

Eksempelforespørgsler (også kaldet "few-shot examples") giver Data Agenten konkrete mønstre at lære af. De er eksempelspørgsmål og deres tilsvarende forespørgselslogik, som oprettere leverer for at styre, hvordan agenten skal reagere. Når en bruger stiller et spørgsmål til en datakilde, henter dataagenten automatisk de mest relevante eksempler – typisk de fire bedste – og føder dem ind i sin genereringsproces. Ved at referere til disse eksempler kan helpdesk-medarbejderen bedre forstå den forventede struktur, filtre og joinforbindelser, hvilket hjælper den med at producere mere nøjagtige, konsistente og kontekstafhængige forespørgselsresultater.

Angiv eksempelforespørgsler

Når du angiver eksempelforespørgsler, skal du medtage både et spørgsmål på naturligt sprog og det tilsvarende forespørgselssvar. Hvert spørgsmål skal være unikt for at give Data Agent et forskelligartet sæt referencepunkter. Hver eksempelforespørgsel valideres i forhold til skemaet for den valgte datakilde – forespørgsler, der ikke består valideringen, sendes ikke til helpdesk-medarbejderen. For at sikre, at dine eksempler bliver brugt, er det vigtigt at bekræfte, at de består dette valideringstrin.

Skærmbillede af tilføjelse af eksempelforespørgsler til dataagenten.

Tabellen viser, hvilke datakilder der aktuelt understøtter eksempelforespørgsler i Data Agent. Disse eksempler hjælper med at styre agentens proces med at generere forespørgsler ved at give mønstre og kontekst.

Type af datakilde Understøtter eksempelforespørgsler?
Lakehouse ✅ Ja
Warehouse ✅ Ja
Eventhouse KQL-databaser ✅ Ja
Semantiske modeller ❌ Nej
Ontologi ❌ Nej

Du kan også bruge visning af kør trin til at fejlfinde, hvilke eksempelforespørgsler der blev hentet og anvendt på en brugers spørgsmål. Dette synspunkt er især nyttigt til at bekræfte, at de rigtige eksempler bruges, og til at diagnosticere, hvorfor visse resultater genereres. Hvis de forkerte eksempler vises, kan du prøve at finjustere dine spørgsmål eller tilføje klarere, mere målrettede eksempler.

Skærmbillede af de refererede eksempelforespørgsler i kørselstrinnene.

Bedste fremgangsmåder for skrivning af eksempelforespørgsler

Når du opretter eksempelforespørgsler til Data Agent, sikrer du ved at følge bedste praksis, at de giver klar og pålidelig vejledning under oprettelse af forespørgsler. Veludformede eksempler hjælper helpdesk-medarbejderen med at forstå, hvordan spørgsmål på naturligt sprog oversættes til SQL/KQL-logik, fremhæve komplekse joinforbindelser eller beregninger og forbedre nøjagtigheden af resultaterne. Brug retningslinjerne til at gøre dine eksempler mere effektive og repræsentative for reelle brugerscenarier.

# Bedste praksis Hvorfor det er vigtigt
1 Sørg for, at spørgsmålene tydeligt knyttes til forespørgslen Data Agent bruger disse eksempler til at lære mønsteret mellem spørgsmålet og den resulterende SQL/KQL at kende. Tvetydighed reducerer nøjagtigheden.
2 Medtag kommentarer i forespørgslen for at vejlede helpdesk-medarbejderen Kommentarer ( -- substitute customer_id here) hjælper agenten med at forstå, hvor værdier skal erstattes eller anvendes vigtig logik.
3 Fremhæv joinlogik eller komplekse mønstre Brug eksempelforespørgsler til at vise, hvordan man håndterer multi-table joins, aggregationer eller anden avanceret logik, som er svær at beskrive i almindelige instruktioner.
4 Undgå overlap eller modsigelser Hvert eksempel skal være tydeligt og ikke-modstridende for at give agenten et klart signal om, hvordan han skal opføre sig.
5 Brug kørselstrin til at fejlfinde, hvilke eksempler der overføres Kør trin giver dig mulighed for at se, hvilke eksempler der blev hentet for et givet brugerspørgsmål – hvis de forkerte dukker op, kan du justere dine spørgsmål eller tilføje mere specifikke eksempler.
6 Afspejle reel brugeradfærd Tilføj eksempelforespørgsler, der repræsenterer de slags spørgsmål, dine brugere stiller, for at maksimere relevans og nøjagtighed.

Validere eksempelforespørgsler

Fabric Data Agent SDK indeholder indbyggede værktøjer til at evaluere og forbedre kvaliteten af dine eksempelforespørgsler. Ved hjælp af evaluate_few_shots funktionen kan du validere hvert par med naturligt sprog/SQL-par for at bekræfte, at det er klart, korrekt og justeret med dit datakildeskema. SDK'et kører hvert eksempel gennem Data Agents evalueringsproces og returnerer et detaljeret resumé af, hvilke eksempler der er bestået, og hvilke der skal forfines.

Angiv eksempelforespørgsler

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 gennem SDK

Ved at gennemgå succesraten og feedbacken kan du iterativt justere dine eksempler – afklare spørgsmål, forbedre SQL-logik eller tilføje kommentarer – så Data Agent lærer af mønstre af højere kvalitet og producerer mere nøjagtige resultater for nye spørgsmå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})")

Feedback på banen

Efter at have kørt validatoren, får du en klar opdeling af, hvilke eksempler der bestod og hvilke der fejlede. Denne feedback gør det nemt at identificere styrker og svagheder i dine eksempler med få skud.

  • Succesfulde sager: Eksempler, hvor SQL matchede de forventede svar. Disse eksempler er stærke referencer, du kan modellere fremtidige eksempler efter.
  • Fejlsager: Eksempler hvor SQL'en ikke matchede det forventede svar, eller hvor spørgsmål/forespørgsels-parret kan være uklart eller ugyldigt. Disse sager bør gennemgås og finjusteres.
# 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

Brug denne feedback til at gentage og forbedre dine eksempelforespørgsler. Regelmæssig styrkelse af svagere eksempler vil hjælpe Data Agent med at producere mere nøjagtige SQL og svar over tid.

Skærmbillede af eksempler på resultater af forespørgselsvalidatorer.

Hvis du vil udforske et komplet arbejdseksempel, kan du se eksempelnotesbogen i GitHub-lageret Fabric Data Agent SDK:

Notat

Dette evalueringsværktøj er i øjeblikket kun tilgængeligt for SQL-baserede eksempelforespørgsler. KQL eller andre forespørgselstyper understøttes endnu ikke.

Opdag konflikter mellem eksempelforespørgsler

Når kvalitetsvalideringen er afsluttet, udfører Evaluation SDK'en automatisk konfliktdetektion på de godkendte eksempelforespørgsler eller few-shot-eksempler. Konfliktdetektion identificerer inkonsistenser, der kan få Data Agenten til at producere uforudsigelige eller forkerte resultater.

En konflikt opdages, når to eller flere eksempler:

  • Repræsentere samme intention (baseret på en normaliseret version af det naturlige sprog-spørgsmål), men referer til forskellige tabeller eller synspunkter
  • Beregn den samme metrik ved hjælp af forskellig aggregeringslogik eller forskellige granularitetsniveauer
  • Generer SQL-forespørgsler, der vil give væsentligt forskellige resultater for det samme forretningsspørgsmål

Disse konflikter indikerer tvetydighed eller inkonsistens i de få eksempler der er givet. At løse dem hjælper med at forbedre forespørgselsdeterminisme, nøjagtighed og den overordnede agentadfærd.

Detaljer om gennemgangskonflikt

Når konflikter opdages, udvider SDK'en hver konflikt til rækker per eksempel og leverer detaljerede diagnosticeringer, herunder:

  • Eksemplerne i konflikten
  • Det naturlige sprogspørgsmål og den tilsvarende SQL for hvert eksempel
  • En beskrivelse af konflikten, der forklarer, hvordan eksemplerne adskiller sig
  • En konfidensscore, der angiver pålideligheden af konfliktdetektionen

Brug denne detaljerede visning til at forstå, hvilke eksempler der er i konflikt og hvorfor, samt til at afgøre, hvilke eksempler der skal opdateres 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 konfliktdetektionsoutputtet, deres tilknyttede spørgsmål og SQL samt konfidensniveauet for hver opdaget konflikt.

Skærmbillede af konfliktdetektion.

Forstå validatorscore

Når du kører validatoren på dine eksempelforespørgsler, genererer den tre nøglescorer for hvert eksempel: Klarhed, Slægtskab og Tilknytning. Disse resultater er afledt af, hvor godt dine spørgsmål og SQL-forespørgsler stemmer overens med bedste praksis.

  • Klarhed
    Måler, om spørgsmålet om naturligt sprog er klart og utvetydigt. Spørgsmålene skal være specifikke, indeholde nødvendige målinger, tidsrammer og filtre og undgå vage eller multi-intent formuleringer.

    Eksempel – Godt: "Samlet omsætning efter region for 2024."
    Eksempel – Behov for forbedring: "Show-optræden."

  • Slægtskab
    Evaluerer, hvor tæt SQL-forespørgslen svarer til hensigten med spørgsmålet om naturligt sprog. SQL skal returnere den korrekte metrikværdi, anvende de korrekte filtre og matche den ønskede granularitet.

    Eksempel – God: Et spørgsmål beder om optælling af kunder i marts 2025 , → SQL tæller kunder med WHERE month='2025-03'.
    Eksempel – Skal forbedres: Et spørgsmål beder om antal, men SQL'en returnerer SUM(omsætning) eller filtrerer en anden periode.

  • Kortlægning
    Kontrollerer, om alle konstanter i spørgsmålet om naturligt sprog vises i SQL-forespørgslen. Hvert tal, dato eller kategori, der er nævnt i spørgsmålet, skal eksplicit repræsenteres i SQL.

    Eksempel – Godt: "Ordrer over 100 i marts 2025 for 'West'" → SQL inkluderer > 100, 2025-03, og 'West'.
    Eksempel – Behov for forbedring: SQL mangler en af disse literals (for eksempel ingen månedsfilter).

Et eksempel betragtes kun som høj kvalitet , hvis alle tre scorer – Klarhed, Slægtskab og Kortlægning – er positive. Brug disse scorer til at indsnævre dine eksempelforespørgsler: omskriv uklare spørgsmål, juster SQL tættere på spørgsmålets hensigt, og sørg for, at alle konstanter i spørgsmålet vises i SQL-forespørgslen. Denne iterative proces hjælper Data Agent med at lære af bedre mønstre og producere mere nøjagtige resultater.

Næste trin

  • Last updated on