Use ativos confiáveis em espaços do AI/BI Genie

Esta página 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 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 o seguinte:

• Consultas SQL de exemplo parametrizado: Quando uma consulta SQL de exemplo parametrizada é usada para gerar uma resposta, a 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): Você pode definir funções personalizadas e registrá-las no Unity Catalog. Em seguida, você pode adicionar essas funções como ativos confiáveis ao configurar instruções no 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. Normalmente, eles fazem isso considerando se a resposta faz sentido e efetivamente aborda 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 plano de fundo 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 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 às 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 que você armazenou como um ativo confiável é executada e retorna o conjunto de resultados especificado. Exemplo de consultas SQL que incluem parâmetros e funções SQL que você adiciona ao contexto de um espaço são tratadas como ativos confiáveis.

• 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 utilizadores do espaço de trabalho podem editar o valor do parâmetro numa resposta e reprocessar a consulta usando o novo valor.
• Funções SQL: Você pode escrever funções SQL personalizadas 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.

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 SQL ou um bloco de anotações 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 categoria de “Pipeline” 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. Defina uma função Unity Catalog.

Sua função Unity Catalog deve parametrizar a consulta e produzir resultados correspondentes às condições específicas que você espera que o usuário pergunte. Por exemplo, suponha que o gerente de vendas 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 Unity Catalog 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 WHERE cláusula 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 críticos para instruir o espaço Genie sobre quando e como invocar essa função.

• Comentários de parâmetro: A open_opps_in_region função 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. Consulte Dicas para escrever funções para obter mais informações sobre como incluir parâmetros opcionais e comentários.
• Comentários da função: O comentário na função de 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 da forma mais precisa possível. Essas informações orientam o Genie 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 você executa o código para criar uma função, ele é registrado no esquema atualmente ativo por padrão. 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. Adicione um ativo confiável.

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

Permissões obrigatórias

Os usuários com pelo menos permissão CAN EDIT em um espaço 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 Unity Catalog. Os objetos protegíveis do Unity Catalog herdam permissões de seus contêineres-mãe. Consulte objetos securitizá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 você deseja usar em seu espaço Genie.

Dicas para funções de escrita

Analise os exemplos a seguir para saber como criar funções dinâmicas para ativos confiáveis.

Incluir um valor de parâmetro padrão

Você pode especificar um valor padrão para um parâmetro. Use a DEFAULT cláusula na assinatura de função, conforme mostrado no exemplo a seguir:

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

Incluir valores de parâmetros de exemplo

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 exemplo 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 como mostrado no exemplo a seguir:

min_date STRING DEFAULT NULL

Especificar 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:

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 produzir resultados imprevisíveis, você deve criar explicitamente uma verificação de valores de NULL em sua função. O exemplo a seguir fornece sintaxe de exemplo:

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