# Instalação do Sherpa AI Server
## Instalação do Sherpa AI Server
#### Descompactação dos arquivos do cliente
Descompacte o arquivo com os arquivos do cliente e prepare o sistema para a instalação.
**Descompactação do arquivo com os arquivos do cliente**
```bash
# Encontre e descompacte o arquivo (a versão mais recente é escolhida automaticamente)
tar -xvzf "$(ls client_files_*.tgz | sort -V | tail -n 1)"
```
💡 Comentários sobre a descompactação do arquivo
**tar -xvzf "$(ls client\_files\_\*.tgz | sort -V | tail -n 1)"** - descompacta o arquivo com os arquivos do cliente
* `tar -xvzf` - descompacta o arquivo com saída detalhada
* `ls client_files_*.tgz` - encontra todos os arquivos de arquivo
* `sort -V` - ordena as versões de forma natural (1.0 < 1.1 < 1.10)
* `tail -n 1` - seleciona o arquivo mais recente
**Resultado esperado:** Um diretório `sh_scripts/` será criado com scripts executáveis e outros arquivos necessários.
**Preparação dos scripts para execução**
```bash
# Vá para o diretório com os scripts
cd sh_scripts/
# Torne todos os scripts executáveis
chmod +x *.sh
# Volte para o diretório raiz do projeto
cd ..
```
💡 Comentários sobre a preparação dos scripts
**cd sh\_scripts/** - muda para o diretório com os scripts de instalação
\**chmod +x .sh* - define permissões de execução para todos os scripts shell
* `chmod +x` - adiciona permissão de execução
* `*.sh` - todos os arquivos com a extensão .sh
**cd ..** - retorna ao diretório raiz do projeto
**O que esses comandos fazem:**
* `chmod +x *.sh` - define permissões de execução para todos os scripts shell
* Isso é necessário para executar os scripts nas próximas etapas da instalação
**Estrutura do arquivo descompactado:**
Após a descompactação, você deve ver os seguintes arquivos e diretórios:
* `sh_scripts/` - diretório com scripts de instalação
* `download_all_latest_docker_images.sh` - script para baixar imagens Docker
* `load_all_docker_images.sh` - script para carregar imagens no Docker
* `extract_models.sh` - script para descompactar modelos de IA
* `extract_vllm.sh` - script para descompactar modelos LLM
* `docker-compose.yml` - configuração do Docker Compose para instalação do cliente
* `.env` - arquivo com variáveis de ambiente para configuração do sistema
**Verificação do sucesso da descompactação:**
```bash
# Verifique o conteúdo do diretório
ls -la
# Certifique-se de que os scripts são executáveis
ls -la sh_scripts/*.sh
```
💡 Comentários sobre a verificação da descompactação
**ls -la** - mostra o conteúdo detalhado do diretório
* `-l` - formato longo
* `-a` - mostra arquivos ocultos
**ls -la sh\_scripts/\*.sh** - verifica os scripts no diretório sh\_scripts
#### Execução dos scripts para descompactação
**Carregamento das imagens Docker**
```bash
# Execute o script de carregamento das imagens Docker
sudo ./sh_scripts/load_all_docker_images.sh
```
💡 Comentários sobre o carregamento das imagens Docker
**sudo ./sh\_scripts/load\_all\_docker\_images.sh** - executa o script de carregamento das imagens Docker
**O que o script faz:**
1. Carrega todas as imagens Docker dos arquivos .tar.gz baixados
2. Importa as imagens para o registro local do Docker
3. Verifica o sucesso do carregamento
**Descompactação dos modelos de IA**
```bash
# Execute o script de descompactação dos modelos principais
sudo ./sh_scripts/extract_models.sh
```
💡 Comentários sobre a descompactação dos modelos principais
**sudo ./sh\_scripts/extract\_models.sh** - executa o script de descompactação dos modelos
**O que o script faz:**
1. Descompacta o modelo Whisper para reconhecimento de fala
2. Descompacta o modelo BGE Reranker para melhorar a busca
3. Descompacta modelos para geração de embeddings
4. Cria os diretórios necessários
5. Verifica o sucesso da descompactação
```bash
# Execute o script de descompactação dos modelos LLM
sudo ./sh_scripts/extract_vllm.sh
```
💡 Comentários sobre a descompactação do modelo LLM
**sudo ./sh\_scripts/extract\_vllm.sh** - executa o script de descompactação do modelo LLM
**O que o script faz:**
1. Descompacta os modelos
2. Coloca os arquivos diretamente no diretório dos modelos
3. Verifica o conteúdo após a descompactação
**Estrutura dos diretórios após a descompactação (exemplo):**
```
./whisper/
└── models/
├── base.pt
└── ...
./bge_reranker/
└── models/
└── bge-reranker-large/
├── config.json
├── model.bin
└── ...
./embed-server/app/
└── model-store/
└── sentence-transformers/
└── paraphrase-multilingual-MiniLM-L12-v2/
├── config.json
├── pytorch_model.bin
└── ...
./llm-server/models/
├── meta-llama/
│ └── Meta-Llama-3-8B-Instruct/
│ ├── config.json
│ ├── model-00001-of-00004.safetensors
│ ├── model-00002-of-00004.safetensors
│ └── ...
└── tokenizer.json
```
#### Configuração da configuração do sistema
O Sherpa AI Server requer a configuração das variáveis de ambiente no arquivo `.env` antes de ser iniciado.
**Abertura do arquivo de configuração**
```bash
# Abra o arquivo .env em um editor de texto
nano ./.env
```
Ou use qualquer editor de texto:
```bash
# Vim
vim ./.env
# VS Code (se instalado)
code ./.env
```
💡 Comentários sobre a abertura do arquivo de configuração
**nano ./.env** - abre o arquivo .env no editor nano
* `nano` - editor de texto simples
* `./.env` - caminho para o arquivo de configuração
**vim .env** - abre o arquivo no editor Vim **code ./.env** - abre o arquivo no VS Code (se instalado)
**Recomendação:** Use o editor com o qual você está familiarizado
**Principais parâmetros de configuração**
**Configurações do servidor principal (aiserver):**
```bash
# Endereço IP do servidor (mude para seu IP estático)
HOST_IP=127.0.0.1
# Nome de domínio (mude para seu domínio)
NGINX_DOMAIN_NAME=aiserver.sherparpa.ru
# Comprimento máximo das mensagens (em tokens)
MAX_TOKENS_MESSAGE=32000
```
**Configurações do banco de dados PostgreSQL:**
```bash
# Senha do PostgreSQL (DEFINE SUA SENHA SEGURA)
POSTGRES_PASSWORD=password
```
**Configurações do servidor LLM:**
**Escolha do modelo de IA:** Escolha um dos modelos disponíveis descomentando a linha desejada e comentando as outras:
```bash
# === ESCOLHA DO MODELO DE IA ===
# Descomente APENAS UM dos modelos abaixo:
# Modelo Llama 3.1 (recomendado para uso geral)
LLM_COMPLETION_MODEL_NAME=/model-store/meta-llama/Meta-Llama-3-8B-Instruct
LLM_CHAT_TEMPLATE=/model-templates/tool_chat_template_llama3.1_json.jinja
LLM_TOOL_CALL_PARSER=llama3_json
# Modelo Qwen (modelo alternativo)
# LLM_COMPLETION_MODEL_NAME=/model-store/Qwen3-30B-A3B-AWQ
# LLM_CHAT_TEMPLATE=/model-templates/tool_chat_template_qwen3coder.jinja
# LLM_TOOL_CALL_PARSER=hermes
# Modelo OCR (especializado em reconhecimento de texto)
# LLM_COMPLETION_MODEL_NAME=/model-store/olmOCR-2-7B-1025-FP8
# === FIM DA ESCOLHA DO MODELO ===
```
**Segurança e senhas**
{% hint style="danger" %}
**Crucial:** Altere todas as senhas padrão para senhas seguras:
{% endhint %}
```bash
# Geração de senhas seguras
openssl rand -base64 32
# Ou use pwgen, se instalado
pwgen -s 32 1
```
**Recomendações para senhas:**
* Mínimo de 32 caracteres
* Use letras, números e caracteres especiais
* Não use palavras do dicionário
* Armazene as senhas em um local seguro
**Verificação da configuração**
Após editar o arquivo `.env`, verifique a correção das configurações:
```bash
# Verifique a sintaxe do arquivo
cat .env | grep -v '^#' | grep '=' | wc -l
# Verifique a presença das variáveis obrigatórias
grep -E "(POSTGRES_PASSWORD|HOST_IP|NGINX_DOMAIN_NAME)" .env
```
💡 Comentários sobre a verificação da configuração
**cat .env | grep -v '^#' | grep '=' | wc -l** - conta o número de variáveis de ambiente
* `cat .env` - exibe o conteúdo do arquivo
* `grep -v '^#'` - exclui comentários (linhas que começam com #)
* `grep '='` - mantém apenas linhas com variáveis
* `wc -l` - conta o número de linhas
**grep -E "(POSTGRES\_PASSWORD|HOST\_IP|NGINX\_DOMAIN\_NAME)" .env** - verifica a presença das variáveis obrigatórias
* `-E` - expressões regulares estendidas\* Enumera variáveis obrigatórias através de |
**Criação de backup**
```bash
# Crie um backup das configurações
cp .env .env.backup
```
💡 Comentários sobre a criação de backup
**cp .env .env.backup** - cria um backup do arquivo de configuração
* `cp` - copy (cópia)
* `.env` - arquivo original
* `.env.backup` - arquivo de backup
{% hint style="warning" %}
**Importante:** Sem a configuração correta do arquivo `.env`, o sistema não será iniciado corretamente.
{% endhint %}
**Cópia de certificados SSL**
Para garantir uma conexão HTTPS segura, é necessário copiar os certificados SSL para o diretório `./oais/backend/config/certs/`:
```bash
# Crie o diretório para os certificados (se não existir)
mkdir -p ./oais/backend/config/certs/
# Copie seus certificados SSL
# Substitua pelos caminhos dos seus certificados reais
cp /path/to/your/certificate.crt ./oais/backend/config/certs/aiserver.crt
cp /path/to/your/private.key ./oais/backend/config/certs/aiserver.key
# Ou se você tiver um certificado wildcard:
cp /path/to/your/wildcard.crt ./oais/backend/config/certs/aiserver.crt
cp /path/to/your/wildcard.key ./oais/backend/config/certs/aiserver.key
```
💡 Comentários sobre a cópia de certificados SSL
**mkdir -p ./oais/backend/config/certs/** - cria o diretório para os certificados
* `-p` - cria diretórios pai se não existirem
**cp /path/to/your/certificate.crt ./oais/backend/config/certs/aiserver.crt** - copia o certificado **cp /path/to/your/private.key ./oais/backend/config/certs/aiserver.key** - copia a chave privada
**Requisitos para os certificados:**
* O certificado deve estar no formato `.crt` ou `.pem`
* A chave privada deve estar no formato `.key`
* Os nomes dos arquivos devem ser `aiserver.crt` e `aiserver.key`
{% hint style="warning" %}
**Importante:** Certifique-se de que os certificados tenham as permissões corretas:
{% endhint %}
```bash
# Defina as permissões corretas para os certificados
chmod 644 ./oais/backend/config/certs/*.crt
chmod 600 ./oais/backend/config/certs/*.key
```
{% hint style="info" %}
**ATENÇÃO**: obtenha os certificados com o administrador da rede ou no seu centro corporativo de certificação; na ausência desses pontos, você pode usar o artigo sobre como obter certificados.
{% endhint %}
#### Início do sistema
Após concluir todas as etapas preparatórias, você pode iniciar o Sherpa AI Server. O sistema funcionará em segundo plano como um conjunto de contêineres Docker.
{% hint style="warning" %}
**Importante:** O cliente recebe o arquivo `docker-compose.yml`, que contém a configuração de todos os serviços. Certifique-se de usar exatamente este arquivo para iniciar o sistema.
{% endhint %}
**Início de todos os serviços**
```bash
# Inicie os serviços básicos em segundo plano
docker compose up -d
```
💡 Comentários sobre o início dos serviços
**docker compose up -d** - inicia todos os serviços em segundo plano
* `docker compose` - usa o Docker Compose para gerenciar contêineres
* `up` - cria e inicia todos os serviços do docker-compose.yml
* `-d` - inicia os contêineres em modo detached (em segundo plano)
**Tempo de inicialização esperado:** 2-5 minutos, dependendo do desempenho do sistema.
**Início de serviços com funcionalidades adicionais**
No arquivo `docker-compose.yml`, alguns serviços têm profiles e são iniciados apenas quando explicitamente especificados:
```bash
# Início com o serviço de reconhecimento de fala Whisper
docker compose --profile whisper up -d
# Início com o serviço de reclassificação BGE Reranker
docker compose --profile reranker up -d
# Início de todos os serviços (Whisper + BGE Reranker + básicos)
docker compose --profile full up -d
```
{% hint style="warning" %}
**Importante:** Considere a quantidade de memória de vídeo (VRAM) disponível em seu sistema. Se você tiver uma quantidade limitada de VRAM, inicie apenas os serviços necessários com os profiles correspondentes. Com falta de memória, o sistema pode funcionar de forma instável ou não iniciar.
{% endhint %}
**Profiles disponíveis:**
* `whisper` - inclui o serviço de reconhecimento de fala (porta 3005)
* `reranker` - inclui o serviço de reclassificação de resultados de busca (porta 8001)
* `full` - inclui todos os serviços adicionais (Whisper + BGE Reranker)
{% hint style="warning" %}
**Importante:** Sem a especificação de profiles, os serviços Whisper e BGE Reranker não serão iniciados. Escolha o profile necessário de acordo com suas necessidades funcionais.
{% endhint %}
**Verificação do status dos contêineres**
```bash
# Verifique o status de todos os contêineres em execução
docker compose ps
# Ou use docker ps para informações detalhadas
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```
💡 Comentários sobre a verificação de status
**docker compose ps** - mostra o status de todos os contêineres Docker Compose
* Exibe nomes, status e portas dos contêineres
**docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"** - mostra informações detalhadas sobre os contêineres
* `--format` - define um formato de saída personalizado
* `table` - formato de tabela
* `{{.Names}}` - nomes dos contêineres
* `{{.Status}}` - status dos contêineres
* `{{.Ports}}` - portas abertas
**Saída esperada (depende do profile escolhido):**
**Serviços básicos (sem profiles):**
```
NAME STATUS PORTS
aiserver Up 2 minutes 0.0.0.0:443->443/tcp, 0.0.0.0:80->80/tcp, 0.0.0.0:4500->4500/tcp
aiserver-db Up 2 minutes 0.0.0.0:3306->3306/tcp
aiserver-pg Up 2 minutes 0.0.0.0:5432->5432/tcp
aiserver-embed Up 2 minutes 0.0.0.0:3004->443/tcp
aiserver-llm-server Up 2 minutes 0.0.0.0:3003->8000/tcp
aiserver-code_interpreter Up 2 minutes 0.0.0.0:3001->3001/tcp
```
**Com o profile `whisper` (adicionado):**
```
aiserver-whisper Up About a minute 0.0.0.0:3005->8000/tcp
```
**Com o profile `reranker` (adicionado):**
```
aiserver-bge_reranker Up About a minute 0.0.0.0:8001->8000/tcp
```
**Com o profile `full` (ambos adicionados):**
```
aiserver-whisper Up About a minute 0.0.0.0:3005->8000/tcp
aiserver-bge_reranker Up About a minute 0.0.0.0:8001->8000/tcp
```
Todos os contêineres em execução devem ter o status "Up" e mostrar as portas abertas.
**Verificação dos logs dos contêineres**
```bash
# Veja os logs do servidor principal
docker compose logs aiserver
# Veja os logs de todos os serviços
docker compose logs
# Monitoramento dos logs em tempo real
docker compose logs -f aiserver
```
💡 Comentários sobre a verificação dos logs
**docker compose logs aiserver** - mostra os logs de um serviço específico
* `aiserver` - nome do serviço
**docker compose logs** - mostra os logs de todos os serviços
**docker compose logs -f aiserver** - acompanha os logs em tempo real
* `-f` - follow (acompanhar novas mensagens)
**Verificação de erros:**
* Procure mensagens de erro de conexão com bancos de dados
* Verifique o carregamento de modelos de IA
* Certifique-se da validade dos certificados SSL
**Verificação da disponibilidade dos serviços**
**Verificação da interface web principal:**
```bash
# Verifique a disponibilidade HTTP (substitua pelo seu domínio)
curl -I http://aiserver.sherparpa.ru
# Verifique a disponibilidade HTTPS (substitua pelo seu domínio)
curl -I https://aiserver.sherparpa.ru
# Resposta esperada: HTTP/2 200 ou redirecionamento para /login
```
💡 Comentários sobre a verificação da interface web
**curl -I ** - verifica a disponibilidade HTTP
* `-I` - mostra apenas os cabeçalhos da resposta
* `http://aiserver.sherparpa.ru` - URL para verificação
**curl -I ** - verifica a disponibilidade HTTPS
**Resposta esperada:** HTTP/2 200 ou redirecionamento para /login
**Verificação dos serviços de IA:**\`\`\`\`bash
## Verifique o servidor LLM
curl -X POST "
-H "Content-Type: application/json"\
-d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "Hello", "max\_tokens": 10}'
💡 Comentários sobre a verificação do servidor LLM
**curl -X POST ""** - verifica o servidor LLM
* `-X POST` - método HTTP POST
* `"http://localhost:3003/v1/completions"` - URL do endpoint da API
* `-H "Content-Type: application/json"` - cabeçalho Content-Type
* `-d '{"model": "...", "prompt": "Hello", "max_tokens": 10}'` - dados da solicitação em formato JSON
#### Verificação da conexão com bancos de dados
```bash
# Verifique a conexão com o PostgreSQL
docker compose exec aiserver-pg psql -U postgres -d postgres -c "SELECT version();"
```
**Testando funções principais**
**Interface web:**
1. Abra o navegador e vá para `https://aiserver.sherparpa.ru`
2. A página de login deve ser exibida
3. Verifique a possibilidade de registro/login
**Gerenciamento do sistema**
**Parar o sistema:**
```bash
# Pare todos os serviços (considerando os profiles em execução)
docker compose down
```
**Reiniciar serviços:**
```bash
# Reinicie um serviço específico
docker compose restart aiserver
# Reinicie todos os serviços em execução
docker compose restart
# Reinicie serviços com um profile específico
docker compose --profile whisper restart aiserver-whisper
```
**Ver recursos:**
```bash
# Verifique o uso de recursos
docker stats
# Verifique o uso da GPU
nvidia-smi
```
💡 Comentários sobre o gerenciamento do sistema
**Parar o sistema:**
* `docker compose down` - para todos os serviços e remove os contêineres
* `docker compose down -v` - para os serviços e remove volumes (os dados serão perdidos!)
**Reiniciar serviços:**
* `docker compose restart aiserver` - reinicia um serviço específico
* `docker compose restart` - reinicia todos os serviços
* `docker compose --profile whisper restart aiserver-whisper` - reinicia o serviço com um profile específico
**Ver recursos:**
* `docker stats` - mostra o uso de CPU, memória e rede para contêineres
* `nvidia-smi` - mostra o uso da GPU NVIDIA
**Possíveis problemas ao iniciar:**
* **Contêineres não iniciam**: Verifique os logs com `docker compose logs`
* **Problemas com SSL**: Verifique a validade dos certificados
* **Erros de conexão com o BD**: Verifique as variáveis de ambiente no `.env`
* **Problemas com GPU**: Verifique as configurações de CUDA\_VISIBLE\_DEVICES
Após o início e teste bem-sucedido do sistema, a instalação do Sherpa AI Server está concluída.
```
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.sherparpa.ru/pt/sherpa-ai/sherpa-ai-server/ustanovka-sherpa-ai-server.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.