Use ativo confiável em AI/BI Genie spaces

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 o senhor prevê dos usuários. Quando um usuário envia uma pergunta que invoca um ativo confiável, ele é indicado na resposta, acrescentando uma camada extra de garantia à precisão dos resultados.

O ativo confiável pode incluir o seguinte:

• Exemplo de consultas parametrizadas SQL: Quando um exemplo parametrizado de consulta SQL é usado para gerar uma resposta, a resposta é um rótulo a ativo confiável. A resposta inclui os valores usados como argumentos na consulta.

• Funções de tabela definidas pelo usuário (UDFs): O senhor pode definir funções personalizadas e registrá-las em Unity Catalog. Em seguida, o senhor pode adicionar essas funções como ativo confiável quando estiver configurando instruções no seu espaço genie. Consulte Criar uma função de tabela SQL e Funções definidas pelo usuário (UDFs) no Unity Catalog.

Observação

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

Por que criar a trusted ativo?

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 a pergunta. Com genie, uma resposta é fornecida 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 conhecimento necessário 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 que é rotulada como um ativo confiável, ele pode ter certeza de que um especialista no domínio analisou a declaração SQL que preenche os resultados.

Qual é a diferença entre o ativo confiável e o exemplo de consultas SQL?

O ativo confiável fornece respostas verificadas às perguntas que o senhor espera que os usuários do espaço genie façam. Quando um ativo confiável pode responder a uma pergunta do usuário, a instrução que o senhor armazenou como um ativo confiável é executada e retorna o conjunto de resultados especificado. Todas as SQL Functions que o senhor incluir nas instruções serão tratadas como ativo confiável. Exemplo SQL As consultas que incluem parâmetros também podem ser tratadas como ativos confiáveis.

• Funções SQL: O senhor pode escrever funções SQL personalizadas para lidar com seus dados e abordar questões específicas da empresa. genie não considera o conteúdo SQL do seu ativo confiável ao responder às 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 se o exemplo de consulta não usar parâmetros, a consulta fornecerá o contexto e o guia genie na geração das declaraçõ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 provável pergunta. Por exemplo, suponha que o senhor esteja trabalhando com uma empresa de ventas pipeline dataset, e uma pergunta comum que um gerente de ventas pode fazer é: "Quais são as oportunidades de ventas abertas no meu pipeline?"

Exemplo: Usar um UDF

Os passos a seguir descrevem os passos para criar um ativo confiável, como o UDF, que responde a essa pergunta:

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

   Essa consulta une duas tabelas e retorna um dataset de oportunidades abertas listadas na categoria de previsão "pipeline". Neste passo, 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 do Unity Catalog.

   Sua função do Unity Catalog deve parametrizar a consulta e produzir resultados que correspondam às condições específicas que o senhor espera que o usuário pergunte. Suponha que o gerente de ventas queira restringir o conjunto de resultados, concentrando-se em uma determinada região ou grupo de regiões.

   O exemplo a seguir define uma função do Unity Catalog que recebe uma lista de regiões como parâmetro e retorna uma tabela. A função return é quase idêntica à declaração SQL no passo 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âmetros: A função open_opps_in_region espera um array de strings como parâmetro. O comentário inclui um exemplo da entrada esperada. Se nenhum parâmetro for fornecido, o valor de default será NULL. Consulte Dicas para escrever funções para saber mais sobre a inclusão de parâmetros opcionais e comentários.

   • Comentários de função: O comentário na função da tabela SQL fornece uma explicação detalhada do que a função faz. Isso é fundamental porque informa ao site genie quando usar a função como resposta às perguntas dos usuários. O comentário deve descrever a finalidade da função da forma mais precisa possível. Este guia de informações genie ajuda o senhor 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 o senhor executa o código para criar uma função, ela é registrada no esquema ativo no momento pelo site default. Consulte Funções definidas pelo usuário (UDFs) no Unity Catalog. Consulte Criar uma função de tabela SQL para ver a sintaxe e os exemplos.

3. Adicionar um ativo confiável.

   Depois que a função for criada em Unity Catalog, um usuário com pelo menos CAN EDIT permissão no espaço genie poderá adicioná-la a partir das instruções tab do espaço genie.

Permissões necessárias

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

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

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 o senhor deseja usar no espaço genie.

Dicas para escrever funções

Analise os exemplos a seguir para saber como criar funções dinâmicas para o ativo confiável.

Incluir um valor de parâmetro padrão

O senhor pode especificar um valor default para um parâmetro. Use a cláusula DEFAULT na assinatura da função, conforme mostrado no exemplo a seguir:

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

Incluir exemplos de valores de parâmetros

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 amostra 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 default como NULL, conforme mostrado no exemplo a seguir:

min_date STRING DEFAULT NULL

Especificar a formatação com comentários

O senhor 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'

Verificar explicitamente os valores NULL

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

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