Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Beispielabfragen (auch als "Few-Shot-Beispiele" bezeichnet) geben dem Datenagenten konkrete Muster, aus denen sie lernen können. Sie sind Beispielfragen und die entsprechende Abfragelogik, die Ersteller bereitstellen, um zu unterstützen, wie der Agent antworten soll. Wenn ein Benutzer eine Frage gegen eine Datenquelle stellt, ruft der Daten-Agent automatisch die relevantesten Beispiele ab – in der Regel die obersten vier – und leitet sie in den Generierungsprozess ein. Durch Verweise auf diese Beispiele kann der Agent die erwartete Struktur, Filter und Verknüpfungen besser verstehen, wodurch sie präzisere, konsistentere und kontextbezogene Abfrageergebnisse erzielen kann.
Bereitstellen von Beispielabfragen
Wenn Sie Beispielabfragen bereitstellen, müssen Sie sowohl eine Frage in natürlicher Sprache als auch die entsprechende Abfrageantwort einschließen. Jede Frage sollte eindeutig sein, um dem Datenagenten eine vielzahl von Referenzpunkten zu geben. Jede Beispielabfrage wird anhand des Schemas der ausgewählten Datenquelle überprüft– Abfragen, die die Überprüfung nicht bestehen, werden nicht an den Agent gesendet. Um sicherzustellen, dass Ihre Beispiele verwendet werden, müssen sie diesen Überprüfungsschritt bestätigen.
Die Tabelle zeigt, welche Datenquellen derzeit Beispielabfragen im Daten-Agent unterstützen. In diesen Beispielen wird der Abfragegenerierungsprozess des Agents durch die Bereitstellung von Mustern und Kontext unterstützt.
| Datenquellentyp | Unterstützt Beispielabfragen? |
|---|---|
| Lakehouse | ✅ Ja |
| Lagerhalle | ✅ Ja |
| Eventhouse-KQL-Datenbanken | ✅ Ja |
| Semantische Modelle | ❌ Nein |
| Ontologie | ❌ Nein |
Sie können auch die Ansicht "Ausführungsschritte " verwenden, um zu debuggen, welche Beispielabfragen abgerufen und auf die Frage eines Benutzers angewendet wurden. Diese Ansicht ist besonders hilfreich, um zu bestätigen, dass die richtigen Beispiele verwendet werden, und um zu diagnostizieren, warum bestimmte Ergebnisse generiert werden. Wenn die falschen Beispiele angezeigt werden, versuchen Sie, Ihre Fragen zu verfeinern oder klarere, gezieltere Beispiele hinzuzufügen.
Bewährte Methoden zum Schreiben von Beispielabfragen
Beim Erstellen von Beispielabfragen für den Daten-Agent stellen die folgenden bewährten Methoden sicher, dass sie während der Abfragegenerierung klare, zuverlässige Anleitungen bereitstellen. Gut gestaltete Beispiele helfen dem Agent zu verstehen, wie Fragen in natürlicher Sprache in SQL/KQL-Logik übersetzt werden, komplexe Verknüpfungen oder Berechnungen hervorheben und die Genauigkeit seiner Ergebnisse verbessern. Verwenden Sie die Richtlinien, um Ihre Beispiele effektiver und repräsentativer für reale Benutzerszenarien zu machen.
| # | Bewährte Methode | Warum es wichtig ist |
|---|---|---|
| 1 | Stellen Sie sicher, dass Fragen der Abfrage eindeutig zugeordnet sind. | Der Daten-Agent verwendet diese Beispiele, um das Muster zwischen der Frage und dem resultierenden SQL/KQL zu erlernen. Mehrdeutigkeit reduziert die Genauigkeit. |
| 2 | Fügen Sie Kommentare in die Abfrage ein, um den Agent zu leiten | Kommentare ( -- substitute customer_id here) helfen dem Agent zu verstehen, wo Werte ersetzt oder wichtige Logik angewendet werden sollen. |
| 3 | Hervorheben von Verknüpfungslogik oder komplexen Mustern | Verwenden Sie Beispielabfragen, um zu zeigen, wie Multi-Table-Verknüpfungen, Aggregationen oder andere erweiterte Logik behandelt werden, die in einfachen Anweisungen schwer zu beschreiben ist. |
| 4 | Überlappungen oder Widersprüche vermeiden | Jedes Beispiel sollte eindeutig und nicht widersprüchlich sein, damit der Agent ein klares Signal für das Verhalten erhält. |
| 5 | Führen Sie die Schritte aus, um zu debuggen, welche Beispiele übergeben werden. | Mit den Schritten können Sie sehen, welche Beispiele für eine bestimmte Benutzerfrage abgerufen wurden . Wenn die falschen angezeigt werden, passen Sie Ihre Fragen an, oder fügen Sie spezifischere Beispiele hinzu. |
| 6 | Wiedergeben des tatsächlichen Benutzerverhaltens | Fügen Sie Beispielabfragen hinzu, die die Arten von Fragen darstellen, die Ihre Benutzer stellen, um die Relevanz und Genauigkeit zu maximieren. |
Überprüfen von Beispielabfragen
Das Fabric Data Agent SDK bietet integrierte Tools zum Auswerten und Verbessern der Qualität Ihrer Beispielabfragen. Mithilfe der evaluate_few_shots Funktion können Sie jedes natürliche Sprache/SQL-Paar überprüfen, um zu bestätigen, dass es klar, richtig und mit dem Datenquellenschema ausgerichtet ist. Das SDK führt jedes Beispiel durch den Evaluierungsprozess des Datenagenten und gibt eine detaillierte Zusammenfassung zurück, welche Beispiele bestanden haben und welche einer Verfeinerung bedürfen.
Bereitstellen von Beispielabfragen
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")
Auswerten über DAS SDK
Durch die Überprüfung der Erfolgsquote und des Feedbacks können Sie Ihre Beispiele iterativ anpassen – Fragen klären, SQL-Logik verbessern oder Kommentare hinzufügen – sodass der Daten-Agent aus mustern höherer Qualität lernt und genauere Ergebnisse für neue Fragen erzeugt.
# 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})")
Nachverfolgen von Feedback
Nachdem Sie den Validator ausgeführt haben, erhalten Sie eine klare Aufschlüsselung der Beispiele, die bestanden haben, und derjenigen, die fehlgeschlagen sind. Dieses Feedback erleichtert ihnen die Identifizierung von Stärken und Schwächen in Ihren wenigen Beispielen.
- Erfolgsfälle: Beispiele, in denen die SQL mit den erwarteten Antworten übereinstimmte. Diese Beispiele sind starke Verweise, nach denen Sie zukünftige Beispiele modellieren können.
- Fehlerfälle: Beispiele, bei denen die SQL nicht mit der erwarteten Antwort übereinstimmt oder wo das Frage-/Abfragepaar unklar oder ungültig sein kann. Diese Fälle sollten überprüft und optimiert werden.
# 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
Verwenden Sie dieses Feedback, um Ihre Beispielabfragen zu iterieren und zu verbessern. Die regelmäßige Stärkung schwächerer Beispiele hilft dem Daten-Agent, präzisere SQL und Antworten im Laufe der Zeit zu erzeugen.
Um ein vollständiges Arbeitsbeispiel zu erkunden, können Sie das Beispielnotizbuch im GitHub-Repository des Fabric Data Agent SDK auschecken:
Hinweis
Dieses Auswertungshilfsprogramm ist derzeit nur für SQL-basierte Beispielabfragen verfügbar. KQL oder andere Abfragetypen werden noch nicht unterstützt.
Erkennen von Konflikten zwischen Beispielabfragen
Sobald die Qualitätsüberprüfung abgeschlossen ist, führt das Evaluierungs-SDK automatisch eine Konflikterkennung für die genehmigten Beispielabfragen oder Few-Shot-Beispiele durch. Die Konflikterkennung identifiziert Inkonsistenzen, die dazu führen können, dass der Daten-Agent unvorhersehbare oder falsche Ergebnisse erzeugt.
Ein Konflikt wird erkannt, wenn zwei oder mehr Beispiele:
- Stellen Sie dieselbe Absicht dar (basierend auf einer normalisierten Version der Frage in natürlicher Sprache), verweisen sie jedoch auf verschiedene Tabellen oder Ansichten.
- Berechnen derselben Metrik mithilfe unterschiedlicher Aggregationslogik oder unterschiedlicher Granularitätsebenen
- Generieren von SQL-Abfragen, die für dieselbe Geschäftsfrage materialunterschiedliche Ergebnisse zurückgeben würden
Diese Konflikte deuten auf Mehrdeutigkeit oder Inkonsistenz in bereitgestellten Few-Shot-Beispielen hin. Durch das Beheben dieser Probleme können Sie den Abfragedeterminismus, die Genauigkeit und das allgemeine Verhalten des Agents verbessern.
Überprüfen von Konfliktdetails
Wenn Konflikte erkannt werden, erweitert das SDK jeden Konflikt zu Zeilen für jedes Beispiel und stellt detaillierte Diagnosen bereit, einschließlich:
- Die an dem Konflikt beteiligten Beispiele
- Die Frage der natürlichen Sprache und die entsprechende SQL-Datei für jedes Beispiel
- Eine Beschreibung des Konflikts, in dem erläutert wird, wie sich die Beispiele unterscheiden
- Eine Konfidenzbewertung, die die Zuverlässigkeit der Konflikterkennung angibt
Verwenden Sie diese detaillierte Ansicht, um zu verstehen, welche Beispiele in Konflikt stehen und warum, und um zu bestimmen, welche Beispiele aktualisiert oder entfernt werden sollen.
# 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.")
Das folgende Beispiel zeigt die Ausgabe der Konflikterkennung, die zugehörigen Fragen und das dazugehörige SQL sowie das Konfidenzniveau jedes erkannten Konflikts.
Grundlegendes zu Validatorbewertungen
Wenn Sie den Validator für Ihre Beispielabfragen ausführen, werden für jedes Beispiel drei Schlüsselergebnisse generiert: Clarity, Relatedness und Mapping. Diese Bewertungen werden davon abgeleitet, wie gut Ihre Fragen in natürlicher Sprache und SQL-Abfragen mit bewährten Methoden übereinstimmen.
Klarheit
Misst, ob die natürlichsprachliche Frage klar und eindeutig ist. Fragen sollten spezifisch sein, erforderliche Metriken, Zeitrahmen und Filter enthalten und vage oder Multi-Intent-Ausdrücke vermeiden.Beispiel – Gut: "Gesamteinnahmen nach Region für 2024."
Beispiel – Verbesserungsbedarf: "Leistung anzeigen."Verwandtschaft
Wertet aus, wie genau die SQL-Abfrage mit der Absicht der Frage der natürlichen Sprache übereinstimmt. Sql sollte die richtige Metrik zurückgeben, die richtigen Filter anwenden und der angeforderten Granularität entsprechen.Beispiel – Gut: Eine Frage stellt die Anzahl der Kunden im März 2025 → SQL zählt Kunden mit
WHERE month='2025-03'.
Beispiel – Verbesserung erforderlich: Eine Frage fragt nach der Anzahl, aber die SQL gibt SUM(Umsatz) zurück oder filtert einen anderen Zeitraum.Abbildung
Überprüft, ob alle Literale in der Frage der natürlichen Sprache in der SQL-Abfrage angezeigt werden. Jede Zahl, jedes Datum oder jede kategorie, die in der Frage erwähnt wird, sollte in sql explizit dargestellt werden.Beispiel – Gut: "Aufträge über 100 im März 2025 für 'West'" → SQL umfasst
> 100,2025-03und'West'.
Beispiel – Verbesserung der Bedürfnisse: SQL fehlt eines dieser Literale (z. B. kein Monatsfilter).
Ein Beispiel gilt nur dann als hohe Qualität , wenn alle drei Bewertungen – Klarheit, Verwandte und Zuordnung – positiv sind. Verwenden Sie diese Bewertungen, um Ihre Beispielabfragen zu verfeinern: Schreiben Sie unklare Fragen neu, richten Sie SQL genauer mit der Frageabsicht aus, und stellen Sie sicher, dass jedes Literal in der Frage in der SQL-Abfrage angezeigt wird. Dieser iterative Prozess hilft dem Daten-Agent, aus besseren Mustern zu lernen und genauere Ergebnisse zu erzielen.