クエリの例（「数ショットの例」とも呼ばれます）は、学習するデータエージェントに具体的なパターンを提示します。 これらは、サンプルの質問とそれに対応するクエリ ロジックであり、作成者はエージェントの応答方法をガイドするために提供します。 ユーザーがデータ ソースに対して質問をすると、データ エージェントは最も関連性の高い例 (通常は上位 4 つ) を自動的に取得し、生成プロセスにフィードします。 これらの例を参照することで、エージェントは予想される構造、フィルター、結合について理解を深めることができます。これにより、より正確で一貫性があり、コンテキストに対応したクエリ結果が生成されます。
クエリの例を指定する
クエリの例を提供する場合は、自然言語の質問とそれに対応するクエリ回答の両方を含める必要があります。 各質問は、データ エージェントにさまざまな参照ポイントのセットを提供するために一意である必要があります。 すべてのサンプル クエリは、選択したデータ ソースのスキーマに対して検証されます。検証に合格しないクエリはエージェントに送信されません。 例を確実に使用するには、この検証手順に合格していることを確認する必要があります。
次の表は、データ エージェントのサンプル クエリを現在サポートしているデータ ソースを示しています。 これらの例は、パターンとコンテキストを提供することで、エージェントのクエリ生成プロセスをガイドするのに役立ちます。
| データ ソースの種類 | サンプル クエリをサポートしていますか? |
|---|---|
| Lakehouse | ✅ はい |
| 倉庫 | ✅ はい |
| Eventhouse KQL データベース | ✅ はい |
| セマンティック モデル | ❌ いいえ |
| オントロジ | ❌ いいえ |
ステップ実行ビューを使用して、どのクエリの例が取得され、ユーザーの質問に適用されたかをデバッグすることもできます。 このビューは、適切な例が使用されていることを確認したり、特定の結果が生成されている理由を診断したりするのに特に役立ちます。 間違った例が表示される場合は、質問を絞り込むか、より明確で対象を絞った例を追加してみてください。
クエリの例を記述するためのベスト プラクティス
データ エージェントのクエリ例を作成する場合、ベスト プラクティスに従うと、クエリの生成中に明確で信頼性の高いガイダンスが提供されます。 適切に作成された例は、自然言語の質問が SQL/KQL ロジックにどのように変換されるかをエージェントが理解し、複雑な結合または計算を強調表示し、結果の精度を向上させるのに役立ちます。 ガイドラインを使用して、実際のユーザー シナリオのより効果的で代表的な例を作成します。
| # | ベスト プラクティス | 重要な理由 |
|---|---|---|
| 1 | 質問がクエリに明確にマップされていることを確認する | データ エージェントでは、これらの例を使用して、質問と結果の SQL/KQL の間のパターンを学習します。 あいまいさは精度を低下させます。 |
| 2 | エージェントをガイドするためのコメントをクエリに含める | コメント ( -- substitute customer_id here) は、エージェントが値を置き換えるか、重要なロジックを適用する場所を理解するのに役立ちます。 |
| 3 | 結合ロジックまたは複雑なパターンを強調表示する | クエリ例を使用して、複数テーブルの結合、集計、または単純な手順では説明しにくいその他の高度なロジックを処理する方法を示します。 |
| 4 | 重複や矛盾を避ける | 各例は、エージェントに動作方法のクリーンなシグナルを提供するために、個別で競合しない必要があります。 |
| 5 | 実行手順を使用して、渡される例をデバッグする | 実行手順を使用すると、特定のユーザーの質問について取得された例を確認できます。間違った質問が表示された場合は、質問を調整するか、より具体的な例を追加します。 |
| 6 | 実際のユーザーの動作を反映する | 関連性と精度を最大化するためにユーザーが尋ねる質問の種類を表すクエリの例を追加します。 |
クエリの例を検証する
Fabric Data Agent SDK には、 サンプル クエリの品質を評価して改善するための組み込みのツールが用意されています。
evaluate_few_shots関数を使用すると、各自然言語と SQL のペアを検証して、データ ソース スキーマが明確で、正しく、配置されていることを確認できます。 SDK は、データ エージェントの評価プロセスを通じて各例を実行し、渡された例と絞り込みを必要とする例の詳細な概要を返します。
クエリの例を指定する
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")
SDK を使用して評価する
成功率とフィードバックを確認することで、質問の明確化、SQL ロジックの改善、コメントの追加など、サンプルを繰り返し調整できるため、データ エージェントはより高品質のパターンから学習し、新しい質問に対してより正確な結果を生成できます。
# 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})")
フィードバックを追跡する
検証コントロールを実行すると、合格した例と失敗 した 例の明確な内訳が表示 されます。 このフィードバックにより、少数の例で長所と短所を簡単に特定できます。
- 成功事例: SQL が予想される回答と一致した例。 これらの例は、後で将来の例をモデル化できる強力な参照です。
- エラーのケース: SQL が予想される回答と一致しなかった場合、または質問とクエリのペアが不明または無効である可能性がある例。 これらのケースを確認し、洗練する必要があります。
# 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
このフィードバックを使用して、クエリの例を 反復処理して改善 します。 弱い例を定期的に強化することで、データ エージェントは時間の経過とともにより正確な SQL と回答を生成できます。
完全に動作する例を調べるには、 Fabric Data Agent SDK GitHub リポジトリのサンプル ノートブックを確認してください。
注
この評価ユーティリティは、現在、 SQL ベースのサンプル クエリでのみ使用できます。 KQL またはその他のクエリの種類はまだサポートされていません。
サンプル クエリ間の競合を検出する
品質検証が完了すると、Evaluation SDK は、承認されたサンプル クエリまたは少数の例に対して 競合検出 を自動的に実行します。 競合検出では、データ エージェントが予期しない、または正しくない結果を生成する可能性がある不整合を特定します。
競合は、次の 2 つ以上の例で検出されます。
- (自然言語の質問の正規化されたバージョンに基づいて) 同じ意図を表しますが、異なるテーブルまたはビューを参照します
- 異なる集計ロジックまたは異なるレベルの粒度を使用して同じメトリックを計算する
- 同じビジネスの質問に対して 大きく異なる結果 を返す SQL クエリを生成する
これらのコンフリクトは、提供された数少ないショットの例における曖昧さや不整合を示しています。 これらを解決すると、クエリの決定性、精度、およびエージェントの全体的な動作が向上します。
競合の詳細を確認する
競合が検出されると、SDK は各競合を例ごとの行に展開し、次のような詳細な診断を提供します。
- 競合に関連する例
- 各例の自然言語の質問と対応する SQL
- 対立がどのように例を分岐させるかを説明する記述
- 競合検出の信頼性を示す信頼度スコア
この詳細ビューを使用して、競合している例とその理由を理解し、更新または削除する必要がある例を特定します。
# 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.")
次の例は、競合検出の出力、関連する質問と SQL、検出された各競合の信頼レベルを示しています。
バリデーター スコアについて
サンプル クエリで検証コントロールを実行すると、各例に対して 3 つのキー スコア ( Clarity、 Relatedness、Mapping) が生成されます。 これらのスコアは、自然言語の質問と SQL クエリがベスト プラクティスとどの程度一致しているかから導き出されます。
明確さ
自然言語の質問が 明確で明確であるかどうかを測定します。 質問は具体的で、必要なメトリック、期間、フィルターを含め、あいまいな言い回しや複数意図の言い回しを避ける必要があります。例 - 良い: "2024 年のリージョン別の総収益。
例 - 改善が必要です。 "パフォーマンスの表示"関連性
SQL クエリが 自然言語の質問の意図とどの程度一致するかを評価します。 SQL は正しいメトリックを返し、適切なフィルターを適用し、要求された粒度と一致する必要があります。例 - 良い:2025 年 3 月の顧客数に関する質問→ SQL では、
WHERE month='2025-03'を持つ顧客がカウントされます。
例 - 改善が必要です。カウントを求める質問がありますが、SQL は SUM(revenue) を返すか、別の期間をフィルター処理します。マッピング
自然言語の質問のすべてのリテラルが SQL クエリに表示されるかどうかを確認します。 質問に記載されているすべての数値、日付、またはカテゴリは、SQL で明示的に表す必要があります。例 - 良い: "2025 年 3 月の 100 件を超える 'West' の注文" → SQL には、
> 100、2025-03、および'West'が含まれます。
例 - 改善が必要です。 SQL には、これらのリテラルのいずれかが不足しています (たとえば、月フィルターなし)。
たとえば、3 つのスコア (明確さ、関連性、マッピング) がすべて肯定的な場合にのみ、高品質と見なされます。 これらのスコアを使用して、クエリの例を絞り込みます。不明確な質問を書き直し、SQL を質問の意図に合わせてより厳密に調整し、質問内のすべてのリテラルが SQL クエリに表示されるようにします。 この反復プロセスは、データ エージェントがより優れたパターンから学習し、より正確な結果を生成するのに役立ちます。