範例查詢

範例查詢（也稱為「少數樣本範例」）提供資料代理可學習的具體模式。 它們是範例問題及其對應的查詢邏輯，由建立者提供，以指導客服專員應如何回應。 當使用者針對資料來源提出問題時，資料代理程式會自動擷取最相關的範例 （通常是前四個），並將其輸入其產生程式。 透過參考這些範例，代理可以更好地理解預期的結構、過濾器和聯結，這有助於其產生更準確、一致和上下文感知的查詢結果。

提供範例查詢

提供範例查詢時，您必須同時包含自然語言問題及其對應的查詢答案。 每個問題都應該是唯一的，以便為資料代理程式提供一組不同的參考點。 每個範例查詢都會根據所選資料來源的結構描述進行驗證，未通過驗證的查詢不會傳送至代理程式。 為了確保你的範例被使用，必須確認它們通過了這個驗證步驟。

表格顯示目前哪些資料來源支援資料代理中的範例查詢。 這些範例透過提供模式與上下文，有助於引導代理的查詢產生流程。

資料來源類型	支援範例查詢？
Lakehouse	✅ 是
倉儲	✅ 是
Eventhouse KQL 資料庫	✅ 是
語意模型	❌ 否
本體	❌ 否

你也可以使用 執行步驟 檢視來除錯哪些範例查詢被檢索並套用到使用者的問題上。 這種觀點對於確認所用的例子正確，以及診斷產生某些結果的原因特別有用。 如果出現錯誤的範例，請嘗試完善您的問題或添加更清晰、更有針對性的範例。

撰寫範例查詢的最佳實務

建立資料代理程式的範例查詢時，遵循最佳實務可確保它們在查詢產生期間提供清晰、可靠的指引。 精心設計的範例可協助代理程式瞭解自然語言問題如何轉換為 SQL/KQL 邏輯、醒目提示複雜的聯結或計算，以及提高結果的準確性。 利用這些指引，讓你的範例更有效，並更貼近真實使用者情境。

#	最佳做法	為什麼它很重要
1	確保問題清楚對應至查詢	資料代理程式會使用這些範例來瞭解問題與產生的 SQL/KQL 之間的模式。 歧義會降低準確性。
2	在查詢中包含註釋以指導客服專員	註解（ -- substitute customer_id here）幫助代理人理解應在哪裡替換數值或應用重要邏輯。
3	強調連接邏輯或複雜模式	使用範例查詢來展示如何處理多表連接、聚合或其他難以用純指令描述的進階邏輯。
4	避免重疊或矛盾	每個範例都應該是獨特且不衝突的，以便為客服人員提供如何行為的清晰訊號。
5	使用執行步驟來偵錯哪些範例已通過	執行步驟可讓您查看針對給定使用者問題擷取了哪些範例 — 如果出現錯誤的範例，請調整您的問題或新增更具體的範例。
6	反映真實的使用者行為	加入代表用戶問題類型的範例查詢，以最大化相關性與準確性。

驗證範例查詢

Fabric 資料代理程式 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 或其他查詢類型。

偵測範例查詢之間的衝突

品質驗證完成後，評估 SDK 會自動對核准的範例查詢或少數樣本範例進行 衝突偵測 。 衝突偵測能識別可能導致資料代理產生不可預測或錯誤結果的不一致之處。

當有兩個或以上的例子時，即偵測到衝突：

• 代表 相同的意圖 （基於自然語言問題的標準化版本），但 引用不同的表格或視角
• 用不同的聚合邏輯或不同細度層級計算相同的指標
• 產生 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，以及每個偵測到衝突的可信度。

了解驗證者分數

當您在範例查詢上執行驗證器時，它會為每個範例產生三個關鍵分數：清晰度、相關性和映射。 這些分數源自於您的自然語言問題和 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 查詢中。 此迭代過程可幫助數據代理從更好的模式中學習並產生更準確的結果。

後續步驟

• 數據代理程式概念
• 資料代理程式案例
• 驗證範例查詢的範例筆記本