Instalação do Sherpa AI Server#

Antes de começar#

É necessário um servidor com Docker e Docker Compose v2, espaço suficiente para arquivos, modelos e contêineres, além de acesso à distribuição ou um conjunto completo de arquivos transferidos antecipadamente. Para um LLM local, escolha um servidor com GPU ou a instalação somente em CPU. Prepare o nome de domínio, o endereço IP e os certificados SSL. Se o LLM estiver em outro computador, consulte a conexão a um servidor LLM separado.

Baixe o arquivo client-files da versão publicada desejada e seu arquivo de checksum. É necessário verificar o SHA-256 seguindo o guia de download da distribuição. Todos os arquivos de imagens Docker devem ser da mesma versão. O instalador confere a versão, os checksums e as tags das imagens antes de iniciar os contêineres. Não selecione arquivos independentemente por latest nem execute load_all_docker_images.sh: esse script auxiliar antigo seleciona o arquivo mais recente de cada imagem separadamente.

Se o servidor não puder acessar o servidor de downloads, transfira client-files, os arquivos de imagens necessários e os arquivos .SHA256SUM correspondentes para um mesmo diretório. O guia de download explica o conjunto necessário e como verificar o espaço disponível em disco.

Instalação pelo script#

O exemplo usa a versão 2.5.1. É necessário informar o nome do arquivo já verificado e execute os comandos no diretório de instalação:

CLIENT_ARCHIVE=docker_aiserver_client_files_2.5.1.tgz
tar -xzf "$CLIENT_ARCHIVE"
chmod +x sh_scripts/*.sh
sudo ./sh_scripts/install.sh

O instalador executa as seguintes etapas:

1. Verifica o Docker, o Docker Compose v2, o arquivo .env e a versão APP_VERSION incluída no pacote.
2. Oferece o modo GPU (vLLM), CPU (llama.cpp) ou LLM e Embedding externos, os serviços opcionais Whisper e BGE Reranker e um modelo LLM disponível. Whisper e reranker exigem GPU. Se escolher vários modelos, considere a memória de vídeo disponível.
3. Encontra os arquivos de imagens Docker necessários para APP_VERSION. Havendo conexão, baixa os arquivos ausentes, verifica SHA-256 e as tags do manifesto Docker, carrega as imagens e extrai os modelos escolhidos. Sem acesso, informa quais arquivos estão faltando.
4. Faz um backup de .env e solicita HOST_IP, NGINX_DOMAIN_NAME, MAX_TOKENS_MESSAGE, a senha do PostgreSQL, o modelo e outras configurações. Substitua a senha padrão por uma senha única e forte. Não guarde senhas em anotações desprotegidas. O instalador restringe o acesso a .env.
5. Oferece HTTPS para o servidor principal e a conexão com o servidor de embeddings. Prepare certificados e chaves confiáveis. Certificados autoassinados podem ser usados em um servidor de testes. Consulte o guia de SSL para detalhes.
6. Mostra as configurações finais e o plano de inicialização do Docker Compose. Confira o modo, o modelo, o domínio e os perfis. Depois confirme a inicialização.

O instalador salva os perfis selecionados em COMPOSE_PROFILES. Se a instalação for interrompida, resolva a causa informada e execute install.sh novamente. Não misture arquivos de versões diferentes para contornar uma verificação malsucedida.

LLM e Embedding externos#

Use esta opção quando os dois serviços já estiverem em outro servidor. O servidor principal precisa de acesso de rede às APIs deles. O LLM deve fornecer uma API compatível, e o Embedding deve fornecer a API do Sherpa Embedding. Prepare certificados confiáveis para HTTPS. Se o Embedding exigir um token, obtenha-o com o administrador do serviço antes da instalação.

1. Execute sudo ./sh_scripts/install.sh no diretório de instalação e escolha [3] LLM e Embedding externos.
2. Informe o endereço do LLM, por exemplo http://llm.example.local:8000, o endereço do Embedding, por exemplo https://embed.example.local:443, e o nome do modelo retornado pela API do LLM. Informe o token do Embedding se a autenticação for necessária. Não inclua /v1 nos endereços.
3. Na etapa dos arquivos, forneça apenas as imagens solicitadas pelo instalador. Imagens e arquivos de modelos locais de LLM e Embedding não são necessários neste modo.
4. Confira o resumo e a lista de serviços. .env deve conter COMPOSE_PROFILES=external. O comando docker compose --profile external config --services não deve listar aiserver-embed, aiserver-llm-server nem aiserver-llm-server-cpu.
5. Após a inicialização, confira docker compose ps, abra o Chat e envie uma solicitação de teste. Confira a busca de documentos se for utilizada. A resposta e os resultados da busca confirmam a conexão com os serviços externos.

O instalador salva as URLs, os hosts, as portas, o esquema da LLM e o nome do modelo em .env. Se o endereço da LLM mudar, atualize a URL, o host, a porta e o esquema em .env. Depois, abra a instância correspondente em Modelos e atualize os campos Host, Porta e Esquema: o Chat usa os parâmetros salvos da instância. Se o endereço ou token do Embedding mudar, atualize também .env. Após editar .env, execute docker compose up -d --force-recreate aiserver: um restart comum não recarrega as variáveis de ambiente. Se as solicitações falharem, confira o acesso de rede a partir do servidor principal e os logs de aiserver. O atualizador mantém o modo externo e não exige imagens nem modelos locais desses serviços.

Serviços e perfis#

Os serviços principais iniciam sem um perfil adicional:

Os perfis adicionais selecionam o LLM e os serviços de processamento:

Ao administrar os perfis manualmente, informe apenas os serviços escolhidos. Por exemplo, GPU com Whisper:

docker compose --profile embed --profile gpu --profile whisper up -d

Para CPU sem GPU:

docker compose --profile embed --profile cpu up -d

Verificação da instalação#

Para diagnosticar a instalação, o administrador precisa ter acesso ao Docker Compose no servidor. No diretório que contém .env e docker-compose.yml, execute:

sudo ./sh_scripts/diagnostics.sh

O script verifica os contêineres principais, o LLM local, Whisper e BGE Reranker quando os perfis estão ativos, PostgreSQL, o espaço livre e a resposta da API. Se tudo estiver correto, ele mostra Диагностика завершена без замечаний e retorna o código 0. Se houver erro, ele identifica o componente afetado e retorna o código 1. Para obter detalhes, execute o comando docker compose logs indicado na mensagem.

Para que o assistente de instalação ofereça o diagnóstico após a inicialização bem-sucedida, inicie-o com SHERPA_DIAGNOSTICS_OFFER=true. Exemplo: sudo env SHERPA_DIAGNOSTICS_OFFER=true ./sh_scripts/install.sh. Por padrão, essa pergunta não aparece. O diagnóstico não altera os dados da instalação.

É necessário verificar o estado dos contêineres e os logs. Os serviços em execução devem estar no estado Up:

docker compose ps
docker compose logs --tail=100 aiserver

É necessário abrir https://<seu-dominio> no navegador e confira se consegue entrar. Para verificar a resposta do servidor web, substitua o domínio de exemplo pelo seu:

curl -I https://aiserver.example.com

É esperada uma resposta HTTP bem-sucedida ou um redirecionamento para a página de login. Confira se o navegador aceita o certificado sem aviso. Se usar um LLM local, envie uma mensagem de teste no chat e confirme que o modelo responde. Se houver problemas, consulte os logs do serviço correspondente:

docker compose logs --tail=100 aiserver-llm-server
docker compose logs --tail=100 aiserver-embed

No modo CPU, use aiserver-llm-server-cpu em vez de aiserver-llm-server. Se um contêiner não iniciar, verifique o espaço em disco e os logs. Para erros de login ou banco de dados, verifique .env. Para HTTPS, confira os certificados e o domínio. Para GPU, verifique o driver, a disponibilidade da placa e a VRAM.

Manutenção#

Execute os comandos no diretório que contém docker-compose.yml e .env:

docker compose ps
docker compose logs -f aiserver
docker compose restart aiserver
docker stats

Para GPU, use também nvidia-smi. docker compose down para e remove os contêineres; não adicione -v se quiser preservar os dados dos volumes Docker. Para atualizar, use o guia de atualização. Antes de atualizar de 2.5.0 para 2.5.1, conclua a preparação dos índices. Se a versão atual for anterior a 2.5.0, combine o caminho de atualização com a equipe de suporte.