Ir para o conteúdo

Ollama (LLM) em Linux / Debian

O assistente de exercícios (POST /api/practices/[id]/drill-advisor) chama o Ollama apenas no servidor Next.js (Route Handlers). O browser não contacta o Ollama directamente.

Instalar o Ollama no servidor

Segue a documentação oficial (instalador Linux / pacotes):

Instalação típica em linha (como root ou com sudo); depois confirma que o serviço está activo se o instalador não o fizer:

curl -fsSL https://ollama.com/install.sh | sh

Descarrega pelo menos um modelo (o nome tem de coincidir exactamente com OLLAMA_MODEL, vê ollama list):

ollama pull llama3.2

Confirma que a API responde em local:

curl -s http://127.0.0.1:11434/api/tags | head

Onde configurar a aplicação

As variáveis são lidas só no processo Node.js (sem prefixo NEXT_PUBLIC_).

Variável Significado Valor por defeito no código se não estiver definida
OLLAMA_BASE_URL URL base da API HTTP do Ollama http://127.0.0.1:11434
OLLAMA_MODEL Tag do modelo (ollama list) llama3.2

Desenvolvimento local (raiz do repositório)

  1. Copia .env.example para .env ou .env.local (ver ficheiros de ambiente do Next.js).
  2. Ajusta OLLAMA_BASE_URL e OLLAMA_MODEL se precisares.
  3. Opcional: npm run ollama:ping na raiz do projecto (o script carrega .env / .env.local) para testar ligação e se o modelo existe.

Produção (Debian + PM2 / systemd)

Usa os mesmos nomes de variáveis no ambiente do processo que corre next start:

  • PM2: env / env_production no ecosystem.config.cjs, ou ficheiro que faça source a um snippet.
  • systemd: Environment= ou EnvironmentFile=/etc/coaching/app.env na unidade que arranca Node/PM2.

Exemplo quando o Ollama corre no mesmo host que a app:

OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2

Se o Ollama estiver noutro host interno (VPN / rede privada), define OLLAMA_BASE_URL para essa URL base (continua a ser inaceitável expor 11434 à Internet pública).

Verificação na app (após login)

Com permissão de leitura de exercícios, o GET /api/ollama/status indica se a URL configurada responde e lista modelos. Serve para validar produção sem ir aos logs do servidor.

Segurança

  • Não abras a porta TCP 11434 à Internet pública. Preferível loopback (127.0.0.1) no host da app ou rede privada apenas.
  • Todo o tráfego do LLM fica só no servidor; ver comentários em src/lib/ollama.ts no repositório.

Ver também

  • .env.example — bloco Ollama no modelo de variáveis.
  • scripts/ollama-ping.ts — teste rápido na CLI.