Auto-hospedagem do Cognee: Escolhendo o LLM no Ollama
Testando o Cognee com LLMs locais – resultados reais
Cognee é um framework em Python para construir grafos de conhecimento a partir de documentos usando LLMs. Mas ele funciona com modelos auto-hospedados?
Testei-o com vários LLMs locais para descobrir.
Essa é uma página de PDF de uma lista de preços que tentei processar.
TL;DR
O Cognee provavelmente funciona bem com LLMs inteligentes com centenas de bilhões de parâmetros, mas para configurações de RAG auto-hospedado que esperam extrair dados automaticamente de PDFs (como listas de preços), ele falhou em meu hardware. A forte dependência do framework em saída estruturada torna desafiador para modelos locais menores performar de forma confiável.
O que é o Cognee?
O Cognee é um framework de código aberto em Python projetado para construir grafos de conhecimento a partir de documentos não estruturados usando LLMs. Diferente dos sistemas RAG tradicionais que simplesmente dividem e incorporam documentos, o Cognee tenta criar uma compreensão semântica ao extrair entidades, relacionamentos e conceitos para um banco de dados de grafos. Essa abordagem alinha-se com arquiteturas RAG avançadas como GraphRAG, que promete melhor recuperação contextual.
O framework suporta vários backends:
- Bancos de dados vetoriais: LanceDB (padrão), com suporte para outros armazenamentos vetoriais
- Bancos de dados de grafos: Kuzu (padrão), permitindo consultas de relacionamentos complexos
- Provedores de LLM: OpenAI, Anthropic, Ollama e outros
- Frameworks de saída estruturada: BAML e Instructor para geração restrita
Para entusiastas de auto-hospedagem, a compatibilidade do Cognee com o Ollama o torna atraente para implantações locais. No entanto, o diabo está nos detalhes - como veremos, os requisitos de saída estruturada criam desafios significativos para modelos menores.
Por que a Saída Estruturada Importa
O Cognee depende fortemente de saída estruturada para extrair informações de documentos em um formato consistente. Ao processar um documento, o LLM deve retornar JSON formatado corretamente contendo entidades, relacionamentos e metadados. É onde muitos modelos menores lutam.
Se você estiver trabalhando com saída estruturada em seus próprios projetos, entender essas restrições é crucial. Os desafios que encontrei com o Cognee espelham problemas mais amplos no ecossistema de LLMs ao trabalhar com modelos locais.
Configuração
Aqui está minha configuração funcional para o Cognee com o Ollama. Observe as definições-chave que habilitam a operação local:
TELEMETRY_DISABLED=1
# STRUCTURED_OUTPUT_FRAMEWORK="instructor"
STRUCTURED_OUTPUT_FRAMEWORK="BAML"
# Configuração do LLM
LLM_API_KEY="ollama"
LLM_MODEL="gpt-oss:20b"
LLM_PROVIDER="ollama"
LLM_ENDPOINT="http://localhost:11434/v1"
# LLM_MAX_TOKENS="25000"
# Configuração de 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"
# Configuração BAML
BAML_LLM_PROVIDER="ollama"
BAML_LLM_MODEL="gpt-oss:20b"
BAML_LLM_ENDPOINT="http://localhost:11434/v1"
# Configurações do Banco de Dados (padrão)
DB_PROVIDER="sqlite"
VECTOR_DB_PROVIDER="lancedb"
GRAPH_DATABASE_PROVIDER="kuzu"
# Autenticação
REQUIRE_AUTHENTICATION=False
ENABLE_BACKEND_ACCESS_CONTROL=False
Escolhas de Configuração Chave
Framework de Saída Estruturada: Testei o BAML, que fornece melhor controle sobre esquemas de saída em comparação com prompts básicos. O BAML é projetado especificamente para saídas estruturadas de LLMs, tornando-o uma escolha natural para tarefas de extração de grafos de conhecimento.
Provedor de LLM: Usar o endpoint de API compatível com OpenAI do Ollama (/v1) permite que o Cognee o trate como qualquer outro serviço estilo OpenAI.
Modelo de Embedding: O modelo SFR-Embedding-Mistral (4096 dimensões) fornece embeddings de alta qualidade. Para mais sobre seleção e desempenho de modelos de embedding, os modelos de embedding Qwen3 oferecem excelentes alternativas com fortes capacidades multilíngues.
Bancos de Dados: SQLite para metadados, LanceDB para vetores e Kuzu para o grafo de conhecimento mantêm tudo local sem dependências externas.
Instalação do Cognee
A instalação é direta usando uv (ou pip). Recomendo usar uv para resolução de dependências mais rápida:
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
Os extras [ollama], [baml] e [instructor] instalam as dependências necessárias para operação local de LLM e saída estruturada. O extra de scraping adiciona capacidades de raspagem web, enquanto o Playwright habilita o processamento de páginas renderizadas com JavaScript.
Exemplo de Código e Uso
Aqui está o fluxo de trabalho básico para processar documentos com o Cognee. Primeiro, adicionamos documentos e construímos o grafo de conhecimento:
msy-add.py:
import cognee
import asyncio
async def main():
# Crie uma folha limpa para o cognee -- reinicie dados e estado do sistema
await cognee.prune.prune_data()
await cognee.prune.prune_system(metadata=True)
# Adicione conteúdo de exemplo
await cognee.add(
"/home/rg/prj/prices/msy_parts_price_20251224.pdf",
node_set=["price_list", "computer_parts", "2025-12-24", "aud"]
)
# Processe com LLMs para construir o grafo de conhecimento
await cognee.cognify()
if __name__ == '__main__':
asyncio.run(main())
O parâmetro node_set fornece tags semânticas que ajudam a categorizar o documento no grafo de conhecimento. O método cognify() é onde a mágica (ou problemas) acontecem - ele envia fragmentos de documentos ao LLM para extração de entidades e relacionamentos.
msy-search.py:
import cognee
import asyncio
async def main():
# Pesquise no grafo de conhecimento
results = await cognee.search(
query_text="Quais produtos estão na lista de preços?"
# query_text="Qual é o preço médio para 32GB de RAM (módulos 2x16GB)?"
)
# Imprima
for result in results:
print(result)
if __name__ == '__main__':
asyncio.run(main())
Diferente da busca vetorial tradicional em sistemas RAG, o Cognee consulta o grafo de conhecimento, permitindo teoricamente uma recuperação baseada em relacionamentos mais sofisticada. Isso é semelhante a como as arquiteturas RAG avançadas funcionam, mas requer que a construção inicial do grafo tenha sucesso.
Resultados dos Testes: Desempenho dos LLMs
Testei o Cognee com um caso de uso do mundo real: extrair informações de produtos de uma lista de preços de peças de computador em PDF. Isso parecia um cenário ideal - dados estruturados em formato tabular. Veja o que aconteceu com cada modelo:
Modelos Testados
1. gpt-oss:20b (20 bilhões de parâmetros)
- Resultado: Falhou com erros de codificação de caracteres
- Problema: Retornou saída estruturada malformada com códigos de caracteres incorretos
- Nota: Apesar de ser projetado especificamente para compatibilidade de código aberto, não conseguiu manter a formatação JSON consistente
2. qwen3:14b (14 bilhões de parâmetros)
- Resultado: Falhou em produzir saída estruturada
- Problema: O modelo gerava texto, mas não no esquema JSON necessário
- Nota: Modelos Qwen geralmente performam bem, mas esta tarefa excedeu suas capacidades de saída estruturada
3. deepseek-r1:14b (14 bilhões de parâmetros)
- Resultado: Falhou em produzir saída estruturada
- Problema: Similar ao qwen3, não conseguiu aderir aos requisitos de esquema do BAML
- Nota: As capacidades de raciocínio não ajudaram com a conformidade de formato
4. devstral:24b (24 bilhões de parâmetros)
- Resultado: Falhou em produzir saída estruturada
- Problema: Mesmo com mais parâmetros, não conseguiu gerar JSON válido consistentemente
- Nota: Modelo de código especializado ainda lutou com aderência estrita ao esquema
5. ministral-3:14b (14 bilhões de parâmetros)
- Resultado: Falhou em produzir saída estruturada
- Problema: O modelo menor do Mistral não conseguiu lidar com as demandas de saída estruturada
6. qwen3-vl:30b-a3b-instruct (30 bilhões de parâmetros)
- Resultado: Falhou em produzir saída estruturada
- Problema: Capacidades de visão não ajudaram na extração de tabelas de PDF neste contexto
7. gpt-oss:120b (120 bilhões de parâmetros)
- Resultado: Não completou o processamento após 2+ horas
- Hardware: Configuração de GPU de consumidor
- Problema: O modelo era grande demais para uso auto-hospedado prático, mesmo que pudesse ter funcionado eventualmente
Principais Achados
Limitação de Tamanho de Fragmento (Chunk): O Cognee usa fragmentos de 4k tokens ao processar documentos com Ollama. Para documentos complexos ou modelos com janelas de contexto maiores, isso parece desnecessariamente restritivo. O framework não oferece uma maneira fácil de ajustar este parâmetro.
Requisitos de Saída Estruturada: O problema central não é a inteligência do modelo, mas a conformidade de formato. Estes modelos podem entender o conteúdo, mas manter um esquema JSON consistente durante todo o processo de extração prova ser desafiador. Isso se alinha com desafios mais amplos em fazer modelos locais respeitarem restrições de saída.
Considerações de Hardware: Mesmo quando um modelo suficientemente grande pode funcionar (como gpt-oss:120b), os requisitos de hardware o tornam impraticável para a maioria dos cenários de auto-hospedagem. Você precisaria de memória GPU e poder de processamento significativos.
Comparação com Melhores Práticas de Saída Estruturada
Esta experiência reforça lições de trabalhar com saída estruturada em diferentes provedores de LLM. APIs comerciais da OpenAI, Anthropic e Google frequentemente possuem mecanismos nativos para impor esquemas de saída, enquanto modelos locais exigem abordagens mais sofisticadas como amostragem baseada em gramática ou múltiplas passagens de validação.
Para uma análise mais profunda sobre escolher o LLM certo para o Cognee no Ollama, incluindo comparações detalhadas de diferentes tamanhos de modelo e suas características de desempenho, existem guias abrangentes disponíveis que podem ajudá-lo a tomar uma decisão informada.
Abordagens Alternativas para RAG Auto-Hospedado
Se você está comprometido com o auto-hospedado e precisa extrair dados estruturados de documentos, considere estas alternativas:
1. RAG Tradicional com Extração Mais Simples
Em vez de construir um grafo de conhecimento complexo antecipadamente, use RAG tradicional com fragmentação de documentos e busca vetorial. Para extração de dados estruturados:
- Parsers tabelas diretamente usando bibliotecas como
pdfplumberoutabula-py - Use prompts mais simples que não exigem aderência estrita ao esquema
- Implemente validação de pós-processamento em Python em vez de depender do formato de saída do LLM
2. Modelos de Embedding Especializados
A qualidade dos seus embeddings impacta significativamente o desempenho de recuperação. Considere usar modelos de embedding de alto desempenho que funcionam bem localmente. Modelos de embedding modernos como as ofertas do Qwen3 fornecem excelente suporte multilíngue e podem melhorar drasticamente a precisão do seu sistema RAG.
3. Reranking para Melhores Resultados
Mesmo com arquiteturas RAG mais simples, adicionar uma etapa de reranking pode melhorar significativamente os resultados. Após a recuperação inicial de busca vetorial, um modelo reranker pode avaliar melhor a relevância. Esta abordagem de dois estágios frequentemente supera sistemas de estágio único mais complexos, especialmente ao trabalhar com hardware restrito.
4. Estratégias de Busca Híbrida
Combinar busca vetorial com busca de palavras-chave tradicional (BM25) frequentemente produz melhores resultados do que qualquer um sozinho. Muitos bancos de dados vetoriais modernos suportam busca híbrida nativamente.
5. Considere Alternativas de Armazenamento Vetorial
Se você está construindo um sistema RAG do zero, avalie diferentes armazenamentos vetoriais com base em suas necessidades. As opções variam de bancos de dados embarcados leves a sistemas distribuídos projetados para escala de produção.
Considerações de Implantação com Docker
Para auto-hospedagem em produção, containerizar sua configuração RAG simplifica a implantação e escalabilidade. Ao executar o Cognee ou frameworks similares com Ollama:
# Execute o Ollama em um container
docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
# Baixe seus modelos
docker exec -it ollama ollama pull gpt-oss:20b
# Configure o Cognee para conectar ao endpoint do container
Certifique-se de configurar corretamente a passagem de GPU e montagens de volume para persistência de modelos.
Lições Aprendidas
1. Adequar Ferramentas ao Hardware: O Cognee é projetado para LLMs em escala de nuvem. Se você está auto-hospedando em hardware de consumidor, arquiteturas mais simples podem ser mais práticas.
2. Saída Estruturada é Difícil: Obter conformidade de esquema consistente de LLMs locais continua desafiador. Se sua aplicação depende criticamente de saída estruturada, use APIs comerciais ou implemente lógica de validação e retry robusta.
3. Teste Cedo: Antes de se comprometer com um framework, teste-o com seu caso de uso específico e hardware. O que funciona em demonstrações pode não funcionar em escala ou com seus documentos.
4. Considere Abordagens Híbridas: Use APIs comerciais para tarefas de extração complexas e modelos locais para consultas mais simples para equilibrar custo e capacidade.
Leitura Relacionada
Saída Estruturada com LLMs
Entender saída estruturada é crucial para frameworks como o Cognee. Estes artigos mergulham profundamente em obter respostas consistentes e conformes ao esquema de LLMs:
- Escolhendo o LLM Certo para o Cognee: Configuração Local Ollama
- LLMs com Saída Estruturada: Ollama, Qwen3 & Python ou Go
- Saída estruturada em provedores populares de LLM - OpenAI, Gemini, Anthropic, Mistral e AWS Bedrock
- Problemas de Saída Estruturada do Ollama GPT-OSS
Arquitetura e Implementação RAG
Para abordagens alternativas ou complementares para extração e recuperação de conhecimento:
- RAG Avançado: LongRAG, Self-RAG e GraphRAG
- Comparação de Armazenamentos Vetoriais para RAG
- Construindo Servidores MCP em Python: WebSearch & Scrape
Embedding e Reranking
Melhorando a qualidade de recuperação através de melhores embeddings e reranking:
- Modelos de Embedding e Reranker Qwen3 no Ollama: Desempenho de Ponta
- Reranking com modelos de embedding
- Reranking de documentos de texto com Ollama e modelo de Embedding Qwen3 - em Go
