Auto-hospedagem do Cognee: Escolhendo o LLM no Ollama

Testando o Cognee com LLMs locais - resultados reais

Conteúdo da página

Cognee é um framework Python para construir grafos de conhecimento a partir de documentos usando LLMs. Mas funciona com modelos auto-hospedados?

Testei com vários LLMs locais para descobrir.

cognee processando pdf com procelist

Essa é uma página de pricelist PDF que tentei processar.

TL;DR

Cognee provavelmente funciona bem com LLMs inteligentes com centenas de bilhões de parâmetros, mas para configurações de RAG auto-hospedadas esperadas para extrair automaticamente dados de PDFs (como pricelists), falhou em entregar no meu hardware. A forte dependência do framework em saída estruturada torna desafiador para modelos locais menores performarem de forma confiável.

O que é Cognee?

Cognee é um framework open-source Python projetado para construir grafos de conhecimento a partir de documentos não estruturados usando LLMs. Ao contrário dos sistemas tradicionais de RAG que simplesmente fragmentam e embalam documentos, o Cognee tenta criar uma compreensão semântica ao extrair entidades, relações e conceitos em um banco de dados gráfico. Essa abordagem se alinha com arquiteturas avançadas de RAG, como o GraphRAG, que promete uma recuperação contextual melhor.

O framework suporta múltiplos backends:

  • Bancos de dados vetoriais: LanceDB (padrão), com suporte para outros armazenamentos vetoriais
  • Bancos de dados gráficos: Kuzu (padrão), permitindo consultas complexas de relações
  • Fornecedores 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 da saída estruturada para extrair informações de documentos em um formato consistente. Ao processar um documento, o LLM deve retornar JSON corretamente formatado contendo entidades, relações e metadados. É aí que muitos modelos menores têm dificuldades.

Se você está 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 LLM ao trabalhar com modelos locais.

Configuração

Aqui está minha configuração funcionando com o Cognee e o Ollama. Observe as configurações-chave que permitem 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 Embalagem
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 do 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ões)
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 oferece melhor controle sobre esquemas de saída em comparação com prompts básicos. O BAML foi projetado especificamente para saídas estruturadas de LLM, tornando-o uma boa escolha natural para tarefas de extração de grafos de conhecimento.

Fornecedor de LLM: Usar a API de endpoint compatível com OpenAI do Ollama (/v1) permite que o Cognee trate-o como qualquer outro serviço estilo OpenAI.

Modelo de Embalagem: O modelo SFR-Embedding-Mistral (4096 dimensões) fornece embalagens de alta qualidade. Para mais informações sobre seleção e desempenho de modelos de embalagem, os modelos de embalagem 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.

Instale o Cognee

A instalação é direta usando uv (ou pip). Recomendo usar uv para resolução mais rápida de dependências:

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 da web, enquanto o Playwright habilita o processamento de páginas renderizadas com JavaScript.

Código e Uso de Exemplo

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 um novo ambiente para o cognee -- redefina os dados e o 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"]
    )
    
    # Processar 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 os problemas) acontecem - ele envia fragmentos de documentos para o LLM para extração de entidades e relações.

msy-search.py:

import cognee
import asyncio

async def main():

    # Pesquisar 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 (2x16GB módulos)?"
    )
    
    # Imprimir
    for result in results:
        print(result)

if __name__ == '__main__':
    asyncio.run(main())

Ao contrário da pesquisa vetorial tradicional em sistemas de RAG, o Cognee consulta o grafo de conhecimento, teoricamente permitindo uma recuperação mais sofisticada baseada em relações. Isso é semelhante ao que arquiteturas avançadas de RAG fazem, mas exige que a construção inicial do grafo tenha sucesso.

Resultados de Teste: Desempenho dos LLMs

Testei o Cognee com um caso de uso real: extrair informações de produto de uma lista de preços de peças de computador em PDF. Isso parecia um cenário ideal - dados estruturados em formato tabular. Aqui está 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 ter sido especificamente projetado para compatibilidade com 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 geraria texto, mas não no esquema JSON exigido
  • Nota: Modelos Qwen geralmente performam bem, mas essa 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 do esquema BAML
  • Nota: As capacidades de raciocínio não ajudaram na conformidade com o 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 consistentemente JSON válido
  • Nota: Modelo especializado em código ainda teve dificuldades com a conformidade estrita com o 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: As capacidades de visão não ajudaram na extração de tabelas de PDF nesse contexto

7. gpt-oss:120b (120 bilhões de parâmetros)

  • Resultado: Não completou o processamento após mais de 2 horas
  • Hardware: Configuração de GPU de consumo
  • Problema: O modelo era muito grande para uso prático auto-hospedado, mesmo que possa ter funcionado eventualmente

Achados Principais

Limitação do Tamanho do Fragmento: O Cognee usa fragmentos de 4k tokens ao processar documentos com o Ollama. Para documentos complexos ou modelos com janelas de contexto maiores, isso parece desnecessariamente restritivo. O framework não fornece uma maneira fácil de ajustar esse parâmetro.

Requisitos de Saída Estruturada: O problema central não é a inteligência do modelo, mas a conformidade com o formato. Esses modelos podem entender o conteúdo, mas manter uma formatação consistente de esquema JSON durante o processo de extração provou ser desafiador. Isso se alinha com desafios mais amplos de obter modelos locais para respeitar restrições de saída.

Considerações de Hardware: Mesmo quando um modelo suficientemente grande poderia funcionar (como o gpt-oss:120b), os requisitos de hardware tornam impraticável para a maioria dos cenários de auto-hospedagem. Você precisaria de uma quantidade significativa de memória de GPU e poder de processamento.

Comparação com Boas Práticas de Saída Estruturada

Essa experiência reforça lições de trabalhar com saída estruturada em diferentes fornecedores de LLM. APIs comerciais de OpenAI, Anthropic e Google frequentemente têm mecanismos embutidos 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 de escolher o LLM certo para Cognee no Ollama, incluindo comparações detalhadas de diferentes tamanhos de modelos e suas características de desempenho, há guias abrangentes disponíveis que podem ajudá-lo a tomar uma decisão informada.

Abordagens Alternativas para RAG Auto-hospedado

Se você estiver comprometido com a auto-hospedagem e precisar extrair dados estruturados de documentos, considere essas alternativas:

1. RAG Tradicional com Extração Simples

Em vez de construir um grafo de conhecimento complexo no início, use o RAG tradicional com fragmentação de documentos e busca vetorial. Para extração de dados estruturados:

  • Parse tabelas diretamente usando bibliotecas como pdfplumber ou tabula-py
  • Use prompts mais simples que não exijam adesão estrita a esquemas
  • Implemente validação pós-processamento em Python em vez de depender da formatação de saída do LLM

2. Modelos de Embalagem Especializados

A qualidade de suas embalagens impacta significativamente o desempenho da recuperação. Considere usar modelos de embalagem de alta performance que funcionam bem localmente. Modelos modernos de embalagem como as ofertas da Qwen3 oferecem excelente suporte multilíngue e podem melhorar drasticamente a precisão do seu sistema RAG.

3. Reordenação para Melhores Resultados

Mesmo com arquiteturas RAG mais simples, adicionar uma etapa de reordenação pode melhorar significativamente os resultados. Após a recuperação inicial de busca vetorial, um modelo de reordenação pode avaliar melhor a relevância. Essa abordagem de duas etapas frequentemente supera sistemas mais complexos de uma única etapa, especialmente quando trabalhando com hardware limitado.

4. Estratégias de Busca Híbrida

Combinar busca vetorial com busca tradicional de palavras-chave (BM25) geralmente produz melhores resultados do que qualquer um sozinho. Muitos bancos de dados vetoriais modernos suportam busca híbrida de fábrica.

5. Considere Alternativas de Armazenamento Vetorial

Se você estiver construindo um sistema RAG do zero, avalie diferentes armazenamentos vetoriais com base em suas necessidades. As opções variam de bancos de dados embutidos leves até sistemas distribuídos projetados para escala de produção.

Considerações de Implantação com Docker

Para implantação em produção de auto-hospedagem, conteinizar sua configuração de RAG simplifica a implantação e a escala. Ao executar o Cognee ou frameworks similares com o Ollama:

# Execute o Ollama em um contêiner
docker run -d --gpus=all -v ollama:/root/.ollama -p 114线:11434 --name ollama ollama/ollama

# Puxe seus modelos
docker exec -it ollama ollama pull gpt-oss:20b

# Configure o Cognee para conectar-se ao endpoint do contêiner

Certifique-se de configurar corretamente a passagem de GPU e montagens de volumes para persistência de modelos.

Lições Aprendidas

1. Corresponda as Ferramentas ao Hardware: O Cognee foi projetado para LLMs de escala de nuvem. Se você estiver auto-hospedando em hardware de consumo, arquiteturas mais simples podem ser mais práticas.

2. Saída Estruturada é Difícil: Obter conformidade consistente com esquemas de saída de LLMs locais permanece desafiador. Se seu aplicativo depender criticamente de saída estruturada, use APIs comerciais ou implemente validação robusta e lógica de tentativa.

3. Teste Cedo: Antes de comprometer-se a um framework, teste-o com seu caso de uso específico e hardware. O que funciona em demos pode não funcionar em escala ou com seus documentos.

4. Considere Abordagens Híbridas: Use APIs comerciais para tarefas complexas de extração e modelos locais para consultas mais simples para equilibrar custo e capacidade.

Leitura Relacionada

Saída Estruturada com LLMs

Entender a saída estruturada é crucial para frameworks como o Cognee. Estes artigos mergulham profundamente em obter respostas consistentes e conformes com esquemas de LLMs:

Arquitetura e Implementação de RAG

Para abordagens alternativas ou complementares de extração de conhecimento e recuperação:

Embalagem e Reordenação

Melhorar a qualidade de recuperação através de embalagens e reordenação melhores:

Ferramentas e Recursos

Recursos Externos