Otimizar a qualidade do Genie Agent

Melhore a precisão e a confiabilidade do Genie Agent adicionando exemplos de queries SQL, funções do Unity Catalog, instruções em texto simples e fragmentos do repositório de conhecimento (descrições de tabelas, relações de join e expressões SQL para semântica de negócios).

nota

Os Genie Agents eram anteriormente conhecidos como Genie Spaces.

Adicionar exemplos e instruções de SQL

Você pode adicionar exemplos de consultas SQL , funções Unity Catalog e instruções em texto simples para ajudar a gerar respostas precisas. Clique em Configurar > Instruções . Use a tab ConsultasSQL para gerenciar consultas e funções Unity Catalog . Use a tab Texto para adicionar instruções em texto simples.

Cada Genie Agent possui dois limites separados:

• Instruções (100 por agente) : Cada exemplo de consulta SQL, cada função SQL e todo o bloco de texto de Instruções gerais contam como uma instrução.
• Fragmentos de armazenamento de conhecimento (200 por agente) : Descrições de tabela, relacionamentos de join e expressões SQL (medidas, filtros e dimensões) compartilham este limite. Consulte Exibir colunas, Definir relacionamentos de join e Definir expressões SQL.

Um Genie Agent visa fornecer respostas consistentes e previsíveis com base em orientação clara e precisa. Como o Genie opera de maneira não determinística, é importante que a orientação esteja livre de informações conflitantes ou ambíguas para minimizar o risco de respostas indesejáveis. Ao configurar o agente, uma tarefa fundamental é revisar e resolver quaisquer inconsistências. Isso ajuda a alcançar resultados confiáveis.

Adicione exemplos de consultas e funções SQL.

Utilize a tab ConsultasSQL para adicionar o seguinte:

• Exemplos de consultas (Recomendado): Exemplos de consultas SQL ajudam o Genie a gerar o SQL correto para responder a perguntas comuns dos usuários. As consultas podem ser estáticas ou parametrizadas. Para cada exemplo de consulta SQL, forneça o SQL e use a frase mais comum da pergunta do usuário como título. Isso melhora a capacidade do Genie de corresponder prompts ao exemplo. O Genie pode usar o exemplo de consulta diretamente ou aprender com ele para lidar com perguntas semelhantes. Usuários com privilégios CAN EDIT no agente podem visualizar a consulta usada para gerar a resposta, o que auxilia na solução de problemas e no refinamento.

• Funções SQL: Para perguntas que não podem ser respondidas com uma query SQL estática ou parametrizada, você pode registrar uma função personalizada no Unity Catalog. Funções podem ser compartilhadas entre suas equipes e usadas pelo Genie para responder a perguntas específicas. Para saber mais sobre como usar funções SQL em seu Genie Agent, consulte ativos confiáveis.

Como o Genie usa consultas de exemplo

Os exemplos de consultas mostram ao Genie como usar os dados disponíveis para responder às perguntas. Insira uma pergunta de exemplo no campo de texto e, em seguida, insira uma consulta SQL que responda a essa pergunta. Escreva a pergunta de exemplo da maneira como um usuário a faria naturalmente. Quando o Genie recebe uma pergunta correspondente, ele pode usar a consulta de exemplo diretamente para fornecer uma resposta. Quando o Genie recebe uma pergunta semelhante, ele usa pistas da consulta de exemplo para aprender e estruturar o SQL fornecido na resposta. Dê ênfase aos exemplos que destacam a lógica exclusiva da sua organização e dos seus dados, como no exemplo a seguir:

SQL

  -- Return our current total open pipeline by region.
  -- Opportunities are only considered pipelines if they are tagged as such.
  SELECT
    a.region__c AS `Region`,
    sum(o.amount) AS `Open Pipeline`
  FROM
    sales.crm.opportunity o
    JOIN sales.crm.accounts a ON o.accountid = a.id
  WHERE
    o.forecastcategory = 'Pipeline' AND
    o.stagename NOT ILIKE '%closed%'
  GROUP BY ALL;

Adicionar parâmetros de consulta

Queries de exemplo parametrizadas permitem que usuários de agente especifiquem um valor que é inserido na query em tempo de execução. Com parâmetros, o Genie pode receber entradas específicas de perguntas de usuários e reutilizar a estrutura de uma query de exemplo para fornecer respostas verificadas.

Para adicionar um parâmetro a uma consulta:

1. Posicione o cursor onde deseja inserir o parâmetro.

2. Clique em Adicionar parâmetro .

   Isso cria um novo parâmetro com o nome default parameter. Para alterar o nome, substitua-o no editor de consultas. Você também pode adicionar um parâmetro digitando dois pontos seguidos de um nome de parâmetro (:parameter_name) diretamente no editor.

Para editar um parâmetro, clique ao lado do nome do parâmetro. A caixa de diálogo Detalhes do parâmetro inclui as seguintes opções:

• Palavra-chave : A palavra-chave que representa o parâmetro na consulta. Você só pode alterá-lo editando diretamente o texto da consulta.
• Tipo de dados : Os tipos suportados incluem strings , data , data e hora , decimal e inteiro . O default são strings .
• Comentário : Uma descrição dos possíveis valores ou limites para o parâmetro. Use isso para fornecer contexto que ajude o Genie a selecionar o valor correto.

nota

Se o valor de entrada não corresponder ao tipo selecionado, o Genie o tratará como um tipo incorreto, o que pode levar a resultados imprecisos.

No modo de chat, quando o texto exato de uma consulta parametrizada é usado em uma resposta, o Genie fornece uma resposta verificada. Veja Ativos confiáveis.

Ativo confiável

Ativos confiáveis são exemplos de queries SQL e funções SQL que fornecem respostas verificadas para perguntas que você antecipa dos usuários. Quando o Genie usa um ativo confiável para responder a uma pergunta, ele fornece uma resposta verificada, dando aos usuários do agente uma camada extra de confiança na precisão do resultado.

Ativos confiáveis incluem:

• **Consultas SQL parametrizadas de exemplo**: No modo de chat, quando o texto exato de uma consulta parametrizada é usado para gerar uma resposta, o Genie fornece uma resposta verificada. Os usuários do Agent podem editar o valor do parâmetro e executar a consulta novamente. Consulte Adicionar parâmetros da consulta.
• Funções SQL : As funções SQL registradas no Unity Catalog podem ser adicionadas a um Genie Agent. Consulte Como o Genie usa as funções SQL?.

Os usuários com permissão de pelo menos CAN EDIT em um Genie Agent podem adicionar ou remover ativos confiáveis. Os usuários do Agent devem ter permissão EXECUTE em quaisquer funções SQL usadas como ativos confiáveis.

Forneça orientações de uso.

Você pode fornecer ao Genie um contexto adicional para explicar quando uma consulta de exemplo é particularmente relevante.

Para adicionar orientações de uso:

1. Clique em Configurar > Instruções > Consultas SQL para acessar a lista de exemplos de consultas.
2. Clique em um exemplo de consulta.
3. Clique em " Orientações de utilização" na parte inferior da tela.
4. Insira detalhes sobre como e quando usar esta consulta de exemplo.

Como o Genie utiliza funções SQL?

As funções SQL são úteis quando uma questão envolve lógica complexa que não pode ser capturada com uma consulta estática ou parametrizada. Eles são armazenados no Unity Catalog e podem ser chamados pelo Genie usando parâmetros fornecidos pelo usuário. Genie não consegue view ou modificar o SQL usado na função, tornando essa abordagem adequada para lógicas que não devem ser expostas ou alteradas. Para obter orientações sobre como registrar uma função no Unity Catalog, consulte Criar uma função de tabela SQL e Funções definidas pelo usuário (UDFs) no Unity Catalog.

Forneça instruções

Clique na tab Texto para escrever instruções em texto simples que ajudem Genie a entender como responder a perguntas específicas sobre sua empresa. Você pode formatar as instruções como uma única nota abrangente ou categorizá-las por tópico para melhor organização.

As instruções ajudam a orientar as respostas do Genie para que ele possa processar o jargão, a lógica e os conceitos específicos de um determinado domínio. As instruções gerais do texto se aplicam a todos os prompts. Se uma instrução for relevante apenas para um subconjunto de prompts, ela deverá ser incluída como um exemplo de consulta ou função, ou documentada na tabela relevante como comentários ou metadados. As instruções em texto servem apenas para contextualizar e devem ser aplicadas globalmente, não se encaixando nos outros formatos.

O exemplo a seguir inclui informações que você pode incluir em instruções gerais:

- **Company-specific business information**:
  - Fiscal year starts in February, for example fiscal year 26 or FY26 is February 1, 2026 through January 31, 2027
- **Formatting**:
  - Always respond in Spanish
  - If no other specification exists, round all decimals to two places
  - Omit commas in results for any column including "Id" or "id" or "\_id"

Construa um repositório de conhecimento

O repositório de conhecimento do Genie permite que você organize e aprimore seu agente por meio de metadados localizados, correspondência de prompts e instruções SQL estruturadas. Esses recursos ajudam o Genie a entender seus dados e a gerar respostas mais precisas e relevantes.

O que é um repositório de conhecimento?

Um repositório de conhecimento é uma coleção de definições semânticas selecionadas que aprimora a compreensão dos seus dados pelo Genie e melhora a precisão das respostas.

O repositório de conhecimento consiste em:

• Personalização de metadados no nível do agente : descrições específicas do agente para tabelas, colunas e termos de negócios e sinônimos.
• Personalização de dados no nível do agente : datasets simplificados e focados sem alterar as tabelas subjacentes do Unity Catalog.
• Correspondência de prompts : Exemplos que ajudam o Genie a encontrar os valores mais relevantes para a pergunta do usuário e a corrigir erros de ortografia nos prompts do usuário. Isso inclui assistência de formatação e correspondência de entidades.
• relações de junção : relações de tabela definidas para declarações JOIN precisas.
• Expressões SQL : Definições estruturadas de medidas, filtros e dimensões que capturam a lógica de negócios.

nota

Cada Genie Agent suporta um máximo de 200 snippets de conhecimento. Descrições de tabela, relações de join e expressões SQL (medidas, filtros e dimensões) contam para este limite. Instruções de texto, exemplos de queries SQL, funções SQL, descrições de coluna e configurações de correspondência de prompt não contam para este limite.

Todas as configurações do repositório de conhecimento têm escopo definido para seu Genie Agent e não afetam os metadados do Unity Catalog ou outros ativos do Databricks.

Gerenciar metadados do armazenamento de conhecimento

Instrua o Genie sobre os dados em seu agente, fornecendo descrições locais de tabelas e colunas e adicionando sinônimos de coluna que se alinham a termos de negócios comuns. Simplifique os dataset ocultando colunas desnecessárias ou duplicadas para manter o Genie focado.

Essas práticas melhoram a usabilidade para usuários que não possuem permissões diretas nas tabelas subjacentes e também permitem iterações mais rápidas na atualização das versões das instruções.

Para acessar metadados no nível do agente, clique em Configurar > Dados no seu Genie Agent. Em seguida, clique em um nome de tabela para visualizar seus metadados e colunas.

ver colunas

Clique no nome de uma tabela para ver uma visão geral dos nomes e detalhes das colunas. O exemplo a seguir mostra uma amostra de uma tabela chamada accounts.

• **Descrição:** O Genie usa metadados para entender seus dados e gerar respostas precisas. A descrição de tabela default exibe os metadados do Unity Catalog associados ao seu ativo de dados. Edite esta descrição para adicionar instruções específicas que ajudem o Genie a criar SQL para seu agente. Clique em **Reset** para restaurar a descrição do Unity Catalog.

• Colunas: Os nomes e descrições das colunas estão incluídos na lista de colunas. Cada coluna é rotulada com tags que indicam se ela inclui assistência de formatação ou correspondência de entidades . Consulte a Visão geral da correspondência de prompts.

Ocultar ou mostrar colunas relevantes

Ocultar uma coluna a remove do contexto do Agente Genie, para que o Genie não a referencie ao gerar SQL ou ao responder a perguntas. Isso é útil para excluir colunas desnecessárias, duplicadas ou potencialmente confusas, para que o Genie permaneça focado nos dados que importam. Ocultar uma coluna não afeta os dados subjacentes ou as permissões do Unity Catalog. A coluna ainda existe na tabela e permanece visível para usuários com acesso direto à tabela.

As colunas podem ser gerenciadas individualmente ou em lote. Siga as instruções abaixo para ocultar ou exibir colunas.

• Ocultar uma única coluna : Clique em ao lado do nome da coluna.

• Ocultar várias colunas :

  • Selecione as caixas de seleção das colunas que deseja ocultar.
  • No menu Ações , selecione Ocultar colunas selecionadas .

• Desfazer alterações : Repita os mesmos passos para exibir uma coluna que estava oculta.

Editar metadados da coluna

Você pode personalizar o seguinte para cada coluna:

• Descrição : Descrições de coluna específicas do agente que aprimoram a compreensão do Genie.
• Sinônimos : Termos comerciais e palavras-chave que ajudam a associar a linguagem do usuário aos nomes das colunas.
• Configurações avançadas : controles de correspondência de prompts.
  • Auxílio de formatação : Ative ou desative a amostragem de valores representativos.
  • Correspondência de entidades : Ative ou desative a correspondência de entidades para colunas categóricas.

Para editar os metadados da coluna:

1. Clique no Ícone de lápis ao lado do nome da coluna.
2. Edite a descrição e os sinônimos da coluna.
3. Se necessário, clique em Configurações avançadas para abrir os controles de correspondência de prompts.
4. Clique em Salvar para manter as alterações e fechar a caixa de diálogo.

Visão geral de correspondência de prompts

A correspondência de prompts permite que o Genie encontre colunas e valores mais relevantes para a pergunta do usuário e corrija erros de ortografia nos prompts. Isso melhora a precisão do Genie e ajuda a gerar consultas SQL mais confiáveis.

Quando um usuário faz uma pergunta no Genie, a linguagem costuma ser coloquial e pode incluir erros como erros de ortografia. Nesses casos, os valores no prompt podem não corresponder à estrutura ou aos valores nos dados. Isso pode fazer com que o Genie interprete a pergunta incorretamente e gere um SQL incorreto.

Exemplo

Analise o seguinte exemplo:

"Mostre-me as vendas de carros na Flórida para o primeiro trimestre."

Se o uso de dados indicar abreviações (como FL), e Genie não conseguir acessar os valores dessa coluna, Genie poderá gerar SQL que inclua ILIKE '%Florida%', que não retorna resultados.

Habilitar a correspondência de entidades na coluna state permite que o Genie acesse valores representativos. Com este contexto, o Genie pode reconhecer que FL corresponde a "Flórida" e gerar SQL mais preciso.

Sem correspondência de entidades	Com correspondência de entidades
WHERE state ILIKE '%Florida%'	WHERE state = 'FL'

componentes de correspondência de prompts

• Assistência de formato : A assistência de formato fornece valores representativos para todas as colunas elegíveis, ajudando o Genie a entender tipos de dados e padrões de formatação. Valores representativos para correspondência de prompt são gerados usando as permissões de dados do autor. Esses valores tornam-se parte do contexto compartilhado do agente e ajudam o Genie a interpretar os prompts do usuário com mais precisão para todos que usam o agente.
• Correspondência de entidades : A correspondência de entidades fornece listas selecionadas de valores distintos para até 120 colunas onde os usuários provavelmente farão referência a entradas específicas, como estados e categorias de produtos. Isso ajuda o Genie a associar a terminologia do usuário aos valores reais dos dados. Cada coluna pode incluir até 1.024 valores distintos, cada um com até 127 caracteres de comprimento. Os dados de correspondência de entidades são armazenados no bucket de armazenamento do seu workspace.

O Genie fornece automaticamente assistência de formato e correspondência de entidades para colunas qualificadas à medida que você adiciona tabelas ao agente. Tabelas com filtros de linha ou máscaras de coluna são excluídas da correspondência de prompt.

® correspondência de prompts

Controle quais colunas fornecem assistência de formato e correspondência de entidades para otimizar a compreensão do Genie dos seus dados. A correspondência de prompts é habilitada por default para todos os Genie Agents.

· assistência de formatação

A assistência de formato é aplicada automaticamente ao adicionar tabelas a um Genie Agent.

Para desativar a assistência de formatação para uma coluna:

1. Clique em Configurar > Dados no seu Genie Agent.
2. Clique no nome de uma tabela para view suas colunas.
3. Clique no Ícone de lápis ao lado do nome da coluna.
4. Clique em Avançado .
5. Desative a assistência de formatação .

Essa ação também desativa automaticamente a correspondência de entidades para essa coluna. Se necessário, use esta configuração para reativar a assistência de formatação .

Configurar correspondência de entidades

O Genie gera respostas usando seu prompt, metadados de tabela relevantes, recursos de correspondência de prompt, sinais de erro e qualquer código ou consulta de entrada. Quando uma coluna tem a correspondência de entidades ativada, o Genie aproveita os valores armazenados para corresponder os prompts do usuário aos dados reais com mais precisão. Isso produz consultas SQL mais confiáveis. A correspondência de entidades melhora significativamente a precisão do Genie, especialmente quando combinada com consultas de exemplo claras e instruções bem elaboradas. Consulte Gerencie um Genie Agent eficaz para obter mais orientações.

O Genie impede que você habilite a correspondência de entidades em tabelas com filtros de linha ou máscaras de coluna. No entanto, os autores de agentes devem desativar a correspondência de entidades para views que referenciam tabelas com filtros de linha ou máscaras de coluna, ou para views dinâmicas.

A correspondência de entidades suporta apenas colunas de texto. A lista a seguir inclui exemplos dos tipos de dados que funcionam bem com a correspondência de entidades:

• Códigos de estado ou país
• categorias de produtos
• Códigos de status
• Nomes dos departamentos

Para ativar a correspondência de entidades, a assistência de formatação deve estar ativada. Em seguida, siga os passos abaixo:

1. Clique em Configurar > Dados no seu Genie Agent.
2. Clique no nome de uma tabela para view suas colunas.
3. Clique no Ícone de lápis ao lado do nome da coluna.
4. Clique em Avançado .
5. Ative a correspondência de entidades .
6. Para desativar a correspondência de entidades para uma coluna, desative a opção "Correspondência de entidades" .

nota

Quando os usuários filtram por uma coluna com a correspondência de entidades ativada, o filtro é exibido como um menu suspenso editável preenchido com os valores armazenados da coluna.

Atualizar ou remover dados correspondentes de prompt

A atualização dos dados correspondentes ao prompt atualiza os valores armazenados em uma coluna. Atualizar valores se:

• Novos valores foram adicionados à coluna.
• O formato dos valores existentes foi alterado.

Para refresh os dados de correspondência de prompts, clique o menu de kebab na view em coluna, depois atualize o prompt correspondente .

Defina relações join

Ajude o Genie a criar declarações JOIN precisas definindo relacionamentos entre tabelas:

1. Click join .

2. Clique em Adicionar .

3. Selecione as mesas da esquerda e da direita nos menus suspensos.

4. Insira uma condição de junção (por exemplo, accounts.id = opportunity.accountid)

   • Para condições join mais complexas, clique em Usar expressão SQL e, em seguida, registre a condição join como uma expressão SQL .

5. Selecione um tipo de relacionamento :

   • Muitos para um : várias linhas à esquerda correspondem a uma linha à direita.
   • Relação um para muitos : uma linha à esquerda corresponde a várias linhas à direita.
   • Um para um : Uma linha à esquerda corresponde a, no máximo, uma linha à direita.

nota

Quando existem várias junções entre as mesmas tabelas ou quando são usadas autojunções, Genie gera automaticamente aliases para a tabela à direita para evitar ambiguidade.

Defina expressões SQL

Na experiência de autoria, as expressões SQL são agrupadas com exemplos de queries SQL para que seja possível definir e gerenciar ambos em um só lugar. Consulte Adicionar exemplos de queries e funções SQL.

As expressões SQL fornecem uma maneira estruturada e guiada de ensinar o Genie sobre termos comerciais comuns, como KPIs, atributos e condições. A Genie utiliza essas definições quando um usuário pergunta sobre esses termos comerciais.

As expressões SQL complementam os exemplos de consultas SQL, especificados nas instruções. Expressões SQL definem conceitos de negócios reutilizáveis, mas exemplos de consultas SQL são mais úteis para ensinar o Genie a abordar formatos comuns de solicitações do usuário. Por exemplo, se os usuários costumam pedir "uma análise detalhada do desempenho", uma consulta SQL de exemplo pode mostrar que isso significa vendas fechadas por região, representante de vendas e gerente.

As expressões SQL funcionam melhor quando você precisa:

• Forneça definições estruturadas para KPIs e métricas, como margem de lucro ou taxa de conversão.
• Forneça ao Genie um contexto explícito sobre como calcular valores importantes.
• Defina campos adicionais para o conjunto de dados como mês ou segmento de cliente
• Ensine o Genie a usar filtros para condições de negócio, como grandes encomendas ou encomendas feitas antes de um horário específico.

tipos de expressão SQL

Você pode definir os seguintes tipos de expressões SQL:

• Filtros : Condições comuns de filtragem. Defina o nome, a lógica do filtro SQL e os sinônimos.
• Medidas : indicadores-chave de desempenho (KPIs) e métricas. Defina o nome, o cálculo SQL e os sinônimos.
• Campos : Atributos para agrupar e analisar dados. Defina o nome, a expressão SQL e os sinônimos.

Para adicionar uma expressão SQL:

1. Clique em Configurar > Instruções > Expressões SQL

2. Clique em Adicionar . Selecione Filtro , Medida ou Campo .

3. No campo Nome , insira um nome para a expressão.

4. No campo Código , insira a expressão SQL.

   • As expressões de filtro resultam em uma condição booleana.
   • As expressões de medida calculam uma agregação em várias linhas da tabela.
   • Expressões de campo alteram o valor de cada linha a partir dos dados existentes.

5. No campo "Sinônimos" , insira maneiras comuns pelas quais os usuários podem se referir às expressões coloquialmente.

6. No campo Instruções , insira instruções específicas que digam ao Genie para que serve a expressão e como trabalhar com ela.

Exemplos de expressões SQL

Os exemplos a seguir mostram uma expressão de cada tipo. Definir a lógica de negócios como expressões SQL produz resultados mais consistentes do que instruções em texto, porque o Genie aplica a lógica exatamente como está escrita, em vez de interpretá-la a partir da linguagem natural.

Filtrar: Pedidos de alto valor

• Nome : Pedidos de alto valor
• Código : orders.amount > 10000
• Sinônimos : grandes encomendas, negócios importantes, encomendas significativas
• Instruções : Aplique quando os usuários perguntarem sobre pedidos grandes ou de alto valor. O limite é de 10.000 dólares.

Métrica: Taxa de vitórias

• Nome : Taxa de vitórias
• Código : COUNT(CASE WHEN stage = 'Closed Won' THEN 1 END) / NULLIF(COUNT(*), 0)
• Sinônimos : taxa de fechamento, taxa de conversão
• Instruções : Retorna a fração de oportunidades que foram ganhas. Os resultados são apresentados como um número decimal entre 0 e 1; multiplique por 100 para exibir em porcentagem.

Campo: Tamanho da negociação

• Nome : Tamanho do negócio
• Código : CASE WHEN amount < 10000 THEN 'Small' WHEN amount < 50000 THEN 'Medium' ELSE 'Large' END
• Sinônimos : nível do negócio, tamanho do contrato, tamanho da oportunidade
• Instruções : Agrupe as oportunidades em Pequenas, Médias ou Grandes com base no valor em dólares. Use esta opção quando os usuários solicitarem a discriminação dos resultados por tamanho do negócio.

Recomendações de mineração de conhecimento

A mineração de conhecimento ajuda a aprimorar o Genie, sugerindo automaticamente atualizações para o repositório de conhecimento, reduzindo a curadoria manual e melhorando a precisão das respostas.

Primeiro, o Genie analisa os metadados do Unity Catalog para as tabelas e views conectadas ao seu agente. Chaves primárias e estrangeiras definidas em seu esquema são automaticamente salvas como relações de junção no Agente Genie.

O Genie também aprende com as interações do autor em conversas. Quando um autor aprova uma resposta ou faz download dos resultados da query, Genie analisa a query. Identifica-se uma lógica útil que pode aprimorar a precisão em futuras perguntas. Genie poderia sugerir novas expressões SQL (medidas, filtros ou campos) e joins adicionais para adicionar ao knowledge store.

Próximos passos

Use os links a seguir para ajudá-lo a continuar a criar seu Genie Agent.

• Saiba as melhores práticas para otimizar seu Genie Agent. Consulte Gerenciar um Genie Agent eficaz
• Avalie e melhore o desempenho do seu agente. Consulte Benchmarks