Quem quer ter o seu proprio laboratório de IA? – Parte 2 de 2

Higgs

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:

  1. 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
  2. Ollama já instalado e configurado conforme descrito no post anterior
  3. Permissões adequadas para executar comandos Docker (pertença ao grupo docker ou utilize sudo)

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:

  1. Parem os containers em execução:
docker-compose down
  1. Editem o ficheiro docker-compose.yml e alterem a configuração de autenticação:
environment:
  - WEBUI_AUTH=true
  1. 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

  1. Acedam ao Open WebUI e naveguem para “Base de Conhecimento” no menu lateral
  2. Cliquem em “Nova Base de Conhecimento”
  3. Atribuam um nome descritivo, como “Documentação Técnica”
  4. Escolha um modelo de embedding (por exemplo, “nomic-embed-text”)
  5. Defina um limite de similaridade (recomenda-se 0.7 para começar)
  6. Clique em “Criar”

2. Carregamento de Documentos

Com a base de conhecimento criada, podemos agora carregar documentos:

  1. Selecionem a base de conhecimento recém-criada
  2. Clique em “Carregar Documentos”
  3. Selecione os ficheiros relevantes (suporta PDF, TXT, DOCX, MD e outros formatos)
  4. 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:

  1. Na seção de bases de conhecimento, cliquem em “Configurações”
  2. 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:

  1. Iniciem uma nova conversa no chat
  2. Cliquem nas configurações da conversa (ícone de engrenagem)
  3. Na seção “Fontes de Conhecimento”, ativem a sua base de conhecimento
  4. 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

  1. Nas configurações da conversa, acedam à seção “Memória”
  2. Ativem “Memória Adaptativa”
  3. 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:

  1. 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
  2. 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

  1. Aceda a “Configurações” > “Ferramentas”
  2. 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:

  1. Nas configurações de ferramentas, ativem “Navegação Web”
  2. Definam um limite para o número de resultados: 3-5 é geralmente suficiente
  3. 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.
  4. 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:

  1. Acedam a “Configurações” > “Integrações”
  2. 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:

  1. Aceda a “Configurações” > “Avançadas”
  2. 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:

  1. Criem uma nova base de conhecimento denominada “Documentação de Programação”
  2. Carreguem manuais de referência, tutoriais e exemplos de código
  3. Configurem um novo chat com um modelo adequado (ex: “codellama:13b”)
  4. Nas configurações da conversa, ativem a base de conhecimento
  5. 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:

  1. Criem uma base de conhecimento com artigos científicos e materiais de referência
  2. Configurem um novo chat com um modelo de grande capacidade (ex: “llama3:70b”)
  3. Ativem a memória adaptativa com estratégia híbrida
  4. 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:

  1. Criem várias bases de conhecimento temáticas
  2. 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:

  1. 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
  2. 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:

  1. Monitorização básica com Docker: 
    # Ver estatísticas em tempo real
docker stats

# Ver logs
docker-compose logs -f
  2. 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:

  1. Verifiquem se ambos os containers estão em execução: 
    docker-compose ps
  2. Verifiquem os logs do Ollama: 
    docker-compose logs ollama
  3. Certifique-se de que a configuração de rede está correta no docker-compose.yml: 
    environment:
  - OLLAMA_API_BASE_URL=http://ollama:11434/api
  4. 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:

  1. Utilizem modelos mais pequenos para tarefas menos exigentes
  2. 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.
  3. 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:

  1. Ajustem o limite de similaridade:
    • Aumente para resultados mais precisos (0.8+)
    • Diminua para resultados mais abrangentes (0.5-0.7)
  2. 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)
  3. 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:

  1. Criem uma base de conhecimento com relatórios financeiros, análises de mercado e terminologia específica
  2. 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.
  1. Ativem a memória adaptativa com resumo recursivo para manter o contexto de análises complexas
  2. 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:

  1. Modelo de triagem: Um modelo pequeno e eficiente (como “tinyllama”) para analisar a consulta inicial
  2. Modelo especializado: Com base na triagem, direcionar para um modelo específico:
    • Consultas de programação → CodeLlama
    • Consultas criativas → Llama3
    • Consultas matemáticas → Qwen
  3. 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:

  1. Criem uma base de conhecimento com guidelines de documentação, padrões e exemplos
  2. Configurem um agente especializado em documentação de código
  3. 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:

  1. Instale o Langchain como um serviço adicional:
langchain:
  image: ghcr.io/langchain/langchain:latest
  ports:
    - "8000:8000"
  networks:
    - ollama-network
  1. 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:

  1. Adicionem uma instância do Qdrant ou Chroma:
qdrant:
  image: qdrant/qdrant:latest
  volumes:
    - ./qdrant_data:/qdrant/storage
  ports:
    - "6333:6333"
  networks:
    - ollama-network
  1. 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:

  1. 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)
  2. 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

 

 

 

Related Posts