Use ativos confiáveis em espaços do AI/BI Genie

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

O que são ativos confiáveis?

Os 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, ela é indicada na resposta, adicionando uma camada extra de garantia à precisão dos resultados.

Os ativos confiáveis podem incluir o seguinte:

• Consultas SQL de exemplo parametrizadas: quando uma consulta SQL de exemplo parametrizada é usada para gerar uma resposta, a 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): Você pode definir funções personalizadas e registrá-las no Unity Catalog. Em seguida, você pode adicionar essas funções como ativos confiáveis ao configurar instruções no espaço do Genie. Consulte Criar uma função de tabela SQL e funções definidas pelo usuário (UDFs) no Unity Catalog.

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 efetivamente aborda 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 plano de fundo para interpretar a instrução SQL ou avaliar a correçã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 em domínio revisou a instrução SQL que preenche os resultados.

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

Os ativos confiáveis fornecem respostas verificadas às 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 você armazenou 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. Exemplo de consultas SQL que incluem parâmetros também podem ser tratadas como ativos confiáveis.

• Funções SQL: Você pode escrever funções SQL personalizadas 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.
• Exemplo de consultas SQL (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 pode fazer é: "Quais são as oportunidades de vendas abertas no meu pipeline?"

Exemplo: Usar um UDF

As etapas a seguir descrevem as etapas para criar um ativo confiável, como um 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. Defina uma função Unity Catalog.

   Sua função Unity Catalog deve parametrizar a consulta e produzir resultados correspondentes às condições específicas que você espera que o usuário pergunte. Suponha que o gerente de vendas queira restringir o conjunto de resultados concentrando-se em uma região ou grupo de regiões específico.

   O exemplo a seguir define uma função Unity Catalog 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 WHERE cláusula 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 críticos para instruir o espaço Genie sobre quando e como invocar essa função.

   • Comentários de parâmetro: A open_opps_in_region função 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. Consulte Dicas para escrever funções para obter mais informações sobre como incluir parâmetros opcionais e comentários.
   • Comentários da função: O comentário na função de tabela SQL fornece uma explicação detalhada do 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 da forma mais precisa possível. Essas informações orientam o Genie a reconhecer a 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, ele é registrado no esquema atualmente ativo por padrão. Consulte Funções definidas pelo usuário (UDFs) no Catálogo Unity. Consulte Criar uma função de tabela SQL para obter sintaxe e exemplos.

3. Adicione um ativo confiável.

   Depois que a função é criada no Unity Catalog, um usuário com pelo menos a permissão CAN EDIT no espaço Genie pode adicioná-la na guia Instruções do espaço Genie.

Permissões obrigatórias

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

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

Para simplificar o compartilhamento 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 em seu espaço Genie.

Dicas para funções de escrita

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

Incluir um valor de parâmetro padrão

Você pode especificar um valor padrão para um parâmetro. Use a DEFAULT cláusula na assinatura de função, conforme mostrado no exemplo a seguir:

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

Incluir valores de parâmetros de exemplo

Para colunas com uma enumeração definida de valores, aumente a precisão definindo-os claramente no comentário. O exemplo a seguir fornece uma lista de exemplo 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 mostrado no exemplo a seguir:

min_date STRING DEFAULT NULL

Especificar formatação com comentários

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

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

Verifique explicitamente os NULL valores

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

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