Usar ativos confiáveis em espaços do Genie de IA/BI

Esta página define ativos confiáveis e explica como usá-los para fornecer respostas verificadas em um espaço do Genie.

O que são ativos confiáveis?

Ativos confiáveis são funções predefinidas e exemplos de consultas 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:

• Exemplo de consultas SQL parametrizadas: quando um exemplo de consulta SQL parametrizada é 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 Unity Catalog. 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 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. Geralmente, eles fazem isso considerando se a resposta faz sentido e aborda de forma efetiva a pergunta feita. Com o 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 para interpretar a instrução SQL ou avaliar a exatidão da resposta. Os ativos confiáveis ajudam a reduzir a probabilidade desses 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?

Os 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. Exemplos de consultas SQL que incluem parâmetros e funções SQL que você adiciona ao contexto de um espaço são tratados como ativos confiáveis.

• 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.
• Funções SQL: você pode escreva funções SQL personalizadas para lidar com seus dados e solucionar dúvidas específicas da empresa. O Genie não considera o conteúdo SQL de seus ativos confiáveis ao responder às 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 possa fazer é: "Quais são as oportunidades de vendas abertas na minha região?"

Exemplo: criar uma UDF para responder a 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 do Unity Catalog.

Sua função do Unity Catalog 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 do Unity Catalog que usa uma lista de regiões como um parâmetro e retorna uma tabela. O retorno da função será 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 da 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 Funções definidas pelo usuário (UDFs) no Unity Catalog. Confira Criar uma função de tabela SQL para obter sintaxe e exemplos.

1. Adicione um ativo confiável.

   Depois que a função é criada no Catálogo do Unity, um usuário com pelo menos a permissão CAN EDIT no espaço do Genie pode adicioná-la ao espaço do Genie. Clique em Configurar>Contexto>Consultas SQL. Em seguida, clique em Adicionar.

Permissões necessárias

Os usuários que têm 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 do 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 Unity Catalog. Os objetos protegíveis do Unity Catalog herdam permissões de seus contêineres pai. Consulte Objetos protegíveis no Unity Catalog.

Para simplificar o compartilhamento em um espaço do Genie, o Databricks recomenda criar um esquema dedicado para conter todas as funções que você deseja usar no espaço do 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 da função, conforme mostrado no seguinte exemplo:

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

Incluir exemplo de valores de parâmetro

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 exemplos 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 valor possível que você deve esperar será NULL. Como a comparação com NULL pode gerar 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)