Qualidade Tune Genie Space

Esta página explica como adicionar exemplos de SQL, instruções e configurações de repositório de conhecimento para melhorar a precisão e a confiabilidade do seu Genie Space.

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 Espaço Genie possui dois limites distintos:

• Instruções (100 por espaço) : Cada exemplo de consulta SQL, cada função SQL e todo o bloco de texto de instruções gerais contam como uma instrução.
• Trechos do repositório de conhecimento (200 por espaço) : Descrições de tabelas, relações join e expressões SQL (medidas, filtros e dimensões) compartilham esse limite. Consulte Exibir colunas, Definir relações join e Definir expressões SQL.

A Genie Space tem como objetivo fornecer respostas consistentes e previsíveis com base em orientações claras e precisas. Como Genie opera de forma não determinística, é importante que as orientações estejam livres de informações conflitantes ou ambíguas para minimizar o risco de respostas indesejáveis. Ao preparar o espaço, uma tarefa key é 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): Os 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 código SQL e utilize a formulação mais típica da pergunta do usuário como título. Isso melhora a capacidade do Genie de associar as solicitações ao exemplo. O Genie pode usar a consulta de exemplo diretamente ou aprender com ela para lidar com perguntas semelhantes. Quando uma consulta parametrizada é utilizada, a resposta é marcada como Confiável . Usuários com privilégios CAN EDIT no espaço podem view a consulta usada para gerar a resposta, o que auxilia na resolução de problemas e no aprimoramento.

• FunçõesSQL : Para perguntas que não podem ser respondidas com uma consulta 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. As respostas que são obtidas usando uma função SQL são marcadas como confiáveis . Para saber mais sobre como usar funções SQL no seu Genie Space, consulte Ativo confiável.

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

As consultas de exemplo parametrizadas permitem que os usuários do espaço especifiquem um valor que será inserido na consulta em tempo de execução. Com parâmetros, Genie pode receber entradas específicas das perguntas do usuário e reutilizar a estrutura de uma consulta de exemplo para fornecer respostas verificadas rotuladas como Confiáveis .

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.

Quando o texto exato de uma consulta parametrizada é usado em uma resposta, a resposta é rotulada como Confiável . Veja Ativo confiável.

Ativo confiável

Os ativos confiáveis são exemplos de consultas e funções SQL que fornecem respostas verificadas para perguntas SQL você prevê que os usuários possam fazer. Quando Genie usa um ativo confiável para responder a uma pergunta, a resposta é rotulada como Confiável , dando aos usuários do espaço uma camada extra de confiança na precisão do resultado.

Ativos confiáveis incluem:

• Exemplos de consultas SQL parametrizadas : Quando o texto exato de uma consulta parametrizada é usado para gerar uma resposta, a resposta é rotulada como Confiável . Os usuários do espaço podem editar o valor do parâmetro e executar a consulta novamente. Consulte Adicionar parâmetros de consulta.
• Funções SQL : Funções SQL registradas no Unity Catalog podem ser adicionadas a um Genie Space. As respostas geradas usando uma função SQL são rotuladas como Confiáveis . Veja Como o Genie usa funções SQL?

Usuários com pelo menos permissão CAN EDIT em um Genie Space podem adicionar ou remover ativos confiáveis. Os usuários do espaço devem ter permissão EXECUTE em quaisquer funções SQL usadas como ativas 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 Genie permite que você organize e aprimore seu espaço por meio de metadados localizados, correspondência de prompts e instruções SQL estruturadas. Esses recursos ajudam 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 em nível de espaço : descrições específicas para tabelas, colunas, termos comerciais e sinônimos.
• Personalização de dados em nível espacial : Conjunto de dados simplificado e focado, sem alterar as tabelas subjacentes 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 Space suporta um máximo de 200 trechos de dados da base de conhecimento. As descrições das tabelas, as relações join e as expressões SQL (medidas, filtros e dimensões) contam para esse limite. Instruções de texto, exemplos de consultas SQL, funções SQL, descrições de colunas e configurações de correspondência de prompts não contam para esse limite.

Todas as configurações do repositório de conhecimento são específicas para o seu Genie Space e não afetam os metadados Unity Catalog nem outros ativos Databricks .

Gerenciar metadados do armazenamento de conhecimento

Ensine o Genie sobre os dados no seu espaço, fornecendo descrições locais de tabelas e colunas e adicionando sinônimos de colunas que estejam alinhados com termos comerciais comuns. Simplifique o conjunto de dados ocultando colunas desnecessárias ou duplicadas para manter 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 os metadados do seu espaço, clique em Configurar > Dados no seu Genie Space. Em seguida, clique no nome da tabela para view 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 default da tabela mostra os metadados Unity Catalog associados aos seus dados ativos. Edite esta descrição para adicionar instruções específicas que ajudem o Genie a criar SQL para o seu espaço. Clique em Reset para restaurar a descrição 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

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 colunas específicas para cada espaço 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 formatação : A assistência de formatação fornece valores representativos para todas as colunas elegíveis, ajudando o Genie a entender os tipos de dados e os padrões de formatação. Os valores representativos para a correspondência de prompts são gerados usando as permissões de dados do autor. Esses valores passam a fazer parte do contexto compartilhado do espaço e ajudam o Genie a interpretar as solicitações do usuário com mais precisão para todos os participantes do espaço.
• 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 formatação e correspondência de entidades para colunas elegíveis à medida que você adiciona tabelas ao espaço. Tabelas com filtros de linha ou máscaras de coluna são excluídas da correspondência de prompts.

® correspondência de prompts

Controle quais colunas fornecem assistência de formatação e correspondência de entidades para otimizar a compreensão dos seus dados pelo Genie. A correspondência de prompts está ativada por default para todos Genie Spaces.

· assistência de formatação

A assistência de formatação é aplicada automaticamente quando você adiciona tabelas a um Genie Space.

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

1. Clique em Configurar > Dados no seu Genie Space.
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 sua solicitação, metadados relevantes da tabela, recursos de correspondência de solicitações, sinais de erro e qualquer código ou consulta de entrada. Quando uma coluna tem a correspondência de entidades ativada, o Genie utiliza os valores armazenados para corresponder com mais precisão às solicitações do usuário aos dados reais. Isso produz consultas SQL mais confiáveis. A correspondência de entidades melhora significativamente a precisão do Genie, especialmente quando combinada com exemplos de consultas claros e instruções bem elaboradas. Consulte a seção "Como criar um espaço Genie 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 do espaço devem desativar a correspondência de entidades para visualizações que fazem referência a tabelas com filtros de linha ou máscaras de coluna, ou para visualizações 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 Space.
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

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 dimensões adicionais para o dataset, como mês ou segmento de clientes.
• 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.
• Dimensões : 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 Dimensão .

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.
   • As expressões dimensionais alteram o valor de cada linha 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.

Dimensão: Tamanho da oferta

• 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, Genie analisa os metadados Unity Catalog para as tabelas e visualizações conectadas ao seu espaço. As chaves primárias e estrangeiras definidas em seu esquema são salvas automaticamente como relações join no Genie Space.

Genie também aprende com as interações do autor em conversas. Quando um autor aprova uma resposta ou downloads os resultados de uma consulta, Genie analisa a consulta e identifica a lógica útil que pode melhorar a precisão em perguntas futuras. Isso pode sugerir novas expressões SQL (medidas, filtros ou dimensões), bem como relações join adicionais para adicionar ao repositório de conhecimento.

Próximos passos

Utilize os links a seguir para continuar a construir seu Espaço Genie.

• Aprenda as melhores práticas para otimizar seu Genie Space. Veja Como organizar um espaço Genie eficaz
• Avalie e melhore o desempenho do seu espaço. Consulte os indicadores de desempenho.