Self-Hosting Cognee: Scegliere LLM su Ollama
Test di Cognee con LLM locali - risultati reali
Cognee è un framework Python per costruire grafi di conoscenza da documenti utilizzando LLM. Ma funziona con modelli auto-hostati?
L’ho testato con diversi LLM locali per scoprire.
Questo è una pagina di un file PDF di pricelist che ho provato a elaborare.
TL;DR
Cognee probabilmente funziona bene con LLM intelligenti con centinaia di miliardi di parametri, ma per configurazioni RAG auto-hostate previste per estrarre automaticamente dati da PDF (come pricelist), è fallito sul mio hardware. L’elevata dipendenza del framework da output strutturati rende difficile il funzionamento affidabile per modelli locali più piccoli.
Cosa è Cognee?
Cognee è un framework open-source Python progettato per costruire grafi di conoscenza da documenti non strutturati utilizzando LLM. A differenza dei sistemi RAG tradizionali che semplicemente frammentano e incapsulano i documenti, Cognee cerca di creare una comprensione semantica estragendo entità, relazioni e concetti in un database grafo. Questo approccio si allinea con architetture RAG avanzate come GraphRAG, che promettono un recupero contestuale migliore.
Il framework supporta diversi backend:
- Database vettoriali: LanceDB (predefinito), con supporto per altri database vettoriali
- Database grafo: Kuzu (predefinito), permettendo query complesse su relazioni
- Fornitori LLM: OpenAI, Anthropic, Ollama e altri
- Frameworks per output strutturati: BAML e Instructor per generazione vincolata
Per gli appassionati di auto-hosting, la compatibilità di Cognee con Ollama la rende attraente per deploy locali. Tuttavia, il diavolo è nei dettagli - come vedremo, i requisiti per l’output strutturato creano sfide significative per i modelli più piccoli.
Perché l’Output Strutturato Conta
Cognee si basa pesantemente sull’output strutturato per estrarre informazioni da documenti in un formato coerente. Quando si elabora un documento, l’LLM deve restituire un JSON correttamente formattato che contenga entità, relazioni e metadati. Questo è dove molti modelli più piccoli incontrano difficoltà.
Se stai lavorando con output strutturati nei tuoi progetti, capire queste limitazioni è cruciale. Le sfide che ho incontrato con Cognee si specchiano in problemi più ampi nell’ecosistema LLM quando si lavora con modelli locali.
Configurazione
Ecco la mia configurazione funzionante per Cognee con Ollama. Nota le impostazioni chiave che abilitano l’operazione locale:
TELEMETRY_DISABLED=1
# STRUCTURED_OUTPUT_FRAMEWORK="instructor"
STRUCTURED_OUTPUT_FRAMEWORK="BAML"
# Configurazione LLM
LLM_API_KEY="ollama"
LLM_MODEL="gpt-oss:20b"
LLM_PROVIDER="ollama"
LLM_ENDPOINT="http://localhost:11434/v1"
# LLM_MAX_TOKENS="25000"
# Configurazione Embedding
EMBEDDING_PROVIDER="ollama"
EMBEDDING_MODEL="avr/sfr-embedding-mistral:latest"
EMBEDDING_ENDPOINT="http://localhost:11434/api/embeddings"
EMBEDDING_DIMENSIONS=4096
HUGGINGFACE_TOKENIZER="Salesforce/SFR-Embedding-Mistral"
# Configurazione BAML
BAML_LLM_PROVIDER="ollama"
BAML_LLM_MODEL="gpt-oss:20b"
BAML_LLM_ENDPOINT="http://localhost:11434/v1"
# Impostazioni Database (predefinite)
DB_PROVIDER="sqlite"
VECTOR_DB_PROVIDER="lancedb"
GRAPH_DATABASE_PROVIDER="kuzu"
# Autenticazione
REQUIRE_AUTHENTICATION=False
ENABLE_BACKEND_ACCESS_CONTROL=False
Scelte di Configurazione Principali
Framework per Output Strutturato: Ho testato BAML, che fornisce un controllo migliore sugli schemi di output rispetto a un semplice prompt. BAML è stato progettato specificamente per output LLM strutturati, rendendolo un’opzione naturale per compiti di estrazione di grafi di conoscenza.
Fornitore LLM: L’uso dell’endpoint API OpenAI-compatibile di Ollama (/v1) permette a Cognee di trattarlo come qualsiasi altro servizio OpenAI.
Modello Embedding: Il modello SFR-Embedding-Mistral (4096 dimensioni) fornisce embedding di alta qualità. Per ulteriori informazioni sulla selezione e sulle prestazioni dei modelli embedding, i modelli Qwen3 embedding offrono eccellenti alternative con forti capacità multilingue.
Database: SQLite per metadati, LanceDB per vettori e Kuzu per il grafo di conoscenza mantengono tutto locale senza dipendenze esterne.
Installazione di Cognee
L’installazione è semplice utilizzando uv (o pip). Consiglio di utilizzare uv per una risoluzione più rapida delle dipendenze:
uv venv && source .venv/bin/activate
uv pip install cognee[ollama]
uv pip install cognee[baml]
uv pip install cognee[instructor]
uv sync --extra scraping
uv run playwright install
sudo apt-get install libavif16
Le opzioni [ollama], [baml] e [instructor] installano le dipendenze necessarie per l’operazione locale degli LLM e per l’output strutturato. L’opzione di scraping aggiunge capacità di scraping web, mentre Playwright abilita l’elaborazione di pagine con JavaScript.
Codice di Esempio e Utilizzo
Ecco il workflow base per elaborare documenti con Cognee. Innanzitutto, aggiungiamo documenti e costruiamo il grafo di conoscenza:
msy-add.py:
import cognee
import asyncio
async def main():
# Crea un ambiente pulito per cognee -- ripristina dati e stato del sistema
await cognee.prune.prune_data()
await cognee.prune.prune_system(metadata=True)
# Aggiungi contenuti di esempio
await cognee.add(
"/home/rg/prj/prices/msy_parts_price_20251224.pdf",
node_set=["price_list", "computer_parts", "2025-12-24", "aud"]
)
# Processa con LLM per costruire il grafo di conoscenza
await cognee.cognify()
if __name__ == '__main__':
asyncio.run(main())
Il parametro node_set fornisce tag semantici che aiutano a categorizzare il documento nel grafo di conoscenza. Il metodo cognify() è dove accade la magia (o i problemi) - invia frammenti del documento all’LLM per l’estrazione di entità e relazioni.
msy-search.py:
import cognee
import asyncio
async def main():
# Cerca nel grafo di conoscenza
results = await cognee.search(
query_text="Quali prodotti sono nell'elenco dei prezzi?"
# query_text="Qual è il prezzo medio per la RAM da 32 GB (2x16 GB)?"
)
# Stampa
for result in results:
print(result)
if __name__ == '__main__':
asyncio.run(main())
A differenza della ricerca vettoriale tradizionale nei sistemi RAG, Cognee interroga il grafo di conoscenza, teoricamente abilitando un recupero più sofisticato basato su relazioni. Questo è simile a come funzionano le architetture RAG avanzate, ma richiede che la costruzione iniziale del grafo abbia successo.
Risultati dei Test: Prestazioni degli LLM
Ho testato Cognee con un caso d’uso reale: l’estrazione di informazioni sui prodotti da un PDF di un elenco dei prezzi per componenti di computer. Questo sembrava un caso ideale - dati strutturati in formato tabellare. Ecco cosa è successo con ogni modello:
Modelli Testati
1. gpt-oss:20b (20 miliardi di parametri)
- Risultato: Fallito a causa di errori di codifica dei caratteri
- Problema: Ha restituito output strutturati difettosi con codici di caratteri errati
- Nota: Nonostante sia stato progettato specificamente per la compatibilità open-source, non è riuscito a mantenere un formato JSON coerente
2. qwen3:14b (14 miliardi di parametri)
- Risultato: Non ha prodotto output strutturati
- Problema: Il modello generava testo ma non nel formato JSON richiesto
- Nota: I modelli Qwen in genere si comportano bene, ma questa attività ha superato le sue capacità di output strutturati
3. deepseek-r1:14b (14 miliardi di parametri)
- Risultato: Non ha prodotto output strutturati
- Problema: Simile a qwen3, non è riuscito a rispettare i requisiti dello schema BAML
- Nota: Le capacità di ragionamento non hanno aiutato nel rispetto del formato
4. devstral:24b (24 miliardi di parametri)
- Risultato: Non ha prodotto output strutturati
- Problema: Anche con più parametri, non è riuscito a generare JSON coerente
- Nota: Modello specializzato per il coding ha comunque avuto difficoltà nel rispettare lo schema rigoroso
5. ministral-3:14b (14 miliardi di parametri)
- Risultato: Non ha prodotto output strutturati
- Problema: Il modello più piccolo di Mistral non è riuscito a gestire i requisiti dell’output strutturato
6. qwen3-vl:30b-a3b-instruct (30 miliardi di parametri)
- Risultato: Non ha prodotto output strutturati
- Problema: Le capacità visive non hanno aiutato nell’estrazione delle tabelle PDF in questo contesto
7. gpt-oss:120b (120 miliardi di parametri)
- Risultato: Non ha completato l’elaborazione dopo più di 2 ore
- Hardware: Configurazione GPU consumer
- Problema: Il modello era troppo grande per un uso pratico auto-hostato, anche se potrebbe aver funzionato in seguito
Principali Risultati
Limite della Dimensione del Frammento: Cognee utilizza frammenti da 4k token quando elabora documenti con Ollama. Per documenti complessi o modelli con finestre di contesto più ampie, sembra eccessivamente restrittivo. Il framework non fornisce un modo semplice per modificare questo parametro.
Requisiti per l’Output Strutturato: Il problema principale non è l’intelligenza del modello ma il rispetto del formato. Questi modelli possono comprendere il contenuto, ma mantenere un schema JSON coerente durante l’estrazione risulta difficile. Questo si allinea con le sfide più ampie nel far rispettare i vincoli di output ai modelli locali.
Considerazioni Hardware: Anche quando un modello sufficientemente grande potrebbe funzionare (come gpt-oss:120b), i requisiti hardware lo rendono impraticabile per la maggior parte dei casi di auto-hosting. Sarebbero necessari una grande quantità di memoria GPU e potenza di calcolo.
Confronto con le Best Practice per Output Strutturati
Quest’esperienza rafforza lezioni apprese lavorando con output strutturati in diversi fornitori LLM. Le API commerciali da OpenAI, Anthropic e Google spesso hanno meccanismi interni per imporre gli schemi di output, mentre i modelli locali richiedono approcci più sofisticati come il campionamento basato su grammatica o passaggi di validazione multipli.
Per un’analisi più approfondita su come scegliere il giusto LLM per Cognee su Ollama, inclusi confronti dettagliati tra diverse dimensioni di modello e le loro caratteristiche di prestazione, sono disponibili guide complete che possono aiutarti a prendere una decisione informata.
Alternative per RAG Auto-Hostato
Se sei impegnato nell’auto-hosting e devi estrarre dati strutturati da documenti, considera queste alternative:
1. RAG Tradizionale con Estrazione Più Semplice
Invece di costruire un grafo di conoscenza complesso all’inizio, utilizza il RAG tradizionale con frammentazione dei documenti e ricerca vettoriale. Per l’estrazione di dati strutturati:
- Parsa le tabelle direttamente utilizzando librerie come
pdfplumberotabula-py - Utilizza prompt più semplici che non richiedono un rispetto rigoroso degli schemi
- Implementa una validazione post-elaborazione in Python invece di affidarsi al formato di output dell’LLM
2. Modelli di Embedding Specializzati
La qualità dei tuoi embedding influisce in modo significativo sulle prestazioni del recupero. Considera l’utilizzo di modelli di embedding ad alte prestazioni che funzionano bene localmente. I moderni modelli di embedding come quelli offerti da Qwen3 forniscono un eccellente supporto multilingue e possono migliorare drasticamente l’accuratezza del tuo sistema RAG.
3. Reranking per Risultati Migliori
Anche con architetture RAG più semplici, l’aggiunta di un passo di reranking può migliorare significativamente i risultati. Dopo il recupero iniziale tramite ricerca vettoriale, un modello reranker può valutare meglio la rilevanza. Questo approccio a due fasi spesso supera sistemi più complessi a un solo stadio, specialmente quando si lavora con hardware vincolato.
4. Strategie di Ricerca ibride
Combinare la ricerca vettoriale con la ricerca tradizionale tramite keyword (BM25) spesso fornisce risultati migliori di ciascuna singola opzione. Molti database vettoriali moderni supportano la ricerca ibrida direttamente.
5. Considerare Alternative ai Database Vettoriali
Se stai costruendo un sistema RAG da zero, valuta diversi database vettoriali in base alle tue esigenze. Le opzioni vanno da database embedded leggeri a sistemi distribuiti progettati per lo scale di produzione.
Considerazioni per il Deployment con Docker
Per il deployment in produzione con auto-hosting, containerizzare la tua configurazione RAG semplifica il deployment e lo scaling. Quando esegui Cognee o framework simili con Ollama:
# Esegui Ollama in un container
docker run -d --gpus=all -v ollama:/root/.ollama -p 11404:11434 --name ollama ollama/ollama
# Scarica i tuoi modelli
docker exec -it ollama ollama pull gpt-oss:20b
# Configura Cognee per connettersi all'endpoint del container
Assicurati di configurare correttamente il pass-through GPU e i montaggi delle volumetriche per la persistenza dei modelli.
Lezioni Imparate
1. Adatta gli Strumenti all’Hardware: Cognee è progettato per LLM a larga scala in cloud. Se stai auto-hostando su hardware consumer, architetture più semplici potrebbero essere più pratiche.
2. L’Output Strutturato è Difficile: Ottenere un rispetto coerente degli schemi da LLM locali rimane una sfida. Se l’applicazione dipende criticamente dall’output strutturato, utilizza API commerciali o implementa logica di validazione e retry robusta.
3. Testa Fin da Subito: Prima di impegnarti in un framework, testalo con il tuo caso d’uso specifico e l’hardware. Ciò che funziona nei demo potrebbe non funzionare a grande scala o con i tuoi documenti.
4. Considera Approcci Ibridi: Utilizza API commerciali per compiti complessi di estrazione e modelli locali per query più semplici per bilanciare costi e capacità.
Lettura Consigliata
Output Strutturato con LLM
Comprendere l’output strutturato è cruciale per framework come Cognee. Questi articoli esplorano in profondità come ottenere risposte coerenti e conformi agli schemi dagli LLM:
- Scegliere il giusto LLM per Cognee: Configurazione locale Ollama
- LLM con Output Strutturato: Ollama, Qwen3 e Python o Go
- Output strutturato tra i fornitori LLM più popolari - OpenAI, Gemini, Anthropic, Mistral e AWS Bedrock
- Problemi di Output Strutturato di Ollama GPT-OSS
Architettura e Implementazione RAG
Per approcci alternativi o complementari all’estrazione di conoscenza e recupero:
- RAG avanzato: LongRAG, Self-RAG e GraphRAG
- Confronto tra database vettoriali per RAG
- Costruire server MCP in Python: Ricerca Web e Scraping
Embedding e Reranking
Migliorare la qualità del recupero attraverso embedding e reranking migliori:
- Modelli di embedding e reranking di Qwen3 su Ollama: Prestazioni all’avanguardia
- Reranking con modelli di embedding
- Reranking di documenti testuali con Ollama e modello di embedding Qwen3 - in Go
