AnythingLLM: RAG pronto per la produzione in locale

#Perché AnythingLLM?

AnythingLLM occupa una nicchia precisa nell'ecosistema RAG locale: impone scelte progettuali più definite di Open WebUI nella gestione dei documenti, è più semplice di uno script LlamaIndex fatto in casa ed è più pronto per l'uso in produzione di una demo Streamlit. Il progetto è open source (MIT) ed è portato avanti da Mintplex Labs, un team che effettua commit con continuità dal 2023.

Workspaces isolati

Ogni workspace ha il proprio corpus di documenti, il proprio LLM, i propri embedding e il proprio system prompt. Non si mescola mai il RAG giuridico con il RAG per l'assistenza clienti.

Multiutente nativo

Autenticazione, ruoli (admin / manager / utente), permessi per workspace. Non serve un reverse proxy con autenticazione HTTP Basic come con un RAG Python essenziale.

Backend LLM intercambiabili

Ollama, LM Studio, llama.cpp server, vLLM, così come le API cloud (OpenAI, Anthropic, ecc.). È possibile cambiare il motore senza toccare i documenti indicizzati.

Agenti integrati

Web scraping, esecuzione SQL, calcoli, ricerca web, salvataggio di documenti — richiamabili con @agent nella chat. Non serve aggiungere LangChain.

API REST nativa

Un endpoint /api/v1/workspace/{slug}/chat permette di collegare qualsiasi applicazione a un workspace specifico. Formato di risposta stabile e documentato.

#Prerequisiti

Docker

Docker Desktop su Mac/Windows, oppure Docker Engine su Linux. Compose non è obbligatorio: basta un comando docker run per iniziare.

Ollama installato e funzionante

Il daemon deve rispondere su http://localhost:11434. Controlla con ollama list. Se Ollama non è ancora installato, installalo prima — è il backend predefinito di questo tutorial.

Un modello LLM Ollama

Almeno un modello da 8-9B come qwen3.5:9b (256k ctx, visione) o granite4.2:8b. Per un RAG di qualità in francese, puntare a mistral-small (24B) o qwen3.8:27b se la VRAM lo permette.

Un modello di embeddings

nomic-embed-text (predefinito) o bge-m3 per una migliore qualità multilingue. Da scaricare con ollama pull nomic-embed-text.

RAM / VRAM

Almeno 8 GB di RAM per il container; con 16 GB si lavora comodamente. Per la GPU, il fabbisogno dipende dal modello Ollama scelto (≈6-7 GB per un 9B Q4, ≈14 GB per un 24B Q4).

4 GB di spazio disco

Per il container, il database SQLite interno e il database vettoriale (LanceDB per impostazione predefinita). Da aumentare in base al volume dei documenti.

#1. Installazione Docker

L'immagine ufficiale è pubblicata su Docker Hub con il nome mintplexlabs/anythingllm. Mintplex mantiene tag stabili (latest, render) e l'immagine include tutto: Node.js, il server API, il frontend, LanceDB come database vettoriale, il worker di raccolta.

1. 01
   Creare una cartella di archiviazione

   AnythingLLM conserva tutto (configurazione, vettori, documenti) in un volume. Crea una cartella dedicata sull'host per non perdere nulla durante un aggiornamento dell'immagine.
2. 02
   Avviare il contenitore

   Il comando seguente monta la cartella di archiviazione, espone la porta 3001 e attiva SYS_ADMIN (richiesto da alcuni scraper interni per il rendering PDF/web).
3. 03
   Aprire l'UI

   Una volta avviato il container, l'interfaccia è disponibile su http://localhost:3001. Al primo avvio, una procedura guidata ti aiuta a configurare la password admin e il backend LLM.

mkdir -p $HOME/anythingllm
touch $HOME/anythingllm/.env

docker run -d -p 3001:3001 \
  --cap-add SYS_ADMIN \
  -v $HOME/anythingllm:/app/server/storage \
  -v $HOME/anythingllm/.env:/app/server/.env \
  -e STORAGE_DIR="/app/server/storage" \
  --name anythingllm \
  --restart unless-stopped \
  mintplexlabs/anythingllm:latest

docker logs -f anythingllm

# À l'écran : "Primary server in HTTP mode listening on port 3001"
# puis : "Collector hot directory found and ready"

#2. Collegare Ollama come backend

Al primo accesso a http://localhost:3001, AnythingLLM avvia una procedura di configurazione iniziale che richiede di scegliere il LLM Provider, il modello di embedding e il database vettoriale, e di creare l'account amministratore. La configurazione può essere effettuata anche successivamente in Settings.

1. 01
   LLM Provider → Ollama

   Seleziona Ollama nell'elenco. Inserisci l'URL di base: http://host.docker.internal:11434 (Mac/Windows) o http://172.17.0.1:11434 (su Linux, per impostazione predefinita).
2. 02
   Scegliere il modello di chat

   Il menu a discesa elenca i tuoi modelli Ollama. Scegli il LLM principale (ad esempio: mistral-small (24B) per un buon compromesso qualità/VRAM in francese, oppure qwen3.5:9b se la VRAM è più limitata). Imposta la finestra di contesto a 8192 o 16384 se il modello lo supporta.
3. 03
   Embedding Provider → Ollama

   Lo stesso backend per gli embedding, oppure scegliere Native (modello locale integrato) se vuoi evitare di caricare un modello di embedding in Ollama. Per AnythingLLM in francese, nomic-embed-text svolge bene il compito, mentre bge-m3 (tramite Ollama) offre risultati migliori.
4. 04
   Vector Database

   Mantieni LanceDB come opzione predefinita. È integrato, non ha dipendenze esterne e offre buone prestazioni fino a diverse centinaia di migliaia di chunk. Se gestisci già Qdrant o Chroma altrove, puoi configurarli qui.

Mac / Windows : http://host.docker.internal:11434
Linux (bridge)  : http://172.17.0.1:11434
Linux (--network host) : http://localhost:11434

#3. Workspaces, documenti e embedding

Un workspace è l'unità fondamentale di AnythingLLM. Riunisce un corpus documentale, un LLM, i parametri di chat e le conversazioni associate. In genere si crea un workspace per ciascun ambito: Legale, Supporto, Risorse umane, Monitoraggio tecnologico.

1. 01
   Creare un workspace

   Barra laterale sinistra → New Workspace. Dagli un nome esplicito (es.: "contrats-2026"). Lo slug viene generato automaticamente e sarà utilizzato nell'URL dell'API.
2. 02
   Caricare documenti

   Clicca sull'icona di upload nel workspace. AnythingLLM accetta PDF, DOCX, TXT, MD, CSV, EPUB e molto altro. È anche possibile indicare un URL web o un repository GitHub: uno scraper interno recupera il contenuto.
3. 03
   Move to Workspace + Embed

   I file caricati vanno prima nel Document Picker (area temporanea). Seleziona quelli da indicizzare, poi usa Move to Workspace. AnythingLLM suddivide i documenti in chunk, calcola gli embedding tramite Ollama e li memorizza in LanceDB.
4. 04
   Imposta il prompt di sistema

   Workspace settings → Chat Settings → Prompt. È qui che si definisce il ruolo ("Sei un assistente giuridico. Cita sempre l'articolo esatto del contratto"). Anche il top-K del retrieval (Document Similarity Threshold) si regola qui.

Chunk size

Per impostazione predefinita, 1000 caratteri con 20 caratteri di sovrapposizione. Per contratti giuridici in cui ogni clausola conta, ridurre a 500. Per documentazione tecnica con blocchi di codice, aumentare a 1500.

Modello di embedding

nomic-embed-text (768 dimensioni) è veloce ma offre risultati mediocri in francese. bge-m3 (1024 dimensioni, multilingue) guadagna il 10-15% di precisione sui contenuti in francese. mxbai-embed-large è una buona via di mezzo.

Modalità chat vs query

Chat utilizza la cronologia della conversazione + RAG. Query si basa esclusivamente sul RAG: se nei documenti non trova alcuna corrispondenza, il LLM rifiuta di rispondere. Query è l'impostazione giusta per gli usi in cui le allucinazioni sono vietate.

# Modèle par défaut, multilingue correct
ollama pull nomic-embed-text

# Meilleur pour le français, 1024 dimensions
ollama pull bge-m3

# Vérifier qu'ils tournent
ollama list | grep embed

#4. Agenti integrati

Oltre al solo RAG, AnythingLLM include un sistema di agenti: si invoca @agent nella chat e il LLM può quindi utilizzare skill (strumenti) per cercare informazioni al di fuori della base documentale. Non serve LangChain né scrivere codice per il tool calling: è tutto integrato.

web-browsing

L'agente apre un URL e legge la pagina (rendering del DOM, non soltanto HTML grezzo). Utile per far rispondere l'assistente su informazioni non presenti nel RAG.

web-scraping

Variante: estrae i contenuti di una pagina tramite scraping e la aggiunge come documento allo spazio di lavoro. Utile per arricchire il corpus al volo.

save-document

L'agente genera un documento (riassunto, sintesi) e lo salva nel workspace. Utile per workflow del tipo «leggere 10 articoli → produrre una nota».

sql-connector

Collega un database PostgreSQL/MySQL e l'agente può scrivere ed eseguire query SQL per rispondere a domande analitiche. Ovviamente, va abbinato a un account SQL in sola lettura.

rag-memory

Memoria a lungo termine condivisa tra le conversazioni. L'agente può salvare fatti che potrà ritrovare nelle sessioni future.

@agent va sur https://blog.example.com/rapport-2026 et fais-moi
un résumé en 5 points des chiffres-clés.

@agent connecte-toi à la base postgres-prod et donne-moi le top 10
des clients par chiffre d'affaires sur le trimestre.

@agent enregistre la conversation précédente sous forme de note
dans ce workspace, titre : "Synthèse veille IA juin 2026".

#5. Esporre l'API

Per collegare AnythingLLM alle tue applicazioni (chatbot interno, plugin Slack, integrazione aziendale), l'API REST è l'interfaccia canonica. Ogni workspace diventa un endpoint limitato al proprio corpus.

1. 01
   Generare una chiave API

   Settings → API Keys → Generate New API Key. Annota la chiave: viene visualizzata una sola volta. Puoi crearne diverse, ad esempio una per ogni applicazione client, e revocarle singolarmente.
2. 02
   Identificare lo slug dello spazio di lavoro

   È visibile nell'URL quando sei nel workspace: .../workspace/contrats-2026 → slug = contrats-2026.
3. 03
   Testare con curl

   L'endpoint principale è POST /api/v1/workspace/{slug}/chat. Header Authorization: Bearer YOUR_KEY, corpo JSON con message e mode (chat o query).

curl -X POST http://localhost:3001/api/v1/workspace/contrats-2026/chat \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quelle est la durée de préavis dans le contrat ACME ?",
    "mode": "query"
  }'

import requests

API_KEY   = "votre-cle-api"
WORKSPACE = "contrats-2026"
BASE_URL  = "http://localhost:3001"

def ask(question: str, mode: str = "chat") -> dict:
    response = requests.post(
        f"{BASE_URL}/api/v1/workspace/{WORKSPACE}/chat",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"message": question, "mode": mode},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

result = ask("Résume la clause 4 du contrat ACME signé en mars.")
print(result["textResponse"])
for source in result.get("sources", []):
    print(" -", source["title"])

#Risoluzione dei problemi

"Could not reach Ollama at ..."

Errore più comune. Controlla l'URL: dal container Docker, localhost non punta all'host. Usa host.docker.internal su Mac/Win, l'IP del bridge o --network host su Linux.

Embedding molto lento

L'embedder viene eseguito sulla CPU per impostazione predefinita se non hai scaricato il modello in Ollama. Forza l'uso di Ollama come provider di embedding e controlla ollama ps durante l'indicizzazione per vedere la GPU al lavoro.

Il RAG non trova un passaggio evidente

Tre cause tipiche: chunk troppo grandi (passa da 1000 a 500 caratteri), un modello di embedding poco efficace in francese (passa a bge-m3), oppure un valore di Document Similarity Threshold troppo restrittivo nelle impostazioni del workspace.

L'agente entra in un ciclo di chiamate allo strumento

Modello non abbastanza potente. Passa a glm-4.7-flash, qwen3.8:27b se possibile, o mistral-small. Per gli agenti, evita i modelli molto piccoli (2-3B) che non hanno ricevuto un fine-tuning sull'uso degli strumenti.

Container terminato dopo alcune ore

OOM del kernel: Docker non ha abbastanza memoria allocata. Su Docker Desktop, aumenta il limite di RAM a 8-16 GB (Settings → Resources).

Aggiornamento dell'immagine

docker pull mintplexlabs/anythingllm:latest puis docker rm -f anythingllm et relancer le run avec les mêmes volumes. Les données dans $HOME/anythingllm sont conservées.

#Per approfondire

A seconda della direzione che vuoi seguire:

Confrontare AnythingLLM con le alternative no-code

« RAG locale con Ollama senza dover scrivere codice (Open WebUI, AnythingLLM) » propone un confronto diretto con Open WebUI sullo stesso backend Ollama.

Ottimizzare gli embedding FR

« I migliori modelli di embedding FR » confronta bge-m3, Solon, E5 e fornisce le impostazioni corrette per AnythingLLM.

Portare oltre lo stack di produzione

«Distribuire un LLM in produzione con Docker Compose» mostra come integrare AnythingLLM in uno stack con un reverse proxy Traefik, Qdrant esterno e backup automatizzati.