Sincronização diária da Central de Ajuda com a base do Robô

Visão geral

Existem duas integrações diferentes entre a Central de Ajuda e o Maestro. Elas têm nomes parecidos, mas escopo e velocidade bem diferentes — confundir as duas é a causa mais comum de "publiquei o artigo e o Robô não sabe":

A primeira sempre funcionou instantaneamente. A segunda — a que leva todo o portal para a base compartilhada da conta — não tinha gatilho automático: só rodava se um administrador da instalação a disparasse manualmente. A partir desta versão ela roda sozinha, todos os dias.

Cada artigo publicado vira um documento na base da conta, no caminho help-center/{portal}/{categoria}/{artigo} — assim o Robô responde com o conteúdo oficial e consegue citar de qual artigo tirou a resposta. Artigos sem categoria ficam em uncategorized.

Pré-requisitos

• Conta com o Maestro habilitado e pelo menos um Robô ativo. A varredura diária ignora contas sem nenhum Robô ativo — não há para quem entregar o conhecimento.
• Um portal da Central de Ajuda com artigos no status publicado.
• Provedor de embeddings com chave e créditos válidos — é a mesma indexação usada pela base de conhecimento do Cérebro da Conta.
• A sincronização precisa estar habilitada na instalação (chave de implantação, no controle do administrador da instalação). Se estiver desligada, nenhuma conta sincroniza.

Passo a passo

1. Escreva e publique os artigos no seu portal, como sempre. Rascunho e arquivado não contam.
2. Não faça mais nada. A varredura roda automaticamente todos os dias às 05:10 UTC (02:10 no horário de Brasília). Ela não é disparada quando o serviço reinicia: espera o horário.
3. No dia seguinte, confirme: pergunte ao Robô algo que só existe naquele artigo. A resposta deve trazer o conteúdo publicado e apontar a origem em help-center/….
4. Precisa valer agora, sem esperar o próximo dia? Duas saídas:
   • marque o artigo (ou a categoria inteira) na aba de conhecimento do Robô — essa seleção vale na hora e continua sincronizada a cada edição;
   • ou peça a um administrador da instalação para disparar a sincronização da conta sob demanda.

Configurações & opções

• Cadência diária, às 05:10 UTC. O horário quebrado é proposital: as outras rotinas automáticas do Maestro rodam em horários cheios, e o mapeamento da estrutura do Cérebro roda 55 minutos antes — assim a leitura dos artigos não disputa a mesma conta com a rotina anterior.
• Escopo: todos os portais da conta, todos os artigos publicados. A categoria vira "pasta" no caminho do documento.
• Conteúdo indexado: o título mais o corpo do artigo. Os subtítulos (##, ###) guiam a quebra em trechos — cada trecho carrega a seção de onde saiu, o que melhora a citação.
• Somente leitura: a sincronização nunca altera, publica, despublica ou apaga um artigo. Ela só lê o portal e escreve na base do Maestro.
• Uma execução por conta, por dia: se a sincronização do dia anterior ainda estiver rodando quando a próxima começa, a nova é descartada. Nunca há duas escrevendo na mesma base ao mesmo tempo.
• Substituição atômica: o conteúdo é indexado antes de a base ser tocada, e a troca acontece numa única transação. Uma falha no meio do caminho nunca esvazia o que já estava indexado.
• Isolamento de erro: um artigo, uma página ou um portal com problema é contabilizado e a varredura continua nos demais — um item ruim não derruba a sincronização inteira.
• Guarda de paginação: a leitura de cada portal é limitada e para sozinha quando os artigos começam a se repetir, evitando leitura infinita.

Casos de uso

• Fazer o Robô responder com a política oficial já publicada, citando o artigo, em vez de uma versão colada à mão e desatualizada.
• Manter uma única fonte de verdade: a equipe edita no portal, e todos os Robôs herdam.
• Contas com muitos artigos: aproveitar todo o portal sem precisar marcar item por item.
• Robôs novos já nascem sabendo — a base é da conta, não de um Robô específico.
• Portais trilíngues: tudo que está publicado em cada idioma entra na base.

Dicas, limites e boas práticas

• Rascunho e arquivado não entram. Artigo com corpo vazio também é ignorado (e o que já estava indexado é preservado).
• Despublicar não remove o artigo da base compartilhada na varredura diária: ela adiciona e atualiza, não apaga documentos de artigos que saíram do ar. Se um conteúdo precisa sumir das respostas imediatamente, use a seleção por Robô (que remove ao despublicar) ou peça a remoção daquela fonte a um administrador.
• Custo: cada execução re-indexa os artigos publicados, e indexar custa dinheiro por conta. Por isso a cadência é diária: é o menor custo estável que mantém a defasagem em, no máximo, 24 horas. Rodar de hora em hora multiplicaria esse custo por 24 para observar um conteúdo que quase nunca muda de hora em hora.
• Janela de até 24 horas: mudanças urgentes devem ir pela seleção por Robô, que vale na hora.
• Artigo bom = resposta boa: títulos claros, seções bem divididas e conteúdo atualizado geram citações melhores. Conteúdo velho gera resposta velha.

Solução de problemas

• "Publiquei ontem e o Robô não sabe": confirme que o artigo está publicado, que a conta tem pelo menos um Robô ativo e que o provedor de embeddings tem créditos. Se o artigo foi publicado depois das 05:10 UTC, ele só entra na varredura seguinte.
• "Nada sincroniza, em nenhuma conta": a sincronização provavelmente está desligada na instalação. Fale com o administrador da instalação.
• "Sincronizou, mas o Robô não usa": o Robô precisa estar autorizado a consultar a base de conhecimento. Revise as ferramentas habilitadas para ele.
• "Um artigo antigo continua aparecendo nas respostas": é o limite descrito acima — despublicar não apaga da base compartilhada. Use a seleção por Robô ou peça a remoção da fonte.
• "Não foi possível indexar" / embeddings indisponíveis: nenhum provedor de embeddings está com chave e créditos válidos. Verifique os créditos do provedor primário ou conecte uma chave alternativa em Integrações — é a mesma causa (e a mesma solução) da base de conhecimento.

Veja também

• Base de conhecimento e mapa do negócio (ontologia) do Cérebro
• Onde cada Robô é usado: as superfícies da conta
• Ferramentas do Maestro por módulo e como habilitá-las
• O que é o Maestro IA e o Cérebro da Conta