Olá a todos!!
No nosso post anterior, exploramos o processo de instalação e configuração do Ollama, uma ferramenta poderosa para executar modelos LLM localmente.
Agora, daremos o próximo passo na construção do nosso homelab de IA, focando-nos na instalação e configuração do (Ollama) Open WebUI, uma interface gráfica que simplifica a interação com os modelos e amplia significativamente as suas capacidades.
O Open WebUI não só proporciona uma experiência de utilizador mais intuitiva, como também adiciona funcionalidades avançadas, incluindo bases de conhecimento, memória adaptativa e RAG (Retrieval-Augmented Generation), transformando os modelos de linguagem básicos em assistentes de IA verdadeiramente poderosos e personalizadoss

O que é o Open WebUI?
O Open WebUI é uma interface web opensource para o Ollama, desenvolvida para facilitar a interação com modelos de linguagem. Ao contrário da interação via linha de comandos, a interface web oferece:
- Chat em tempo real com diferentes modelos
- Gestão de contextos e histórico de conversas
- Criação e gestão de bases de conhecimento para RAG
- Memória persistente para conversas prolongadas
- Personalização do comportamento dos modelos
- Suporte para formatação avançada e visualização de resultados
- Integração com documentos e ficheiros externos
Instalação do Open WebUI via Docker
A abordagem recomendada para instalar o Open WebUI é através do Docker, que encapsula todas as dependências necessárias e simplifica significativamente o processo de instalação e atualização.
Neste texto estou claro, a assumir que temos já instalada uma plataforma de docker no nosso homelab.
Antes de avançarmos, certifiquem-se de que possuem:
- Docker instalado no seu sistema:
- Para Linux:
sudo apt-get install docker.io docker-compose
(Ubuntu/Debian) - Para macOS: Instale o Docker Desktop a partir do site oficial
- Para Linux:
- Ollama já instalado e configurado conforme descrito no post anterior
- Permissões adequadas para executar comandos Docker (pertença ao grupo
docker
ou utilizesudo
)
Instalação Passo a Passo
1. Preparação do Ambiente
Primeiro, vamos criar um diretório dedicado para o Open WebUI e os seus ficheiros de configuração:
mkdir -p ~/homelab/ollama-webui
cd ~/homelab/ollama-webui
2. Criação do Ficheiro Docker Compose
Para simplificar a gestão dos contentores Docker, iremos utilizar o Docker Compose. Criem um ficheiro docker-compose.yml
com o seguinte conteúdo:
nano docker-compose.yml
Façam paste do seguinte conteúdo (lembrem-se que é um yaml file):
version: '3.8'
services:
ollama-webui: container_name: ollama-webui
image: ghcr.io/ollama-webui/ollama-webui:main
restart: unless-stopped
ports:
- "3000:8080" volumes:
- ./data:/app/backend/data
environment:
- OLLAMA_API_BASE_URL=http://ollama:11434/api
- WEBUI_AUTH=false # Ative para autenticação
- TZ=Europe/Lisbon # Ajuste para o seu fuso horário
networks:
- ollama-network
depends_on:
- ollama
ollama:
container_name: ollama
image: ollama/ollama:latest
restart: unless-stopped
volumes:
- ./ollama:/root/.ollama
ports:
- "11434:11434"
environment:
- OLLAMA_HOST=0.0.0.0:11434
- OLLAMA_NUM_THREAD=6 # Ajuste para o seu hardware
networks:
- ollama-network
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
networks:
ollama-network:
driver: bridge
Nota: Se não tiverem um GPU NVIDIA ou estiver num macOS, remova a seção
deploy
com as configurações da GPU.
3. Configuração para macOS (Apple Silicon)
Se estiverem a utilizar um Mac com Apple Silicon (M1/M2/M3), ajustem a configuração do serviço Ollama no docker-compose.yml
:
ollama:
# Outras configurações permanecem iguais
environment:
- OLLAMA_HOST=0.0.0.0:11434
- OLLAMA_NUM_THREAD=6
- OLLAMA_METAL=1 # Ativa suporte para GPU Metal
4. Iniciar os Contentores
Com o ficheiro de configuração pronto, iniciem os vossos contentores:
docker-compose up -d
Este comando descarrega as imagens necessárias, cria os contentores e os iniciará em segundo plano.
5. Verificar a Instalação
Verifiquem se os contentores estão em execução:
docker-compose ps
Deverão ver ambos os contentores com o estado “Up”.
6. Aceder à Interface Web
Abra no vosso browser e acedam a:
http://localhost:3000
Nota: se colocaram a vossa instancia de ollama a escutar num ip de rede, deverão aceder a ele via esse IP.
http://192.168.1.100:3000 # Substituam pelo IP real
No browser deverão ver a interface de login do Open WebUI. Na primeira utilização, será necessário criarem uma conta de utilizador (se a autenticação estiver ativada) ou serão dirigidos diretamente para a interface principal.
Configuração Avançada do Open WebUI
Agora que temos o Open WebUI em funcionamento, iremos explorar as configurações avançadas para maximizar o seu potencial.
Nota: Os comandos abaixo foram retirados da pagina e manuais do Open WebUI.
Ativação da Autenticação
Para ambientes partilhados ou expostos à Internet, é recomendável ativar a autenticação:
- Parem os containers em execução:
docker-compose down
- Editem o ficheiro
docker-compose.yml
e alterem a configuração de autenticação:
environment:
- WEBUI_AUTH=true
- Reiniciem os contentores:
docker-compose up -d
Na próxima vez que acedam à interface, será solicitado que criarem uma conta de administrador. O processo pode ser efetuado no percurso inverso caso tenham perdido a credencial de administrador.
Configuração da Base de Conhecimento para RAG
Uma das funcionalidades mais poderosas do Open WebUI é a capacidade de criar bases de conhecimento para utilização com RAG (Retrieval-Augmented Generation), permitindo que os modelos complementem o seu conhecimento com informações específicas fornecidas por si.
1. Criação de uma Base de Conhecimento
- Acedam ao Open WebUI e naveguem para “Base de Conhecimento” no menu lateral
- Cliquem em “Nova Base de Conhecimento”
- Atribuam um nome descritivo, como “Documentação Técnica”
- Escolha um modelo de embedding (por exemplo, “nomic-embed-text”)
- Defina um limite de similaridade (recomenda-se 0.7 para começar)
- Clique em “Criar”
2. Carregamento de Documentos
Com a base de conhecimento criada, podemos agora carregar documentos:
- Selecionem a base de conhecimento recém-criada
- Clique em “Carregar Documentos”
- Selecione os ficheiros relevantes (suporta PDF, TXT, DOCX, MD e outros formatos)
- Aguardem o processamento dos documentos. Sem GPU poderá demorar algum tempo
O Open WebUI processará automaticamente os documentos, dividindo-os em chunks e criando embeddings que serão utilizados para recuperar informações relevantes durante as conversas.
3. Configuração do Processamento de Documentos
Para um processamento mais eficiente, podemos ajustar as configurações avançadas:
- Na seção de bases de conhecimento, cliquem em “Configurações”
- Ajustem os seguintes parâmetros:
- Tamanho do chunk: 1000 (controla o tamanho dos fragmentos de texto)
- Sobreposição do chunk: 200 (determina a sobreposição entre fragmentos)
- Limite de similaridade para respostas: 0.7 (quanto maior, mais restritiva é a recuperação)
4. Utilização da Base de Conhecimento nas Conversas
Para utilizar a base de conhecimento numa conversa:
- Iniciem uma nova conversa no chat
- Cliquem nas configurações da conversa (ícone de engrenagem)
- Na seção “Fontes de Conhecimento”, ativem a sua base de conhecimento
- Opcionalmente, ativem “Citações Automáticas” para incluir referências nas respostas
Agora, quando fizer perguntas relacionadas com o conteúdo da sua base de conhecimento, o modelo recuperará informações relevantes e incorporá-las-á nas suas respostas.
Configuração da Memória Adaptativa
A memória adaptativa permite que o modelo mantenha contexto ao longo de conversas prolongadas, mesmo além do limite de tokens do contexto normal.
1. Ativação da Memória Adaptativa
- Nas configurações da conversa, acedam à seção “Memória”
- Ativem “Memória Adaptativa”
- Configurem os seguintes parâmetros:
- Limite de mensagens para resumir: 10 (número de mensagens antes de criar um resumo)
- Comprimento máximo do contexto: 4000 (em tokens, ajuste de acordo com o modelo)
- Modelo para resumo: escolham um modelo eficiente para resumos (ex: “gemma:2b”)
2. Personalização da Estratégia de Memória
A memória adaptativa do Open WebUI oferece diferentes estratégias:
- Resumo Recursivo: Cria resumos do histórico da conversa para manter o contexto
- Ideal para conversas prolongadas sobre tópicos complexos
- Configuração recomendada:
threshold: 10, max_tokens: 4000
- Memória Híbrida: Combina resumos com recuperação de mensagens relevantes
- Equilibra o contexto recente com informações históricas importantes
- Configuração recomendada:
threshold: 15, max_tokens: 6000, retrieval_threshold: 0.7
Para configurar estas estratégias, aceda a “Configurações Avançadas” nas opções de memória.
Integração de Ferramentas e Extensões
O Open WebUI pode ser estendido com várias ferramentas que ampliam as capacidades dos modelos. Uma nota neste ponto: Cuidado com o que instalam. Ataques de supply chain acontecem, até aqui.
1. Configuração de Ferramentas Integradas
- Aceda a “Configurações” > “Ferramentas”
- Ative as ferramentas desejadas:
- Navegação Web: Permite que o modelo obtenha informações da Internet
- Pesquisa de Imagens: Habilita a geração de imagens baseada em texto
- Análise de Código: Melhora a capacidade de análise e explicação de código
2. Configuração da Navegação Web
Para permitir que o modelo aceda à Internet:
- Nas configurações de ferramentas, ativem “Navegação Web”
- Definam um limite para o número de resultados: 3-5 é geralmente suficiente
- Configurem os motores de busca preferidos. No meu caso e tendo em conta os custos envolvidos para outros engines de procura, instalei um docker com searxng e utilizo ele.
- Nas configurações da conversa, ativem a opção “Permitir Acesso à Web”
3. Integração com APIs Externas
Para funcionalidades mais avançadas, o Open WebUI permite integração com APIs externas:
- Acedam a “Configurações” > “Integrações”
- Configurem as integrações disponíveis:
- APIs de geração de imagens
- Serviços de transcrição de áudio
- Ferramentas de análise de dados
Otimização de Desempenho
Para garantir o melhor desempenho do Open WebUI, especialmente ao utilizar funcionalidades avançadas como RAG, considerem as seguintes otimizações:
1. Ajuste de Recursos para Contentores Docker
Editem o ficheiro docker-compose.yml
para alocar recursos apropriados:
services:
ollama-webui:
# Outras configurações permanecem iguais
deploy:
resources:
limits:
cpus: '2'
memory: 2G
ollama:
# Outras configurações permanecem iguais
deploy:
resources:
limits:
cpus: '6'
memory: 12G
Ajustme estes valores de acordo com o vosso hardware disponível. E acreditem que o RAG puxa a sério pelos recursos disponíveis.
2. Otimização de Modelos
A escolha do modelo certo para cada tarefa pode melhorar significativamente o desempenho:
- Para RAG e consulta a bases de conhecimento: modelos menores como “gemma:2b” ou “phi:3b” são geralmente suficientes
- Para resumos de memória: modelos compactos como “tinyllama” são eficientes
- Para tarefas complexas: modelos maiores como “llama3:70b” ou “mixtral”
Para descarregar um modelo específico:
docker exec -it ollama ollama pull gemma:2b
3. Configuração de Cache
O cache pode melhorar significativamente o desempenho da recuperação de conhecimento:
- Aceda a “Configurações” > “Avançadas”
- Configure o cache:
- Tamanho máximo do cache: 1000 (número de entradas)
- Tempo de expiração do cache: 3600 (em segundos)
Implementação de Fluxos de Trabalho Avançados
Com o Open WebUI configurado, podemos implementar fluxos de trabalho avançados que tiram partido de todas as suas capacidades.
1. Assistente de Programação com RAG
Criem um assistente especializado em programação:
- Criem uma nova base de conhecimento denominada “Documentação de Programação”
- Carreguem manuais de referência, tutoriais e exemplos de código
- Configurem um novo chat com um modelo adequado (ex: “codellama:13b”)
- Nas configurações da conversa, ativem a base de conhecimento
- Definam um sistema prompt especializado:
És um assistente de programação experiente. Utiliza a documentação fornecida
para ajudar a resolver problemas de código. Quando forneças exemplos, certifica-te
de que são funcionais e bem explicados. Cita sempre as fontes da documentação
quando relevante.
2. Assistente de Pesquisa Académica
Configurem um assistente para auxiliar na pesquisa académica:
- Criem uma base de conhecimento com artigos científicos e materiais de referência
- Configurem um novo chat com um modelo de grande capacidade (ex: “llama3:70b”)
- Ativem a memória adaptativa com estratégia híbrida
- Configure o sistema prompt:
És um assistente de pesquisa académica. Ajuda a analisar, sintetizar e discutir
informações de artigos científicos. Mantém sempre um tom académico e objetivo.
Quando citares informações, indica claramente a fonte. Ajuda a formular hipóteses
e a identificar lacunas na literatura existente.
3. Sistema de Análise de Documentos
E que tal um sistema para análise automática de documentos:
- Criem várias bases de conhecimento temáticas
- Configurem um fluxo de trabalho com prompts específicos para:
- Extrair informações-chave de documentos
- Categorizar automaticamente o conteúdo
- Gerar resumos executivos
- Identificar pontos de ação
Manutenção e Atualizações
Como na maioria dos projetos opensource, o Open Webui tem um ciclo de vida muito dinâmico, sendo atualizado regularmente, Para manterem o seu sistema atualizado e a funcionar sem problemas façam:
1. Atualização Regular dos Contentores
Execute regularmente:
cd ~/homelab/ollama-webui
docker-compose pull
docker-compose up -d
2. Backup de Dados
Para proteger o seu trabalho e configurações, implemente um sistema de backup regular:
- Backup manual:
# Parar os contentores (opcional, mas recomendado para consistência) docker-compose down # Criar backup tar -czvf ollama-webui-backup-$(date +%Y%m%d).tar.gz ./data ./ollama # Reiniciar os contentores docker-compose up -d
- Script automatizado de backup: Crie um ficheiro
backup.sh
:#!/bin/bash BACKUP_DIR="/caminho/para/backups" DATE=$(date +%Y%m%d) # Navegar para o diretório do projeto cd ~/homelab/ollama-webui # Criar diretório de backup se não existir mkdir -p $BACKUP_DIR # Criar backup tar -czvf $BACKUP_DIR/ollama-webui-backup-$DATE.tar.gz ./data ./ollama # Manter apenas os 5 backups mais recentes ls -t $BACKUP_DIR/ollama-webui-backup-*.tar.gz | tail -n +6 | xargs -r rm echo "Backup concluído: $BACKUP_DIR/ollama-webui-backup-$DATE.tar.gz"
Torne o script executável e agende-o com cron:
chmod +x backup.sh crontab -e
Adicionem a seguinte linha para executar o backup diariamente às 3 da manhã:
0 3 * * * /caminho/para/backup.sh >> /caminho/para/backup.log 2>&1
3. Monitorização do Sistema
Para garantir que o vosso homelab de IA funciona de forma estável:
- Monitorização básica com Docker:
# Ver estatísticas em tempo real docker stats # Ver logs docker-compose logs -f
- Integração com Prometheus e Grafana (para utilizadores avançados): Adicione ao seu
docker-compose.yml
:prometheus: image: prom/prometheus:latest volumes: - ./prometheus:/etc/prometheus ports: - "9090:9090" networks: - ollama-network grafana: image: grafana/grafana:latest volumes: - ./grafana:/var/lib/grafana ports: - "3001:3000" networks: - ollama-network depends_on: - prometheus
Configurem a monitorização do Ollama e Open WebUI para visualizar o uso de recursos e performance
Resolução de Problemas Comuns
Como não existe bela sem senão, qui estão algumas soluções para problemas frequentes que podem encontrar:
1. Problemas de Conexão com o Ollama
Sintoma: O Open WebUI não consegue conectar-se ao serviço Ollama.
Solução:
- Verifiquem se ambos os containers estão em execução:
docker-compose ps
- Verifiquem os logs do Ollama:
docker-compose logs ollama
- Certifique-se de que a configuração de rede está correta no
docker-compose.yml
:environment: - OLLAMA_API_BASE_URL=http://ollama:11434/api
- Reiniciem os serviços:
docker-compose restart
2. Problemas de Desempenho (quem nunca?).
Sintoma: Modelos demoram muito tempo a responder ou consomem demasiada memória.
Solução:
- Utilizem modelos mais pequenos para tarefas menos exigentes
- Ajustem o número de threads no ficheiro
docker-compose.yml
:environment: - OLLAMA_NUM_THREAD=4 # Reduza para sistemas com menos recursos
. A regra básica é uma thread por core. - Limitem o contexto da conversa:
environment: - OLLAMA_CONTEXT_SIZE=2048 # Reduza o tamanho do contexto
3. Problemas com Bases de Conhecimento
Sintoma: RAG não funciona corretamente ou não retorna informações relevantes.
Solução:
- Ajustem o limite de similaridade:
- Aumente para resultados mais precisos (0.8+)
- Diminua para resultados mais abrangentes (0.5-0.7)
- Verifiquem o processamento dos documentos:
- Reduzam o tamanho do chunk para documentos densos (500-700)
- Aumentem a sobreposição para melhor continuidade (30-40% do tamanho do chunk)
- Experimentem diferentes modelos de embedding:
nomic-embed-text
(equilíbrio entre velocidade e qualidade)all-minilm
(mais rápido, menos preciso)e5-large
(mais preciso, mais lento)
Casos de Uso Avançados
Agora que temos um homelab de IA completo, vamos explorar alguns casos de uso avançados que demonstram todo o potencial desta configuração.
1. Criação de Agentes Especializados
O Open WebUI permite criar agentes especializados através da combinação de prompts de sistema, bases de conhecimento e configurações específicas.
Agente de Análise Financeira:
- Criem uma base de conhecimento com relatórios financeiros, análises de mercado e terminologia específica
- Configurem um prompt de sistema detalhado:
És um analista financeiro especializado. Utilizas a base de conhecimento para fornecer
análises detalhadas e precisas sobre mercados, empresas e tendências económicas.
Quando apresentares dados, inclui sempre o contexto e possíveis limitações da análise.
Distingue claramente entre factos, projeções e opiniões. Cita sempre as fontes das
informações específicas.
- Ativem a memória adaptativa com resumo recursivo para manter o contexto de análises complexas
- Adicionem ferramentas como acesso à web para obter dados atualizados
2. Implementação de Fluxos de Trabalho com Múltiplos Modelos
Através da API do Open WebUI, podemos criar fluxos de trabalho que utilizam diferentes modelos para tarefas específicas:
- Modelo de triagem: Um modelo pequeno e eficiente (como “tinyllama”) para analisar a consulta inicial
- Modelo especializado: Com base na triagem, direcionar para um modelo específico:
- Consultas de programação → CodeLlama
- Consultas criativas → Llama3
- Consultas matemáticas → Qwen
- Modelo de refinamento: Um modelo focado em melhorar e formatar a resposta final
Este fluxo pode ser implementado através da API REST do Open WebUI ou com scripts personalizados.
Em breve farei um post sobre o tema, pelo que devem subscrever o feed se ainda não o fizeram.
3. Sistema de Documentação Automatizada
Configurem um sistema para documentação automatizada de código e projetos:
- Criem uma base de conhecimento com guidelines de documentação, padrões e exemplos
- Configurem um agente especializado em documentação de código
- Implementem um fluxo de trabalho que:
- Analisa código-fonte
- Gera documentação de funções e classes
- Cria diagramas explicativos
- Mantém um índice de documentação atualizado
Extensão do Homelab de IA
Para expandir ainda mais as capacidades do nosso homelab de IA, considerem estas integrações adicionais:
1. Integração com Langchain
O Open WebUI pode ser integrado com o Langchain para fluxos de trabalho mais avançados:
- Instale o Langchain como um serviço adicional:
langchain:
image: ghcr.io/langchain/langchain:latest
ports:
- "8000:8000"
networks:
- ollama-network
- Configurem integrações para:
- Processamento avançado de documentos
- Agentes autónomos
- Pipelines de processamento complexos
2. Adição de Vector Database Dedicada
Para melhorar o desempenho do RAG em grandes bases de conhecimento:
- Adicionem uma instância do Qdrant ou Chroma:
qdrant:
image: qdrant/qdrant:latest
volumes:
- ./qdrant_data:/qdrant/storage
ports:
- "6333:6333"
networks:
- ollama-network
- Configurem o Open WebUI para utilizar esta base de dados vetorial externa para:
- Melhor escalabilidade
- Pesquisa mais rápida
- Funcionalidades avançadas como pesquisa por filtros
3. Integração com Ferramentas de Desenvolvimento
Liguem o vosso homelab ao ambiente de desenvolvimento:
- Configure webhooks ou integrações de API com:
- IDEs (VS Code, JetBrains)
- Sistemas de gestão de projeto (Jira, GitHub, Gittea)
- Plataformas de documentação (Confluence, GitBook)
- Implemente plugins para acelerar fluxos de trabalho comuns:
- Geração e revisão de código
- Documentação automática
- Análise de requisitos
Neste post, exploramos em detalhe a instalação e configuração do Open WebUI através do Docker, transformando o nosso servidor Ollama básico num completo homelab de IA com capacidades avançadas. Desde a configuração inicial até à implementação de fluxos de trabalho complexos com RAG, memória adaptativa e integração com ferramentas externas, agora temos um ambiente robusto para explorar o potencial dos modelos de linguagem localmente.
As possibilidades são virtualmente ilimitadas tanto em capacidade como exploração: à medida que novos modelos e funcionalidades são lançados, o nosso homelab pode evoluir para incorporá-los, mantendo sempre o controlo sobre os nossos dados e a flexibilidade para adaptar o sistema às nossas necessidades específicas.
Com o Ollama e o Open WebUI, conseguimos uma implementação robusta de IA generativa que rivaliza com muitos serviços comerciais em nuvem, mas com a vantagem adicional da privacidade, personalização e potencial de integração com outros sistemas locais.
Espero que este guia vos ajude a configurar o vosso próprio homelab de IA e a apanhar este novo elevador de nível em IT. Não hesitem em experimentar diferentes configurações, modelos e fluxos de trabalho para descobrir o que melhor se adapta às vossas necessidades específicas.
Se notarem alguma coisa menos correcta, ou queiram adicionar a este (longo) post, já sabem onde me encontrar.
Abraço
Nuno