Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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.
| Tipo de fonte de dados | Suporta consultas de exemplo? |
|---|---|
| Lakehouse | ✅ Sim |
| Armazém | ✅ Sim |
| Bases de Dados KQL da Eventhouse | ✅ Sim |
| Modelos semânticos | ❌ Não |
| Ontologia | ❌ Não |
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.
| # | Melhores Práticas | Por que é importante |
|---|---|---|
| 1 | Garantir que as perguntas correspondam claramente à consulta | O Data Agent 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 perceber onde substituir valores ou aplicar lógica importante. |
| 3 | Realçar lógica de junção ou padrões complexos | Use consultas de exemplo para mostrar como lidar com junções entre múltiplas tabelas, agregações ou outra lógica avançada difícil de descrever com instruções simples. |
| 4 | Evitar sobreposições ou contradições | Cada exemplo deve ser distinto e não conflitante para dar ao agente um sinal claro de como se comportar. |
| 5 | Use as 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 | Reflita o comportamento real do usuário | Adicione exemplos de consultas que representem os tipos de perguntas que os seus utilizadores colocam para maximizar a relevância e a precisão. |
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:
Observação
Este utilitário de avaliação está atualmente disponível apenas para consultas de exemplo baseadas em SQL. KQL ou outros tipos de consulta ainda não são suportados.
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.