Solucionar problemas do Genie Agents

Resolva problemas comuns ao criar e manter um Genie Agent: jargão de negócios incompreendido, uso incorreto de tabelas ou colunas, erros de filtragem em valores específicos e truncamento de limite de tokens em conversas longas. Cada seção abaixo aborda o sintoma, a causa e a correção.

nota

Os Genie Agents eram anteriormente conhecidos como Genie space.

Para muitos desses problemas, o caminho mais rápido para uma correção é o Genie Code. Descreva o problema para o Genie Code, e ele sugere alterações de contexto para revisão e aceitação. Para diagnosticar uma única resposta incorreta, veja Depurar respostas com o Genie Code. Para revisar as falhas de benchmark juntos, veja Analisar uma execução de benchmark com o Genie Code.

Jargão de negócios mal interpretado

A maioria das empresas ou domínios tem abreviações específicas 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 este ano fiscal pode começar em fevereiro ou março em vez de janeiro. Para permitir que o Genie responda a estas perguntas de forma natural e precisa, inclua instruções que mapeiam explicitamente seu jargão de negócios para palavras e conceitos que o Genie pode entender. Consulte Fornecer instruções.

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, é possível 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 corresponde à terminologia dos usuários nas perguntas enviadas. Caso contrário, refine a descrição ou adicione uma instrução que mapeie a terminologia usada na tabela para a terminologia usada na pergunta.
• Adicione queries de exemplo : forneça queries SQL de exemplo que o Genie pode usar para aprender a responder a certas perguntas. Consulte Fornecer instruções.
• Remover Tabelas ou Colunas do Agent : Algumas tabelas podem incluir colunas ou conceitos sobrepostos que dificultam que o Genie saiba quais dados usar em uma resposta. Se possível, remova tabelas ou colunas desnecessárias ou sobrepostas. Para ocultar colunas da UI do Genie Agent sem alterar os objetos de dados subjacentes, consulte Ocultar ou mostrar colunas relevantes.

Filtrando erros

Queries geradas muitas vezes incluem uma cláusula WHERE para filtrar resultados de acordo com um valor específico. Quando o Genie não tem visibilidade dos valores dos dados, ele pode definir a cláusula WHERE para filtrar pelo valor errado. Por exemplo, ele pode tentar corresponder ao nome "California" quando a tabela usa abreviações como "CA".

Para situações como essa, verifique se as colunas relevantes têm **valores de exemplo** e **dicionários de valores** ativados. Se novos dados foram adicionados às tabelas relevantes, refresh os valores. Consulte Visão geral da correspondência de prompts.

Joins incorretos

Se as referências de chave estrangeira não estiverem definidas no Unity Catalog, o agente pode não saber como join tabelas diferentes.

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

• Defina referências de chave estrangeira no Unity Catalog quando possível. Consulte a Cláusula CONSTRAINT.
• Se os relacionamentos de foreign key de suas tabelas não estiverem especificados no Unity Catalog, defina os relacionamentos de join no armazenamento de conhecimento de seu Genie Agent. Esta estratégia é útil para cenários de junção mais complexos, como autojunções, ou se o senhor não tiver permissão suficiente para modificar as tabelas subjacentes. Consulte Definir relacionamentos de join.
• Forneça queries de exemplo onde você faz join em tabelas de maneiras padrão.

Se nenhuma destas opções resolver o problema, pré-una a tabela em uma view e use-a como entrada para o agente.

Comentários da coluna não sincronizando de tabelas externas

A Databricks não gerencia os metadados, dados ou semânticas para gravações em tabelas estrangeiras. Dependendo da tabela de origem, os comentários podem não estar acessíveis na Databricks. Para disponibilizar comentários, a Databricks recomenda fazer uma das seguintes ações:

• Edite os metadados da coluna na UI do Genie Agent. Os metadados editados se aplicam apenas ao Genie Agent onde são escritos. Consulte Editar metadados da coluna.
• Criar views materializadas sobre tabelas federadas. É possível adicionar e editar comentários em uma view materializada, assim como faria em uma tabela gerenciada. É possível reutilizar esta view em vários Agentes Genie. Para obter detalhes sobre o carregamento de dados de tabelas estrangeiras em uma visualização materializada, consulte Carregar dados de tabelas estrangeiras com visualizações materializadas. Para saber mais sobre como trabalhar com visualizações materializadas, consulte Visualizações materializadas.

Problemas de cálculo de métricas

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

Experimente 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 de tabelas base, forneça exemplos de queries SQL que calculem cada valor de roll-up.
• Se suas métricas foram pré-calculadas e estão 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 agregadas.
• Se o SQL que você está tentando gerar for muito complicado, tente criar views que já tenham agregado suas métricas para seu agente.

Cálculos incorretos baseados no tempo

Genie nem sempre conseguirá inferir o fuso horário representado nos dados ou o fuso horário no qual sua análise precisa ser realizada, a menos que você forneça explicitamente orientações 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 os horários para um fuso horário específico : Neste exemplo, suponha que o timestamp de origem seja UTC e você deseja os resultados no fuso horário America/Los_Angeles. Adicione o seguinte às instruções, substituindo <timezone-column> pelo nome da coluna apropriada:

  • Fusos horários nas tabelas estão em UTC.
  • Converta todos os fusos horários usando a seguinte função: convert_timezone('UTC', 'America/Los_Angeles', <timezone-column>).

• Converter formatos de data/hora não-UTC para UTC: Se o fuso horário default do Workspace 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 às instruções gerais do agente:

  • Para referenciar hoje , use date(convert_timezone('UTC', 'America/Los_Angeles', current_timestamp())).

Consulte a funçãoconvert_timezone 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 poderá não estar usando-os corretamente.

Experimente uma ou mais das seguintes estratégias:

• Forneça queries de exemplo que usam suas tabelas corretamente. Queries de exemplo são especialmente eficazes para ensinar seu agente a usar seus dados.
• Oculte as colunas irrelevantes no Genie Agent. Consulte Ocultar ou mostrar colunas relevantes.
• Crie views a partir de suas tabelas que fornecem uma view mais simples de seus dados.
• Revise suas instruções e tente focar o agente removendo tabelas ou instruções irrelevantes.
• Experimente iniciar uma nova conversa. Interações anteriores podem influenciar as respostas do Genie em qualquer chat, 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 queries excepcionalmente longas ou respostas de texto, pode demorar muito para responder ou até mesmo exceder o tempo limite durante a fase de raciocínio.

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

• Verifique o histórico de queries para identificar queries de execução lenta. Muitos problemas de desempenho podem ser resolvidos otimizando as queries SQL geradas em vez de modificar a configuração do Genie Agent. Revise os tempos de execução e planos de query no histórico de queries do seu SQL warehouse para identificar gargalos e oportunidades de otimização.
• Use ativos confiáveis ou views para encapsular queries complexas. Consulte Ativos confiáveis.
• Reduza o comprimento de suas queries SQL de exemplo sempre que possível.
• Comece uma nova conversa se o Genie começar a gerar respostas lentas ou com falha.

Respostas não confiáveis a perguntas de missão crítica

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

Aviso de limite de tokens

Tokens são as unidades básicas de texto que o Genie usa para processar e entender a linguagem. Instruções de texto e metadados em um Genie Agent são convertidos em tokens. Se seu agente se aproximar do limite de tokens, um aviso será exibido. 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 aparecer, a qualidade pode ser reduzida se um contexto importante for filtrado. Quando o limite de tokens é excedido, você não pode mais enviar ou receber mensagens no Genie Agent.

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

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

Sua account não está habilitada para processamento cross-geo.

Genie é um serviço designado gerenciado pela Databricks. Os serviços designados usam o Databricks Geos para gerenciar a residência de dados. Dados não podem ser processados na mesma Geo que o workspace para algumas regiões. Se o seu workspace estiver em uma dessas regiões, o processamento cross-Geo deverá ser habilitado pelo seu account administrator.

O último autor do agente é removido do workspace

Um Genie Agent processa todas as queries usando as credenciais de compute incorporadas pelo autor que configurou mais recentemente o SQL Warehouse do agente. Se esse autor for removido do Workspace, as credenciais incorporadas dele não serão mais válidas, e as queries falharão para todos que usam o agente.

Para restaurar o agente, solicite que outro usuário com pelo menos permissão CAN EDIT no Genie Agent reconfigure o SQL warehouse do agente. Salvar uma seleção de warehouse incorpora as credenciais de compute do usuário editor em vez das do autor removido. Consulte Definir configurações.