Usar ativos confiáveis em espaços Genie de IA/BI

Este artigo define o que são ativos confiáveis e explica como usá-los para fornecer respostas verificadas em um espaço Genie.

O que são ativos confiáveis?

Ativos confiáveis são funções predefinidas e consultas de exemplo destinadas a fornecer respostas verificadas às perguntas que você espera dos usuários. Quando um usuário envia uma pergunta que invoca um ativo confiável, a resposta inclui essa indicação, o que adiciona uma camada adicionar de garantia à precisão dos resultados.

Os ativos confiáveis podem incluir:

• Consultas SQL com exemplo parametrizado: quando uma consulta SQL com exemplo parametrizado é usada para gerar uma resposta, essa resposta é rotulada como um ativo confiável. A resposta inclui os valores usados como argumentos na consulta.
• Funções de tabela definidas pelo usuário (UDFs): é possível definir funções personalizadas e registrá-las no Catálogo do Unity. Em seguida, você pode adicionar essas funções como ativos confiáveis ao configurar as instruções em seu espaço Genie. Consulte Criar uma função de tabela SQL e UDFs (funções definidas pelo usuário) no Catálogo do Unity.

Observação

Os ativos confiáveis não substituem todas as outras instruções. O Databricks recomenda o uso de ativos confiáveis para perguntas recorrentes. Eles fornecem respostas exatas para perguntas específicas.

Por que criar ativos confiáveis?

Ao usar qualquer ferramenta de IA, os usuários devem avaliar a precisão das respostas geradas. Normalmente, eles fazem isso considerando se a resposta faz sentido e aborda efetivamente sua pergunta. Com o Genie, uma resposta é entregue como uma tabela de resultados. Os usuários podem revisar o SQL gerado que cria o conjunto de resultados, mas os usuários não técnicos podem não ter o histórico para interpretar a instrução SQL ou avaliar a exatidão da resposta. Os ativos confiáveis ajudam a reduzir a probabilidade de esses usuários encontrarem respostas enganosas, incorretas ou difíceis de interpretar.

Quando um usuário recebe uma resposta rotulada como um ativo confiável, ele pode ter certeza de que um especialista de domínio revisou a instrução SQL que preenche os resultados.

Qual é a diferença entre ativos confiáveis e consultas SQL de exemplo?

Ativos confiáveis fornecem respostas verificadas a perguntas que você espera que os usuários do espaço Genie façam. Quando um ativo confiável pode responder à pergunta de um usuário, a instrução que armazenada como um ativo confiável é executada e retorna o conjunto de resultados especificado. Todas as funções SQL incluídas nas instruções são tratadas como ativos confiáveis. Consultas SQL de exemplo que incluem parâmetros também podem ser tratadas como ativos confiáveis.

• Funções SQL: escreva funções SQL personalizadas para lidar com seus dados e abordar questões específicas da empresa. O Genie não considera o conteúdo SQL de seus ativos confiáveis ao responder a perguntas.
• Consultas SQL de exemplo (com parâmetros): quando o texto exato de uma consulta de exemplo parametrizada é usado para gerar uma resposta, a resposta é automaticamente rotulada como um ativo confiável. Se o texto exato da consulta não for usado ou a consulta de exemplo não usar parâmetros, a consulta fornecerá contexto e orientará o Genie na geração das instruções SQL para processar outras perguntas.

Definir um ativo confiável

A definição de um ativo confiável começa com a identificação de uma pergunta provável. Por exemplo, suponha que você esteja trabalhando com um conjunto de dados de pipeline de vendas e uma pergunta comum que um gerente de vendas possa fazer é: “Quais são as oportunidades de vendas abertas no meu pipeline?”

Exemplo: usar uma UDF

As seguintes etapas descrevem como criar um ativo confiável, como uma UDF, que responde a essa pergunta:

1. Defina e teste uma consulta SQL que responda à pergunta.

   Essa consulta une duas tabelas e retorna um conjunto de dados de oportunidades abertas listadas na categoria de previsão “Pipeline”. Nesta etapa, o objetivo é escrever uma consulta básica que retorne os 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. Definir uma função de Catálogo do Unity.

   Sua função de Catálogo do Unity deve parametrizar a consulta e produzir resultados que correspondam às condições específicas que você espera que um usuário pergunte. Suponha que o gerente de vendas queira restringir o conjunto de resultados com foco em uma determinada região ou grupo de regiões.

   O exemplo a seguir define uma função de Catálogo do Unity que usa uma lista de regiões como parâmetro e retorna uma tabela. O retorno da função é quase idêntico à instrução SQL na etapa anterior, exceto que a cláusula WHERE foi modificada para filtrar os resultados por região, se uma região tiver sido fornecida. Os comentários fornecidos nas definições de função são essenciais para instruir o espaço Genie sobre quando e como invocar essa função.

   • Comentários de parâmetro: a função open_opps_in_region espera uma matriz de cadeias de caracteres como um parâmetro. O comentário inclui um exemplo da entrada esperada. Se nenhum parâmetro for fornecido, o valor padrão será NULL. Confira Dicas para escrever funções para obter mais informações sobre como incluir comentários e parâmetros opcionais.
   • Comentários de função: o comentário na função de tabela SQL fornece uma explicação detalhada sobre o que a função faz. Isso é fundamental porque informa ao Genie quando usar a função como resposta às perguntas do usuário. O comentário deve descrever o propósito da função com a maior precisão possível. Essas informações orientam o Genie no reconhecimento da relevância da função para questões 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)
     );
   

   Quando você executa o código para criar uma função, ela é registrada no esquema ativo atualmente por padrão. Consulte UDFs (funções definidas pelo usuário) no Catálogo do Unity. Confira Criar uma função de tabela SQL para obter sintaxe e exemplos.

3. Adicionar um ativo confiável.

   Após criar uma função no Catálogo do Unity, um usuário com pelo menos a permissão CAN EDIT no espaço Genie pode adicioná-la da guia Instruções do espaço Genie.

Permissões necessárias

Os usuários com pelo menos a permissão CAN EDIT em um espaço do Genie podem adicionar ou remover ativos confiáveis.

Os usuários do espaço Genie devem ter permissão CAN USE no catálogo e no esquema que contém a função. Para invocar um ativo confiável, eles devem ter permissão EXECUTE na função no Catálogo do Unity. Os objetos protegíveis do Catálogo do Unity herdam permissões de seus contêineres pai. Consulte Objetos protegíveis no Catálogo do Unity.

Para um compartilhamento simplificado em um espaço Genie, o Databricks recomenda a criação de um esquema dedicado para conter todas as funções que você deseja usar no espaço Genie.

Dicas para escrever funções

Revise os exemplos a seguir para saber como criar funções dinâmicas para ativos confiáveis.

Incluir um valor de parâmetro padrão

É possível especificar um valor padrão para um parâmetro. Use a cláusula DEFAULT na assinatura de função, conforme mostrado no seguinte exemplo:

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

Incluir valores de parâmetro de exemplo

Para colunas com uma enumeração definida de valores, aumente a precisão definindo-os claramente no comentário. O seguinte exemplo fornece uma lista de amostras de valores:

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

Criar um parâmetro opcional

Para criar um parâmetro opcional, defina o parâmetro padrão como NULL, conforme mostrado no seguinte exemplo:

min_date STRING DEFAULT NULL

Especificar a formatação com comentários

Você pode especificar um formato exato para um parâmetro incluindo-o em um comentário, conforme mostrado no seguinte exemplo:

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

Verifique explicitamente os valores NULL

Se você incluir um parâmetro opcional, um possível valor que você deve esperar é NULL. Como a comparação com NULL pode produzir resultados imprevisíveis, você deve criar explicitamente uma verificação de valores NULL em sua função. O seguinte exemplo fornece um exemplo de sintaxe:

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