Consultas de ejemplo

Las consultas de ejemplo (también denominadas "ejemplos de aprendizaje con pocos ejemplos") proporcionan al Agente de Datos patrones concretos de los cuales aprender. Son preguntas de ejemplo y su lógica de consulta correspondiente que los creadores proporcionan para guiar cómo debe responder el agente. Cuando un usuario realiza una pregunta en un origen de datos, el Agente de datos recupera automáticamente los ejemplos más relevantes (normalmente los cuatro primeros) y los alimenta en su proceso de generación. Al hacer referencia a estos ejemplos, el agente puede comprender mejor la estructura esperada, los filtros y las combinaciones, lo que le ayuda a generar resultados de consulta más precisos, coherentes y compatibles con el contexto.

Proporcionar consultas de ejemplo

Al proporcionar consultas de ejemplo, debe incluir una pregunta de lenguaje natural y su respuesta de consulta correspondiente. Cada pregunta debe ser única para proporcionar al Agente de datos un conjunto diverso de puntos de referencia. Cada consulta de ejemplo se valida con el esquema del origen de datos seleccionado: las consultas que no pasan la validación no se envían al agente. Para garantizar que tus ejemplos se utilicen, es esencial confirmar que pasen la validación.

En la tabla se muestran los orígenes de datos que admiten actualmente consultas de ejemplo en el Agente de datos. Estos ejemplos ayudan a guiar el proceso de generación de consultas del agente proporcionando patrones y contexto.

También puede usar la vista de pasos de ejecución para depurar qué consultas de ejemplo se recuperaron y aplicaron a la pregunta de un usuario. Esta vista es especialmente útil para confirmar que se usan los ejemplos correctos y para diagnosticar por qué se generan determinados resultados. Si aparecen ejemplos incorrectos, intente refinar sus preguntas o agregar ejemplos más claros y específicos.

Procedimientos recomendados para escribir consultas de ejemplo

Al crear consultas de ejemplo para el Agente de datos, los procedimientos recomendados siguientes garantizan que proporcionan instrucciones claras y confiables durante la generación de consultas. Los ejemplos bien diseñados ayudan al agente a comprender cómo las preguntas del lenguaje natural se traducen en lógica de SQL/KQL, resaltan combinaciones complejas o cálculos y mejoran la precisión de sus resultados. Use las instrucciones para que los ejemplos sean más eficaces y representativos de escenarios de usuario reales.

Validación de consultas de ejemplo

El SDK de Fabric Data Agent proporciona herramientas integradas para evaluar y mejorar la calidad de las consultas de ejemplo. Con la evaluate_few_shots función , puede validar cada par de lenguaje natural o SQL para confirmar que está claro, correcto y alineado con el esquema del origen de datos. El SDK ejecuta cada ejemplo a través del proceso de evaluación del Agente de Datos, devolviendo un resumen detallado de qué ejemplos pasaron y cuáles necesitan refinamiento.

Proporcionar consultas de ejemplo

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

Evaluación a través del SDK

Al revisar la tasa de éxito y los comentarios, puede ajustar de forma iterativa los ejemplos (aclarando preguntas, mejorando la lógica de SQL o agregando comentarios), por lo que el Agente de datos aprende de patrones de mayor calidad y genera resultados más precisos para nuevas preguntas.

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

Seguimiento de comentarios

Después de ejecutar el validador, recibirá un desglose claro de qué ejemplos pasaron y cuáles fallaron. Estos comentarios facilitan la identificación de puntos fuertes y débiles en los ejemplos de pocos planos.

• Casos de éxito: Ejemplos en los que SQL coincidía con las respuestas esperadas. Estos ejemplos son referencias sólidas en las que puede basarse para modelar ejemplos futuros.
• Casos de error: Ejemplos en los que SQL no coincide con la respuesta esperada o en los que el par de preguntas o consultas puede ser poco claro o no válido. Estos casos deben revisarse y refinarse.

# 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 estos comentarios para iterar y mejorar las consultas de ejemplo. El fortalecimiento periódico de los ejemplos más débiles ayudará al Agente de datos a generar SQL y respuestas más precisos a lo largo del tiempo.

Para explorar un ejemplo de trabajo completo, puede consultar el cuaderno de ejemplo en el repositorio de GitHub del SDK de Fabric Data Agent:

Detecta conflictos entre consultas de ejemplo

Una vez completada la validación de calidad, el SDK de evaluación realiza automáticamente la detección de conflictos en las consultas de ejemplo aprobadas o en ejemplos de pocos disparos. La detección de conflictos identifica incoherencias que pueden hacer que el Agente de datos genere resultados impredecibles o incorrectos.

Se detecta un conflicto cuando dos o más ejemplos:

• Representa la misma intención (basada en una versión normalizada de la pregunta del lenguaje natural), pero hace referencia a tablas o vistas diferentes.
• Calcule la misma métrica mediante una lógica de agregación diferente o niveles diferentes de granularidad.
• Generar consultas SQL que devolverían resultados materialmente diferentes para la misma pregunta empresarial

Estos conflictos indican ambigüedad o incoherencia en los ejemplos de pocos disparos proporcionados. Resolverlos ayuda a mejorar el determinismo de las consultas, la precisión y el comportamiento general del agente.

Revisar los detalles del conflicto

Cuando se detectan conflictos, el SDK expande cada conflicto en filas individuales para cada ejemplo, lo que proporciona los diagnósticos detallados, entre los que se incluyen:

• Ejemplos implicados en el conflicto
• Pregunta del lenguaje natural y SQL correspondiente para cada ejemplo
• Descripción del conflicto en el que se explica cómo se divergen los ejemplos
• Puntuación de confianza que indica la confiabilidad de la detección de conflictos

Use esta vista detallada para comprender qué ejemplos están en conflicto y por qué, y para determinar qué ejemplos se deben actualizar o quitar.

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

En el ejemplo siguiente se muestra la salida de detección de conflictos, sus preguntas asociadas y SQL, y el nivel de confianza de cada conflicto detectado.

Descripción de las puntuaciones del validador

Al ejecutar el validador en las consultas de ejemplo, genera tres puntuaciones clave para cada ejemplo: Claridad, Relación y Mapeo. Estas puntuaciones se derivan de la forma en que las preguntas de lenguaje natural y las consultas SQL se alinean con los procedimientos recomendados.

• Claridad
  Mide si la pregunta del lenguaje natural es clara e inequívoca. Las preguntas deben ser específicas, incluir métricas, períodos de tiempo y filtros necesarios, y evitar expresiones vagas o de varias intenciones.

  Ejemplo: Bueno: "Ingresos totales por región para 2024".
  Ejemplo – Necesita mejora: "Mostrar rendimiento".

• Relación
  Evalúa de cerca que la consulta SQL coincide con la intención de la pregunta del lenguaje natural. SQL debe devolver la métrica correcta, aplicar los filtros adecuados y coincidir con la granularidad solicitada.

  Ejemplo – Bueno: La formulación de la pregunta solicita el recuento de clientes en marzo de 2025 → SQL cuenta los clientes con WHERE month='2025-03'.
  Ejemplo: Necesita mejora: Una pregunta solicita un 'count', pero el SQL devuelve SUM(revenue) o filtra un período diferente.

• Cartografía
  Comprueba si todos los literales de la pregunta del lenguaje natural aparecen en la consulta SQL. Cada número, fecha o categoría mencionado en la pregunta debe representarse explícitamente en SQL.

  Ejemplo: Bueno: "Pedidos de más de 100 en marzo de 2025 para "Oeste" → SQL incluye > 100, 2025-03y 'West'.
  Ejemplo – Necesita Mejora: A SQL le falta uno de esos literales (por ejemplo, falta el filtro de mes).

Un ejemplo se considera de alta calidad solo si las tres puntuaciones (Claridad, Relación y Asignación) son positivas. Use estas puntuaciones para refinar las consultas de ejemplo: vuelva a escribir preguntas poco claras, alinee SQL más estrechamente con la intención de la pregunta y asegúrese de que todos los literales de la pregunta aparecen en la consulta SQL. Este proceso iterativo ayuda al Agente de datos a obtener mejores patrones y a generar resultados más precisos.

Pasos siguientes

• Concepto de agente de datos
• Escenario del agente de datos
• Cuaderno de ejemplo para validar consultas de ejemplo