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

En este artículo se definen los recursos de confianza y se explica cómo usarlos para proporcionar respuestas verificadas 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 recursos de confianza pueden incluir los siguientes:

• Consultas SQL de ejemplo parametrizadas: cuando se usa una consulta SQL de ejemplo parametrizada para generar una respuesta, el repositorio se etiqueta como un recurso de confianza. La respuesta incluye los valores usados como argumentos en la consulta.
• Funciones de tabla definidas por el usuario (UDF): puede definir funciones personalizadas y registrarlas en Unity Catalog. Después, 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 recursos de confianza no son un sustituto del resto de 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 un recurso de confianza, puede estar seguro de que un experto en dominio ha revisado la instrucción SQL rellenando los resultados.

¿En qué se diferencian los recursos de confianza y las consultas SQL de ejemplo?

Los recursos de confianza proporcionan respuestas verificadas 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. Todas las funciones SQL que incluya en las instrucciones se tratan como recursos de confianza. Las consultas SQL de ejemplo que incluyen parámetros también se pueden tratar como recursos de confianza.

• Funciones SQL: puede escribir funciones SQL personalizadas adaptadas para controlar los datos y abordar preguntas específicas de la empresa. Genie no tiene en cuenta el contenido SQL de los recursos de confianza al responder a preguntas.
• Consultas SQL de ejemplo (con parámetros): cuando se usa el texto exacto de una consulta de ejemplo parametrizada para generar una respuesta, esta respuesta se etiqueta automáticamente como un recurso de confianza. Si no se usa el texto exacto de la consulta o la consulta de ejemplo no usa parámetros, esta consulta proporciona contexto y guía a Genie para generar las instrucciones SQL a fin de procesar otras preguntas.

Definición de un recurso de confianza

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

Ejemplo: Uso de un UDF

En los pasos siguientes se describen los pasos para crear un recurso de confianza, como UDF, que responde a esta pregunta:

1. Defina y pruebe una consulta SQL que responda a la pregunta.

   Esta consulta combina dos tablas y devuelve un conjunto de datos de oportunidades abiertas mostradas en la categoría de previsión "Canalización". 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%';
   

2. 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. Supongamos que el director 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 en 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.

3. Agregue un recurso de confianza.

   Después de publicarse la función en Unity Catalog, un usuario con al menos el permiso CAN EDIT en el espacio de Genie puede agregarlo desde la pestaña Instrucciones del espacio de Genie.

Permisos necesarios

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

Los usuarios del 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'

Comprobación explícita de 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)