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, ela é indicada na resposta, adicionando uma camada extra 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. Os usuários podem editar o valor do parâmetro na resposta.
• 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 quando estiver configurando instruções em seu espaço do 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 Confiável, isso significa que um especialista em domínio adicionou a instrução SQL usada para gerar os resultados como uma instrução no espaço.

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 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.
• Exemplo de consultas SQL (com parâmetros): quando um texto exato de uma consulta de exemplo parametrizado é usado para gerar uma resposta, a resposta é rotulada automaticamente como Confiável. Os usuários de espaço podem editar o valor do parâmetro em uma resposta e executar novamente a consulta usando o novo valor.

Observação

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

Exemplo: criar uma UDF para responder à pergunta

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

1. Use o editor do SQL ou um notebook para definir e testar uma consulta SQL que responda à pergunta.

Essa consulta une duas tabelas e retorna um conjunto de dados de oportunidades abertas listadas na “Pipeline” categoria de previsão. 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%';

1. 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. Por exemplo, suponha que o gerente de vendas queira restringir o conjunto de resultados focando 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 a finalidade da função da forma mais precisa possível. Essas informações orientam o Genie a reconhecer a relevância da função para perguntas 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.

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