Ollama Proxy Server: Uma API gateway para serviços de AI Ollama. Para o homelab e para a empresa.

Higgs

Olá a todos.

No panorama atual da Inteligência Artificial, o acesso eficiente e seguro a modelos de linguagem tornou-se uma necessidade crítica para organizações de todas as dimensões, desde as empresas ás startups.
Recentemente, pediram-me para pensar numa forma de garantir acesso a um LLM através da internet, de forma “securizada” em que o acesso não fosse free for all. O pré requisito seria, API based, SSL encrypted and authenticated.
Procurei e alem do nosso querido apache reverse-proxy que pode ser tweakado para isso, achei o Ollama Proxy Server.
Este surge como uma ferramenta fundamental para quem utiliza o ecossistema Ollama e pretende implementar uma gestão robusta de acessos à API interna. O nosso artigo explora a importância desta solução, as suas funcionalidades e como ela se compara com alternativas mais rudimentares.

O Que É o Ollama Proxy Server?

Como o nome indica, o Ollama Proxy Server, desenvolvido por ParisNeo, é uma aplicação intermediária (broker) concebida especificamente para gerir o acesso ao servidor Ollama. Esta ferramenta foi criada para responder a uma lacuna importante: enquanto o Ollama oferece uma forma eficaz de executar modelos de linguagem localmente, carece de mecanismos robustos para controlar e monitorizar os acessos à sua API.

Este proxy server – disponível tanto em binário como em docker container – funciona como uma camada adicional entre os clientes e o servidor Ollama, oferecendo:

  • Autenticação e autorização
  • Registo detalhado de atividades
  • Gestão de recursos e quotas
  • Interface web para administração
  • Monitorização em tempo real
  • Compatibilidade com a API original do Ollama

A Importância de Um Broker para Controlar Acessos à API Interna

Segurança Reforçada

Se até agora não aprenderam que terem “coisas” abertas para a internet é um risco, então tem andado a ler as coisas erradas. A mesma coisa é valida para uma API de ollama. Não ter portão de acesso é convidar as hordas a colapsar a nossa instancia, mais rapidamente que conseguem escrever printf(“Hello, World!”);.
O mesmo se pode dizer num ambiente empresarial: A implementação de um servidor Ollama sem um broker adequado representa um risco significativo de segurança. O acesso direto à API permite que qualquer utilizador com conhecimento do endpoint execute pedidos sem restrições, podendo levar a:

  1. Uso não autorizado de recursos computacionais: Sem autenticação, qualquer pessoa na rede pode utilizar os recursos de processamento destinados a modelos de IA.
  2. Acesso a informações sensíveis: Os prompts e as respostas podem conter dados confidenciais que devem ser protegidos.
  3. Ausência de auditoria: Sem um broker, torna-se impossível rastrear quem está a utilizar o sistema e para que finalidades.

O Ollama Proxy Server resolve estes problemas implementando um sistema de autenticação baseado em tokens, garantindo que apenas utilizadores autorizados podem aceder ao serviço.

Gestão de Recursos

O maior dos desafios na implementação de serviços de IA é a gestão eficiente de recursos computacionais. Os modelos de linguagem consomem quantidades significativas de GPU e memória, tornando crucial a otimização da sua utilização. Melhor gestão = Melhores serviços que podemos disponibilizar, com menos custos para os nossos clientes finais.

O Ollama Proxy Server permite:

  • Definir quotas de utilização: Limite o número de tokens que cada utilizador pode processar.
  • Priorizar pedidos: Atribua diferentes níveis de prioridade a utilizadores ou aplicações.
  • Balancear cargas: Distribua pedidos entre múltiplas instâncias de Ollama quando disponíveis.

Esta gestão centralizada assegura uma distribuição justa de recursos e previne situações onde um único utilizador monopoliza o sistema.

Monitorização e Análise

Para otimizar um serviço de IA, é essencial compreender como está a ser utilizado. O Ollama Proxy Server oferece ainda capacidades avançadas de monitorização:

  • Registo detalhado de cada pedido (timestamp, utilizador, modelo, prompt)
  • Estatísticas de utilização por utilizador e por modelo
  • Métricas de desempenho (tempo de resposta, tokens processados)
  • Alertas configuráveis para situações anómalas

Estas informações permitem identificar padrões de utilização, otimizar a alocação de recursos e planear expansões de capacidade com base em dados concretos.

Compatibilidade com Clientes Existentes

Uma característica vital do Ollama Proxy Server é a sua compatibilidade com clientes que utilizam a API Ollama standard. Isto significa que não é necessário modificar aplicações existentes para beneficiar das funcionalidades de segurança e gestão. O proxy atua como um intermediário transparente, preservando a compatibilidade enquanto adiciona camadas de controlo.

Funcionalidades Principais do Ollama Proxy Server

O Ollama Proxy Server, como qualquer API GW que se preze,  oferece um conjunto abrangente de funcionalidades que o tornam uma solução completa para gestão de acesso:

Sistema de Autenticação Flexível

  • Autenticação baseada em tokens API
  • Integração opcional com sistemas de autenticação existentes (LDAP, OAuth)
  • Diferentes níveis de acesso (administrador, utilizador standard, read-only)

Interface de Administração Intuitiva

  • Painel web para gestão de utilizadores e permissões
  • Visualização em tempo real de métricas de utilização
  • Configuração de políticas de acesso através de UI

Capacidades de Logging e Auditoria

  • Registo detalhado de todas as interações
  • Exportação de logs para sistemas de análise externos
  • Retenção configurável de histórico de utilização

Gestão Avançada de Modelos

  • Restrição de acesso a modelos específicos por utilizador
  • Definição de limites de contexto por modelo
  • Controlo granular sobre parâmetros de geração (temperatura, top_p, etc.)

Escalabilidade e Alta Disponibilidade

  • Suporte para múltiplas instâncias de Ollama
  • Balanceamento de carga entre servidores
  • Failover automático em caso de indisponibilidade

Implementação do Ollama Proxy Server

A implementação do Ollama Proxy Server é relativamente simples, especialmente para quem já utiliza Docker, que será a plataforma onde hoje nos iremos concentrar:

# Pull da imagem Docker
docker pull parisneo/ollama_proxy_server

# Execução do container
docker run -p 8000:8000 \
  -e OLLAMA_API_BASE_URL="http://endereço-do-servidor-ollama:11434" \
  -e SECRET_KEY="chave-secreta-para-encriptação" \
  -v ./config:/app/config \
  parisneo/ollama_proxy_server

Após iniciar o servidor, é possível aceder à interface de administração através do navegador em http://localhost:8000/admin e configurar utilizadores, tokens de API e políticas de acesso.

Nota: As aplicações cliente podem então ser configuradas para utilizar o endpoint do proxy em vez do servidor Ollama direto:

http://endereço-do-proxy:8000/api/

Alternativa: Reverse Proxy Rudimentar

Embora o Ollama Proxy Server ofereça uma solução completa, em alguns cenários pode ser desejável implementar uma abordagem mais simples utilizando um reverse proxy convencional. Por exemplo para ambientes com light access, de POCs ou ainda em estágios iniciais de desenvolvimento.
Embora esta alternativa seja mais rudimentar e menos funcional, mas pode ser suficiente para necessidades básicas de autenticação e logging e sobretudo, e assumindo que já existem infraestruturas de reverse-proxy (estão carecas de serem avisados) será apenas uma questão de fazerem mais um vhost.

Usando Apache como Reverse Proxy

Claro que não iria deixar de colocar uma referencia ao nosso canivete suíço de proxying – O veneravel Apache.
Uma implementação básica com Apache pode ser configurada da seguinte forma (nota que este formato não é open-ai api compatible. A diferença principal será no X-API-Key que deverá ser convertida para o formato bearer)  :


<VirtualHost *:443>
ServerName api.blablabla.com
ServerAlias api.blablabla.com
LogFormat "remote_addr:%h %l remote_user:%u %t request:\"%r\" status:%>s %b \"%{Referer}i\" \"%{User-agent}i\" %{SSL_PROTOCOL}x %{SSL_CIPHER}x" combinedssl
 ErrorLog ${APACHE_LOG_DIR}/ollama_error.log
CustomLog ${APACHE_LOG_DIR}/ollama_access.log combined
LogLevel warn
Header always set X-Frame-Options 'deny'
Header always set X-Content-Type-Options 'nosniff'
Header always set X-XSS-Protection '1; mode=block'
SSLEngine On
SSLCompression Off
SSLProtocol -ALL +TLSv1.2 +TLSv1.3
SSLHonorCipherOrder On
SSLCipherSuite 'TLS_AES_256_GCM_SHA384:AES256+EECDH'
SSLCertificateKeyFile /etc/letsencrypt/live/blablabla.com/privkey.pem
SSLCertificateFile /etc/letsencrypt/live/blablabla.com/cert.pem
SSLCertificateChainFile /etc/letsencrypt/live/blablabla.com/chain.pem
SSLProxyEngine On


# Enable proxy and rewrite modules
ProxyRequests Off
ProxyPreserveHost On

# Enable mod_rewrite for API key authentication
<IfModule mod_rewrite.c>
RewriteEngine On

# First check if API key is provided and valid
RewriteCond %{HTTP:X-API-Key} ^A_VOSSA_API_INVENTADA_AQUI$
RewriteRule .* - [E=AUTHENTICATED:1,S=1]

# If API key fails, require basic auth
RewriteRule .* - [E=AUTHENTICATED:0]
</IfModule>

<Location />
Options FollowSymLinks

# Skip basic auth if already authenticated via API key
<If "-n '%{env:AUTHENTICATED}' && %{env:AUTHENTICATED} == '1'">
Require all granted
</If>
<Else>
AuthType Basic
AuthName "API"
AuthUserFile File /etc/apache2/.htpasswd
Require valid-user
</Else>

Order allow,deny
Allow from all

# Proxy configuration (moved inside Location to prevent auth bypass)
ProxyPass http://ip_do_vosso_host_de_ollama:11434/
ProxyPassReverse /
</Location>

# Additional headers
RequestHeader set X-Real-IP "%{REMOTE_ADDR}e"
RequestHeader set X-Forwarded-For "%{X-Forwarded-For}i"
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"

# WebSocket-specific headers
ProxyAddHeaders On
</VirtualHost>

Para criar o ficheiro de autenticação:

sudo htpasswd -c /etc/apache2/.htpasswd nome_utilizador

Para uma limitação mais avançada de taxa de pedidos, pode-se utilizar o módulo mod_qos:

<IfModule mod_qos.c>
    # Limitar a 5 pedidos por segundo por IP
    QS_SrvRequestRate 5
    
    # Limitar a 3 conexões simultâneas por IP
    QS_SrvMaxConn 3
</IfModule>

Limitações da Abordagem com Reverse Proxy

Embora funcional, esta solução apresenta várias limitações significativas como é bem visível pela configuração:

  1. Autenticação rudimentar: A autenticação básica HTTP é simples mas limitada, não permitindo níveis de acesso diferenciados ou integração com sistemas modernos de identidade.
  2. Gestão de tokens limitada: Não existe um sistema robusto para gerir tokens de API ou revogar acessos. Apenas um API token carregado a mão e que tem de ser mantido a mão sempre que um novo API token é necessário.
  3. Ausência de monitorização detalhada: Embora existam logs, falta uma interface para análise e visualização de métricas.
  4. Sem controlo específico por modelo: Não é possível limitar o acesso a modelos específicos.
  5. Configuração manual complexa: Implementar funcionalidades adicionais requer configuração manual extensa e conhecimentos avançados de Nginx.
  6. Sem interface de administração: Todas as alterações requerem edição manual de ficheiros de configuração.

Quando Utilizar Cada Solução

Como um amigo meu diz, hey, this is linux. There is always an alternative. E ele tem razão. Embora um martelo sirva para prender um parafuso, não é a ferramenta adequada.
Então quando devo escolher o que?

Optar pelo Ollama Proxy Server quando:

  • A segurança e controlo de acesso são prioridades elevadas
  • Existem múltiplos utilizadores com diferentes necessidades de acesso
  • É necessária monitorização detalhada da utilização
  • Pretende-se uma solução completa e integrada
  • São necessárias funcionalidades avançadas de gestão de recursos

Optar pelo Reverse Proxy quando:

  • O cenário de implementação é simples, com poucos utilizadores
  • Os requisitos de segurança são básicos
  • Já existe infraestrutura Nginx em utilização
  • Os recursos computacionais para execução do proxy são limitados
  • É necessária apenas uma solução temporária ou de teste

E chegamos ao fim do post desta semana. Neste vimos como a implementação de um broker como o Ollama Proxy Server representa uma prática fundamental para organizações que pretendem utilizar modelos de linguagem de forma segura e eficiente. Enquanto o Ollama fornece uma forma excelente de executar modelos localmente, o proxy adiciona as camadas necessárias de gestão, segurança e monitorização.

Os benefícios de implementar uma solução robusta como o Ollama Proxy Server superam significativamente o esforço de configuração inicial, especialmente em ambientes onde a segurança dos dados e a otimização de recursos são prioritárias. Comparado com alternativas mais rudimentares baseadas em reverse proxies convencionais, oferece funcionalidades avançadas que respondem às necessidades específicas de serviços de IA.

À medida que as organizações continuam a integrar modelos de linguagem nas suas operações, a importância de infraestruturas bem geridas e seguras para estes serviços continuará a crescer. O Ollama Proxy Server posiciona-se como uma ferramenta essencial neste ecossistema em evolução, permitindo extrair o máximo valor dos modelos de linguagem enquanto mantém o controlo necessário sobre a sua utilização.

Até ao post da próxima semana, e já sabem, se tiverem duvidas ou virem algo menos correcto, pf informem. Sabem onde me encontrar. 😉
Abraço
Nuno

Related Posts