範例查詢 （也稱為「少量範例」） 提供資料代理程式可供學習的具體模式。 它們是範例問題及其對應的查詢邏輯，由建立者提供，以指導客服專員應如何回應。 當使用者針對資料來源提出問題時，資料代理程式會自動擷取最相關的範例 （通常是前四個），並將其輸入其產生程式。 透過參考這些範例，代理可以更好地理解預期的結構、過濾器和聯結，這有助於其產生更準確、一致和上下文感知的查詢結果。
提供範例查詢
提供範例查詢時，您必須同時包含自然語言問題及其對應的查詢答案。 每個問題都應該是唯一的，以便為資料代理程式提供一組不同的參考點。 每個範例查詢都會根據所選資料來源的結構描述進行驗證，未通過驗證的查詢不會傳送至代理程式。 為了確保您的範例實際使用，必須確認它們通過了此驗證步驟。
下表顯示哪些資料來源目前支援資料代理程式中的範例查詢。 這些範例透過提供模式和上下文來幫助指導代理程式的查詢產生過程。
| 資料來源類型 | 支援範例查詢？ |
|---|---|
| Lakehouse | ✅ 是 |
| 倉儲 | ✅ 是 |
| Eventhouse KQL 資料庫 | ✅ 是 |
| 語意模型 | ❌ 否 |
您也可以使用 執行步驟 檢視來偵錯實際擷取哪些範例查詢並將其套用至使用者的問題。 這對於確認是否使用了正確的範例以及診斷生成某些結果的原因特別有用。 如果出現錯誤的範例，請嘗試完善您的問題或添加更清晰、更有針對性的範例。
撰寫範例查詢的最佳實務
建立資料代理程式的範例查詢時，遵循最佳實務可確保它們在查詢產生期間提供清晰、可靠的指引。 精心設計的範例可協助代理程式瞭解自然語言問題如何轉換為 SQL/KQL 邏輯、醒目提示複雜的聯結或計算，以及提高結果的準確性。 使用下列指導方針，讓您的範例更有效，並代表實際使用者案例。
| # | 最佳做法 | 為什麼它很重要 |
|---|---|---|
| 1 | 確保問題清楚對應至查詢 | 資料代理程式會使用這些範例來瞭解問題與產生的 SQL/KQL 之間的模式。 歧義會降低準確性。 |
| 2 | 在查詢中包含註釋以指導客服專員 | 註解（例如， -- substitute customer_id here）幫助客服專員了解在何處替換值或應用重要邏輯。 |
| 3 | 強調連接邏輯或複雜模式 | 使用範例查詢來示範如何處理多表聯結、彙總或其他難以在簡單指令中描述的進階邏輯。 |
| 4 | 避免重疊或矛盾 | 每個範例都應該是獨特且不衝突的，以便為客服人員提供如何行為的清晰訊號。 |
| 5 | 使用執行步驟來偵錯哪些範例已通過 | 執行步驟可讓您查看針對給定使用者問題擷取了哪些範例 — 如果出現錯誤的範例，請調整您的問題或新增更具體的範例。 |
| 6 | 反映真實的使用者行為 | 新增範例查詢，代表使用者實際會提出的問題類型，以最大化相關性和準確性。 |
驗證範例查詢
Fabric 資料代理程式 SDK 提供內建工具來 評估和改善範例查詢的品質。 使用函 evaluate_few_shot_examples 式，您可以驗證每個自然語言/SQL 配對，以確認其清晰、正確，且與您的資料來源結構描述一致。 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 = evaluate_few_shot_examples(
examples, # The list of few-shot examples you loaded and formatted earlier
llm_client=llm_client, # The OpenAI/Fabric LLM client you configured
model_name=model_name, # Model to use for evaluation, e.g., 'gpt-4o'
batch_size=20, # Number of examples to evaluate per batch
use_fabric_llm=True # Whether to use the Fabric LLM wrapper for evaluation
)
# 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})")
運行驗證器後，您將收到哪些示例 通過 和 哪些示例失敗的清晰明細。 此回饋可讓您輕鬆識別少量範例中的優點和缺點。
- 成功案例： SQL 符合預期答案的範例。 這些是有力的範例模型，您可以用來作為未來案例的參照。
- 故障案例： SQL 不符合預期答案的範例，或問題/查詢配對可能不清楚或無效。 這些案例應該被審查和完善。
# Convert success and failure cases to Pandas DataFrames for easy inspection
success_df = cases_to_dataframe(result.success_cases)
failure_df = cases_to_dataframe(result.failure_cases)
# Display results for analysis
display(success_df)
display(failure_df)
使用此意見反應來 反覆執行並改善 範例查詢。 定期強化較弱的範例，將有助於資料代理程式產生更準確的 SQL 和答案。
若要探索完整的工作範例，您可以查看 Fabric Data Agent SDK GitHub 存放庫中的範例筆記本：
備註
此評估公用程式目前 僅適用於 SQL 型範例查詢。 尚不支援 KQL 或其他查詢類型。
了解驗證者分數
當您在範例查詢上執行驗證器時，它會為每個範例產生三個關鍵分數：清晰度、相關性和映射。 這些分數源自於您的自然語言問題和 SQL 查詢與最佳實踐的一致性。
透明
測量自然語言問題是否 清晰明確。 問題應該具體，包括必要的指標、時間範圍和過濾器，並避免模糊或多意圖的措辭。
範例 – 好： “2024 年按地區劃分的總收入。”
範例 – 需要改進： “顯示效能。”相關性
評估 SQL 查詢與 自然語言問題意圖的相符程度。 SQL 應該傳回正確的度量、套用適當的篩選器，並符合要求的粒度。
範例 – 好： 一個問題要求 2025 年 3 月的客戶計數 ，→ SQL 會計算具有WHERE month='2025-03'的客戶。
範例 – 需要改進： 問題要求 計數，但 SQL 會傳回 SUM（revenue） 或篩選不同的期間。映射
檢查 自然語言問題中的所有文字是否出現在 SQL 查詢中。 問題中提到的每個數字、日期或類別都應在 SQL 中明確表示。 這不會判斷資料行名稱，只會判斷文字值。
範例 – 好： 「2025 年 3 月『西部』訂單超過 100 個」→ SQL 包括> 100、2025-03和'West'。
範例 – 需要改進： SQL 缺少其中一個字面值（例如，沒有月份篩選條件）。
只有當所有三個分數（清晰度、相關性和映射）都是正數時，範例才會被視為高品質。 使用這些分數來優化您的範例查詢：重寫不清楚的問題、使 SQL 更緊密地與問題意圖保持一致，並確保問題中的每個文字都出現在 SQL 查詢中。 此迭代過程可幫助數據代理從更好的模式中學習並產生更準確的結果。