Exemplos de consultas

Consultas de exemplo (também chamadas de "exemplos de poucos exemplos") dão ao Agente de Dados padrões concretos para aprender. São perguntas de exemplo e sua lógica de consulta correspondente que os criadores fornecem para orientar como o agente deve responder. Quando um usuário faz uma pergunta em relação a uma fonte de dados, o Agente de Dados recupera automaticamente os exemplos mais relevantes, normalmente os quatro principais, e os alimenta em seu processo de geração. Ao fazer referência a esses exemplos, o agente pode entender melhor a estrutura, os filtros e as junções esperadas, o que o ajuda a produzir resultados de consulta mais precisos, consistentes e sensíveis ao contexto.

Fornecer consultas de exemplo

Ao fornecer consultas de exemplo, você deve incluir uma pergunta de linguagem natural e sua resposta de consulta correspondente. Cada pergunta deve ser única para dar ao Agente de Dados um conjunto diversificado de pontos de referência. Cada consulta de exemplo é validada em relação ao esquema da fonte de dados selecionada — as consultas que não passam na validação não são enviadas ao agente. Para garantir que os seus exemplos são usados, é essencial confirmar que passaram esta etapa de validação.

A tabela mostra que fontes de dados suportam atualmente consultas de exemplo no Data Agent. Estes exemplos ajudam a orientar o processo de geração de consultas do agente, fornecendo padrões e contexto.

Também pode usar a visualização de passos de execução para depurar quais consultas de exemplo foram recuperadas e aplicadas à pergunta de um utilizador. Esta perspetiva é especialmente útil para confirmar que os exemplos corretos estão a ser usados e para diagnosticar porque certos resultados estão a ser gerados. Se aparecerem exemplos errados, tente refinar as perguntas ou adicionar exemplos mais claros e direcionados.

Práticas recomendadas para escrever consultas de exemplo

Ao criar consultas de exemplo para o Data Agent, seguir as práticas recomendadas garante que elas forneçam orientação clara e confiável durante a geração da consulta. Exemplos bem elaborados ajudam o agente a entender como as perguntas de linguagem natural se traduzem em lógica SQL/KQL, destacam junções ou cálculos complexos e melhoram a precisão de seus resultados. Use as diretrizes para tornar os seus exemplos mais eficazes e representativos de cenários reais de utilizadores.

Validar consultas de exemplo

O SDK do Fabric Data Agent fornece ferramentas internas para avaliar e melhorar a qualidade de suas consultas de exemplo. Usando a evaluate_few_shots função, você pode validar cada par de linguagem natural/SQL para confirmar que está claro, correto e alinhado com seu esquema de fonte de dados. O SDK executa cada exemplo pelo processo de avaliação do Agente de Dados, devolvendo um resumo detalhado dos exemplos que passaram e quais necessitam de aperfeiçoamento.

Fornecer consultas de exemplo

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")

Avaliar através do SDK

Ao analisar a taxa de sucesso e o feedback, você pode ajustar iterativamente seus exemplos, esclarecendo perguntas, melhorando a lógica SQL ou adicionando comentários, para que o Agente de Dados aprenda com padrões de maior qualidade e produza resultados mais precisos para novas perguntas.

# 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})")

Acompanhar feedback

Depois de executar o validador, receberá uma explicação clara dos exemplos que passaram e quais falharam. Esse feedback facilita a identificação de pontos fortes e fracos em seus poucos exemplos.

• Casos de Sucesso: Exemplos em que o SQL correspondeu às respostas esperadas. Esses exemplos são referências fortes que pode usar para modelar futuros exemplos após.
• Casos de Falha: Exemplos em que o SQL não correspondeu à resposta esperada, ou onde o par pergunta/consulta pode ser pouco claro ou inválido. Estes casos devem ser revistos e aperfeiçoados.

# 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

Use esse feedback para iterar e melhorar suas consultas de exemplo. O fortalecimento regular de exemplos mais fracos ajudará o Agente de Dados a produzir SQL e respostas mais precisas ao longo do tempo.

Para explorar um exemplo de trabalho completo, você pode conferir o bloco de anotações de exemplo no repositório GitHub do Fabric Data Agent SDK:

Detetar conflitos entre consultas de exemplo

Após a conclusão da validação de qualidade, o SDK de Avaliação realiza automaticamente a deteção de conflitos nas consultas de exemplo aprovadas ou nos exemplos de poucos disparos. A deteção de conflitos identifica inconsistências que podem levar o Agente de Dados a produzir resultados imprevisíveis ou incorretos.

Um conflito é detetado quando dois ou mais exemplos:

• Representam a mesma intenção (com base numa versão normalizada da questão da linguagem natural), mas referenciam tabelas ou vistas diferentes
• Calcule a mesma métrica usando lógica de agregação diferente ou diferentes níveis de granularidade
• Gerar consultas SQL que devolvam resultados materialmente diferentes para a mesma questão de negócio

Estes conflitos indicam ambiguidade ou inconsistência entre os poucos exemplos fornecidos. Resolvê-los ajuda a melhorar o determinismo das consultas, a precisão e o comportamento geral do agente.

Rever detalhes do conflito

Quando são detetados conflitos, o SDK expande os conflitos em linhas correspondentes a cada exemplo, fornecendo diagnósticos detalhados, incluindo:

• Os exemplos envolvidos no conflito
• A questão da linguagem natural e o SQL correspondente para cada exemplo
• Uma descrição do conflito que explica como os exemplos divergem
• Uma pontuação de confiança que indica a fiabilidade da deteção de conflitos

Use esta visão detalhada para compreender quais exemplos estão em conflito e porquê, e para determinar quais exemplos devem ser atualizados ou removidos.

# 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.")

O exemplo seguinte mostra a saída de deteção de conflitos, as suas perguntas associadas e SQL, e o nível de confiança de cada conflito detetado.

Compreender as pontuações do validador

Quando você executa o validador em suas consultas de exemplo, ele gera três pontuações principais para cada exemplo: clareza, relação e mapeamento. Essas pontuações são derivadas de quão bem suas perguntas de linguagem natural e consultas SQL se alinham com as práticas recomendadas.

• Clareza
  Mede se a questão da linguagem natural é clara e inequívoca. As perguntas devem ser específicas, incluir métricas, prazos e filtros necessários e evitar frases vagas ou com várias intenções.

  Exemplo – Bom: "Receita total por região para 2024."
  Exemplo – Precisa de Melhorias: "Mostrar desempenho."

• Relação
  Avalia até que ponto a consulta SQL corresponde à intenção da pergunta de linguagem natural. O SQL deve retornar a métrica correta, aplicar os filtros adequados e corresponder à granularidade solicitada.

  Exemplo – Bom: Uma pergunta pede contagem de clientes em março de 2025 → SQL conta clientes com WHERE month='2025-03'.
  Exemplo – Precisa de Melhorias: Uma pergunta pede contagem, mas o SQL retorna SOMA(receita) ou filtra um período diferente.

• Mapeamento
  Verifica se todos os literais na pergunta de linguagem natural aparecem na consulta SQL. Cada número, data ou categoria mencionado na pergunta deve ser explicitamente representado no SQL.

  Exemplo – Bom: "Encomendas superiores a 100 em março de 2025 para 'West'" → SQL inclui > 100, 2025-03, e 'West'.
  Exemplo – Precisa de Melhorias: O SQL está sem um desses valores literais (por exemplo, sem filtro mensal).

Um exemplo só é considerado de alta qualidade se todas as três pontuações — Clareza, Relação e Mapeamento — forem positivas. Use essas pontuações para refinar suas consultas de exemplo: reescreva perguntas pouco claras, alinhe o SQL mais de perto com a intenção da pergunta e garanta que cada literal na pergunta apareça na consulta SQL. Esse processo iterativo ajuda o Agente de Dados a aprender com padrões melhores e produzir resultados mais precisos.

Próximos passos

• Conceito de agente de dados
• Cenário do agente de dados
• Bloco de anotações de exemplo para validar consultas de exemplo