Uso de recursos de confianza en espacios de AI/BI Genie

En esta página se definen los recursos de confianza y se explica cómo usarlos para proporcionar respuestas comprobadas en un espacio de Genie.

¿Qué son los recursos de confianza?

Los recursos de confianza son funciones predefinidas y consultas de ejemplo diseñadas para proporcionar respuestas verificadas a preguntas que prevé que hagan los usuarios. Cuando un usuario envía una pregunta que invoca un recurso de confianza, se indica en la respuesta, agregando una capa adicional de garantía a la precisión de los resultados.

Los activos de confianza pueden incluir los siguientes:

• Consultas SQL de ejemplo parametrizadas: Cuando se usa una consulta SQL de ejemplo parametrizada para generar una respuesta, esta se etiqueta como un recurso de confianza. La respuesta incluye los valores usados como argumentos en la consulta. Los usuarios pueden editar el valor del parámetro en la respuesta.
• Funciones de tabla definidas por el usuario (UDF): puede definir funciones personalizadas y registrarlas en Unity Catalog. A continuación, puede agregar esas funciones como recursos de confianza cuando configure instrucciones en el espacio de Genie. Vea Creación de una función de tabla SQL y Funciones definidas por el usuario (UDF) en Unity Catalog.

Nota:

Los activos de confianza no son un sustituto de otras instrucciones. Databricks recomienda usar recursos de confianza para preguntas periódicas bien establecidas. Proporcionan respuestas exactas a preguntas específicas.

¿Por qué conviene crear recursos de confianza?

Al usar cualquier herramienta de IA, los usuarios deben evaluar la precisión de las respuestas generadas. Normalmente, lo hacen teniendo en cuenta si la respuesta tiene sentido y aborda de forma eficaz su pregunta. Con Genie, se entrega una respuesta en forma de tabla de resultados. Los usuarios pueden revisar la instrucción SQL generada que crea el conjunto de resultados, pero es posible que los usuarios sin conocimientos técnicos no tengan los conocimientos para interpretar la instrucción SQL o evaluar la exactitud de la respuesta. Los recursos de confianza ayudan a reducir la probabilidad de que estos usuarios encuentren respuestas erróneas, incorrectas o difíciles de interpretar.

Cuando un usuario recibe una respuesta etiquetada como Trusted, significa que un experto en dominio ha agregado la instrucción SQL utilizada para generar los resultados como una instrucción en el espacio.

¿Cuál es la diferencia entre los recursos de confianza y las consultas SQL de ejemplo?

Los recursos de confianza proporcionan respuestas comprobadas a preguntas que espera que los usuarios del espacio de Genie hagan. Cuando un recurso de confianza puede responder a la pregunta de un usuario, la instrucción que ha almacenado como un recurso de confianza se ejecuta y devuelve el conjunto de resultados especificado. Las consultas SQL de ejemplo que incluyen parámetros y funciones SQL que se agregan al contexto de un espacio se tratan como recursos de confianza.

• Consultas SQL de ejemplo (con parámetros): cuando se usa el texto exacto de una consulta de ejemplo para generar una respuesta, la respuesta se etiqueta automáticamente como De confianza. Los usuarios del espacio pueden editar el valor de un parámetro en una respuesta y ejecutar de nuevo la consulta con el nuevo valor.
• Funciones SQL: puede escribir funciones SQL personalizadas adaptadas para controlar los datos y abordar preguntas específicas de la empresa. Genie no toma en consideración el contenido SQL de tus activos de confianza al responder preguntas.

Nota:

Si no se usa el texto exacto de la consulta o la consulta de ejemplo no usa parámetros, las consultas de ejemplo proporcionan contexto y guía a Genie para generar las instrucciones SQL, pero no se marcan como De confianza.

Definición de un recurso de confianza

La definición de un recurso de confianza comienza por identificar una pregunta probable. Por ejemplo, supongamos que está trabajando con un conjunto de datos de canalización de ventas y una pregunta común que podría plantear un administrador de ventas es"¿Cuáles son las oportunidades de ventas abiertas en mi región?"

Ejemplo: Crear una UDF para responder a la pregunta

En los pasos siguientes se describe cómo escribir una consulta de prueba y usarla para crear una UDF:

1. Use el editor SQL o un cuaderno para definir y probar una consulta SQL que responda a la pregunta.

Esta consulta combina dos tablas y devuelve un conjunto de datos de oportunidades abiertas enumeradas en la categoría de previsión de “Pipeline”. En este paso, el objetivo es escribir una consulta básica que devuelva los resultados esperados.

SELECT
  o.id AS `OppId`,
  a.region__c AS `Region`,
  o.name AS `Opportunity Name`,
  o.forecastcategory AS `Forecast Category`,
  o.stagename,
  o.closedate AS `Close Date`,
  o.amount AS `Opp Amount`
FROM
users.user_name.opportunity o
JOIN catalog.schema.accounts a ON o.accountid = a.id
WHERE
o.forecastcategory = 'Pipeline'
AND o.stagename NOT LIKE '%closed%';

1. Defina una función de Unity Catalog.

La función Unity Catalog debe parametrizar la consulta y generar resultados que coincidan con las condiciones específicas sobre las que espera que el usuario pregunte. Por ejemplo, supongamos que el administrador de ventas quiere restringir el conjunto de resultados centrándose en una región o grupo de regiones concretos.

En el ejemplo siguiente se define una función Unity Catalog que toma una lista de regiones como parámetro y devuelve una tabla. La función devuelta es casi idéntica a la instrucción SQL del paso anterior, excepto que la cláusula WHERE se ha modificado para filtrar los resultados por región si se ha proporcionado una. Los comentarios proporcionados en las definiciones de función son fundamentales para indicar al espacio de Genie cuándo y cómo invocar esta función.

• Comentarios de parámetro: La open_opps_in_region función espera una matriz de cadenas como parámetro. El comentario incluye un ejemplo de la entrada esperada. Si no se proporciona ningún parámetro, el valor predeterminado es NULL. Vea Recomendaciones para escribir funciones a fin de obtener más información sobre cómo incluir parámetros y comentarios opcionales.
• Comentarios de función: el comentario de la función de tabla SQL aporta una explicación detallada de lo que hace la función. Esto es fundamental porque informa a Genie cuándo usar la función como respuesta a las preguntas del usuario. El comentario debe describir el propósito de la función de la forma más precisa posible. Esta información guía a Genie para reconocer la relevancia de la función en preguntas específicas.

CREATE
OR REPLACE FUNCTION users.user_name.open_opps_in_region (
  regions ARRAY < STRING >
  COMMENT 'List of regions.  Example: ["APAC", "EMEA"]' DEFAULT NULL
) RETURNS TABLE
COMMENT 'Addresses questions about the pipeline in the specified regions by returning
a list of all the open opportunities. If no region is specified, returns all open opportunities.
Example questions: "What is the pipeline for APAC and EMEA?", "Open opportunities in
APAC"'
RETURN
  SELECT
  o.id AS `OppId`,
  a.region__c AS `Region`,
  o.name AS `Opportunity Name`,
  o.forecastcategory AS `Forecast Category`,
  o.stagename,
  o.closedate AS `Close Date`,
  o.amount AS `Opp Amount`
  FROM
  catalog.schema.opportunity o
  JOIN catalog.schema.accounts a ON o.accountid = a.id
  WHERE
  o.forecastcategory = 'Pipeline'
  AND o.stagename NOT LIKE '%closed%'
  AND (
    isnull(open_opps_in_region.regions)
    OR array_contains(open_opps_in_region.regions, region__c)
  );

Al ejecutar el código para crear una función, se registra en el esquema activo actualmente de forma predeterminada. Consulte Funciones definidas por el usuario (UDF) en Unity Catalog. Vea Creación de una función de tabla SQL para obtener sintaxis y ejemplos.

1. Agregue un recurso de confianza.

   Una vez creada la función en el catálogo de Unity, un usuario con al menos el permiso CAN EDIT en el espacio de Genie puede agregarlo al espacio de Genie. Haga clic en Configurar>contexto>consultas SQL. A continuación, haga clic en Agregar.

Permisos necesarios

Los usuarios con al menos el permiso CAN EDIT en un espacio de Genie pueden agregar o quitar activos de confianza.

Los usuarios de espacio de Genie deben tener el permiso CAN USE en el catálogo y el esquema que contiene la función. Para invocar un recurso de confianza, deben tener el permiso EXECUTE en la función en Unity Catalog. Los objetos protegibles del Unity Catalog heredan los permisos de sus contenedores primarios. Vea Objetos protegibles en Unity Catalog.

Para simplificar el uso compartido en un espacio de Genie, Databricks recomienda crear un esquema dedicado para contener todas las funciones que quiere usar en el espacio de Genie.

Recomendaciones para escribir funciones

Revise los ejemplos siguientes a fin de obtener información sobre cómo crear funciones dinámicas para recursos de confianza.

Inclusión de un valor de parámetro predeterminado

Puede especificar un valor predeterminado para un parámetro. Use la cláusula DEFAULT en la signatura de función tal como se muestra en el ejemplo siguiente:

countries ARRAY<STRING> COMMENT 'List of countries' DEFAULT ARRAY()

Inclusión de valores de parámetro de ejemplo

Para las columnas con una enumeración establecida de valores, aumente la precisión definiéndolas claramente en el comentario. En el ejemplo siguiente se proporciona una lista de valores de muestra:

regions ARRAY < STRING > COMMENT 'List of regions. Values: ["AF","AN","AS", "EU", "NA", "OC", "SA", NULL]'

Creación de un parámetro opcional

Para crear un parámetro opcional, establezca el parámetro NULL predeterminado tal como se muestra en el ejemplo siguiente:

min_date STRING DEFAULT NULL

Especificación del formato con comentarios

Puede especificar un formato exacto para un parámetro incluyéndolo en un comentario, tal como se muestra en el ejemplo siguiente:

min_date STRING COMMENT 'minimum date (included) for a transaction, in `yyyy-mm-dd` format'

Verifica explícitamente los valores NULL

Si incluye un parámetro opcional, un valor posible que debe esperar es NULL. Dado que la comparación con NULL puede producir resultados imprevisibles, debe crear explícitamente una comprobación de los valores NULL en la función. En el ejemplo siguiente se proporcionan sintaxis de muestra:

WHERE (isnull(min_date) OR created_date >= min_date)