Autosserviço do Cognee: Testes de Desempenho de LLM

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 lista de preços em 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 listas de preços), falhou em minha hardware. A forte dependência do framework de saída estruturada torna desafiadora a performance confiável de modelos locais menores.

O que é o Cognee?

Cognee é um framework open-source Python projetado para construir grafos de conhecimento a partir de documentos não estruturados usando LLMs. Diferente dos sistemas tradicionais de RAG que simplesmente dividem e embalam documentos, o Cognee tenta criar uma compreensão semântica ao extrair entidades, relações e conceitos em um banco de dados de grafos. Esta abordagem alinha-se 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 de grafos: 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 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, compreender 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 funcional para o Cognee com Ollama. Note as configuraçõ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 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 maior 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 escolha natural para tarefas de extração de grafos de conhecimento.

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

Modelo de Embedding: O modelo SFR-Embedding-Mistral (4096 dimensões) fornece embeddings de alta qualidade. Para mais informações sobre a seleção e desempenho de modelos de embedding, os modelos de embedding Qwen3 oferecem alternativas excelentes 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 a operação local de LLM e saída estruturada. O extra de scraping adiciona capacidades de raspagem da web, enquanto o Playwright permite o processamento de páginas renderizadas com JavaScript.

Código de Exemplo e Uso

Aqui está o fluxo 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 amostra
    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 acontece a magia (ou os problemas) - ele envia os fragmentos de documento para o LLM para extração de entidades e relações.

msy-search.py:

import cognee
import asyncio

async def main():

    # Pesquise o 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)?"
    )
    
    # Imprima
    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 com base 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 dos Testes: 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 ser 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 necessário
  • Nota: Os 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 conseguia 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 conseguia gerar consistentemente JSON válido
  • Nota: Modelo especializado em programação ainda teve dificuldades com a conformidade estrita do 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 conseguia lidar com os requisitos 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 neste 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

Conclusões Principais

Limitação de Tamanho de Fragmento: O Cognee usa fragmentos de 4k tokens ao processar documentos com Ollama. Para documentos complexos ou modelos com janelas de contexto maiores, isso parece excessivamente restritivo. O framework não oferece uma forma 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 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 prova 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 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

Esta experiência reforça lições aprendidas ao 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 passes de validação múltipla.

Para uma análise mais profunda de escolher o LLM certo para o Cognee no Ollama, incluindo comparações detalhadas de diferentes tamanhos de modelos 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ê 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 divisã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 exigem aderência 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 Embedding Especializados

A qualidade dos seus embeddings impacta significativamente o desempenho de recuperação. Considere usar modelos de embedding de alta performance que funcionam bem localmente. Modelos modernos de embedding, como os oferecidos pela Qwen3, fornecem excelente suporte multilíngue e podem melhorar drasticamente a precisão do seu sistema de RAG.

3. Reordenação para Resultados Melhores

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

4. Estratégias de Busca Híbrida

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

5. Considere Alternativas de Armazenamento Vetorial

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

Considerações sobre Implantação com Docker

Para implantação em produção, containerizar sua configuração de 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

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

# Configure o Cognee para conectar-se 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. Corresponda Ferramentas ao Hardware: O Cognee é projetado para LLMs em 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 modelos locais ainda é desafiador. Se sua aplicação depender criticamente da saída estruturada, use APIs comerciais ou implemente lógica robusta de validação e retenção.

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 de extração complexas e modelos locais para consultas mais simples para equilibrar custo e capacidade.

Leituras Relacionadas

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 compatíveis com esquemas de LLMs:

Arquitetura e Implementação de RAG

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

Embedding e Reordenação

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

Ferramentas e Recursos

Recursos Externos