Voorbeeldvragen

Voorbeeldquery's (ook wel 'paar-shot-voorbeelden' genoemd) geven de gegevensagent concrete patronen om van te leren. Ze zijn voorbeeldvragen en de bijbehorende querylogica die makers leveren om te bepalen hoe de agent moet reageren. Wanneer een gebruiker een vraag stelt op basis van een gegevensbron, haalt de gegevensagent automatisch de meest relevante voorbeelden op, meestal de top vier, en voert deze in het generatieproces. Door te verwijzen naar deze voorbeelden, kan de agent beter inzicht krijgen in de verwachte structuur, filters en joins, zodat deze nauwkeurigere, consistentere en contextbewuste queryresultaten kan produceren.

Voorbeeldquery's opgeven

Wanneer u voorbeeldquery's opgeeft, moet u zowel een vraag in natuurlijke taal als het bijbehorende queryantwoord opnemen. Elke vraag moet uniek zijn om de gegevensagent een diverse set referentiepunten te geven. Elke voorbeeldquery wordt gevalideerd op basis van het schema van de geselecteerde gegevensbron. Query's die niet worden gevalideerd, worden niet naar de agent verzonden. Om ervoor te zorgen dat uw voorbeelden worden gebruikt, is het essentieel om te bevestigen dat ze deze validatiestap passeren.

In de tabel ziet u welke gegevensbronnen momenteel voorbeeldquery's ondersteunen in de gegevensagent. Deze voorbeelden helpen het proces voor het genereren van query's van de agent te begeleiden door patronen en context op te geven.

U kunt ook de weergave uitvoeringsstappen gebruiken om fouten op te sporen in welke voorbeeldquery's zijn opgehaald en toegepast op de vraag van een gebruiker. Deze weergave is vooral handig om te bevestigen dat de juiste voorbeelden worden gebruikt en om te diagnosticeren waarom bepaalde resultaten worden gegenereerd. Als de verkeerde voorbeelden worden weergegeven, verfijnt u uw vragen of voegt u duidelijkere, gerichtere voorbeelden toe.

Aanbevolen procedures voor het schrijven van voorbeeldquery's

Wanneer u voorbeeldquery's voor de gegevensagent maakt, zorgt de volgende aanbevolen procedures ervoor dat ze duidelijke, betrouwbare richtlijnen bieden tijdens het genereren van query's. Goed ontworpen voorbeelden helpen de agent te begrijpen hoe vragen in natuurlijke taal worden omgezet in SQL/KQL-logica, complexe joins of berekeningen markeren en de nauwkeurigheid van de resultaten verbeteren. Gebruik de richtlijnen om uw voorbeelden effectiever en representatiever te maken voor echte gebruikersscenario's.

Voorbeeldquery's valideren

De Fabric Data Agent SDK biedt ingebouwde hulpprogramma's om de kwaliteit van uw voorbeeldquery's te evalueren en te verbeteren. Met behulp van de evaluate_few_shots functie kunt u elke natuurlijke taal/SQL-paar valideren om te bevestigen dat het duidelijk, juist en afgestemd is op uw gegevensbronschema. De SDK voert elk voorbeeld uit via het evaluatieproces van de Gegevensagent, waarmee een gedetailleerd overzicht wordt geretourneerd van welke voorbeelden zijn doorgegeven en welke verfijning nodig is.

Voorbeeldquery's opgeven

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

Evalueren via SDK

Door het slagingspercentage en de feedback te bekijken, kunt u uw voorbeelden iteratief aanpassen( vragen verduidelijken, SQL-logica verbeteren of opmerkingen toevoegen), zodat de Data Agent leert van patronen van hogere kwaliteit en nauwkeurigere resultaten produceert voor nieuwe vragen.

# 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 bijhouden

Nadat u de validator hebt uitgevoerd, ontvangt u een duidelijke uitsplitsing van welke voorbeelden zijn doorgegeven en welke mislukt. Met deze feedback kunt u eenvoudig sterke en zwakke punten identificeren in uw few-shot voorbeelden.

• Geslaagde gevallen: Voorbeelden waarbij de SQL overeenkomt met de verwachte antwoorden. Deze voorbeelden zijn sterke verwijzingen waarnaar u toekomstige voorbeelden kunt modelleren.
• Foutcases: Voorbeelden waarbij de SQL niet overeenkomt met het verwachte antwoord of waarbij het vraag-/querypaar onduidelijk of ongeldig kan zijn. Deze gevallen moeten worden herzien en verfijnd.

# 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

Gebruik deze feedback om uw voorbeeldquery's te herhalen en te verbeteren . Het regelmatig versterken van zwakkere voorbeelden helpt de Data Agent in de loop van de tijd nauwkeurigere SQL en antwoorden te produceren.

Als u een volledig werkend voorbeeld wilt verkennen, kunt u het voorbeeldnotebook bekijken in de GitHub-opslagplaats van de Fabric Data Agent SDK:

Conflicten tussen voorbeeldquery's detecteren

Nadat de kwaliteitsvalidatie is voltooid, voert de Evaluatie-SDK automatisch conflictdetectie uit op de goedgekeurde voorbeeldquery's of enkele voorbeelden. Conflictdetectie identificeert inconsistenties die ertoe kunnen leiden dat de gegevensagent onvoorspelbare of onjuiste resultaten produceert.

Er wordt een conflict gedetecteerd wanneer twee of meer voorbeelden:

• Vertegenwoordig dezelfde intentie (op basis van een genormaliseerde versie van de vraag in natuurlijke taal) maar verwijst naar verschillende tabellen of weergaven
• Dezelfde metrische gegevens berekenen met behulp van verschillende aggregatielogica of verschillende granulariteitsniveaus
• SQL-query's genereren die materiaal verschillende resultaten opleveren voor dezelfde bedrijfsvraag

Deze conflicten duiden op dubbelzinnigheid of inconsistentie binnen enkele few-shot voorbeelden. Door ze op te lossen kunt u het determinisme, de nauwkeurigheid en het algemene gedrag van de agent verbeteren.

Conflictgegevens bekijken

Wanneer er conflicten worden gedetecteerd, breidt de SDK elk conflict uit in rijen per voorbeeld, met gedetailleerde diagnostische gegevens, waaronder:

• De voorbeelden die betrokken zijn bij het conflict
• De vraag in natuurlijke taal en de bijbehorende SQL voor elk voorbeeld
• Een beschrijving van het conflict waarin wordt uitgelegd hoe de voorbeelden afwijken
• Een betrouwbaarheidsscore die de betrouwbaarheid van de conflictdetectie aangeeft

Gebruik deze gedetailleerde weergave om te begrijpen welke voorbeelden conflicteren en waarom, en om te bepalen welke voorbeelden moeten worden bijgewerkt of verwijderd.

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

In het volgende voorbeeld ziet u de uitvoer van conflictdetectie, de bijbehorende vragen en SQL en het betrouwbaarheidsniveau van elk gedetecteerd conflict.

Validatorscores begrijpen

Wanneer u de validatie uitvoert op uw voorbeeldquery's, worden er drie belangrijke scores gegenereerd voor elk voorbeeld: Clarity, Relatedness en Mapping. Deze scores zijn afgeleid van hoe goed uw vragen in natuurlijke taal en SQL-query's overeenkomen met best practices.

• Duidelijkheid
  Meet of de vraag in natuurlijke taal duidelijk en ondubbelzinnig is. Vragen moeten specifiek zijn, vereiste metrische gegevens, tijdsbestekken en filters bevatten en vage formuleringen met meerdere intenties voorkomen.

  Voorbeeld : goed: "Totale omzet per regio voor 2024."
  Voorbeeld: verbetering van behoeften: 'Prestaties weergeven'.

• Verwantschap
  Evalueert hoe dicht de SQL-query overeenkomt met de intentie van de vraag in natuurlijke taal. De SQL moet de juiste metrische gegevens retourneren, de juiste filters toepassen en overeenkomen met de aangevraagde granulariteit.

  Voorbeeld : goed: Een vraag vraagt om het aantal klanten in maart 2025 → SQL telt klanten met WHERE month='2025-03'.
  Voorbeeld: verbetering van behoeften: Een vraag vraagt om aantal, maar de SQL retourneert SUM(revenue) of filtert een andere periode.

• In kaart brengen
  Hiermee wordt gecontroleerd of alle letterlijke gegevens in de vraag in natuurlijke taal worden weergegeven in de SQL-query. Elk getal, elke datum of categorie die in de vraag wordt genoemd, moet expliciet worden weergegeven in de SQL.

  Voorbeeld – Goed: "Orders boven de 100 in maart 2025 voor 'West'" → SQL bevat > 100, 2025-03, en 'West'.
  Voorbeeld: verbetering van behoeften: SQL ontbreekt een van deze letterlijke waarden (bijvoorbeeld geen maandfilter).

Een voorbeeld wordt alleen als een hoge kwaliteit beschouwd als alle drie de scores ( Clarity, Relatedness en Mapping) positief zijn. Gebruik deze scores om uw voorstelquery's te verfijnen: herschrijf onduidelijke vragen, stem de SQL beter af op de intentie van de vraag en zorg ervoor dat elke letterlijke tekst in de vraag verschijnt in de SQL-query. Dit iteratieve proces helpt de Data Agent te leren van betere patronen en nauwkeurigere resultaten te produceren.

Volgende stappen

• Concept van gegevensagent
• Scenario voor gegevensagent
• Sample notebook voor het valideren van voorbeeldqueries