Atualizações do Sherpa AI Server#

Antes de atualizar, leia as notas de todas as versões, desde a instalada até a de destino, e prepare um backup dos dados. As notas podem conter etapas obrigatórias para a atualização. Notas da última versão publicada: versão 2.5.1. Os serviços serão interrompidos temporariamente durante a atualização.

Ao atualizar da versão 2.5.0 para a 2.5.1, primeiro prepare os índices do banco de dados preenchido. Execute a atualização somente depois de verificar os índices com sucesso. Caso contrário, a migração poderá falhar.

Atualização pelo script#

Na raiz da instalação existente do Sherpa AI Server, execute:

sudo ./sh_scripts/update.sh

O script determina a versão de destino pelo arquivo client-files e seleciona apenas os arquivos dessa versão. Antes de interromper os serviços, ele verifica as somas SHA-256 disponíveis e os manifests dos arquivos Docker, o espaço livre e as imagens necessárias. Em seguida, faz backups da configuração e dos dados, atualiza arquivos e imagens, executa as migrações e verifica a inicialização. Confira a versão e a lista de ações exibidas antes de confirmar.

Quando um componente não é publicado para a versão de destino, o script preserva a imagem atual :latest e verifica, antes de interromper os serviços, se ela existe e corresponde à imagem do contêiner em execução. Essa é uma versão parcial prevista. O arquivo client-files da versão de destino é sempre obrigatório. Se um arquivo publicado não puder ser baixado ou faltar o arquivo .SHA256SUM obrigatório de um artefato disponível online, a atualização para.

Para atualizar sem acesso ao servidor, copie docker_aiserver_client_files_<versão>.tgz e os arquivos dos componentes efetivamente publicados para a mesma versão à raiz da instalação. Inclua os respectivos arquivos .SHA256SUM quando fornecidos. Antes de executar o script, confira o conjunto com a lista de componentes publicados: em modo offline, ele não distingue um componente omitido intencionalmente de um arquivo esquecido na transferência. Obtenha qualquer arquivo publicado que esteja faltando antes da atualização. Se um arquivo offline não tiver .SHA256SUM, o script verifica sua estrutura, mas não pode conferir o SHA-256. Toda soma de verificação fornecida deve coincidir. Não misture versões nem escolha imagens em endpoints /latest independentes.

Mudar para LLM e Embedding externos durante uma atualização#

Em um servidor com LLM e Embedding locais, o script oferece a mudança para serviços externos. Pressione Enter para manter o modo atual ou digite y para mudar. Antes de interromper os contêineres, informe as URLs dos dois serviços no formato http(s)://host:port, o nome do modelo LLM e, se necessário, o token de Embedding. Digite 0 para cancelar a entrada; as configurações da instalação ativa permanecerão inalteradas.

Na mudança, o script salva os endereços e parâmetros em .env, interrompe os contêineres locais anteriores e não solicita as imagens nem os arquivos de modelos deles. Os perfis opcionais de Whisper e BGE Reranker são preservados. Após a atualização, confira se COMPOSE_PROFILES em .env contém external e o estado dos contêineres com docker compose --profile external ps.

Na seção Modelos, abra a instância LLM utilizada. Informe os valores do serviço externo nos campos “Host”, “Porta”, “Esquema” e “Caminho do modelo” e salve a instância. O Chat usa as configurações salvas da instância, portanto, alterar apenas .env não é suficiente. Confira uma resposta no Chat e indexe um documento de teste. Se a conexão falhar, verifique o acesso aos endereços externos a partir do servidor principal e consulte os logs do aiserver.

Retenção de backups#

Por padrão, o script mantém todos os backups. Para manter os dois conjuntos completos mais recentes após uma atualização bem-sucedida, o administrador deve executar:

sudo env SHERPA_UPDATE_BACKUPS_KEEP=2 ./sh_scripts/update.sh

Um conjunto completo inclui cópias de .env, docker-compose.yml, dos arquivos do cliente, um dump do PostgreSQL e os arquivos dos volumes Docker. Se o dump ou os arquivos dos volumes da atualização atual estiverem ausentes, os conjuntos antigos não serão excluídos. O valor deve ser um número inteiro positivo. A rotação também inclui os diretórios de backup dos modelos. Conjuntos criados antes da inclusão da marca de cópia completa permanecem intactos. O valor 0 ou a ausência da variável desativa a rotação.

Verificação do resultado#

Após a atualização, o administrador pode executar o diagnóstico completo no diretório da instalação:

sudo ./sh_scripts/diagnostics.sh

O código de saída 0 e a mensagem Диагностика завершена без замечаний indicam que as verificações dos contêineres, do PostgreSQL, do espaço livre e da resposta da API passaram. Se o código for 1, leia o componente afetado na mensagem e consulte os logs indicados. Para receber uma pergunta sobre o diagnóstico após uma atualização bem-sucedida, inicie o assistente com SHERPA_DIAGNOSTICS_OFFER=true. Por padrão, a pergunta fica desativada.

Ao terminar, confirme que o script informou migrações e verificações de serviços bem-sucedidas. É necessário verificar também os contêineres e o log da aplicação:

docker compose ps
docker compose logs --tail 100 aiserver

Se a atualização falhar, guarde a saída e use as instruções de recuperação e os backups indicados pelo script. Não substitua arquivos nem repita migrações sem investigar a causa. Depois de alterar .env manualmente, aplique as configurações com docker compose up -d --force-recreate; docker compose restart não recarrega as variáveis de ambiente.