Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Les exemples de requêtes (également appelés « exemples à quelques prises ») fournissent à l'Agent de données des modèles concrets pour apprendre. Il s’agit d’exemples de questions et de leur logique de requête correspondante que les créateurs fournissent pour guider la façon dont l’agent doit répondre. Lorsqu’un utilisateur pose une question à une source de données, l’Agent de données récupère automatiquement les exemples les plus pertinents( généralement les quatre premiers) et les alimente dans son processus de génération. En référençant ces exemples, l’agent peut mieux comprendre la structure, les filtres et les jointures attendus, ce qui lui permet de produire des résultats de requête plus précis, cohérents et prenant en charge le contexte.
Fournir des exemples de requêtes
Lorsque vous fournissez des exemples de requêtes, vous devez inclure à la fois une question en langage naturel et sa réponse de requête correspondante. Chaque question doit être unique pour donner à l’Agent de données un ensemble diversifié de points de référence. Chaque exemple de requête est validé par rapport au schéma de la source de données sélectionnée, les requêtes qui ne passent pas de validation ne sont pas envoyées à l’agent. Pour vous assurer que vos exemples sont utilisés, il est essentiel de confirmer qu’ils réussissent cette étape de validation.
Le tableau indique quelles sources de données prennent actuellement en charge des exemples de requêtes dans l’Agent de données. Ces exemples aident à guider le processus de génération de requêtes de l’agent en fournissant des modèles et un contexte.
| Type de source de données | Prend en charge des exemples de requêtes ? |
|---|---|
| Lakehouse | ✅ Oui |
| Entrepôt | ✅ Oui |
| Bases de données Eventhouse KQL | ✅ Oui |
| Modèles sémantiques | ❌ Non |
| Ontologie | ❌ Non |
Vous pouvez également utiliser la vue des étapes d’exécution pour déboguer les exemples de requêtes récupérés et appliqués à la question d’un utilisateur. Cette vue est particulièrement utile pour confirmer que les bons exemples sont utilisés et pour diagnostiquer la raison pour laquelle certains résultats sont générés. Si les exemples incorrects apparaissent, essayez d’affiner vos questions ou d’ajouter des exemples plus clairs, plus ciblés.
Meilleures pratiques pour l’écriture d’exemples de requêtes
Lors de la création d’exemples de requêtes pour l’Agent de données, les bonnes pratiques suivantes garantissent qu’elles fournissent des conseils clairs et fiables pendant la génération de requêtes. Les exemples bien conçus aident l’agent à comprendre comment les questions en langage naturel se traduisent en logique SQL/KQL, mettent en évidence des jointures ou des calculs complexes et améliorent la précision de ses résultats. Utilisez les instructions pour rendre vos exemples plus efficaces et représentatifs des scénarios d’utilisateurs réels.
| # | Meilleure Pratique | Pourquoi cela importe |
|---|---|---|
| 1 | Vérifier que les questions correspondent clairement à la requête | L’Agent de données utilise ces exemples pour apprendre le modèle entre la question et le SQL/KQL résultant. L’ambiguïté réduit la précision. |
| 2 | Inclure des commentaires dans la requête pour guider l’agent | Les commentaires ( -- substitute customer_id here) aident l’agent à comprendre où remplacer les valeurs ou appliquer une logique importante. |
| 3 | Mettre en surbrillance la logique de jointure ou les modèles complexes | Utilisez des exemples de requêtes pour montrer comment gérer des jointures à plusieurs tables, des agrégations ou d’autres logiques avancées difficiles à décrire dans des instructions simples. |
| 4 | Éviter les chevauchements ou les contradictions | Chaque exemple doit être distinct et non conflictuel pour donner à l’agent un signal propre de comportement. |
| 5 | Utiliser les étapes d’exécution pour déboguer les exemples passés | Les étapes d’exécution vous permettent de voir quels exemples ont été récupérés pour une question utilisateur donnée : si les erreurs s’affichent, ajustez vos questions ou ajoutez des exemples plus spécifiques. |
| 6 | Refléter le comportement réel de l’utilisateur | Ajoutez des exemples de requêtes qui représentent les types de questions que vos utilisateurs posent pour optimiser la pertinence et la précision. |
Valider des exemples de requêtes
Le SDK Fabric Data Agent fournit des outils intégrés pour évaluer et améliorer la qualité de vos exemples de requêtes. À l’aide de la evaluate_few_shots fonction, vous pouvez valider chaque paire de langage naturel/SQL pour confirmer qu’elle est claire, correcte et alignée avec votre schéma de source de données. Le Kit de développement logiciel (SDK) exécute chaque exemple via le processus d’évaluation de l’Agent de données, en retournant un résumé détaillé des exemples passés et nécessitant un affinement.
Fournir des exemples de requêtes
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")
Évaluer par le biais du Kit de développement logiciel (SDK
En examinant le taux de réussite et les commentaires, vous pouvez ajuster de manière itérative vos exemples ( clarifier les questions, améliorer la logique SQL ou ajouter des commentaires) afin que l’Agent de données apprenne à partir de modèles de qualité supérieure et génère des résultats plus précis pour de nouvelles questions.
# 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})")
Suivre les commentaires
Après avoir exécuté le validateur, vous recevrez une répartition claire des exemples passés et qui ont échoué. Ces commentaires facilitent l’identification des forces et des faiblesses dans vos exemples à faible nombre de données.
- Cas de réussite : Exemples où sql correspond aux réponses attendues. Ces exemples sont des références fortes après lesquelles vous pouvez modéliser des exemples futurs.
- Cas d’échec : Exemples où le sql ne correspond pas à la réponse attendue, ou où la paire question/requête peut ne pas être claire ou non valide. Ces cas doivent être examinés et affinés.
# 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
Utilisez ces commentaires pour itérer et améliorer vos exemples de requêtes. Renforcer régulièrement les exemples de moindre robustesse aidera l’Agent de données à produire des réponses plus précises et SQL au fil du temps.
Pour explorer un exemple fonctionnel complet, vous pouvez consulter l'exemple de notebook dans le dépôt GitHub du SDK Fabric Data Agent.
Note
Cet utilitaire d’évaluation est actuellement disponible uniquement pour les exemples de requêtes SQL. KQL ou d’autres types de requête ne sont pas encore pris en charge.
Détecter les conflits entre des exemples de requêtes
Une fois la validation de qualité terminée, le Kit de développement logiciel (SDK) d’évaluation effectue automatiquement la détection des conflits sur les exemples approuvés de requêtes ou exemples de few-shot. La détection de conflit identifie les incohérences qui peuvent entraîner la production de résultats imprévisibles ou incorrects par l’Agent de données.
Un conflit est détecté quand deux exemples ou plus sont :
- Représenter la même intention (basée sur une version normalisée de la question du langage naturel), mais référencer différentes tables ou vues
- Calculez la même métrique à l’aide d’une logique d’agrégation différente ou de différents niveaux de granularité
- Générer des requêtes SQL qui retournent des résultats matériellement différents pour la même question métier
Ces conflits indiquent l’ambiguïté ou l’incohérence dans quelques exemples de tir fournis. Les résoudre permettent d’améliorer le déterminisme des requêtes, la précision et le comportement global de l’agent.
Passer en revue les détails des conflits
Lorsque des conflits sont détectés, le Kit de développement logiciel (SDK) développe chaque conflit en lignes individuelles pour chaque exemple, fournissant ainsi des diagnostics détaillés, notamment :
- Les exemples impliqués dans le conflit
- Question du langage naturel et SQL correspondant pour chaque exemple
- Description du conflit expliquant comment les exemples diffèrent
- Score de confiance indiquant la fiabilité de la détection des conflits
Utilisez cette vue détaillée pour comprendre quels exemples sont en conflit et pourquoi, et pour déterminer quels exemples doivent être mis à jour ou supprimés.
# 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.")
L’exemple suivant montre la sortie de détection de conflit, leurs questions associées et SQL, ainsi que le niveau de confiance de chaque conflit détecté.
Comprendre les scores de validateur
Lorsque vous exécutez le validateur sur vos exemples de requêtes, il génère trois scores clés pour chaque exemple : Clarté, Relation et Mappage. Ces scores sont dérivés de la façon dont vos questions en langage naturel et vos requêtes SQL s’alignent sur les meilleures pratiques.
Clarté
Mesure si la question du langage naturel est claire et non ambiguë. Les questions doivent être spécifiques, inclure les métriques nécessaires, les délais et les filtres, et éviter la formulation vague ou multi-intention.Exemple : Bon : « Chiffre d’affaires total par région pour 2024 ».
Exemple – Amélioration des besoins : « Afficher les performances ».Connexité
Évalue la précision de la requête SQL correspondant à l’intention de la question du langage naturel. Sql doit retourner la métrique correcte, appliquer les filtres appropriés et correspondre à la granularité demandée.Exemple : Bon : Une question demande le nombre de clients en mars 2025 → SQL compte les clients avec
WHERE month='2025-03'.
Exemple – Amélioration des besoins : Une question demande le nombre, mais le SQL retourne SUM(revenue) ou filtre une période différente.Cartographie
Vérifie si tous les littéraux de la question du langage naturel apparaissent dans la requête SQL. Chaque nombre, date ou catégorie mentionné dans la question doit être représenté explicitement dans le SQL.Exemple : Bon : « Commandes supérieures à 100 en mars 2025 pour « West » → SQL inclut
> 100,2025-03et'West'.
Exemple – Amélioration des besoins : SQL manque l’un de ces littéraux (par exemple, aucun filtre de mois).
Un exemple est considéré comme de haute qualité uniquement si les trois scores (Clarté, Relation et Mappage) sont positifs. Utilisez ces scores pour affiner vos exemples de requêtes : réécrire des questions peu claires, aligner sql plus étroitement avec l’intention de la question et vérifier que chaque littéral de la question apparaît dans la requête SQL. Ce processus itératif aide l’Agent de données à apprendre à partir de meilleurs modèles et à produire des résultats plus précis.