Hermes Agent: Guia de configuração autoalojada para utilizadores de servidores domésticos

Eva Wong é a redatora técnica e entusiasta residente na ZimaSpace. Uma geek desde sempre, apaixonada por homelabs e software de código aberto, dedica-se a traduzir conceitos técnicos complexos em guias práticos. A Eva acredita que a auto-hospedagem deve ser divertida, não intimidante. Através dos seus tutoriais, ajuda a comunidade a desmistificar configurações de hardware, desde montar o primeiro NAS até dominar os contentores Docker.

Resposta rápida

O Hermes Agent pode ser alojado localmente num servidor doméstico se quiser um agente de IA que se ligue a um fornecedor de modelos, utilize ferramentas e comunique através de um gateway de mensagens, como o Telegram. Para a maioria dos principiantes, a parte mais difícil não é apenas executar a aplicação. É perceber onde ocorre cada ação: no servidor anfitrião, dentro do contentor, no ambiente da aplicação ou através de uma plataforma de mensagens.

Uma configuração segura alojada localmente deve responder a seis perguntas antes de iniciar qualquer resolução de problemas:

  • Estou a trabalhar no anfitrião ou dentro do contentor?
  • Onde ficam a configuração da aplicação, os registos, os ficheiros transferidos e os dados do ambiente de execução?
  • Que utilizador é proprietário dos ficheiros e executa a aplicação?
  • A aplicação consegue aceder ao fornecedor do modelo e à API de mensagens?
  • As chaves de API, os tokens de bots e as listas de permissões estão protegidos?
  • Como posso confirmar que o agente continua a funcionar após reiniciar?

Se mantiver estes limites bem definidos, será muito mais fácil compreender, verificar e corrigir a configuração do Hermes Agent.

O que é o Hermes Agent numa configuração de servidor doméstico alojado localmente?

O Hermes Agent é um fluxo de trabalho de agente de IA alojado localmente que pode ligar-se a um fornecedor de modelos, utilizar ferramentas e interagir através de canais de terminal ou de mensagens. Num servidor doméstico, fica muitas vezes entre o modelo de IA, o ambiente do servidor e uma interface de comunicação, como um painel Web ou um gateway de bots.

O importante é que um agente alojado localmente não é apenas um chatbot. Dependendo da configuração, pode interagir com ficheiros, ferramentas de terminal, APIs de modelos, plataformas de mensagens e dados do ambiente de execução. Por isso, é importante definir limites para os caminhos, as permissões e o acesso.

O que o Hermes Agent faz para a interação com IA e as mensagens

O Hermes Agent pode ser configurado para se ligar a um fornecedor de modelos, iniciar conversas, utilizar ferramentas e ligar gateways de mensagens. O fluxo de início rápido do Hermes Agent explica como instalar o Hermes, configurar um fornecedor de modelos, iniciar uma primeira conversa, utilizar ferramentas de terminal e, mais tarde, ligar plataformas de mensagens através de um gateway.

Para quem utiliza um servidor doméstico, isto significa que o Hermes pode tornar-se um assistente de IA persistente, em execução num dispositivo que controla. Também pode introduzir novas etapas de configuração: credenciais do modelo, ambiente de execução da aplicação, definições do gateway e permissões de acesso.

Quando a configuração através da interface Web é suficiente

A configuração através da interface Web costuma ser suficiente quando a aplicação disponibiliza todas as definições necessárias diretamente no painel. Esta é a opção mais segura para a maioria dos utilizadores, pois evita aceder ao terminal do contentor, a menos que algo esteja em falta ou avariado.

Uma abordagem baseada na interface Web é adequada quando:

  • a aplicação instala-se sem problemas;
  • o fornecedor do modelo pode ser configurado através da interface;
  • o gateway de mensagens pode ser ligado sem acesso à shell;
  • o painel apresenta o estado de forma clara;
  • os registos não apresentam erros de permissões ou de rede.

Se o painel de controlo disponibilizar a opção de que precisa, comece por usá-la. A configuração do terminal do contentor deve ser considerada uma alternativa ou uma opção avançada, não o primeiro passo por predefinição para todos os utilizadores.

Quando precisa de configurar o terminal do contentor

Poderá precisar de configurar o terminal do contentor quando o painel de controlo não disponibilizar uma opção necessária, quando a aplicação exigir um assistente de configuração dentro do contentor ou quando a resolução de problemas exigir acesso a registos, ao ambiente de execução ou a comandos específicos da aplicação.

É aqui que muitos utilizadores ficam confusos. Um comando executado na shell do anfitrião pode não afetar a aplicação dentro do contentor. Um ficheiro visível dentro do contentor pode não existir no mesmo caminho no anfitrião. Um erro de permissões pode ser causado pelo utilizador que executa a aplicação, e não pelo fornecedor do modelo ou pelo token do bot.

Antes de usar o terminal do contentor, confirme exatamente em que shell está e com que utilizador está a executar comandos.

O que precisa antes de começar

A configuração de um agente autoalojado exige mais do que um servidor em funcionamento. Precisa de uma ligação de rede funcional, acesso a modelos, credenciais de mensagens e permissões suficientes para gerir a aplicação sem alterar acidentalmente os ficheiros errados.

Um servidor doméstico com acesso à Internet

O servidor doméstico deve conseguir aceder à Internet se pretender usar um fornecedor de modelos na cloud ou uma API de mensagens. Se usar um ponto de acesso a modelos locais, o servidor continua a precisar de aceder a esse ponto na rede local ou na rede do contentor.

O acesso à rede é importante porque um agente pode parecer estar corretamente instalado e, ainda assim, não responder. Por exemplo, a ligação ao fornecedor do modelo, o gateway de mensagens ou o painel de controlo podem depender de percursos de rede diferentes.

Comece por confirmar:

  • o servidor tem uma ligação LAN estável;
  • o servidor consegue aceder ao ponto de acesso ou fornecedor do modelo;
  • o servidor consegue aceder à API de mensagens;
  • a porta do painel de controlo está acessível a partir do seu navegador;
  • nenhuma regra da firewall está a bloquear o gateway.

Um fornecedor de modelos ou um ponto de acesso a modelos locais

O Hermes precisa de uma ligação a um modelo antes de poder gerar respostas úteis. Pode ser um fornecedor na cloud, uma chave da API ou um ponto de acesso compatível com a API da OpenAI. Alguns utilizadores podem ligar um serviço de modelos local, se o hardware e a pilha de modelos o permitirem.

O detalhe importante da configuração é que a configuração do modelo é independente da configuração de mensagens. Um bot pode estar corretamente ligado, mas o fornecedor do modelo estar incorreto; e um fornecedor do modelo pode funcionar, mas o gateway do bot falhar.

Organize o URL base do modelo, a chave da API, o nome do modelo e as definições de contexto antes de iniciar a configuração.

Uma conta de mensagens e um token de bot

Se quiser falar com o agente através do Telegram ou de outra plataforma de mensagens, precisa de uma conta nessa plataforma e de uma credencial de bot ou gateway. No caso do Telegram, isso costuma significar criar um bot e guardar o respetivo token.

Um token de bot deve ser tratado como uma palavra-passe. O Telegram explica que cada bot recebe um token único usado para autorizar pedidos à Bot API, e que os pedidos incluem o token no caminho da API no modelo de autorização de tokens de bots do Telegram.

Não cole um token de bot em conversas públicas, capturas de ecrã, registos, problemas do GitHub ou documentos partilhados. Se um token for exposto, gere um novo através do procedimento oficial da plataforma de mensagens.

Endereço IP do anfitrião, acesso de início de sessão e permissões do contentor

Precisa do endereço IP do anfitrião para aceder ao painel do servidor ou ligar-se por SSH. Também precisa de acesso de início de sessão que lhe permita gerir a aplicação em segurança.

Nas configurações baseadas em contentores, as permissões têm frequentemente várias camadas:

Camada de permissões O que controla Erro comum Verificação segura
Utilizador do anfitrião / conta SSH Acesso ao sistema de ficheiros do servidor doméstico, aos comandos Docker e ao painel do servidor. Partir do princípio de que as permissões do anfitrião se aplicam automaticamente dentro do contentor. Confirme qual é a conta com sessão iniciada e que ações ao nível do servidor pode executar.
Utilizador do contentor O utilizador que executa o processo da aplicação e escreve ficheiros da aplicação dentro do contentor. Executar a configuração como root quando a aplicação costuma ser executada por um utilizador sem privilégios de root. Verifique qual é o utilizador pretendido do contentor antes de criar ou editar dados da aplicação.
Pasta montada do anfitrião A pasta do anfitrião ou o volume Docker exposto ao contentor. Editar uma pasta do anfitrião que não está montada no caminho que a aplicação lê. Verifique o caminho de origem no anfitrião e o caminho de destino no contentor.
Caminho de execução da aplicação Onde são guardados os ficheiros de configuração, os registos, as transferências, as sessões e os dados temporários. Alterar ficheiros na camada errada ou perder definições após o reinício. Confirme que o caminho persiste após o reinício e que o utilizador da aplicação pode escrever nele.

Não parta do princípio de que a raiz é sempre a opção certa. Usar o utilizador root na altura errada pode criar ficheiros propriedade de root que o utilizador da aplicação não consegue modificar mais tarde.

Caminho do anfitrião vs. caminho do contentor vs. caminho dos dados da aplicação

Este é o conceito mais importante deste artigo. Muitos problemas de configuração do Hermes Agent resultam da confusão entre caminhos do anfitrião, caminhos do contentor, caminhos dos dados da aplicação, registos, transferências e volumes montados.

Utilize O Mapa de Controlo do Contentor do Agent antes de executar ou depurar comandos.

Camada Pergunta a responder Indicador de validação Falha típica
Sistema anfitrião É possível aceder ao servidor, ao painel, à sessão SSH e ao gestor de contentores? O painel ou a sessão SSH abre e o contentor aparece como em execução. A aplicação parece estar instalada, mas não é possível aceder ao servidor nem ao contentor.
Ambiente de execução do contentor Estou no contentor correto e a usar o utilizador esperado? A shell, o diretório de trabalho e o utilizador correspondem ao caminho de configuração da aplicação. Os comandos são executados na shell do anfitrião e não afetam a aplicação dentro do contentor.
Caminho dos dados da aplicação Onde ficam os ficheiros de configuração, os registos, as transferências e os ficheiros de execução? As definições e os registos persistem após o reinício e podem ser escritos pelo utilizador da aplicação. As definições desaparecem após o reinício ou a aplicação apresenta erros de acesso negado.
Percurso de rede O contentor consegue aceder ao fornecedor do modelo, ao ponto final local e à API de mensagens? As verificações do fornecedor, as chamadas ao gateway e o acesso ao painel funcionam a partir da camada esperada. O modelo ou o bot falha, apesar de a aplicação parecer estar corretamente instalada.
Credenciais e acesso As chaves API, os tokens do bot e os utilizadores na lista de permissões estão configurados de forma segura? As mensagens de teste privadas funcionam e os registos não apresentam erros de token nem de acesso. O token do bot é inválido ou foi exposto, ou o ID de utilizador permitido está incorreto.
Validação do reinício A configuração continua a funcionar após o reinício do gateway ou do serviço? O bot responde, o painel está operacional e os registos mantêm-se limpos após o reinício. A configuração antiga continua ativa ou as novas definições não ficam guardadas.

O que o sistema anfitrião consegue ver

O sistema anfitrião é o sistema operativo do servidor doméstico. Pode ver pastas do anfitrião, contentores Docker, interfaces de rede, dispositivos de armazenamento e serviços ao nível do sistema.

Se uma aplicação estiver a ser executada no Docker, o anfitrião pode não ver o caminho interno da aplicação da mesma forma que o contentor. O anfitrião pode ver um volume Docker, uma pasta montada por bind ou metadados do contentor.

É por isso que um caminho como /opt/data ou /app/config pode não significar o mesmo no anfitrião e dentro do contentor.

O que o contentor consegue ver

Um contentor vê o seu próprio sistema de ficheiros. Também pode ver pastas do anfitrião que tenham sido montadas nele. O caminho do contentor é o caminho do ponto de vista da aplicação.

O Docker explica que uma montagem bind monta um ficheiro ou diretório da máquina anfitriã num contentor, enquanto um volume Docker é criado no diretório de armazenamento do Docker no anfitrião e gerido pelo Docker através do modelo de armazenamento de montagens bind do Docker.

Esta distinção é importante porque um contentor só consegue aceder aos caminhos do anfitrião que estão montados nele. Se a aplicação não conseguir encontrar um ficheiro, o problema pode ser o ficheiro existir no anfitrião, mas não estar montado no caminho esperado dentro do contentor.

Onde se encontram normalmente a configuração da aplicação e os dados de execução

A configuração da aplicação, os registos, as transferências e os dados de execução podem estar em locais diferentes, consoante a forma como a aplicação foi empacotada. Alguns dados podem estar dentro do contentor, outros num volume Docker e outros ainda montados a partir do anfitrião.

Para um agente autoalojado, os tipos de dados comuns incluem:

  • definições do fornecedor de modelos;
  • configuração do gateway;
  • token do bot ou definições de mensagens;
  • registos e estado da sessão;
  • transferências temporárias;
  • resultados das ferramentas;
  • dados de execução específicos da aplicação.

A questão importante não é apenas «onde está o ficheiro?», mas «que camada é responsável por este ficheiro e que utilizador o pode modificar?»

Ecrã do Hermes Agent para selecionar um fornecedor de modelos durante a configuração

Porque é que a confusão com os caminhos causa problemas de permissões e de dados

A confusão com os caminhos causa dois problemas comuns. Primeiro, os utilizadores editam um ficheiro no anfitrião, mas o contentor lê outro ficheiro no seu próprio caminho. Segundo, os utilizadores executam a configuração como root e criam ficheiros que o utilizador da aplicação não consegue modificar mais tarde.

As montagens bind também podem ocultar ficheiros já existentes no contentor quando uma pasta do anfitrião é montada sobre um diretório do contentor que não esteja vazio. Nesse caso, os ficheiros podem parecer desaparecidos, apesar de estarem apenas ocultos pela montagem.

Antes de corrigir um problema com os dados de uma aplicação, verifique a camada de execução, os caminhos montados, o proprietário do ficheiro e o utilizador do contentor.

Como configurar um agente autoalojado passo a passo

A configuração de um agente autoalojado deve avançar das verificações de baixo risco para a configuração e, em seguida, para a validação. Não comece por alterar permissões ou reiniciar serviços antes de saber qual é a camada que está a falhar.

Passo 1: Instale ou abra a aplicação a partir do painel do servidor

Comece pelo método mais simples suportado para instalar ou iniciar aplicações no seu servidor doméstico. Se o servidor disponibilizar um painel de aplicações, utilize-o para confirmar que o Hermes Agent está instalado, visível e em execução.

Nesta fase, não entre no contentor, a menos que a aplicação o exija. Primeiro, confirme o estado no painel, a versão da aplicação, se for apresentada, e se existe uma página de configuração.

Se a aplicação nem sequer arrancar, consulte os registos antes de alterar os ficheiros de configuração.

Passo 2: Confirme o IP do anfitrião e o acesso à rede

Confirme o endereço IP do anfitrião e certifique-se de que o seu navegador ou terminal consegue aceder ao servidor. Dependendo da configuração, poderá utilizar o mesmo IP para aceder ao painel, por SSH ou ao gateway local.

Em seguida, confirme o acesso à rede externa. Um bot de mensagens não responderá se o contentor não conseguir aceder à API de mensagens, e um fornecedor de modelos falhará se o servidor não conseguir aceder ao ponto de acesso do modelo.

Esta verificação ajuda a distinguir entre «a configuração da aplicação falhou» e «o acesso à rede falhou».

Passo 3: Entre no contentor com o utilizador correto

Se for necessário configurar o terminal do contentor, entre no contentor com o utilizador previsto para a aplicação. Isto é importante porque os ficheiros criados pelo utilizador errado podem causar erros de permissões mais tarde.

Não trate a shell do anfitrião e a shell do contentor como se fossem o mesmo ambiente. Um comando que funciona no anfitrião poderá não existir no contentor, e um caminho de ficheiro dentro do contentor poderá não existir no anfitrião.

Antes de executar comandos de configuração, confirme:

  1. Está no contentor correto.
  2. Está a utilizar o utilizador previsto para o contentor.
  3. Está no diretório de trabalho esperado.
  4. O comando necessário da aplicação está disponível.
  5. Sabe como sair do contentor e voltar a entrar.

Passo 4: Ative o ambiente da aplicação antes de executar comandos de configuração

Algumas aplicações autoalojadas utilizam um ambiente virtual ou uma configuração de shell específica da aplicação. Se o ambiente não estiver ativado, o comando da aplicação poderá não ser encontrado ou poderá ser executado com dependências incorretas.

Este passo não é uma mera formalidade. Garante que o assistente de configuração, o comando do gateway e o comando de configuração do modelo são executados no mesmo contexto de execução da aplicação.

Se um comando falhar inesperadamente, verifique se está no contentor correto e se o ambiente da aplicação está ativo antes de reinstalar seja o que for.

Passo 5: Ligar a um fornecedor de modelos ou serviço de modelo local

Configure o fornecedor do modelo, o ponto de acesso personalizado ou o serviço de modelo local. Mantenha o URL base, a chave API, o nome do modelo e as definições relacionadas com o contexto compatíveis com o fornecedor que utiliza.

Se a configuração do modelo falhar, verifique o seguinte, por esta ordem:

  • A chave API está correta?
  • É possível aceder ao URL base a partir do contentor?
  • O nome do modelo é suportado pelo ponto de acesso?
  • A aplicação precisa de um modelo com contexto longo?
  • Há problemas de rede ou DNS dentro do contentor?

Evite confundir erros do modelo com erros de mensagens. O facto de um bot do Telegram não responder e de um fornecedor de modelos falhar só está relacionado porque o agente precisa de ambos para concluir o fluxo de trabalho.

Passo 6: Configurar o gateway de mensagens

O gateway de mensagens liga o ambiente de execução do agente a uma plataforma de mensagens. No caso do Telegram, isso envolve normalmente um token de bot e a identidade de um utilizador autorizado.

Uma boa configuração do gateway deve definir quem pode enviar mensagens ao agente, que token de bot é utilizado e se o bot se destina a conversas privadas, de grupo ou a ambas.

Nunca trate um bot de mensagens como uma interface pública por predefinição. Um agente alojado localmente pode ter acesso a ferramentas, dados locais ou ações que não devem estar disponíveis para todos os utilizadores que consigam contactar o bot.

Passo 7: Reiniciar o gateway e aplicar a nova configuração

Após alterações ao modelo ou ao gateway de mensagens, poderá ser necessário reiniciar o gateway para que a nova configuração seja aplicada. O comportamento durante o reinício é importante, porque uma configuração pode parecer concluída e, ainda assim, continuar a usar definições antigas.

Após o reinício, valide tanto do lado do utilizador como do lado do servidor. Envie uma mensagem de teste, verifique o estado no painel de controlo e analise os registos à procura de erros de permissões, de token ou de rede.

Se a reconfiguração não persistir após o reinício, volte ao caminho dos dados e aos limites de permissões.

Ecrã de controlo do bot do Telegram do Hermes Agent para validar o gateway de mensagens

Permissões, tokens e controlo de acesso

Os agentes alojados localmente combinam permissões de execução locais com credenciais externas. Isto significa que uma configuração pode funcionar tecnicamente e, ainda assim, não ser segura se os tokens, as listas de permissões ou os limites entre utilizadores estiverem incorretos.

Porque é que o utilizador do contentor é importante

O utilizador do contentor controla os ficheiros que a aplicação pode ler e escrever dentro do contentor. Se os comandos de configuração forem executados como root e, mais tarde, a aplicação for executada como utilizador não root, os dados da aplicação podem ficar inacessíveis para a própria aplicação.

Isto surge frequentemente como um erro de permissões no caminho dos dados da aplicação. A solução nem sempre é continuar a usar o root. Em muitos casos, a melhor abordagem é restaurar as permissões de propriedade corretas e executar a aplicação como o utilizador previsto.

Utilize root apenas quando for necessário para uma etapa de recuperação específica e evite criar ficheiros da aplicação de uso corrente como root.

Porque é necessário proteger as chaves de API e os tokens de bot

As chaves de API e os tokens de bot são credenciais. Uma chave de API de modelo pode conceder acesso a um fornecedor de modelos. Um token de bot pode autorizar pedidos em nome do bot.

Não inclua estes valores em repositórios públicos, capturas de ecrã, registos partilhados ou mensagens de suporte. Durante a resolução de problemas, oculte os tokens antes de partilhar qualquer configuração ou registo.

Se um token tiver sido exposto, substitua-o em vez de esperar que ninguém o utilize.

Como a lista de utilizadores autorizados controla o acesso privado

Uma lista de utilizadores autorizados limita os utilizadores que podem interagir com o agente através de um gateway de mensagens. Isto é importante porque o bot de mensagens pode estar acessível a mais pessoas do que espera.

Para conversas privadas com IA, use a lista de utilizadores autorizados mais restrita possível. Confirme que o ID do utilizador autorizado está correto e que as mensagens de teste são enviadas a partir dessa conta.

Se várias pessoas precisarem de acesso, adicione-as intencionalmente em vez de deixar o bot acessível a todos.

Porque não deve tratar os bots de mensagens como interfaces públicas

Um bot de mensagens pode parecer uma interface de chat normal, mas por trás pode estar um agente alojado por si, com acesso a modelos, ferramentas, sessões e permissões de execução locais.

Isso torna-o diferente de um simples bot de notificações. Deve ter regras de acesso claras, tokens protegidos e um caminho de rede controlado.

Nas conversas de grupo, seja prudente. As permissões do grupo, o modo de privacidade e o estatuto de administrador do bot podem alterar as mensagens que o bot consegue ver ou às quais consegue responder.

Problemas de configuração comuns e como resolvê-los

A maioria dos problemas de configuração pode ser atribuída a uma de seis camadas: ambiente de execução, caminho dos dados, permissões, gateway, segredo ou validação.

Erros de permissões no caminho dos dados da aplicação

Um erro de permissões significa geralmente que o utilizador atual da aplicação não consegue ler ou escrever num ficheiro ou numa pasta necessários. Isto pode acontecer quando um comando de configuração anterior criou ficheiros como root ou quando uma pasta montada tem um proprietário incorreto.

Comece por verificar o seguinte:

  • Está dentro do contentor ou no anfitrião?
  • Que utilizador está a executar a aplicação?
  • Quem é o proprietário da pasta de dados da aplicação?
  • O caminho dos dados da aplicação está montado a partir do anfitrião?
  • Foi executado anteriormente um comando de configuração como root?

Não altere recursivamente as permissões de pastas abrangentes, a menos que saiba o que está a fazer. Corrija apenas o caminho específico mais restrito necessário.

O bot não responde após a configuração

Um bot pode não responder mesmo quando o Hermes Agent está em execução. O problema pode estar relacionado com o token, a lista de utilizadores autorizados, o gateway de mensagens, o acesso à rede ou as permissões do grupo.

Verifique pela seguinte ordem:

  1. Confirme que o token do bot está correto.
  2. Confirme que o ID de utilizador está autorizado.
  3. Confirme que o gateway foi reiniciado após a configuração.
  4. Confirme que o contentor consegue aceder à API de mensagens.
  5. Verifique os registos da aplicação para detetar erros de token, rede ou permissões.
  6. Teste o chat privado antes de investigar problemas no chat de grupo.

Normalmente, é mais simples testar o chat privado do que o chat de grupo, porque as permissões do grupo acrescentam variáveis.

As definições do fornecedor do modelo estão incorretas

Se o bot de mensagens responder, mas as respostas do modelo falharem, o problema pode estar no fornecedor do modelo. Verifique o URL base, a chave API, o nome do modelo e a compatibilidade do endpoint.

No caso de endpoints de modelos locais, verifique também se o serviço do modelo está em execução e se está acessível a partir do contentor. Um serviço acessível a partir do anfitrião pode não estar acessível a partir do contentor se a rede for diferente.

Mantenha a resolução de problemas do fornecedor separada da resolução de problemas das mensagens. Assim, evita alterar o bot quando o verdadeiro problema está na ligação ao modelo.

O contentor não consegue aceder à API de mensagens

Se o contentor não conseguir aceder à API de mensagens, o gateway não poderá receber nem enviar mensagens corretamente. Isto pode dever-se a problemas de DNS, regras de firewall, definições de proxy ou falta de acesso à Internet para tráfego de saída.

Verifique se o anfitrião tem acesso à Internet e se o contentor também tem. Nem sempre é a mesma coisa.

Se o servidor doméstico utilizar uma VPN, um proxy ou uma rede restrita, confirme que o contentor pode efetuar pedidos HTTPS de saída.

As permissões do chat de grupo ou o modo de privacidade impedem as respostas

O comportamento no chat de grupo é mais complexo do que no chat privado. Um bot pode responder no chat privado, mas não num grupo, porque não consegue ver a mensagem, não tem as permissões adequadas ou é afetado pelas definições de privacidade.

Comece por testar o chat privado. Depois, teste o chat de grupo separadamente.

Para utilizar o bot em grupos, verifique se é necessário mencioná-lo diretamente, se precisa de permissões de administrador e se as respetivas definições de privacidade lhe permitem receber as mensagens necessárias.

Como verificar se o Hermes Agent está a funcionar

A configuração não está concluída só porque a instalação terminou. Está concluída quando o modelo, o gateway, as permissões, o painel de controlo, os registos e o comportamento de reconfiguração passam nas verificações básicas.

O assistente de configuração é concluído sem erros

O assistente de configuração deve ser concluído sem erros de comandos em falta, erros do fornecedor ou erros de permissões. Se falhar, identifique a camada que falhou antes de tentar novamente.

Um erro no assistente de configuração costuma pertencer a uma destas categorias:

  • credenciais do fornecedor do modelo;
  • ambiente de execução;
  • permissões do contentor;
  • comando da aplicação em falta;
  • acesso à rede;
  • configuração do gateway.

Use essa categoria para decidir qual deve ser a próxima verificação.

O bot de mensagens responde a uma mensagem de teste privada

A forma mais simples de testar as mensagens é enviar uma mensagem de teste privada. Envie uma mensagem básica e confirme que o bot responde.

Se o chat privado funcionar, é provável que o token, a lista de permissões, o gateway e a ligação ao modelo estejam quase corretamente configurados. Se o chat de grupo continuar a falhar, concentre-se nas permissões do grupo e nas definições de privacidade, em vez de reinstalar a aplicação.

A conversa privada deve ser o primeiro teste de mensagens bem-sucedido.

O painel de controlo indica que o agente está em execução

O painel de controlo deve indicar que o agente ou o gateway está em execução, consoante o sistema. O estado no painel de controlo é útil porque oferece uma perspetiva do lado do servidor, em vez de depender apenas da aplicação de mensagens.

Se o painel de controlo apresentar o estado parado ou não saudável, verifique os registos antes de alterar os tokens ou as definições do modelo.

O estado no painel de controlo e a resposta do bot devem coincidir. Se um funcionar e o outro falhar, a diferença indica a camada com problemas.

Os registos não apresentam erros de permissões ou de rede

Os registos não devem apresentar repetidamente erros de acesso negado, token inválido, fornecedor inacessível, falha do gateway ou tempo limite da rede.

Use os registos para determinar o passo seguinte. Um erro de permissão aponta para a propriedade dos ficheiros ou para o utilizador do contentor. Um erro de rede aponta para a acessibilidade da API. Um erro de token aponta para a configuração das credenciais.

Evite corrigir todas as camadas ao mesmo tempo. Altere uma variável, reinicie se necessário e volte a testar.

A reconfiguração funciona após o reinício

Uma configuração duradoura deve manter-se após um reinício ou uma reconfiguração. Depois de alterar as definições do modelo ou do gateway, reinicie o serviço ou gateway necessário e confirme que as novas definições continuam a ser aplicadas.

Se as definições desaparecerem após o reinício, verifique onde a configuração está armazenada e se o caminho dos dados da aplicação é persistente.

É aqui que o conhecimento dos caminhos do anfitrião e do contentor, bem como dos volumes montados, se torna prático.

Como funciona num ambiente real de servidor doméstico

Num ambiente real de servidor doméstico, o modelo geral de configuração mantém-se: confirmar a camada de execução, verificar os caminhos de dados, proteger as credenciais, configurar o acesso ao gateway e validar através dos registos e do estado no painel de controlo.

Um guia de configuração específico para o dispositivo pode então indicar o caminho exato dos comandos. Por exemplo, o fluxo de configuração do Hermes Agent no ZimaOS explica um processo de configuração do Hermes Agent que inclui a configuração do fornecedor do modelo, a ligação de um bot do Telegram, o acesso ao contentor do Hermes como utilizador da aplicação, a ativação do ambiente da aplicação, a execução dos comandos de configuração, a verificação do estado no painel de controlo e a resolução de problemas de permissões ou de erros nas respostas do bot.

Para os utilizadores que executam aplicações alojadas localmente, gateways de mensagens e fluxos de trabalho leves de agentes num servidor compacto sempre ligado, servidor de IA doméstico ZimaBoard 2 adequa-se a ambientes em que é necessário compreender em conjunto as aplicações Docker, o acesso ao terminal, os serviços locais e os caminhos de dados específicos das aplicações. Não é a única forma de alojar um agente, mas é um exemplo relevante do tipo de fluxo de trabalho de servidor doméstico descrito neste artigo.

A principal lição é aplicável a qualquer configuração: não memorize apenas um comando de configuração. Perceba em que camada está a trabalhar e como validar o resultado.

Perguntas frequentes

Posso configurar o Hermes Agent apenas através de um painel Web?

Em muitos casos, um painel Web pode ser suficiente para a configuração básica, especialmente se disponibilizar definições de modelos e do gateway. A configuração no terminal do contentor torna-se necessária quando o painel não disponibiliza uma opção necessária ou quando a resolução de problemas exige comandos ao nível da aplicação. Comece pela WebUI sempre que possível e use o terminal do contentor apenas quando o processo de configuração o exigir.

Porque tenho de entrar no contentor em vez de usar a shell do anfitrião?

Alguns comandos da aplicação só existem dentro do contentor, pois é aí que se encontram o ambiente de execução e as dependências da aplicação. Executar o mesmo comando no anfitrião pode falhar ou afetar o ambiente errado. Entrar no contentor com o utilizador correto ajuda a garantir que as alterações de configuração se aplicam à própria aplicação.

Qual é a diferença entre os dados do anfitrião e os dados da aplicação do contentor?

Os dados do anfitrião encontram-se no sistema de ficheiros do servidor doméstico. Os dados da aplicação do contentor podem estar dentro do contentor, num volume gerido pelo Docker ou numa pasta do anfitrião montada no contentor. O mesmo caminho de pasta visível pode não corresponder à mesma localização nas camadas do anfitrião e do contentor, por isso, confirme os pontos de montagem e as localizações dos dados da aplicação antes de editar ficheiros.

Porque é que o Hermes Agent apresenta um erro de permissão?

Um erro de permissão significa muitas vezes que o utilizador da aplicação não consegue ler ou escrever num ficheiro ou pasta necessário. Isto pode acontecer se os ficheiros tiverem sido criados pelo root, se uma pasta montada tiver o proprietário errado ou se o contentor estiver a ser executado como um utilizador diferente do esperado. Verifique a camada de execução, o utilizador do contentor, a localização dos dados da aplicação e a propriedade dos ficheiros antes de alterar permissões de forma abrangente.

Porque é que o meu bot do Telegram não responde?

Um bot do Telegram pode não responder porque o token está incorreto, o ID do utilizador não está autorizado, o gateway não foi reiniciado, o contentor não consegue aceder à API do Telegram ou as permissões do chat de grupo bloqueiam a mensagem. Teste primeiro numa conversa privada, pois isso elimina muitas variáveis relacionadas com grupos. Depois, verifique os registos para detetar erros de token, rede ou permissões.

Devo expor o Hermes Agent diretamente à Internet?

A exposição pública direta não é, normalmente, a melhor opção por defeito para um agente autoalojado. Um bot de mensagens ou gateway pode ligar-se a ferramentas, ao acesso a modelos e, possivelmente, a ações de execução locais, pelo que o acesso deve ser restringido. Utilize padrões de acesso privado, credenciais fortes, listas de permissões e permissões restritivas antes de considerar qualquer configuração acessível ao público.

Assistência e dicas

Mais para ler

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.