Esimerkkikyselyt

Esimerkkikyselyt (joita kutsutaan myös "muutaman otoksen esimerkeiksi") antavat Data Agentille konkreettisia kaavoja, joista oppia. Ne ovat esimerkkikysymyksiä ja niitä vastaavaa kyselylogiikkaa, jonka tekijät toimittavat ohjaamaan, miten agentin tulisi vastata. Kun käyttäjä esittää kysymyksen tietolähteestä, data-agentti hakee automaattisesti tärkeimmät esimerkit – yleensä neljä parasta – ja syöttää ne luontiprosessiinsa. Näihin esimerkkeihin viittaamalla agentti voi ymmärtää paremmin odotetun rakenteen, suodattimet ja liitokset, mikä auttaa sitä tuottamaan tarkempia, johdonmukaisempia ja tilannetietoisempia kyselytuloksia.

Esimerkkikyselyiden tarjoaminen

Kun annat esimerkkikyselyitä, sinun on sisällytettävä sekä luonnollisen kielen kysymys että sitä vastaava kyselyvastaus. Jokaisen kysymyksen tulee olla yksilöllinen, jotta Data Agent saa monipuolisen joukon vertailukohtia. Jokainen esimerkkikysely tarkistetaan valitun tietolähteen rakenteen perusteella – kyselyitä, jotka eivät läpäise vahvistusta, ei lähetetä asiakaspalvelijalle. Jotta esimerkkisi varmasti käytetään, on tärkeää varmistaa, että ne läpäisevät tämän validointivaiheen.

Taulukko näyttää, mitkä tietolähteet tukevat tällä hetkellä esimerkkikyselyitä Data Agentissa. Nämä esimerkit ohjaavat agentin kyselyjen generointiprosessia tarjoamalla kaavoja ja kontekstia.

Tietolähteen tyyppi	Tukeeko esimerkkikyselyitä?
Lakehouse	✅ Kyllä
Varasto	✅ Kyllä
Eventhouse KQL-tietokannat	✅ Kyllä
Semanttiset mallit	❌ Ei
Ontologia	❌ Ei

Voit myös käyttää Run Steps -näkymää selvittääksesi, mitkä esimerkkikyselyt on haettu ja sovellettu käyttäjän kysymykseen. Tämä näkemys on erityisen hyödyllinen varmistamaan, että oikeita esimerkkejä käytetään ja diagnosoimaan, miksi tiettyjä tuloksia tuotetaan. Jos näkyviin tulee vääriä esimerkkejä, kokeile tarkentaa kysymyksiäsi tai lisätä selkeämpiä, kohdennetumpia esimerkkejä.

Esimerkkikyselyjen kirjoittamisen parhaat käytännöt

Kun luot esimerkkikyselyitä tietoagentille, parhaiden käytäntöjen noudattaminen varmistaa, että ne antavat selkeät ja luotettavat ohjeet kyselyn luomisen aikana. Hyvin muotoillut esimerkit auttavat agenttia ymmärtämään, miten luonnollisen kielen kysymykset muuttuvat SQL/KQL-logiikaksi, korostavat monimutkaisia liitoksia tai laskutoimituksia ja parantavat tulosten tarkkuutta. Käytä ohjeita tehdäksesi esimerkeistäsi tehokkaampia ja edustavampia todellisia käyttäjätilanteita.

#	Paras käytäntö	Miksi sillä on merkitystä
1	Varmista, että kysymykset yhdistetään selkeästi kyselyyn	Data Agent käyttää näitä esimerkkejä oppiakseen kysymyksen ja tuloksena olevan SQL/KQL:n välisen mallin. Epäselvyys heikentää tarkkuutta.
2	Sisällytä kyselyyn kommentteja asiakaspalvelijan ohjaamiseksi	Kommentit ( -- substitute customer_id here) auttavat agenttia ymmärtämään, missä arvot tulisi korvata tai soveltaa tärkeää logiikkaa.
3	Korosta liitoslogiikkaa tai monimutkaisia malleja	Käytä esimerkkikyselyitä näyttämään, miten käsitellä monitaululiitoksia, aggregaatioita tai muuta kehittynyttä logiikkaa, jota on vaikea kuvailla pelkillä käskyillä.
4	Vältä päällekkäisyyksiä tai ristiriitoja	Jokaisen esimerkin tulee olla erillinen ja ristiriidaton, jotta agentti saa selkeän signaalin siitä, miten hänen tulee käyttäytyä.
5	Käytä suoritusvaiheita läpäisttyjen esimerkkien virheenkorjaukseen	Suoritusvaiheiden avulla näet, mitkä esimerkit on haettu tietylle käyttäjäkysymykselle – jos vääriä esimerkkejä tulee näkyviin, muokkaa kysymyksiä tai lisää tarkempia esimerkkejä.
6	Heijastaa todellista käyttäjien käyttäytymistä	Lisää esimerkkejä kyselyistä, jotka edustavat käyttäjien esittämiä kysymyksiä, jotta niiden relevanssi ja tarkkuus maksimoidaan.

Esimerkkikyselyjen vahvistaminen

Fabric Data Agent SDK tarjoaa sisäisiä työkaluja esimerkkikyselyjen laadun arvioimiseen ja parantamiseen. Funktion avulla evaluate_few_shots voit vahvistaa kunkin luonnollisen kielen / SQL-parin varmistaaksesi, että se on selkeä, oikea ja linjassa tietolähteen rakenteen kanssa. SDK ajaa jokaisen esimerkin Data Agentin arviointiprosessin läpi, palauttaen yksityiskohtaisen yhteenvedon siitä, mitkä esimerkit on hyväksytty ja mitkä tarvitsevat tarkennuksia.

Esimerkkikyselyiden tarjoaminen

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

Arviointi SDK:n avulla

Tarkastelemalla onnistumisprosenttia ja palautetta voit iteratiivisesti muokata esimerkkejäsi – selventää kysymyksiä, parantaa SQL-logiikkaa tai lisätä kommentteja – jotta Data Agent oppii laadukkaammista malleista ja tuottaa tarkempia tuloksia uusille kysymyksille.

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

Kappalepalaute

Validaattorin suorittamisen jälkeen saat selkeän erittelyn siitä, mitkä esimerkit läpäisivät ja mitkä epäonnistuivat. Tämän palautteen avulla on helppo tunnistaa vahvuudet ja heikkoudet muutaman laukauksen esimerkeissäsi.

• Menestystapaukset: Esimerkkejä, joissa SQL vastasi odotettuja vastauksia. Nämä esimerkit ovat vahvoja viitteitä, joiden pohjalta voit mallintaa tulevia esimerkkejä.
• Epäonnistumistapaukset: Esimerkkejä, joissa SQL ei vastannut odotettua vastausta tai joissa kysymys/kyselypari voi olla epäselvä tai virheellinen. Näitä tapauksia olisi tarkasteltava uudelleen ja tarkennettava.

# 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

Tämän palautteen avulla voit iteroida ja parantaa esimerkkikyselyitäsi. Heikompien esimerkkien säännöllinen vahvistaminen auttaa Data Agentia tuottamaan tarkempia SQL:iä ja vastauksia ajan myötä.

Jos haluat tutustua täydelliseen toimivaan esimerkkiin, voit tutustua Fabric Data Agent SDK GitHub -säilön mallimuistikirjaan:

Note

Tämä arviointiapuohjelma on tällä hetkellä käytettävissä vain SQL-pohjaisissa esimerkkikyselyissä. KQL:ää tai muita kyselytyyppejä ei vielä tueta.

Tunnista ristiriidat esimerkkikyselyiden välillä

Laadun validoinnin jälkeen arviointi-SDK suorittaa automaattisesti ristiriitojen tunnistuksen hyväksytyille esimerkkikyselyille tai vähäisistä esimerkeistä. Ristiriitojen tunnistus tunnistaa epäjohdonmukaisuuksia, jotka voivat aiheuttaa tietoagentille arvaamattomia tai virheellisiä tuloksia.

Ristiriita havaitaan, kun kaksi tai useampi esimerkki:

• Edusta samaa tarkoitusta (perustuen normaalimuotoiseen luonnollisen kielen kysymykseen), mutta viittaa eri taulukoihin tai näkemyksiin
• Laske sama metriikkaeri aggregaatiologiikalla tai eri rakeisuustasoilla
• Luo SQL-kyselyt, jotka palauttavat olennaisesti erilaisia tuloksia samasta liiketoimintakysymyksestä

Nämä ristiriidat viittaavat epäselvyyteen tai epäjohdonmukaisuuteen harvoissa kuvaesimerkeissä. Niiden ratkaiseminen auttaa parantamaan kyselyjen determinismiä, tarkkuutta ja agentin yleistä käyttäytymistä.

Arvostelun konfliktin yksityiskohdat

Kun ristiriitoja havaitaan, SDK laajentaa jokaisen konfliktin esimerkkiriveihin, tarjoten yksityiskohtaisia diagnostiikkaratkaisuja, mukaan lukien:

• Sotaan liittyvät esimerkit
• Luonnollisen kielen kysymys ja vastaava SQL jokaiselle esimerkille
• Kuvaus konfliktista, jossa selitetään, miten esimerkit eroavat
• Luottamuspiste, joka osoittaa konfliktin havaitsemisen luotettavuuden

Käytä tätä yksityiskohtaista näkymää ymmärtääksesi, mitkä esimerkit ovat ristiriidassa ja miksi, sekä päättääksesi, mitkä esimerkit tulisi päivittää tai poistaa.

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

Seuraava esimerkki näyttää ristiriitojen tunnistustuloksen, niihin liittyvät kysymykset ja SQL:n sekä kunkin havaitun konfliktin luottamustason.

Validointipisteiden ymmärtäminen

Kun suoritat validaattorin esimerkkikyselyissäsi, se luo kullekin esimerkille kolme avainpistemäärää: Selkeys, Suhde ja Kartoitus. Nämä pisteet johdetaan siitä, kuinka hyvin luonnollisen kielen kysymykset ja SQL-kyselyt vastaavat parhaita käytäntöjä.

• Selkeys
  Mittaa, onko luonnollisen kielen kysymys selkeä ja yksiselitteinen. Kysymysten tulee olla tarkkoja, sisältää tarvittavat mittarit, aikataulut ja suodattimet ja välttää epämääräisiä tai usean tarkoituksen muotoiluja.

  Esimerkki – Hyvä: "Kokonaisliikevaihto alueittain vuodelle 2024."
  Esimerkki – Tarvitsee parannusta: "Näytä esitys."

• Yhteenkuuluvuus
  Arvioi, kuinka tarkasti SQL-kysely vastaa luonnollisen kielen kysymyksen tarkoitusta. SQL:n pitäisi palauttaa oikea mittari, käyttää oikeita suodattimia ja vastata pyydettyä rakeisuutta.

  Esimerkki – Hyvä: Kysymyksessä kysytään asiakkaiden määrää maaliskuussa 2025 → SQL laskee asiakkaat, joilla on WHERE month='2025-03'.
  Esimerkki – Kaipaa parannusta: Kysymyksessä kysytään määrää, mutta SQL palauttaa SUM(tulot) tai suodattaa eri ajanjakson.

• -
  Tarkistaa, näkyvätkö kaikki luonnollisen kielen kysymyksen literaalit SQL-kyselyssä. Jokainen kysymyksessä mainittu numero, päivämäärä tai luokka tulee esittää eksplisiittisesti SQL:ssä.

  Esimerkki – Hyvä: "Yli 100 tilausta maaliskuussa 2025 'Westille'" → SQL sisältää > 100, 2025-03, ja 'West'.
  Esimerkki – Tarvitsee parannusta: SQL:ltä puuttuu yksi niistä literaaleista (esimerkiksi ei kuukausisuodatinta).

Esimerkkiä pidetään laadukkaana vain, jos kaikki kolme pistettä – selkeys, sukulaisuus ja kartoitus – ovat positiivisia. Näiden pisteiden avulla voit tarkentaa esimerkkikyselyitäsi: kirjoita epäselvät kysymykset uudelleen, kohdista SQL tarkemmin kysymyksen tarkoitukseen ja varmista, että kaikki kysymyksen literaalit näkyvät SQL-kyselyssä. Tämä iteratiivinen prosessi auttaa data-agenttia oppimaan paremmista malleista ja tuottamaan tarkempia tuloksia.

Seuraavat vaiheet

• tietoagenttikonsepti
• Tietoagentin skenaario
• Esimerkkimuistikirja esimerkkikyselyjen vahvistamiseen