Příkladové dotazy

Ukázkové dotazy (označované také jako "příklady s malým počtem vzorů") poskytují datovému agentovi konkrétní vzory, ze kterých se může učit. Jedná se o ukázkové otázky a odpovídající logiku dotazů, kterou tvůrci poskytují, aby mohli řídit, jak by měl agent reagovat. Když se uživatel zeptá na zdroj dat, agent dat automaticky načte nejrelevantní příklady – obvykle první čtyři – a předává je do procesu generování. Odkazováním na tyto příklady může agent lépe porozumět očekávané struktuře, filtrům a spojením, což mu pomůže dosáhnout přesnějších, konzistentnějších a kontextových výsledků dotazů.

Zadání ukázkových dotazů

Při zadávání ukázkových dotazů musíte zahrnout otázku v přirozeném jazyce i odpovídající odpověď na dotaz. Každá otázka by měla být jedinečná, aby datový agent získal různorodou sadu referenčních bodů. Každý ukázkový dotaz se ověří ve schématu vybraného zdroje dat – dotazy, které neprojdou ověřením, se do agenta neodesílají. Abyste měli jistotu, že se vaše příklady použijí, je důležité ověřit, že projdou tímto ověřovacím krokem.

Tabulka ukazuje, které zdroje dat aktuálně podporují ukázkové dotazy v datovém agentu. Tyto příklady pomáhají s procesem generování dotazů agenta tím, že poskytují vzory a kontext.

Typ zdroje dat	Podporuje příklady dotazů?
Lakehouse	✅ Ano
Sklad	✅ Ano
Databáze KQL Eventhouse	✅ Ano
Sémantické modely	❌ Ne
Ontologie	❌ Ne

Pomocí zobrazení běhu kroků můžete také ladit, které ukázkové dotazy byly načteny a aplikovány na otázku uživatele. Toto zobrazení je užitečné zejména pro potvrzení, že se používají správné příklady a pro diagnostiku, proč se generují určité výsledky. Pokud se zobrazí nesprávné příklady, zkuste upřesnit své otázky nebo přidat jasnější a cílenější příklady.

Osvědčené postupy pro psaní ukázkových dotazů

Při vytváření ukázkových dotazů pro datového agenta následující osvědčené postupy zajistí, že během generování dotazů poskytují jasné a spolehlivé pokyny. Dobře vytvořené příklady pomáhají agentům pochopit, jak se otázky přirozeného jazyka překládají do logiky SQL/KQL, zvýrazňují složité spojení nebo výpočty a zlepšují přesnost výsledků. Řiďte se pokyny, abyste své příklady učinili efektivnějšími a lépe reprezentujícími skutečné uživatelské scénáře.

#	Nejlepší praxe	Proč je to důležité
1	Zajistěte, aby otázky jasně odpovídaly dotazu	Datový agent používá tyto příklady k seznámení se vzorem mezi otázkou a výsledným jazykem SQL/KQL. Nejednoznačnost snižuje přesnost.
2	Přidejte komentáře do dotazu pro usnadnění práce agenta	Komentáře ( -- substitute customer_id here) pomáhají agentu pochopit, kde nahradit hodnoty nebo použít důležitou logiku.
3	Zvýraznění logiky spojení nebo složitých vzorů	Ukázkové dotazy vám ukážou, jak zpracovávat spojení s více tabulkami, agregace nebo jinou pokročilou logiku, která se obtížně popisuje v prostých pokynech.
4	Vyhněte se překrývání nebo rozporům	Každý příklad by měl být odlišný a nekolidující, aby agent měl čistý signál o chování.
5	Použijte kroky běhu k ladění příkladů, které byly úspěšně dokončeny	Spuštěním kroků zjistíte, které příklady byly načteny pro danou otázku uživatele – pokud se zobrazí nesprávné, upravte své otázky nebo přidejte konkrétnější příklady.
6	Odraz skutečného chování uživatele	Přidejte ukázkové dotazy, které představují druhy otázek, které uživatelé požádají, aby maximalizovali relevanci a přesnost.

Ověření ukázkových dotazů

Sada SDK datového agenta Fabric poskytuje integrované nástroje pro vyhodnocení a zlepšení kvality ukázkových dotazů. evaluate_few_shots Pomocí funkce můžete ověřit každou dvojici přirozeného jazyka nebo SQL a ověřit, že je jasná, správná a zarovnaná se schématem zdroje dat. Sada SDK spouští každý příklad procesem hodnocení Data agenta a vrací podrobný souhrn, které příklady byly úspěšné a které vyžadují upřesnění.

Zadání ukázkových dotazů

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

Vyhodnocení prostřednictvím sady SDK

Když si projdete míru úspěšnosti a zpětnou vazbu, můžete iterativně upravovat příklady—objasnění otázek, zlepšení logiky SQL nebo přidání komentářů—aby se datový agent učil z příkladů vyšší kvality a generoval přesnější výsledky pro nové otázky.

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

Sledování zpětné vazby

Po spuštění validátoru se zobrazí jasný rozpis předaných příkladů a neúspěšných příkladů. Tato zpětná vazba usnadňuje identifikaci silných a slabých stránek v několika ukázkových příkladech.

• Případy úspěchu: Příklady, kde SQL odpovídal očekávaným odpovědím Tyto příklady jsou silné vzory, podle kterých můžete modelovat budoucí příklady.
• Případy selhání: Příklady, kdy SQL neodpovídá očekávané odpovědi nebo kde může být dvojice dotazů nejasná nebo neplatná. Tyto případy by se měly zkontrolovat a upřesnit.

# 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

Pomocí této zpětné vazby můžete iterovat a vylepšovat ukázkové dotazy. Pravidelné posilování slabších příkladů pomůže datovému agentu vytvářet přesnější SQL a odpovědi v průběhu času.

Pokud chcete prozkoumat plně funkční příklad, můžete si projít poznámkový blok v Fabric Data Agent SDK GitHub repository:

Poznámka:

Tento nástroj pro vyhodnocení je aktuálně k dispozici pouze pro ukázkové dotazy založené na SQL. KQL nebo jiné typy dotazů se zatím nepodporují.

Detekce konfliktů mezi ukázkovými dotazy

Po dokončení ověření kvality sada SDK pro vyhodnocení automaticky provede detekci konfliktů u schválených ukázkových dotazů nebo několika snímků příkladů. Detekce konfliktů identifikuje nekonzistence, které můžou způsobit nepředvídatelné nebo nesprávné výsledky datového agenta.

Konflikt je zjištěn, pokud se vyskytne dva nebo více případů:

• Reprezentují stejný záměr (na základě normalizované verze otázky přirozeného jazyka), ale odkazují na různé tabulky nebo zobrazení
• Výpočet stejné metriky pomocí různé agregační logiky nebo různých úrovní členitosti
• Generování dotazů SQL, které by vrátily materiálně odlišné výsledky pro stejnou obchodní otázku

Tyto konflikty značí nejednoznačnost nebo nekonzistence v rámci několika ukázkových snímků. Jejich řešení pomáhá zlepšit determinismus, přesnost a celkové chování agenta.

Kontrola podrobností o konfliktu

Když se zjistí konflikty, sada SDK rozšíří jednotlivé konflikty na ukázkové řádky a poskytuje podrobnou diagnostiku, mezi které patří:

• Příklady, které jsou součástí konfliktu
• Otázka přirozeného jazyka a odpovídající JAZYK SQL pro každý příklad
• Popis konfliktu vysvětlující, jak se příklady liší
• Skóre spolehlivosti označující spolehlivost detekce konfliktů

V tomto podrobném zobrazení zjistíte, které příklady jsou v konfliktu a proč, a k určení příkladů, které by se měly aktualizovat nebo odebrat.

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

Následující příklad ukazuje výstup detekce konfliktů, související otázky a SQL a úroveň spolehlivosti každého zjištěného konfliktu.

Vysvětlení skóre validátoru

Když na ukázkových dotazech spustíte validátor, vygeneruje pro každý příklad tři klíčové skóre: Přehlednost, Související aMapování. Tato skóre vycházejí z toho, jak dobře odpovídají vašim dotazům v přirozeném jazyce a dotazům SQL, které odpovídají osvědčeným postupům.

• Jasnost
  Měří, zda je otázka přirozeného jazyka jasná a jednoznačná. Otázky by měly být specifické, zahrnují nezbytné metriky, časové rámce a filtry a vyhněte se vágním nebo multi-záměrným formulací.

  Příklad – dobrý: "Total revenue by region for 2024" (Celkové výnosy podle regionu za 2024).
  Příklad – Vyžaduje zlepšení: "Show performance" (Zobrazit výkon).

• Souvislost
  Vyhodnotí, jak přesně dotaz SQL odpovídá záměru otázky v přirozeném jazyce. SQL by měl vrátit správnou metriku, použít správné filtry a odpovídat požadované členitosti.

  Příklad – dobrý: Otázka se ptá na počet zákazníků v březnu 2025 → SQL počítá zákazníky s WHERE month='2025-03'.
  Příklad – Vyžaduje zlepšení: Otázka se zeptá na počet, ale SQL vrátí sumu (výnosy) nebo filtruje jiné období.

• Mapování
  Zkontroluje, jestli se v dotazu SQL zobrazí všechny literály v otázce přirozeného jazyka. Každé číslo, datum nebo kategorie uvedené v otázce by mělo být explicitně reprezentováno v SQL.

  Příklad – dobrý: "Objednávky nad 100 v březnu 2025 pro 'West'" → SQL zahrnuje > 100, 2025-03a 'West'.
  Příklad – Vyžaduje zlepšení: Sql chybí jeden z těchto literálů (například bez filtru měsíce).

Příklad se považuje za vysokou kvalitu pouze v případě, že jsou kladná všechna tři skóre – Přehlednost, Související a Mapování. Pomocí těchto skóre můžete upřesnit ukázkové dotazy: přepsat nejasné otázky, lépe zarovnat JAZYK SQL se záměrem otázky a zajistit, aby se v dotazu SQL zobrazil každý literál. Tento iterativní proces pomáhá datovému agentu učit se z lepších vzorů a vytvářet přesnější výsledky.

Další kroky

• koncept datového agenta
• Scénář datového agenta
• Ukázkový poznámkový blok pro ověření ukázkových dotazů