Use ativo confiável em AI/BI genie espaços

Prévia

Este recurso está em Prévia pública. Os administradores do espaço de trabalho podem ativar esse recurso na página Pré-visualizações. Consulte Manage Databricks Previews.

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?

Trusted ativo são funções de tabela definidas pelo usuário que podem ser escritas para responder a perguntas específicas que o senhor prevê dos usuários. O senhor pode usá-las para definir funções SQL validadas e parametrizadas que funcionam como receitas para responder a perguntas comuns. 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.

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 a perguntas específicas e não são reutilizados pelo site genie para abordar perguntas adjacentes.

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 usa um ativo confiável, ele pode ter certeza de que um especialista no domínio revisou a instruçã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 função de tabela definida pelo usuário é armazenada como uma execução de ativo confiável e retorna o conjunto de resultados especificado. Dessa forma, o senhor sabe que seus usuários estão recebendo as informações corretas que respondem às suas perguntas, e os usuários corporativos têm a garantia adicional de que estão recebendo uma resposta aprovada. genie não considera o conteúdo SQL do seu ativo confiável ao responder às perguntas.

As consultas do exemplo SQL oferecem outra opção para configurar um espaço genie. Elas fornecem contexto para ensinar a genie como processar outras perguntas e escrever as declarações SQL que elas geram. Os exemplos exatos fornecidos na seção Example SQL Queries de um conjunto de instruções não são necessariamente retornados quando um usuário corporativo faz uma pergunta relacionada.

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?"

Os passos a seguir descrevem os passos para criar um ativo confiável que responda 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 SQL personalizadas 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)