Interrogazioni di esempio

Le query di esempio (dette anche "esempi a bassa quantità") forniscono modelli concreti per l'Agente Dati da cui apprendere. Si tratta di domande di esempio e della logica di query corrispondente che gli autori forniscono per guidare il modo in cui l'agente deve rispondere. Quando un utente pone una domanda su un'origine dati, l'agente dati recupera automaticamente gli esempi più rilevanti, in genere i primi quattro, e li inserisce nel processo di generazione. Facendo riferimento a questi esempi, l'agente può comprendere meglio la struttura, i filtri e i join previsti, che consente di produrre risultati di query più accurati, coerenti e compatibili con il contesto.

Fornisci query di esempio

Quando si forniscono query di esempio, è necessario includere sia una domanda in linguaggio naturale che la risposta alla query corrispondente. Ogni domanda deve essere univoca per assegnare all'agente dati un set diversificato di punti di riferimento. Ogni query di esempio viene convalidata sullo schema dell'origine dati selezionata. Le query che non superano la convalida non vengono inviate all'agente. Per assicurarsi che vengano usati gli esempi, è essenziale verificare che superino questo passaggio di convalida.

La tabella mostra quali origini dati supportano attualmente query di esempio nell'agente dati. Questi esempi consentono di guidare il processo di generazione di query dell'agente fornendo modelli e contesto.

È anche possibile usare la visualizzazione dei passaggi di esecuzione per eseguire il debug delle query di esempio recuperate e applicate alla domanda di un utente. Questa vista è particolarmente utile per confermare che vengono usati gli esempi corretti e per la diagnosi del motivo per cui vengono generati determinati risultati. Se vengono visualizzati esempi errati, provare a perfezionare le domande o ad aggiungere esempi più chiari e mirati.

Migliori pratiche per la scrittura di query di esempio

Quando si creano query di esempio per l'agente dati, le procedure consigliate seguenti garantiscono indicazioni chiare e affidabili durante la generazione di query. Esempi ben creati consentono all'agente di comprendere in che modo le domande in linguaggio naturale si traducono in logica SQL/KQL, evidenziano join o calcoli complessi e migliorano l'accuratezza dei risultati. Usare le linee guida per rendere gli esempi più efficaci e rappresentativi di scenari utente reali.

Convalida delle query di esempio

Fabric Data Agent SDK offre strumenti predefiniti per valutare e migliorare la qualità delle query di esempio. Usando la evaluate_few_shots funzione, è possibile convalidare ogni coppia di linguaggio naturale/SQL per verificare che sia chiara, corretta e allineata allo schema dell'origine dati. L'SDK esegue ogni esempio tramite il processo di valutazione dell'agente dati, restituendo un riepilogo dettagliato degli esempi passati e che richiedono perfezionamento.

Fornisci query di esempio

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

Valutare tramite SDK

Esaminando il tasso di successo e il feedback, è possibile modificare in modo iterativo gli esempi, chiarire le domande, migliorare la logica SQL o aggiungere commenti, in modo che l'agente dati impari da modelli di qualità superiore e produa risultati più accurati per le nuove domande.

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

Tenere traccia dei commenti e suggerimenti

Dopo aver eseguito il validator, si riceverà una scomposizione chiara degli esempi passati e che hanno avuto esito negativo. Questo feedback semplifica l'identificazione dei punti di forza e dei punti deboli negli esempi di pochi scatti.

• Casi di esito positivo: Esempi in cui SQL corrisponde alle risposte previste. Questi esempi sono forti riferimenti su cui puoi basare gli esempi futuri.
• Casi di errore: Esempi in cui SQL non corrisponde alla risposta prevista o in cui la coppia di domande/query potrebbe non essere chiara o non valida. Questi casi devono essere esaminati e perfezionati.

# 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

Usare questo feedback per iterare e migliorare le query di esempio. Il rafforzamento regolare degli esempi più deboli consentirà all'agente dati di produrre risposte e SQL più accurati nel tempo.

Per esplorare un esempio funzionante completo, è possibile consultare il notebook di esempio nel repository GitHub di Fabric Data Agent SDK:

Rilevare conflitti tra query di esempio

Al termine della convalida della qualità, Evaluation SDK esegue automaticamente il rilevamento dei conflitti nelle query di esempio approvate o in alcuni esempi. Il rilevamento dei conflitti identifica le incoerenze che possono causare la generazione di risultati imprevedibili o errati da parte dell'agente dati.

Viene rilevato un conflitto quando due o più esempi:

• Rappresentare la stessa finalità (in base a una versione normalizzata della domanda in linguaggio naturale) ma fare riferimento a tabelle o viste diverse
• Calcolare la stessa metrica usando logica di aggregazione diversa o livelli di granularità diversi
• Generare query SQL che restituiscono risultati materialmente diversi per la stessa domanda aziendale

Questi conflitti indicano ambiguità o incoerenza all'interno di alcuni esempi di pochi scatti forniti. La risoluzione di questi problemi aiuta a migliorare il determinismo, l'accuratezza e il comportamento complessivo dell'agente.

Esaminare i dettagli del conflitto

Quando vengono rilevati conflitti, l'SDK espande ogni conflitto in righe di esempio, fornendo diagnostica dettagliata, tra cui:

• Gli esempi coinvolti nel conflitto
• Domanda del linguaggio naturale e SQL corrispondente per ogni esempio
• Descrizione del conflitto che spiega in che modo gli esempi divergono
• Punteggio di attendibilità che indica l'affidabilità del rilevamento dei conflitti

Utilizzare questa visualizzazione dettagliata per comprendere quali esempi sono in conflitto e perché e per determinare quali esempi devono essere aggiornati o rimossi.

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

L'esempio seguente mostra l'output di rilevamento dei conflitti, le domande associate e SQL e il livello di attendibilità di ogni conflitto rilevato.

Comprendere i punteggi del validator

Quando si esegue il validator nelle query di esempio, vengono generati tre punteggi di chiave per ogni esempio: Clarity, Relatedness e Mapping. Questi punteggi derivano dal modo in cui le domande in linguaggio naturale e le query SQL sono allineate alle procedure consigliate.

• Chiarezza
  Misura se la domanda in linguaggio naturale è chiara e non ambigua. Le domande devono essere specifiche, includere metriche, tempi e filtri necessari ed evitare formulazioni vaghe o con più intenti.

  Esempio: Buono: "Ricavi totali per regione per il 2024."
  Esempio – Necessita di miglioramenti: "Visualizza prestazioni".

• Correlazione
  Valuta in che modo la query SQL corrisponde alla finalità della domanda in linguaggio naturale. SQL deve restituire la metrica corretta, applicare i filtri appropriati e corrispondere alla granularità richiesta.

  Esempio: Buono: Una domanda chiede il numero di clienti nel mese di marzo 2025 → SQL conteggia i clienti con WHERE month='2025-03'.
  Esempio: miglioramento delle esigenze: Una domanda chiede il conteggio, ma SQL restituisce SUM(revenue) o filtra un periodo diverso.

• Mappatura
  Controlla se tutti i valori letterali nella domanda in linguaggio naturale vengono visualizzati nella query SQL. Ogni numero, data o categoria menzionata nella domanda deve essere rappresentato in modo esplicito in SQL.

  Esempio – Buono: "Ordini superiori a 100 in marzo 2025 per «West»" → SQL include > 100, 2025-03 e 'West'.
  Esempio: miglioramento delle esigenze: SQL non dispone di uno di questi valori letterali( ad esempio, nessun filtro mensile).

Un esempio è considerato di alta qualità solo se tutti e tre i punteggi, Clarity, Relatedness e Mapping, sono positivi. Usare questi punteggi per perfezionare le query di esempio: riscrivere domande poco chiare, allineare SQL più strettamente alla finalità della domanda e assicurarsi che ogni valore letterale nella domanda venga visualizzato nella query SQL. Questo processo iterativo consente all'agente dati di apprendere da modelli migliori e produrre risultati più accurati.

Passaggi successivi

• Concetto di agente dei dati
• Scenario dell'agente dati
• Notebook di esempio per convalidare query di esempio