예제 쿼리("몇 번의 예제"라고도 함)는 데이터 에이전트에 학습할 구체적인 패턴을 제공합니다. 샘플 질문과 작성자가 에이전트가 응답하는 방법을 안내하기 위해 제공하는 해당 쿼리 논리입니다. 사용자가 데이터 원본에 대해 질문을 하면 데이터 에이전트는 가장 관련성이 큰 예제(일반적으로 상위 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 리포지토리에서 샘플 Notebook을 확인할 수 있습니다.
비고
이 평가 유틸리티는 현재 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(수익) 을 반환하거나 다른 기간을 필터링합니다.매핑
자연어 질문의 모든 리터럴이 SQL 쿼리에 표시되는지 여부를 확인합니다. 질문에 언급된 모든 숫자, 날짜 또는 범주는 SQL에 명시적으로 표시되어야 합니다.예 – 양호: "2025년 3월에 'West'에 대한 100개 이상의 주문" → SQL에는
> 100,2025-03및'West'가 포함됩니다.
예제 – 개선이 필요합니다. SQL에 이러한 리터럴 중 하나가 없습니다(예: 월 필터 없음).
예를 들어 선명도, 관련성 및 매핑이라는 세 가지 점수가 모두 양수인 경우에만 고품질로 간주됩니다. 이러한 점수를 사용하여 명확하지 않은 질문을 다시 작성하고, SQL을 질문 의도에 더 가깝게 정렬하고, 질문의 모든 리터럴이 SQL 쿼리에 표시되는지 확인하여 예제 쿼리를 구체화합니다. 이 반복 프로세스는 데이터 에이전트가 더 나은 패턴에서 학습하고 보다 정확한 결과를 생성하는 데 도움이 됩니다.