Ajustar 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 snippets de armazenamento de conhecimento (descrições de tabela, relacionamentos de join e expressões SQL para semântica de negócios).

nota

Genie Agents eram anteriormente conhecidos como Genie Spaces.

Adicionar exemplos e instruções SQL

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

Cada Genie Agent tem dois limites separados:

• Instruções (100 por agente) : Cada exemplo de query SQL, cada função SQL e todo o bloco de texto Instruções gerais contam como uma instrução.
• Snippets do armazenamento de conhecimento (200 por agente) : Descrições de tabelas, relacionamentos de join e expressões SQL (medidas, filtros e dimensões) compartilham este limite. Consulte Colunas da view, 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 key tarefa é revisar e resolver quaisquer inconsistências. Isso ajuda a alcançar resultados confiáveis.

Adicionar exemplo de queries e funções SQL

Use a tab SQL Queries para adicionar o seguinte:

• Queries de exemplo (Recomendado): Queries SQL de exemplo ajudam o Genie a gerar o SQL correto para responder a perguntas comuns do usuário. Queries podem ser estáticas ou parametrizadas. Para cada query SQL de exemplo, 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 associar prompts ao exemplo. O Genie pode usar a query de exemplo diretamente ou aprender com ela para lidar com perguntas semelhantes. Usuários com privilégios CAN EDIT no agente podem visualizar a query usada para gerar a resposta, o que ajuda 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. As funções podem ser compartilhadas entre suas equipes e usadas pelo Genie para responder a perguntas específicas. Para saber mais sobre o uso de funções SQL em seu Genie Agent, consulte Ativos confiáveis.

Como o Genie usa queries de exemplo

Queries de exemplo mostram ao Genie como usar os dados disponíveis para responder a perguntas. Insira uma pergunta de exemplo no campo de texto, e em seguida, insira uma query SQL que responda a essa pergunta. Escreva a pergunta de exemplo da forma como um usuário a faria naturalmente. Quando o Genie recebe uma pergunta correspondente, ele pode usar a query de exemplo diretamente para fornecer uma resposta. Quando o Genie recebe uma pergunta semelhante, ele usa pistas da query de exemplo para aprender e estruturar o SQL fornecido na resposta. Concentre-se em fornecer exemplos que destaquem a lógica exclusiva da sua organização e dos 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 da query

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

Para adicionar um parâmetro a uma query:

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 mudar o nome, substitua-o no editor de query. Você também pode adicionar um parâmetro digitando dois-pontos seguidos por um nome de parâmetro (:parameter_name) diretamente no editor.

Para editar um parâmetro, clique em 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 query. Você só pode alterá-lo editando o texto da query diretamente.
• Tipo de dados : Os tipos compatíveis incluem strings , Data , Data e Hora , Decimal e Inteiro . O default é string .
• Comentário : Uma descrição dos valores ou limites possíveis para o parâmetro. Utilize isto para fornecer contexto que ajude Genie a selecionar o valor correto.

nota

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

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

Ativos confiáveis

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:

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

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

Fornecer orientação de uso

O senhor/A senhora pode fornecer ao Genie contexto adicional para explicar quando uma query de exemplo é particularmente relevante.

Para adicionar guia de uso:

1. Clique em Configurar > Instruções > Queries SQL para acessar a lista de queries de exemplo.
2. Clique em uma query de exemplo.
3. Clique em **Orientações de uso** próximo à parte inferior da tela.
4. Insira detalhes sobre como e quando usar esta query de exemplo.

Como o Genie usa funções SQL?

As funções SQL são úteis quando uma questão envolve uma lógica complexa que não pode ser capturada com uma query estática ou parametrizada. Eles são armazenados no Unity Catalog e podem ser chamados pelo Genie usando parâmetros fornecidos pelo usuário. O Genie não pode visualizar nem modificar o SQL usado na função, tornando esta abordagem adequada para a lógica que não deve ser exposta ou alterada. Para obter orientação sobre o registro de 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.

Fornecer instruções

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

As instruções ajudam a guiar as respostas do Genie para que ele possa processar o jargão, a lógica e os conceitos exclusivos em um determinado domínio. As instruções gerais de texto se aplicam a todos os prompts. Se uma instrução for relevante apenas para um subconjunto de prompts, ela deve ser incluída como uma query ou função de exemplo, ou documentada na tabela relevante como comentários ou metadados. As instruções de texto são apenas para o contexto que deve ser aplicado globalmente e não se encaixam nos outros formatos.

O exemplo a seguir inclui informações que você poderia incluir nas 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"

Crie uma base de conhecimento

O repositório de conhecimento do Genie permite que você cure e aprimore seu agente por meio de metadados localizados, correspondência de prompt 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 armazenamento de conhecimento é uma coleção de definições semânticas selecionadas que aprimora o entendimento do Genie sobre seus dados e melhora a precisão da resposta.

A loja 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: conjuntos de dados simplificados e focados sem alterar as tabelas subjacentes do Unity Catalog.
• Correspondência de prompts : Exemplos que ajudam o Genie a corresponder valores que são mais relevantes para a pergunta do usuário e a corrigir problemas de ortografia nos prompts do usuário. Isso inclui assistência de formato e correspondência de entidades.
• Relações de join : Relações de tabela definidas para instruçõ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 do knowledge store. Descrições de tabela, relacionamentos de join e expressões SQL (medidas, filtros e dimensões) contam para este limite. Instruções de texto, queries SQL de exemplo, funções SQL, descrições de colunas e configurações de correspondência de prompt não contam para este limite.

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

Gerencie metadados do armazenamento de conhecimento

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

Essas práticas melhoram a usabilidade para usuários que não têm permissões diretas nas tabelas subjacentes, e também suportam iterações mais rápidas ao atualizar as versões das instruções.

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

Colunas de view

Clique em um nome de tabela para ver uma visão geral dos nomes das colunas e dos detalhes. 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 da tabela default mostra 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: nomes e descrições de colunas estão incluídos na lista de colunas. Cada coluna é rotulada com tags que mostram se ela inclui Assistência de Formato ou Correspondência de Entidades . Consulte a Visão Geral da Correspondência de Prompt.

Ocultar ou mostrar colunas relevantes

Ocultar uma coluna a remove do contexto do Genie Agents, para que o Genie não a referencie ao gerar SQL ou responder a perguntas. Isso é útil para excluir colunas desnecessárias, duplicadas ou potencialmente confusas, para que o Genie permaneça focado nos dados importantes. 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 massa. Use as seguintes instruções para ocultar ou mostrar colunas.

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

• Ocultar múltiplas colunas :

  • Marque as caixas de seleção para as colunas que você deseja ocultar.
  • No menu Ações , selecione Ocultar colunas selecionadas .

• Desfazer alterações : Repita os mesmos passos para mostrar 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 de negócios e palavras-chave que ajudam a combinar a linguagem do usuário com os nomes das colunas.
• Configurações avançadas : Controles de correspondência de prompt.
  • Assistência de formato : Ative ou desative a amostragem de valores representativos.
  • Correspondência de entidades : Habilitar ou desabilitar a correspondência de entidades para colunas categóricas.

Para editar metadados da coluna:

1. Clique no ícone de lápis ao lado de um nome de 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 prompt.
4. Clique em Salvar para manter suas alterações e fechar a caixa de diálogo.

Visão geral da correspondência de prompts

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

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

Exemplo

Analise o seguinte exemplo:

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

Se os dados usarem abreviações de estado (como FL) e o Genie não conseguir acessar os valores para essa coluna, o Genie poderá gerar SQL que inclui ILIKE '%Florida%', o que não retorna resultados.

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

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

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

Componentes de correspondência de prompt

• 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 se tornam parte do contexto compartilhado do agente e ajudam o Genie a interpretar 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 produto. Isso ajuda o Genie a correlacionar a terminologia do usuário com os valores de dados reais. 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 elegíveis à 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.

Gerenciar 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 prompt é ativada por default para todos os Genie Agents.

Gerenciar assistência de formato

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 em um nome de tabela para view suas colunas.
3. Clique no ícone de lápis ao lado do nome da coluna.
4. Clique em Avançado .
5. Desativar **Assistência de formato**.

Esta ação também desabilita automaticamente a correspondência de entidades para aquela coluna. Se necessário, use esta configuração para ativar novamente a **Assistência de formato**.

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 de entrada ou query. Quando uma coluna tem correspondência de entidades ativada, o Genie aproveita os valores armazenados para corresponder prompts do usuário a dados reais com mais precisão. Isso produz queries SQL mais confiáveis. A correspondência de entidades melhora significativamente a precisão do Genie, especialmente quando combinada com queries de exemplo claras e instruções bem elaboradas. Consulte Crie um Genie Agent eficaz para obter mais orientações.

O Genie impede a ativação da 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 visualizações que referenciam tabelas com filtros de linha ou máscaras de coluna, ou para visualizações dinâmicas.

A correspondência de entidades só oferece suporte a colunas de strings. 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 produto
• Códigos de status
• Nomes de departamentos

Para habilitar a correspondência de entidade, a Assistência de formato deve estar ativada. Em seguida, use os seguintes passos:

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

nota

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

Refresh ou remova dados de correspondência de prompt

A atualização dos dados de correspondência de prompt atualiza os valores armazenados de uma coluna. refresh valores se:

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

Para fazer refresh nos dados de correspondência de prompt, clique em o menu kebab na view de coluna e, em seguida, em Fazer refresh na correspondência de prompt .

Definir relações de join

Ajude a Genie a criar instruções JOIN precisas definindo as relações de tabela:

1. Click join .

2. Clique em Adicionar .

3. Selecione as tabelas esquerda e direita nos menus suspensos.

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

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

5. Selecione um **Tipo de relacionamento**:

   • Muitos para um : Múltiplas linhas à esquerda mapeiam para uma linha à direita.
   • Um para muitos : Uma linha à esquerda mapeia para várias linhas à direita
   • Um para um : uma linha à esquerda mapeia para, no máximo, uma linha à direita.

nota

Quando existem múltiplas junções entre as mesmas tabelas ou junções automáticas são usadas, o Genie gera automaticamente apelidos 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 você possa definir e gerenciar ambos em um só lugar. Consulte Adicionar exemplos de queries e funções SQL.

As expressões SQL fornecem uma forma estruturada e guiada de ensinar ao Genie sobre termos de negócios comuns, como KPIs, atributos e condições. O Genie então usa essas definições quando um usuário pergunta sobre esses termos de negócios.

As expressões SQL complementam queries SQL de exemplo, especificadas nas instruções. As expressões SQL definem conceitos de negócios reutilizáveis, mas as queries SQL de exemplo são mais úteis para ensinar o Genie a abordar formatos comuns de prompt de usuário. Por exemplo, se os usuários frequentemente pedem "uma análise de desempenho", uma query SQL de exemplo pode mostrar que isso significa ventas fechadas por região, representante de ventas 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.
• Dê ao Genie contexto explícito sobre como calcular valores importantes.
• Defina campos adicionais para o conjunto de dados, como mês ou segmento de cliente
• Ensine ao Genie filtros para condições de negócios, como pedidos grandes ou pedidos antes de um horário específico

Tipos de expressão SQL

É possível definir os seguintes tipos de expressões SQL:

• Filtros : Condições de filtragem comuns. Defina o nome, a lógica de 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 avaliam uma condição booleana.
   • Expressões de medida calculam uma agregação em várias linhas na tabela.
   • Expressões de campo alteram o valor de cada linha a partir dos dados existentes.

5. No campo Sinônimos , insira as formas comuns como os usuários podem se referir às expressões coloquialmente.

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

Exemplos de expressão 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 de texto, porque o Genie aplica a lógica exatamente como escrita, em vez de interpretá-la da linguagem natural.

Filtro: Pedidos de alto valor

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

Medida: 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 ganhas. Os resultados são um decimal entre 0 e 1; multiplique por 100 para exibir como porcentagem.

Campo: Tamanho da negociação

• Nome : Tamanho da negociação
• 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 : Agrupa oportunidades em Pequenas, Médias ou Grandes com base no valor em dólar. Utilize quando os usuários solicitarem para detalhar os resultados por tamanho do negócio.

Recomendações de mineração de conhecimento

A mineração de conhecimento ajuda a aprimorar o Genie ao sugerir 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 salvas automaticamente como relações de junção no Genie Agent.

O Genie também aprende com as interações do autor em conversas. Quando um autor curte uma resposta ou faz download dos resultados da query, o Genie analisa a query. Ele identifica uma lógica útil que pode melhorar a precisão em perguntas futuras. O Genie pode sugerir novas expressões SQL (medidas, filtros ou campos) e relações de join adicionais para adicionar ao repositório de conhecimento.

Próximos passos

Use os links a seguir para ajudar você a continuar a construir seu Genie Agent.

• Aprenda 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