WIP MITDidattici

FastAPI RAG Ollama

Costruisci un microservizio RAG self-hosted con FastAPI + Ollama + RediSearch HNSW

Stato
WIP
Licenza
MIT
Categoria
Didattici
Aggiornato
Source GitHub

Stato del progetto

Descrizione

FastAPI RAG Ollama mostra come costruire un microservizio RAG (Retrieval Augmented Generation) self-hosted senza dipendere da cloud AI provider (OpenAI, Anthropic, Cohere, Google). Il pattern è preso direttamente dal portfolio del progetto (`ml-service/` in produzione reale su VPS Hetzner Nuremberg), distillato in un tutorial 8 settimane progressivo accessibile a sviluppatori Python mid. Il percorso copre passo dopo passo: setup Ollama locale (llama3.1:8b come default, alternative llama3.2:3b, mistral-nemo:12b, qwen2.5:14b discusse con trade-off di latency e qualità), embedding generation con sentence-transformers all-MiniLM-L6-v2 (384 dimensioni, batch async per throughput), vector store RediSearch HNSW con index creation guidata, similarity search KNN, hybrid search (dense + BM25 sparse), re-rank con cross-encoder ms-marco-MiniLM-L-6-v2 per migliorare precision top-K, prompt engineering pattern (system prompt template, context injection con citation tracking, chain-of-thought reasoning, output JSON schema enforcement), graceful degradation se Ollama down (deterministic fallback ai top-K candidates raw + warning user-facing, no fallback cloud automatico per coerenza privacy), benchmark latency P50/P95/P99 con locust + report markdown, observability con OpenTelemetry tracing end-to-end, deploy systemd unit hardened (NoNewPrivileges, ProtectSystem=strict, PrivateTmp). La filosofia è 'AI on-prem first': dimostra che si può fare RAG di qualità con Ollama + RediSearch senza fornitori cloud, riducendo costi a €0/mese e proteggendo dati sensibili (GDPR, data residency EU). Il dominio scelto è un knowledge base di documenti tecnici (articoli, ADR, manuali), abbastanza vicino al caso reale da essere immediatamente utile, abbastanza generico da essere riadattato a contesti enterprise diversi. License MIT, codice production-grade riutilizzabile.

Funzionalità chiave

  • Ollama on-prem integration

    Client HTTP per Ollama API, model warm-up, streaming response support, fallback chain configurabile (llama3.1:8b → llama3.2:3b).

  • Embedding pipeline sentence-transformers

    all-MiniLM-L6-v2 model 384-dim, batch embedding async, caching embedding per content-hash, document chunking strategy (sentence-aware).

  • RediSearch HNSW vector store

    Index creation con HNSW parameters tuning (M, efConstruction, efRuntime), KNN search, metadata filtering, hybrid search BM25 + dense.

  • Re-rank cross-encoder

    ms-marco-MiniLM-L-6-v2 per re-ranking top-K candidates, latency budget controllato, A/B test re-rank on/off.

  • Graceful degradation

    Se Ollama down, endpoint restituisce risultato deterministico (top-K candidates raw) + warning 'AI unavailable', nessun crash, no fallback cloud automatico.

  • Benchmark suite locust

    Load test con locust, latency P50/P95/P99 reporting, throughput RPS, memory footprint Ollama monitoring.

  • Prompt engineering patterns

    System prompt template, context injection con citation tracking, chain-of-thought reasoning, output JSON schema enforcement.

  • Deploy production-grade

    systemd unit hardening (NoNewPrivileges, ProtectSystem=strict), env var externalization, log structured JSON, healthcheck endpoint con Ollama liveness.

Tech stack

  • FastAPI 0.115+
  • Python 3.12
  • Ollama
  • Redis Stack 7
  • RediSearch HNSW
  • sentence-transformers
  • cross-encoder
  • asyncio
  • Pydantic v2
  • locust
  • OpenTelemetry

Casi d'uso

  • Sviluppatori che vogliono imparare RAG production-grade senza dipendere da OpenAI o Anthropic
  • Team enterprise con vincoli GDPR/data residency che cercano stack AI 100% on-prem
  • Hobbyisti tech con homelab che vogliono un knowledge base privato con AI
  • PMI EU che valutano AI on-prem come alternativa a SaaS (riduzione costi + privacy)

Roadmap

  1. v0.1.0 Pianificata

    Baseline RAG: embedding + vector search

    • Setup Ollama + sentence-transformers
    • RediSearch HNSW index creation
    • Endpoint /embed e /search
    • Chunking strategy sentence-aware
  2. v0.5.0 Pianificata

    Re-rank + Hybrid + Generation

    • Cross-encoder re-rank pipeline
    • Hybrid search BM25 + dense
    • Generation endpoint con prompt template
    • Graceful degradation se Ollama down
  3. v1.0.0 Pianificata

    Production hardening + Benchmark

    • Benchmark suite locust + report markdown
    • OpenTelemetry tracing end-to-end
    • systemd unit hardened deploy guide
    • Documentazione MkDocs completa

A chi è rivolto

  • Pro Dev junior-mid
  • Pro Dev senior

Quick Start

Avvia il progetto localmente in pochi comandi. 

# Quick start (work-in-progress, repo non ancora pubblicato)
# git clone https://github.com/<tba>/fastapi-rag-ollama.git
# cd fastapi-rag-ollama
# ollama pull llama3.1:8b && ollama pull nomic-embed-text
# docker compose up -d redis-stack
# uv venv && uv pip install -e .[dev]
# uvicorn app.main:create_app --factory --reload

Contribuisci al progetto

FastAPI RAG Ollama è open source. Apri una issue, proponi una pull request o lascia una stella su GitHub: ogni contributo, anche piccolo, è benvenuto.

  • ⭐ Lascia una stella se ti è utile
  • 🐛 Segnala bug o proponi feature via issue
  • 🔧 Invia pull request con fix o miglioramenti
  • 📣 Condividi il progetto se lo trovi interessante
Star su GitHubApri una issuePull request
← ⭐ Vedi su GitHub