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. Os usuários podem editar o valor do parâmetro na resposta.
• 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.

nota

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 do site AI, 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 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 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 com o rótulo Trusted , isso significa que um especialista no domínio adicionou a declaração SQL usada para gerar os resultados como uma instrução no espaço.

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 Confiável . Os usuários do espaço podem editar o valor do parâmetro em uma resposta e executar novamente a consulta usando o novo valor.

nota

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, mas não será marcada como confiável .

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 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 em aberto na minha região?"

Exemplo: Criar um UDF para responder à pergunta

As etapas a seguir descrevem como escrever uma consulta de teste e usá-la para criar um UDF:

1. Use o editorSQL ou um Notebook para definir e testar 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”. Nesta etapa, o objetivo é escrever uma consulta básica que retorne os resultados esperados.

SQL

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%';

1. 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. Por exemplo, 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. O retorno da função é quase idêntico à instrução SQL da 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 sobre o parâmetro : A função open_opps_in_region espera uma matriz 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 e comentários opcionais.
• 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 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. Este guia de informações Genie ajuda o senhor a reconhecer a relevância da função para questões específicas.

SQL

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.

1. 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.

Os usuários do Genie Space 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, a Databricks recomenda a criação de um esquema dedicado para conter todas as funções que o senhor deseja usar em seu 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 default

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:

SQL

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-as claramente no comentário. O exemplo a seguir fornece uma lista de exemplos de valores:

SQL

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

Crie um parâmetro opcional

Para criar um parâmetro opcional, defina o parâmetro default como NULL, conforme mostrado no exemplo a seguir:

SQL

min_date STRING DEFAULT NULL

Especifique 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 exemplo a seguir:

SQL

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

Verifique explicitamente os valores de NULL

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

SQL

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