From 195cbec7bf9eeb5ded8a17cd37c27248b76dfd94 Mon Sep 17 00:00:00 2001 From: Daniel Dias Pereira <86617987+DanielDPereira@users.noreply.github.com> Date: Thu, 1 Oct 2026 18:05:20 -0300 Subject: [PATCH] chore(ai): run Ollama outside Docker --- .env.example | 2 ++ AGENTS.md | 8 ++++---- docker-compose.yml | 28 +++------------------------- docs/Architecture/README.md | 2 +- docs/SETUP_GUIDE.md | 29 ++++++++++++++++++++++------- 5 files changed, 32 insertions(+), 37 deletions(-) diff --git a/.env.example b/.env.example index b03007b..274b9fc 100644 --- a/.env.example +++ b/.env.example @@ -25,6 +25,8 @@ N8N_API_KEY= # --- Runtime de IA e Embeddings Locais (Ollama) --- OLLAMA_PORT=11434 OLLAMA_BASE_URL=http://localhost:11434 +# URL usada pelo ai-service quando ele é executado dentro do Docker Compose. +OLLAMA_DOCKER_BASE_URL=http://host.docker.internal:11434 # Modelos recomendados no PRD (Qwen 2.5 / Llama 3.1 para LLM, bge-m3 para embeddings) OLLAMA_LLM_MODEL=qwen2.5:1.5b OLLAMA_NUM_PREDICT=1024 diff --git a/AGENTS.md b/AGENTS.md index 7927729..2c78306 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,7 +117,7 @@ The application is structured into conteinerized, local microservices: | **Frontend** | React 19 / Vite / TS | `5173` | SPA for POs (requirements hierarchy, quality indicators, acervo search, chat). | | **AI Service** | Python 3.11+ / FastAPI | `8000` | Chunking source of truth, RAG retrieval, `bge-m3` embedding calculation, PRO4TECH Harness. | | **n8n** | n8n `latest` | `5678` | Asynchronous file ingestion workflow (`/files`), GitOps versioned via `n8n-local-sync`. | -| **Ollama** | Ollama Container | `11434` | Local LLM (`qwen2.5:1.5b`) and Embedding (`bge-m3`) runtime. | +| **Ollama** | Host runtime | `11434` | Local LLM (`qwen2.5:1.5b`) and Embedding (`bge-m3`) runtime, executed outside Docker. | --- @@ -229,10 +229,10 @@ cp .env.example .env # 2. Start core docker services docker compose up -d -# 3. Pull Ollama models (optional) +# 3. Start the optional AI service and pull host Ollama models separately docker compose --profile local-ai up -d -docker compose --profile local-ai exec ollama ollama pull bge-m3 -docker compose --profile local-ai exec ollama ollama pull qwen2.5:1.5b +ollama pull bge-m3 +ollama pull qwen2.5:1.5b ``` ### Verification & Testing Commands: diff --git a/docker-compose.yml b/docker-compose.yml index b6bfbf0..56433e9 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -47,26 +47,6 @@ services: networks: - sinapse-network - ollama: - profiles: [local-ai] - image: ollama/ollama:latest - container_name: sinapse-ollama - restart: unless-stopped - ports: - - "${OLLAMA_PORT:-11434}:11434" - volumes: - - ollama_data:/root/.ollama - environment: - - OLLAMA_KEEP_ALIVE=${OLLAMA_KEEP_ALIVE:-24h} - healthcheck: - test: ["CMD-SHELL", "ollama list || exit 1"] - interval: 10s - timeout: 5s - retries: 5 - start_period: 10s - networks: - - sinapse-network - backend: build: context: . @@ -108,12 +88,14 @@ services: restart: unless-stopped ports: - "${AI_SERVICE_PORT:-8000}:8000" + extra_hosts: + - "host.docker.internal:host-gateway" volumes: - repo_analysis_data:/app/workspace_analyzer environment: - AI_SERVICE_PORT=8000 - AI_SERVICE_HOST=0.0.0.0 - - OLLAMA_BASE_URL=http://ollama:11434 + - OLLAMA_BASE_URL=${OLLAMA_DOCKER_BASE_URL:-http://host.docker.internal:11434} - OLLAMA_LLM_MODEL=${OLLAMA_LLM_MODEL:-qwen2.5:1.5b} - OLLAMA_NUM_PREDICT=${OLLAMA_NUM_PREDICT:-1024} - OLLAMA_NUM_CTX=${OLLAMA_NUM_CTX:-8192} @@ -131,8 +113,6 @@ services: depends_on: postgres: condition: service_healthy - ollama: - condition: service_healthy networks: - sinapse-network @@ -152,8 +132,6 @@ volumes: name: sinapse_postgres_data n8n_data: name: sinapse_n8n_data - ollama_data: - name: sinapse_ollama_data documents_data: name: sinapse_documents_data repo_analysis_data: diff --git a/docs/Architecture/README.md b/docs/Architecture/README.md index b629e20..c83c92e 100644 --- a/docs/Architecture/README.md +++ b/docs/Architecture/README.md @@ -22,7 +22,7 @@ flowchart LR | Backend | `backend/`, Express + TypeScript | API, sessões, autorização por perfil, validações, regras de domínio, acesso ao Postgres, storage de documentos e histórico de conversa. | | Banco | `database/init.sql` + `database/migrations/`, PostgreSQL 16 e extensão pgvector | Persistência do domínio, índices e estruturas para conteúdo de conhecimento. O backend aplica migrations pendentes ao iniciar o container. | | Serviço Python | `ai-service/`, FastAPI | Endpoints de saúde, chunking, embeddings, consulta RAG e execução/consulta de análises de repositório. É executado no perfil Docker `local-ai`. | -| Ollama | container opcional | Provedor local de modelos de embedding e geração. Os modelos são baixados pelo operador; não vêm no build da imagem. | +| Ollama | runtime no host | Provedor local de modelos de embedding e geração, executado fora do Docker para melhor acesso aos recursos de CPU/GPU. Os modelos são baixados pelo operador; não vêm no build da imagem. | | n8n | container padrão, integrações opcionais | Consumidor de eventos/integrador. O evento de remoção pode ser enviado por `DOCUMENT_EVENTS_WEBHOOK_URL`; sem URL, é retido e reprocessado. | **Diretriz de dados:** o backend é a autoridade de negócio para autenticação, regras, autorização e mutações do domínio. Os clientes web e modelos não devem contornar essas validações. Configure acesso ao PostgreSQL apenas para serviços confiáveis na rede privada. diff --git a/docs/SETUP_GUIDE.md b/docs/SETUP_GUIDE.md index b4bebd1..2821bc6 100644 --- a/docs/SETUP_GUIDE.md +++ b/docs/SETUP_GUIDE.md @@ -39,15 +39,29 @@ O primeiro acesso à aplicação começa pela tela de autenticação. Cadastre u ### Habilitar IA local (opcional) -Ollama e o serviço Python usam o perfil `local-ai`: +O Ollama roda diretamente no host, fora do Docker. Essa configuração evita a camada adicional de virtualização do runtime de modelos e permite que ele use melhor os recursos de CPU/GPU disponíveis na máquina. + +Instale o Ollama pelo [site oficial](https://ollama.com/download) e confirme que o comando está disponível: + +```bash +ollama --version +ollama serve +``` + +Em outro terminal, baixe os modelos usados pelo projeto: + +```bash +ollama pull bge-m3 +ollama pull qwen2.5:1.5b +``` + +Com o Ollama em execução no host, inicie o serviço Python pelo perfil `local-ai`: ```bash docker compose --profile local-ai up --build -d -docker compose --profile local-ai exec ollama ollama pull bge-m3 -docker compose --profile local-ai exec ollama ollama pull qwen2.5:1.5b ``` -Os modelos são baixados separadamente e ocupam espaço significativo. O healthcheck do container Ollama confirma que o serviço iniciou, não que cada modelo já foi baixado. A integração de IA deve ser validada no fluxo desejado; o app possui comportamento de fallback quando o assistente está indisponível. +O `ai-service` containerizado acessa o Ollama por `http://host.docker.internal:11434` (ou pelo valor de `OLLAMA_DOCKER_BASE_URL`). Para executar o serviço Python no próprio host, use `OLLAMA_BASE_URL=http://localhost:11434`. Os modelos são baixados separadamente e ocupam espaço significativo. Valide a integração no fluxo desejado; o app possui comportamento de fallback quando o assistente está indisponível. ## Opção B — Frontend/backend no host @@ -60,7 +74,7 @@ cp .env.example .env docker compose up -d postgres ``` -Se também precisar das integrações locais, inicie `n8n` ou o perfil `local-ai` separadamente. Os containers acessam PostgreSQL pelo hostname `postgres` na porta `5432`; processos no host usam `localhost` e a porta publicada `POSTGRES_PORT` (padrão `55432`). +Se também precisar das integrações locais, inicie `n8n` ou o perfil `local-ai` separadamente. Os containers acessam PostgreSQL pelo hostname `postgres` na porta `5432`; processos no host usam `localhost` e a porta publicada `POSTGRES_PORT` (padrão `55432`). O Ollama permanece no host e deve estar iniciado antes do `ai-service`. ### 2. Instale dependências e aplique as migrations @@ -122,7 +136,8 @@ O serviço lê sua configuração a partir de `ai-service/config.py`. O serviço | `N8N_PORT` | `5678` | Porta publicada do n8n. | | `DOCUMENT_MAX_SIZE_MB` | `20` | Tamanho máximo de upload aceito pela API. | | `DOCUMENT_EVENTS_WEBHOOK_URL` | vazio | Destino HTTP dos eventos de remoção de documento. Sem consumidor configurado, o evento permanece pendente e é tentado novamente. | -| `OLLAMA_PORT` | `11434` | Porta publicada quando o perfil `local-ai` está ativo. | +| `OLLAMA_PORT` | `11434` | Porta do Ollama executado no host. | +| `OLLAMA_DOCKER_BASE_URL` | `http://host.docker.internal:11434` | URL do Ollama vista pelo `ai-service` dentro do Docker. | | `OLLAMA_LLM_MODEL` | `qwen2.5:1.5b` | Modelo de geração local. | | `OLLAMA_EMBEDDING_MODEL` | `bge-m3` | Modelo de embedding local. | @@ -184,7 +199,7 @@ docker compose config --quiet - **Alteração de schema não aparece:** confira `_schema_migrations` e os logs do backend. Criar novamente um container não reaplica `init.sql` num volume já existente; crie uma migration versionada. - **Upload falha:** verifique o healthcheck `/health`, espaço no volume de documentos e o limite configurado em `DOCUMENT_MAX_SIZE_MB`. - **Busca ou chat sem trechos:** a busca depende de conteúdo/chunks disponíveis e isolados por projeto; um arquivo armazenado não implica, por si só, que foi extraído e indexado. -- **IA indisponível:** confirme perfil `local-ai`, healthchecks, URLs entre containers, download dos modelos e configuração Ollama. +- **IA indisponível:** confirme que o Ollama está em execução no host, teste `ollama list`, verifique o download dos modelos e confirme `OLLAMA_BASE_URL`. Para o `ai-service` em Docker, o endereço padrão é `http://host.docker.internal:11434`. ## Documentos relacionados