Como Transformar uma Montanha de Documentos Caóticos em Grafos de Conhecimento Rigorosos

Recentemente encontrei um utilitário que resolve uma das tarefas mais tediosas ao trabalhar com modelos de linguagem grandes. Trata-se de analisar texto bruto em formatos previsíveis sem escrever prompts quilométricos.

O projeto se chama Hyper-Extract. É um utilitário CLI e biblioteca Python projetado para transformar arquivos não estruturados em estruturas de dados tipadas: desde listas familiares e modelos Pydantic até hipergrafos e relações espaço-temporais.

O que há de errado com o RAG padrão

Um RAG ingênuo típico com fragmentação de texto em pedaços de 500 tokens e busca em banco de dados vetorial frequentemente produz uma bagunça. Relações complexas entre entidades se perdem, e o contexto de eventos ao longo do tempo fica desfocado. Quando você tenta alimentar um relatório financeiro ou artigo científico em um modelo, a busca vetorial plana raramente dá uma imagem precisa das interconexões.

Frameworks como GraphRAG ou LightRAG tentaram corrigir isso, mas integrá-los aos seus projetos do zero pode ser um incômodo. O autor do Hyper-Extract decidiu empacotar motores de extração de conhecimento em um utilitário de linha de comando compacto e biblioteca com modelos prontos.

O que há dentro e como funciona

Por baixo dos panos, a biblioteca depende de uma arquitetura de três camadas.

1. Oito tipos de estruturas de dados. Estes incluem modelos Pydantic, listas simples, conjuntos, grafos de conhecimento padrão, hipergrafos, além de grafos temporais e espaço-temporais.
2. Algoritmos de extração. O framework suporta os motores KG-Gen, GraphRAG, LightRAG, Hyper-RAG e Cog-RAG.
3. Modelos prontos. O repositório contém mais de 80 arquivos YAML pré-fabricados para diferentes domínios: finanças, medicina, direito, artigos científicos.

Os modelos funcionam sem código. Você simplesmente pega um preset pronto e especifica quais campos e tipos de relacionamento extrair. Por exemplo, para um grafo de relacionamento, o modelo parece um manifesto YAML padrão com definições de entidade (entities) e relacionamento (relations):

language: en
name: Knowledge Graph
type: graph
tags: [general]
description: 'Extract entities and their relationships.'
output:
  entities:
    fields:
    - name: name
      type: str
    - name: type
      type: str
    - name: description
      type: str
  relations:
    fields:
    - name: source
      type: str
    - name: target
      type: str
    - name: type
      type: str
identifiers:
  entity_id: name
  relation_id: '{source}|{type}|{target}'

Começando em poucos minutos

O utilitário é instalado via um gerenciador de pacotes moderno uv em literalmente um comando:

uv tool install hyperextract

A seguir, você precisa configurar um provedor de modelo. O utilitário funciona com OpenAI, Anthropic Claude, DeepSeek, Alibaba Cloud Bailian e instâncias vLLM locais.

Se você estiver usando DeepSeek ou Claude, tenha em mente um detalhe: eles não possuem API de embedding própria, então para busca vetorial, você precisará configurar o modelo de embedding separadamente (por exemplo, através de um endpoint compatível com OpenAI):

# Настройка для связки DeepSeek + OpenAI Embeddings
he config llm -p deepseek -k YOUR_DEEPSEEK_API_KEY
he config embedder -p openai -k YOUR_OPENAI_API_KEY

Para operação totalmente local sem enviar dados externamente, você pode subir o vLLM com modelos como Qwen e bge-m3:

he config llm -p vllm -u http://localhost:8000/v1 -k dummy -m Qwen/Qwen3.5-9B
he config embedder -p vllm -u http://localhost:8001/v1 -k dummy -m BAAI/bge-m3

Quando a configuração estiver pronta, comece a analisar o documento:

# Извлекаем граф связей из биографии
he parse examples/en/tesla.md -t general/biography_graph -o ./output/ -l en

# Делаем семантический поиск по собранной базе
he search ./output/ "What are Tesla's major achievements?"

# Запускаем интерактивную визуализацию графа прямо в браузере
he show ./output/

Como resultado de executar o comando he show, uma interface interativa é gerada onde você pode explorar os nós e relacionamentos resultantes.

Se você está escrevendo em Python, pode chamar a análise programaticamente através da classe Template:

from hyperextract import Template

ka = Template.create("general/biography_graph")

with open("examples/en/tesla.md") as f:
    result = ka.parse(f.read())

result.show()

Recursos interessantes

Recentemente, o projeto adicionou algumas integrações úteis que o diferenciam de scripts de análise comuns.

Primeiro, exportação para Obsidian. Com um único comando he export obsidian ./output/ -o ./vault/, o grafo se transforma em um conjunto de notas Markdown vinculadas entre si via [[вики-ссылки]] padrão. Isso é um salvador para quem mantém uma base de conhecimento no Obsidian e não quer transferir entidades manualmente.

Segundo, um servidor MCP integrado (Model Context Protocol). Ao executar o comando he-mcp, você abre acesso à sua base de conhecimento para Claude Desktop ou agentes de IDE. Eles podem chamar busca, executar RAG e buscar contexto diretamente através do protocolo padrão.

Terceiro, atualizações incrementais. Se você tem um novo documento, não precisa reconstruir o grafo do zero. Basta alimentar o novo arquivo no diretório existente, e o banco de dados será complementado com novos nós.

Para quem este projeto é útil

A ferramenta atenderá desenvolvedores que constroem pipelines complexos sobre documentos corporativos e estão cansados de lutar com alucinações de LLM em respostas não estruturadas. Também é útil para analistas e pesquisadores para digitalizar rapidamente centenas de páginas de PDF em uma estrutura compreensível.

O repositório é bem organizado, tem documentação clara e usa a licença Apache 2.0. Se você está procurando uma forma de trazer ordem ao trabalho com grafos de conhecimento e RAG, experimente o Hyper-Extract em um par dos seus próprios documentos. Você pode ver o código e os modelos no repositório GitHub do projeto.