Поделиться через

Примеры запросов

Примеры запросов (также называемые "примеры с малым количеством примеров") предоставляют агенту данных конкретные шаблоны для обучения. Они представляют собой примеры вопросов и их соответствующую логику запроса, которую создатели предоставляют, чтобы помочь агенту ответить. Когда пользователь задает вопрос источнику данных, агент данных автоматически извлекает наиболее важные примеры ( как правило, первые четыре) и передает их в процесс создания. Ссылаясь на эти примеры, агент лучше понимает ожидаемую структуру, фильтры и соединения, что помогает получать более точные, согласованные и учитывающие контекст результаты запросов.

Укажите примеры запросов

При предоставлении примеров запросов необходимо включить как вопрос естественного языка, так и соответствующий ответ на запрос. Каждый вопрос должен быть уникальным, чтобы предоставить агенту данных разнообразный набор ссылочных точек. Каждый пример запроса проверяется на схему выбранного источника данных— запросы, которые не передают проверку, не отправляются агенту. Чтобы примеры были использованы, важно подтвердить, что они проходят проверку.

Снимок экрана: добавление примеров запросов к агенту данных.

В таблице показано, какие источники данных в настоящее время поддерживают примеры запросов в агенте данных. Эти примеры помогают управлять процессом создания запросов агента, предоставляя шаблоны и контекст.

Тип источника данных Поддерживает примеры запросов?
Lakehouse ✅ Да
Склад ✅ Да
Базы данных eventhouse KQL ✅ Да
Семантические модели ❌ Нет
Онтология ❌ Нет

Вы также можете использовать представление шагов выполнения для отладки примеров запросов, полученных и примененных к вопросу пользователя. Это представление особенно полезно для подтверждения того, что используются правильные примеры и для диагностики того, почему создаются определенные результаты. Если отображаются неправильные примеры, попробуйте уточнить вопросы или добавить более четкие, более целевые примеры.

Снимок экрана: указанные примеры запросов в шагах выполнения.

Рекомендации по написанию примеров запросов

При создании примеров запросов для агента данных следование наилучшим практикам обеспечивает четкие и надёжные рекомендации во время создания запросов. Хорошо созданные примеры помогают агенту понять, как вопросы естественного языка преобразуются в логику SQL/KQL, выделяют сложные соединения или вычисления и повышают точность результатов. Используйте рекомендации, чтобы сделать примеры более эффективными и представительными для реальных сценариев пользователей.

# Лучшие практики Почему это важно
1 Обеспечьте четкое сопоставление вопросов с запросом Агент данных использует эти примеры для изучения шаблона соответствия между вопросом и результирующим SQL/KQL. Неоднозначность снижает точность.
2 Включение примечаний в запрос для руководства агентом Примечания ( -- substitute customer_id here) помогают агенту понять, где заменить значения или применить важную логику.
3 Подсветка логики соединений или сложных паттернов Используйте примеры запросов, чтобы показать, как обрабатывать соединения с несколькими таблицами, агрегаты или другую расширенную логику, которую трудно описать в простых инструкциях.
4 Избегайте перекрытия или противоречий Каждый пример должен быть уникальным и не конфликтующим, чтобы дать агенту чистый сигнал о том, как вести себя.
5 Используйте шаги выполнения для отладки примеров, которые передаются Этапы выполнения позволяют увидеть, какие примеры были получены для заданного вопроса пользователя — если отображаются неверные примеры, вы корректируете вопросы или добавляете более конкретные примеры.
6 Отражение реального поведения пользователя Добавьте примеры запросов, представляющих типы вопросов, которые задают пользователям, чтобы повысить релевантность и точность.

Проверка примеров запросов

Пакет SDK агента данных Fabric предоставляет встроенные средства для оценки и улучшения качества примеров запросов. evaluate_few_shots С помощью функции можно проверить каждую пару естественного языка или SQL, чтобы убедиться, что она понятна, правильно и соответствует схеме источника данных. Пакет SDK выполняет каждый пример с помощью процесса оценки агента данных, возвращая подробную сводку по примерам, переданным и которым требуется уточнение.

Укажите примеры запросов

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

Оценка с помощью пакета SDK

Просматривая уровень успеха и отзывы, вы можете итеративно настроить свои примеры — уточнение вопросов, улучшение логики SQL или добавление комментариев, чтобы Данные агент учился на основе более качественных шаблонов и давал более точные результаты для новых вопросов.

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

Отслеживание отзывов

После запуска проверяющего элемента вы получите четкое описание того, какие примеры прошли и которые завершились сбоем. Эта обратная связь упрощает выявление сильных и слабых мест в примерах с несколькими выстрелами.

  • Успешные случаи: Примеры, в которых SQL соответствовал ожидаемым ответам. Эти примеры являются строгими ссылками, после которых можно моделировать будущие примеры.
  • Случаи сбоя: Примеры, в которых SQL не соответствовал ожидаемому ответу или где пара вопросов и запросов может быть неясной или недопустимой. Эти случаи должны быть рассмотрены и уточнены.
# 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

Используйте этот отзыв для итерации и улучшения примеров запросов. Регулярное укрепление более слабых примеров поможет агенту данных создавать более точные SQL и ответы с течением времени.

Снимок экрана: пример результатов проверки запроса.

Чтобы изучить полный рабочий пример, вы можете ознакомиться с примером записной книжки в репозитории GitHub пакета SDK агента данных Fabric:

Замечание

Эта программа оценки в настоящее время доступна только для примеров запросов на основе SQL. KQL или другие типы запросов пока не поддерживаются.

Обнаружение конфликтов между примерами запросов

После завершения проверки качества пакет SDK для оценки автоматически выполняет обнаружение конфликтов в утвержденных примерах запросов или примерах с небольшим количеством примеров. Обнаружение конфликтов определяет несоответствия, которые могут привести к возникновению непредсказуемых или неправильных результатов агента данных.

Конфликт обнаруживается при двух или более примерах:

  • Представляет ту же цель (на основе нормализованной версии вопроса на естественном языке), но ссылается на разные таблицы или представления.
  • Вычисление одной и той же метрики с помощью другой логики агрегирования или различных уровней детализации
  • Создание запросов SQL, возвращающих существенно разные результаты для одного и того же бизнес-вопроса

Эти конфликты указывают на неоднозначность или несоответствие в приведенных нескольких примерах снимка. Разрешение их помогает улучшить детерминированность запросов, точность и общее поведение агента.

Просмотр сведений о конфликте

При обнаружении конфликтов SDK расширяет каждый конфликт в строки для каждого примера, предоставляя подробную диагностику, такие как:

  • Примеры, связанные с конфликтом
  • Вопрос естественного языка и соответствующий SQL для каждого примера
  • Описание конфликта, объясняющего, как примеры расходятся.
  • Оценка достоверности, указывающая надежность обнаружения конфликтов

Используйте это подробное представление, чтобы понять, какие примеры конфликтуют и почему, и определить, какие примеры следует обновить или удалить.

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

В следующем примере показаны выходные данные обнаружения конфликтов, связанные с ними вопросы и SQL, а также уровень достоверности каждого обнаруженного конфликта.

Снимок экрана: обнаружение конфликтов.

Понимание оценок валидатора

При запуске проверяющего элемента в примерах запросов он создает три ключевые оценки для каждого примера: ясность, связанность и сопоставление. Эти оценки являются производными от того, насколько хорошо ваши вопросы естественного языка и запросы SQL соответствуют рекомендациям.

  • Ясность
    Измеряет, является ли вопрос на естественном языке ясным и однозначным. Вопросы должны быть конкретными, включать необходимые метрики, временные интервалы и фильтры, а также избегать расплывчатых или многонамерных выражений.

    Пример— хороший: "Общий доход по регионам за 2024 год".
    Пример. Требуется улучшение: "Показать производительность".

  • Связанность
    Оценивает, насколько тесно SQL-запрос соответствует намерению вопроса естественного языка. SQL должен возвращать правильную метрику, применять соответствующие фильтры и соответствовать запрошенной детализации.

    Пример — хороший: Вопрос заключается в подсчете количества клиентов в марте 2025 года → SQL подсчитывает клиентов с WHERE month='2025-03'.
    Пример. Требуется улучшение: Вопрос задает количество, но SQL возвращает СУММ(доход) или фильтрует другой период.

  • Картирование
    Проверяет , отображаются ли все литералы в вопросе естественного языка в SQL-запросе. Каждое число, дата или категория, упомянутые в вопросе, должны быть явно представлены в SQL.

    Пример— хороший: "Заказы более 100 в марте 2025 года для "Запад" → SQL включают > 100, 2025-03и 'West'.
    Пример – Требуется улучшение: У SQL отсутствует один из этих литералов (например, без фильтра месяца).

Пример считается высоким качеством только в том случае, если все три оценки — Ясность, связанность и сопоставление — положительны. Используйте эти оценки, чтобы уточнить примеры запросов: переписать неясные вопросы, выровнять SQL более тесно с намерением вопроса и убедиться, что каждый литерал в вопросе отображается в SQL-запросе. Этот итеративный процесс помогает агенту данных узнать о лучших шаблонах и получить более точные результаты.

Дальнейшие шаги

  • Last updated on