Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Consultas de exemplo (também chamadas de "exemplos de poucas capturas") 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 primeiros, e os alimenta em seu processo de geração. Ao referenciar esses exemplos, o agente pode entender melhor a estrutura, os filtros e as junções esperados, o que ajuda a produzir resultados de consulta mais precisos, consistentes e com reconhecimento de 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 exclusiva 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 pela validação não são enviadas ao agente. Para garantir que seus exemplos sejam usados, é essencial confirmar se eles passam nessa etapa de validação.
A tabela mostra quais fontes de dados atualmente dão suporte a consultas de exemplo no Agente de Dados. Esses exemplos ajudam a orientar o processo de geração de consulta do agente fornecendo padrões e contexto.
| Tipo de fonte de dados | Dá suporte a consultas de exemplo? |
|---|---|
| Lakehouse | ✅ Sim |
| Armazém | ✅ Sim |
| Bancos de dados KQL do Eventhouse | ✅ Sim |
| Modelos semânticos | ❌ Não |
| Ontologia | ❌ Não |
Você também pode usar a exibição de etapas de execução para depurar quais consultas de exemplo foram recuperadas e aplicadas à pergunta de um usuário. Essa exibição é especialmente útil para confirmar que os exemplos certos estão sendo usados e para diagnosticar por que determinados resultados estão sendo gerados. Se os exemplos errados aparecerem, tente refinar suas perguntas ou adicionar exemplos mais claros e mais direcionados.
Práticas recomendadas para escrever consultas de exemplo
Ao criar consultas de exemplo para o Agente de Dados, as práticas recomendadas a seguir garantem que elas forneçam diretrizes claras e confiáveis durante a geração de consulta. Exemplos bem elaborados ajudam o agente a entender como as perguntas de linguagem natural se traduzem na lógica SQL/KQL, realçam junções ou cálculos complexos e melhoram a precisão de seus resultados. Use as diretrizes para tornar seus exemplos mais eficazes e representativos de cenários reais de usuário.
| # | Melhor Prática | Por que isso importa |
|---|---|---|
| 1 | Garantir que as perguntas sejam mapeadas claramente para a consulta | O Agente de Dados usa esses exemplos para aprender o padrão entre a pergunta e o SQL/KQL resultante. A ambiguidade reduz a precisão. |
| 2 | Incluir comentários na consulta para orientar o agente | Comentários ( -- substitute customer_id here) ajudam o agente a entender onde substituir valores ou aplicar uma lógica importante. |
| 3 | Realçar a lógica de junção ou padrões complexos | Use consultas de exemplo para mostrar como lidar com junções de várias tabelas, agregações ou outra lógica avançada difícil de descrever em instruções simples. |
| 4 | Evitar sobreposição ou contradições | Cada exemplo deve ser distinto e não conflitante para dar ao agente um sinal limpo de como se comportar. |
| 5 | Usar etapas de execução para depurar quais exemplos são passados | As etapas de execução permitem que você veja quais exemplos foram recuperados para uma determinada pergunta do usuário: se os errados aparecerem, ajuste suas perguntas ou adicione exemplos mais específicos. |
| 6 | Refletir o comportamento real do usuário | Adicione consultas de exemplo que representam os tipos de perguntas que seus usuários fazem para maximizar a relevância e a precisão. |
Validar consultas de exemplo
O SDK do Agente de Dados do Fabric 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 ele está claro, correto e alinhado com o esquema da fonte de dados. O SDK executa cada exemplo por meio do processo de avaliação do Agente de Dados, retornando um resumo detalhado de quais exemplos foram passados e quais precisam de refinamento.
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 por meio do SDK
Ao revisar a taxa de êxito e os comentários, você pode ajustar iterativamente seus exemplos, esclarecendo perguntas, melhorando a lógica do 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 comentários
Depois de executar o validador, você receberá um detalhamento claro de quais exemplos foram passados e quais falharam. Esses comentários facilitam a identificação de pontos fortes e fracos em seus exemplos de poucas tomadas.
- Casos de sucesso: Exemplos em que o SQL correspondeu às respostas esperadas. Esses exemplos são referências fortes que você pode modelar exemplos futuros depois.
- Casos de falha: Exemplos em que o SQL não correspondeu à resposta esperada ou em que o par de perguntas/consultas pode não estar claro ou inválido. Esses casos devem ser revistos e refinados.
# 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 esses comentários para iterar e melhorar suas consultas de exemplo. O fortalecimento regular de exemplos mais fracos ajudará o Agente de Dados a produzir respostas e SQL mais precisas ao longo do tempo.
Para explorar um exemplo de trabalho completo, confira o bloco de anotações de exemplo no repositório GitHub do SDK do Agente de Dados do Fabric:
Observação
No momento, esse utilitário de avaliação está disponível apenas para consultas de exemplo baseadas em SQL. Ainda não há suporte para KQL ou outros tipos de consulta.
Detectar conflitos entre consultas de exemplo
Após a conclusão da validação de qualidade, o SDK de Avaliação executará automaticamente a detecção de conflitos nas consultas de exemplo aprovadas ou em exemplos de poucas capturas. A detecção de conflitos identifica inconsistências que podem fazer com que o Agente de Dados produza resultados imprevisíveis ou incorretos.
Um conflito é detectado quando dois ou mais exemplos:
- Representar a mesma intenção (com base em uma versão normalizada da questão da linguagem natural), mas referenciar tabelas ou exibições diferentes
- Compute a mesma métrica usando lógica de agregação diferente ou níveis diferentes de granularidade
- Gerar consultas SQL que retornariam resultados materialmente diferentes para a mesma questão de negócios
Esses conflitos indicam ambiguidade ou inconsistência dentro dos exemplos few shot fornecidos. Resolvê-los ajuda a melhorar o determinismo de consulta, a precisão e o comportamento geral do agente.
Examinar detalhes do conflito
Quando conflitos são detectados, o SDK expande cada conflito em linhas por exemplo, fornecendo diagnóstico detalhado, incluindo:
- Os exemplos envolvidos no conflito
- A questão da linguagem natural e o SQL correspondente para cada exemplo
- Uma descrição do conflito explicando como os exemplos divergem
- Uma pontuação de confiança que indica a confiabilidade da detecção de conflitos
Use essa exibição detalhada para entender quais exemplos estão em conflito e por quê e 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 a seguir mostra a saída de detecção de conflitos, suas perguntas associadas e SQL e o nível de confiança de cada conflito detectado.
Entender 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
Avalia se a questão em linguagem natural é clara e inequívoca. As perguntas devem ser específicas, incluir métricas, quadros de tempo e filtros necessários e evitar frases vagas ou de várias intenções.Exemplo – Bom: "Receita total por região para 2024."
Exemplo – precisa de melhorias: "Mostrar desempenho".Relacionamento
Avalia a proximidade com que a consulta SQL corresponde à intenção da questão da linguagem natural. O SQL deve retornar a métrica correta, aplicar os filtros adequados e corresponder à granularidade solicitada.Exemplo – Bom: Uma pergunta solicita a contagem de clientes em março de 2025 → o SQL conta os clientes com
WHERE month='2025-03'.
Exemplo – precisa de melhorias: Uma pergunta solicita contagem, mas o SQL retorna SOMA(receita) ou filtra um período diferente.Mapeamento
Verifica se todos os literais na questão da linguagem natural aparecem na consulta SQL. Cada número, data ou categoria mencionada na pergunta deve ser explicitamente representado no SQL.Exemplo – Bom: "Pedidos acima de 100 em março de 2025 para 'Oeste'" → SQL inclui
> 100,2025-03e'West'.
Exemplo – precisa de melhorias: O SQL não tem um desses literais (por exemplo, nenhum filtro de mês).
Um exemplo é considerado de alta qualidade somente 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 não claras, alinhe o SQL mais de perto com a intenção de pergunta e verifique se todos os literais na pergunta são exibidos na consulta SQL. Esse processo iterativo ajuda o Agente de Dados a aprender com melhores padrões e produzir resultados mais precisos.