Pt

Execução do servidor LLM em um servidor separado#

Nesta seção, descrevemos a configuração para executar apenas o servidor LLM em um servidor separado, sem os demais componentes do Sherpa AI Server.

Quando isso é necessário#

Executar o servidor LLM em um servidor separado é útil quando:

  • É necessário distribuir a carga entre servidores
  • O servidor LLM requer GPUs poderosas e é melhor colocá-lo em um servidor separado
  • É necessário escalonamento - vários servidores LLM para balanceamento de carga
  • É preciso isolar o servidor LLM do aplicativo principal

Requisitos#

  • Servidor com GPU NVIDIA (CUDA 11.8+)
  • Docker e Docker Compose instalados
  • NVIDIA Container Toolkit instalado
  • Modelos LLM carregados no diretório llm-server/models/

Configuração#

Passo 1: Preparação do servidor#

Certifique-se de que todos os componentes necessários estão instalados no servidor

# Verifique a GPU
nvidia-smi

# Verifique o Docker
docker --version
docker compose version

Passo 2: Preparar arquivos e imagem#

É necessário criar um diretório de trabalho. Copie o modelo para llm-server/models/ e, se necessário, os modelos de prompt para llm-server/templates/. É necessário criar .env conforme a etapa 4. O arquivo client-files do servidor principal não contém a imagem Docker do LLM: em um host LLM novo, obtenha separadamente o arquivo da imagem da mesma versão do Sherpa AI Server principal e sua soma de verificação. Por exemplo, para a versão 2.5.1:

set -e
RELEASE_VERSION=2.5.1
ARCHIVE=aiserver-llm-server_$RELEASE_VERSION.tar.gz
BASE_URL=https://downloads.sherparpa.ru/SherpaAIServer/aiserver-llm-server
curl -fL --retry 3 -o "$ARCHIVE" "$BASE_URL/$ARCHIVE"
curl -fL --retry 3 -o "$ARCHIVE.SHA256SUM" "$BASE_URL/$ARCHIVE.SHA256SUM"
sha256sum -c "$ARCHIVE.SHA256SUM"
docker load -i "$ARCHIVE"
docker image inspect "aiserver-llm-server:$RELEASE_VERSION" >/dev/null

Sem acesso ao servidor de downloads, transfira os dois arquivos da mesma versão para o host LLM e execute os três últimos comandos. Se a soma de verificação falhar ou a imagem com a tag necessária estiver ausente, pare e confira o conjunto. Defina APP_VERSION no .env com essa mesma versão. Não use uma tag :latest independente no lugar da versão verificada.

Passo 3: Configurar o Docker Compose#

É necessário salvar o conteúdo a seguir como docker-compose.llm-only.yml no diretório de trabalho. Ele executa um único contêiner LLM com a tag verificada da imagem. Por padrão, o HTTP fica disponível somente em 127.0.0.1:3003. Para acesso direto de outro servidor, altere a linha da porta para "3003:8000" e limite o acesso à porta 3003 ao endereço do servidor principal. Para HTTPS, mantenha a vinculação local.

services:
  aiserver-llm-server:
    container_name: aiserver-llm-server
    image: aiserver-llm-server:${APP_VERSION}
    restart: always
    env_file:
      - .env
    ports:
      - "127.0.0.1:3003:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    volumes:
      - "./llm-server/models:/model-store"
      - "./llm-server/templates:/model-templates"

Passo 4: Configurar variáveis de ambiente#

É necessário criar ou edite o arquivo .env com as configurações do servidor LLM:

APP_VERSION=2.5.1
# Configurações do servidor LLM
LLM_CUDA_VISIBLE_DEVICES=0
LLM_TENSOR_PARALLEL_SIZE=1
LLM_GPU_MEMORY_UTILIZATION=0.90
LLM_COMPLETION_MODEL_NAME=/model-store/meta-llama/Meta-Llama-3-8B-Instruct
LLM_DTYPE=auto
LLM_TRUST_REMOTE_CODE=false
LLM_QUANTIZATION=false
LLM_MAX_MODEL_LEN=8192
LLM_HOST=0.0.0.0
LLM_PORT=8000
LLM_MAX_NUM_BATCHED_TOKENS=16384
LLM_MAX_NUM_SEQS=16
LLM_ENABLE_TOOLS=true
LLM_TOOL_CALL_PARSER=llama3_json
LLM_EXCLUDE_TOOLS_WHEN_NONE=true

Importante:

  • Certifique-se de que o caminho para o modelo está correto: LLM_COMPLETION_MODEL_NAME=/model-store/nome-do-modelo

Passo 5: Verificar a configuração#

Antes de iniciar, verifique a configuração:

docker compose -f docker-compose.llm-only.yml config
# Confira se a porta 3003 está livre antes de iniciar
ss -ltn '( sport = :3003 )'
ls -la llm-server/models/

Passo 6: Iniciar o servidor LLM#

docker compose -f docker-compose.llm-only.yml up -d aiserver-llm-server
docker compose -f docker-compose.llm-only.yml ps

Resultado esperado: Apenas o contêiner aiserver-llm-server deve ser iniciado.

Passo 7: Verificar o funcionamento#

# Verifique os logs
docker logs aiserver-llm-server

# Verifique o uso da GPU
nvidia-smi

# Verifique a disponibilidade da API (deve retornar informações sobre o modelo)
curl http://localhost:3003/v1/models

Resultado esperado:

  • O contêiner deve iniciar com sucesso
  • Não deve haver erros críticos nos logs
  • A API deve responder às solicitações
  • A GPU deve ser utilizada para carregar o modelo

Conexão de outro servidor#

Se o servidor LLM estiver em um servidor separado, configure a conexão a partir do servidor principal.

No servidor principal (HTTP direto)#

Para HTTP direto, altere primeiro a linha da porta em docker-compose.llm-only.yml para "3003:8000" e aplique a configuração com docker compose -f docker-compose.llm-only.yml up -d aiserver-llm-server. Limite as conexões de entrada à porta 3003 ao endereço do servidor principal. No arquivo .env do servidor principal, especifique o endereço do servidor LLM:

# Endereço do servidor LLM (substitua pelo IP ou domínio do seu servidor LLM)
LLM_MODEL_API_BASE_URL=http://192.168.1.100:3003
# ou
LLM_MODEL_API_BASE_URL=http://llm-server.example.com:3003

Depois de alterar o .env, recrie o contêiner backend com docker compose up -d --force-recreate aiserver. Para uma instância de modelo separada, defina também a URL base nas configurações da instância.

Conexão por HTTPS#

No host LLM, instale o nginx pelo gerenciador de pacotes do seu sistema operacional e coloque fullchain.pem e privkey.pem no diretório protegido /etc/sherpa/llm-certs/. O certificado deve incluir o nome DNS do host LLM. O arquivo client-files da versão 2.5.1 não inclui um arquivo Docker Compose separado para HTTPS nem uma configuração do nginx. É necessário criar a configuração abaixo no host LLM. Ela encaminha as requisições para o contêiner já em execução e não inicia um segundo LLM.

Em docker-compose.llm-only.yml, confirme que a porta está vinculada a "127.0.0.1:3003:8000". Se você já tiver exposto HTTP para acesso direto, restaure a vinculação local e aplique a mudança:

docker compose -f docker-compose.llm-only.yml up -d aiserver-llm-server
docker compose -f docker-compose.llm-only.yml ps

É necessário criar /etc/nginx/conf.d/llm-server.conf:

server {
    listen 443 ssl;
    server_name llm-server.example.com;
    ssl_certificate /etc/sherpa/llm-certs/fullchain.pem;
    ssl_certificate_key /etc/sherpa/llm-certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    client_max_body_size 500m;

    location / {
        proxy_pass http://127.0.0.1:3003;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 600s;
        proxy_buffering off;
    }
}

Valide a configuração, inicie o nginx e limite o acesso à porta TCP/443 ao endereço do servidor principal:

sudo nginx -t
sudo systemctl enable --now nginx
sudo systemctl reload nginx

No servidor principal, configure a URL correspondente ao nome do certificado e ative a verificação TLS no .env:

LLM_MODEL_API_BASE_URL=https://llm-server.example.com
LLM_TLS_VERIFY=1

Se você usa uma autoridade certificadora privada, adicione o certificado raiz ao armazenamento de confiança do contêiner backend. Recrie aiserver e verifique a conexão sem curl -k:

docker compose up -d --force-recreate aiserver
curl -fsS https://llm-server.example.com/v1/models

Se LLM_API_KEY estiver ativada, adicione o cabeçalho Authorization: Bearer <chave> à requisição de verificação e configure essa chave na instância de modelo do Sherpa AI Server. Depois envie uma mensagem de teste no chat. LLM_TLS_VERIFY fica desativada por padrão para manter a compatibilidade com instalações antigas. É necessário usar 1 para HTTPS com um certificado confiável.

Problemas potenciais#

O contêiner não inicia#

Problema: O contêiner falha imediatamente após o início.

Solução:

  1. É necessário verificar os logs: docker logs aiserver-llm-server
  2. Certifique-se de que a GPU está disponível: nvidia-smi
  3. É necessário verificar se o modelo existe: ls -la llm-server/models/
  4. É necessário verificar as permissões do diretório dos modelos

O modelo não carrega#

Problema: Erros ao carregar o modelo.

Solução:

  1. É necessário verificar o caminho do modelo no .env: LLM_COMPLETION_MODEL_NAME
  2. Certifique-se de que o modelo está carregado: ls -la llm-server/models/
  3. É necessário verificar os logs para erros de carregamento: docker logs aiserver-llm-server | grep -i error

Memória GPU insuficiente#

Problema: O modelo não cabe na memória da GPU.

Solução:

  • Reduza LLM_GPU_MEMORY_UTILIZATION no .env
  • É necessário usar a versão quantizada do modelo (defina LLM_QUANTIZATION=true)
  • É necessário utilizar um modelo menor

Porta indisponível externamente#

Problema: Não consigo conectar ao servidor LLM de outro servidor.

Solução:

  1. É necessário verificar o firewall: sudo ufw status
  2. É necessário verificar se a porta está mapeada: docker port aiserver-llm-server
  3. É necessário verificar as configurações de rede do Docker

Monitoramento#

Para monitorar o funcionamento do servidor LLM:

# Status do contêiner
docker ps | grep llm-server

# Uso de recursos
docker stats aiserver-llm-server

# Uso da GPU
watch -n 1 nvidia-smi

# Logs em tempo real
docker logs -f aiserver-llm-server

# Verificação da API
curl http://localhost:3003/health
curl http://localhost:3003/v1/models

Otimização de desempenho#

Para otimizar o desempenho do servidor LLM:

  1. Configuração da memória GPU:

    LLM_GPU_MEMORY_UTILIZATION=0.90  # Use o máximo de memória disponível

  2. Configuração de batching:

    LLM_MAX_NUM_BATCHED_TOKENS=16384
LLM_MAX_NUM_SEQS=16

  3. Uso de quantização:

    LLM_QUANTIZATION=true  # Para modelos com suporte a quantização

Após essas etapas, um único contêiner LLM estará em execução no servidor separado. A API usa a porta 3003 para HTTP direto. Para HTTPS, conecte-se ao nginx na porta 443.