Solucionar problemas de agentes do Genie

Resolva problemas comuns ao criar e manter um agente do Genie: jargão empresarial mal compreendido, uso incorreto de tabelas ou colunas, erros de filtragem em valores específicos e truncamento devido ao limite de tokens em conversas longas. Cada seção abaixo aborda o sintoma, a causa e a correção.

Para muitos desses problemas, o caminho mais rápido para uma correção é o Genie Code. Descreva o problema para o Genie Code e sugere alterações de contexto para você examinar e aceitar. Para diagnosticar uma única resposta incorreta, consulte respostas de depuração com o Genie Code. Para analisar as falhas de benchmark juntas, consulte Analisar uma execução de benchmark com o Genie Code.

Jargão empresarial mal compreendido

A maioria das empresas ou domínios tem uma terminologia específica que usam para se comunicar sobre eventos específicos de negócios. Por exemplo, ao se referir a um ano, isso pode sempre significar o ano fiscal, e esse ano fiscal pode começar em fevereiro ou março, em vez de janeiro. Para permitir que o Genie responda a essas perguntas de maneira natural e precisa, inclua instruções que associem explicitamente o jargão do seu negócio a palavras e conceitos que o Genie possa compreender. Consulte Instruções de Fornecer.

Uso incorreto de tabela ou coluna

Se o Genie estiver tentando extrair dados de uma tabela incorreta ou executar a análise em colunas incorretas, você poderá ajustar os dados de uma das seguintes maneiras:

• Forneça descrições claras e precisas: verifique suas tabelas e metadados associados para verificar se a terminologia usada lá corresponde à terminologia dos usuários nas perguntas enviadas. Caso contrário, refine a descrição ou adicione uma instrução que associe a terminologia usada na tabela à terminologia usada na pergunta.
• Adicione consultas de exemplo: forneça consultas SQL de exemplo que o Genie possa usar para saber como responder a determinadas perguntas. Consulte Instruções de Fornecer.
• Excluir tabelas ou colunas do agente: Algumas tabelas podem incluir colunas ou conceitos sobrepostos, o que dificulta ao Genie saber quais dados usar em uma resposta. Se possível, remova tabelas ou colunas desnecessárias ou sobrepostas. Para ocultar colunas da interface do usuário do Agente do Genie sem alterar os objetos de dados subjacentes, consulte Ocultar ou mostrar colunas relevantes.

Filtrando erros

As consultas geradas geralmente incluem uma cláusula WHERE para filtrar os resultados de acordo com um valor específico. Quando o Genie não tem visibilidade dos valores de dados, ele pode definir a WHERE cláusula para filtrar o valor errado. Por exemplo, ele pode tentar corresponder ao nome "Califórnia" quando a tabela usa abreviações como "AC".

Para situações como esta, verifique se as colunas relevantes têm valores de exemplo e dicionários de valor habilitados. Se novos dados tiverem sido adicionados a tabelas relevantes, atualize os valores. Confira a visão geral da correspondência de prompts.

Junções incorretas

Se as referências de chave estrangeira não estiverem definidas no Catálogo do Unity, o agente talvez não saiba como unir tabelas diferentes.

Tente implementar uma ou mais das seguintes soluções:

• Defina referências de chave externa em seu Catálogo do Unity quando possível. Consulte a cláusula CONSTRAINT.
• Se as relações de chave estrangeira de suas tabelas não forem especificadas no Catálogo do Unity, defina relações de junção no repositório de conhecimento do Genie Agent. Essa estratégia é útil para cenários de junção mais complexos, como autojunções, ou se você não tiver permissão suficiente para modificar as tabelas subjacentes. Consulte Definir relações de junção.
• Forneça consultas de exemplo nas quais você una tabelas de maneiras padrão.

Se nenhuma dessas alternativas resolver o problema, una previamente a tabela a uma visualização e use-a como entrada para o agente.

Comentários de coluna não estão sendo sincronizados a partir de tabelas externas

O Azure Databricks não gerencia os metadados, dados ou semântica para gravações em tabelas estrangeiras. Dependendo da tabela de origem, os comentários podem não estar acessíveis do Azure Databricks. Para disponibilizar comentários, o Azure Databricks recomenda fazer um dos seguintes procedimentos:

• Edite os metadados da coluna na interface do usuário do Genie Agent. Os metadados editados se aplicam apenas ao Agente Genie onde estão escritos. Consulte Editar metadados de coluna.
• Crie uma visão materializada com base em tabelas federadas. Você pode adicionar e editar comentários em uma exibição materializada como faria em uma tabela gerenciada. Você pode reutilizar esta visualização em vários agentes do Genie. Para obter detalhes sobre como carregar dados de tabelas estrangeiras para uma exibição materializada, consulte Carregar dados de tabelas estrangeiras com exibições materializadas. Para saber mais sobre como trabalhar com exibições materializadas, consulte Exibições materializadas.

Problemas de cálculo de métricas

A maneira como as métricas são computadas e acumuladas pode ser arbitrariamente complicada e abranger muitos detalhes de negócios que seu agente não entende. Isso pode gerar relatórios incorretos.

Tente implementar uma ou mais das seguintes soluções:

• Defina suas métricas como expressões SQL no repositório de conhecimento. As expressões SQL fornecem definições reutilizáveis e precisas para medidas, filtros e dimensões que o Genie pode aplicar consistentemente. Consulte Definir expressões SQL.
• Se suas métricas forem agregadas a partir das tabelas base, forneça consultas SQL de exemplo que calculem cada valor de consolidação.
• Se suas métricas tiverem sido previamente calculadas e estiverem armazenadas em tabelas agregadas, explique isso nos comentários da tabela. Especifique agregações válidas para cada métrica se as métricas nessa tabela puderem ser ainda mais consolidadas.
• Se o SQL que você está tentando gerar for muito complicado, tente criar visualizações que já tenham agregado suas métricas no seu agente.

Cálculos baseados em tempo incorretos

O Genie pode nem sempre ser capaz de inferir o fuso horário representado nos dados ou no fuso horário no qual sua análise precisa ser executada, a menos que você forneça explicitamente diretrizes adicionais.

Inclua instruções mais explícitas detalhando o fuso horário de origem original, a função de conversão e o fuso horário de destino. Os exemplos a seguir mostram como alterar as instruções gerais para conversões de fuso horário mais confiáveis:

• Sempre converta horários em um fuso horário específico: neste exemplo, suponha que o carimbo de data/hora de origem seja UTC e você queira obter resultados no fuso horário America/Los_Angeles. Adicione o seguinte às instruções, substituindo <timezone-column> pelo nome da coluna apropriado:
  • Os fusos horários nas tabelas estão em UTC.
  • Converter todos os fusos horários usando a seguinte função: convert_timezone('UTC', 'America/Los_Angeles', <timezone-column>).
• Converter formatos de data e hora que não estão em UTC para UTC: Se o fuso horário padrão do espaço de trabalho for UTC, mas os usuários em Los Angeles precisarem fazer referência a hoje para um conjunto específico de registros, adicione o seguinte nas instruções gerais do agente:
  • Para fazer referência hoje, use date(convert_timezone('UTC', 'America/Los_Angeles', current_timestamp())).

Consulte convert_timezone a função para obter mais detalhes e sintaxe.

Ignorando instruções

Mesmo que você tenha explicado suas tabelas e colunas em comentários e fornecido instruções gerais, seu agente ainda pode não estar usando-as corretamente.

Tente uma ou mais das seguintes estratégias:

• Forneça consultas de exemplo que usem suas tabelas corretamente. Consultas de exemplo são especialmente eficazes para ensinar seu agente a usar seus dados.
• Ocultar colunas irrelevantes no Agente do Genie. Consulte Ocultar ou mostrar colunas relevantes.
• Crie exibições de suas tabelas que forneçam uma exibição mais simples de seus dados.
• Examine suas instruções e tente concentrar o agente removendo tabelas ou instruções irrelevantes.
• Tente iniciar um novo chat. Interações anteriores podem influenciar as respostas do Genie em qualquer chat específico, mas iniciar um novo chat oferece um ponto de partida em branco para testar novas instruções.

Problemas de desempenho

Quando o Genie precisa gerar consultas ou respostas de texto excepcionalmente longas, pode levar muito tempo para responder ou até mesmo exceder o tempo limite durante a fase de processamento.

Experimente uma ou mais das seguintes ações para melhorar o desempenho:

• Verifique o histórico de consultas para identificar consultas de execução lenta. Muitos problemas de desempenho podem ser resolvidos otimizando as consultas SQL geradas em vez de modificar a configuração do Genie Agent. Examine os tempos de execução da consulta e os planos de consulta no histórico de consultas do sql warehouse para identificar gargalos e oportunidades de otimização.
• Use ativos confiáveis ou visualizações para encapsular consultas complexas. Consulte ativos confiáveis.
• Reduza o comprimento das consultas SQL de exemplo sempre que possível.
• Inicie um novo chat se o Genie começar a gerar respostas lentas ou com falha.

Respostas não confiáveis a perguntas críticas

Use ativos confiáveis para fornecer respostas verificadas a perguntas específicas que você espera que os usuários façam. Consulte ativos confiáveis.

Aviso de limite de token

Tokens são as unidades básicas de texto que o Genie usa para processar e compreender a linguagem. Instruções de texto e metadados em um agente do Genie são convertidos em tokens. Se o agente se aproximar do limite de token, um aviso será exibido. O Genie usa a filtragem de contexto para priorizar os tokens que considera mais relevantes para uma pergunta. Embora as respostas ainda devam ser geradas quando um aviso é exibido, a qualidade pode ser reduzida se o contexto importante for filtrado. Quando o limite de token é excedido, você não pode mais enviar ou receber mensagens no Agente do Genie.

Considere as seguintes práticas para reduzir a contagem de tokens:

• Remova colunas desnecessárias: colunas desnecessárias nas suas tabelas podem contribuir significativamente para o uso do token. Quando possível, crie exibições para excluir campos redundantes ou não essenciais de suas tabelas brutas. Você também pode ocultar colunas desnecessárias em um Agente do Genie. Consulte Ocultar ou mostrar colunas relevantes.
• Simplifique as descrições das colunas: embora as descrições das colunas sejam importantes, evite duplicar informações já transmitidas por nomes de coluna. Por exemplo, se uma coluna for nomeada account_name, uma descrição como "o nome da sua conta" poderá ser redundante e poderá ser omitida.
• Editar metadados de coluna no Agente Genie: consulte Editar metadados de coluna para saber como editar descrições e fornecer sinônimos em metadados de coluna.
• Elimine exemplos de consultas SQL: inclua uma variedade de exemplos de consultas SQL para abranger vários tipos de perguntas, mas remova exemplos sobrepostos ou redundantes.
• Simplifique as instruções: verifique se as instruções são claras e concisas. Evite palavras desnecessárias.

Sua conta não está habilitada para processamento entre áreas geográficas

O Genie é um Serviço Designado gerenciado pelo Azure Databricks. Os Serviços Designados usam regiões geográficas do Databricks para gerenciar a residência de dados. Os dados não podem ser processados na mesma região geográfica que o espaço de trabalho em algumas regiões. Se o workspace estiver em uma dessas regiões, o processamento entre áreas geográficas deverá ser habilitado pelo administrador da conta.

O último autor do agente é removido do espaço de trabalho

Um Agente Genie acessa seu SQL warehouse usando as credenciais de computação embutidas pelo autor que o configurou mais recentemente. Se esse autor for removido do workspace, suas credenciais inseridas não serão mais válidas e as consultas falharão para todos que usam o agente.

Para restaurar o agente, tenha outro usuário com pelo menos a permissão CAN EDIT no Genie Agent para reconfigurar o sql warehouse do agente. Salvar uma seleção do repositório incorpora as credenciais de computação do usuário que está editando no lugar das do autor removido. Consulte Definir configurações.