Come Trasformare una Montagna di Documenti Caotici in Grafici di Conoscenza Rigorosi

Recentemente mi sono imbattuto in un'utilità che risolve uno dei compiti più noiosi nel lavoro con i modelli linguistici di grandi dimensioni. Si tratta di analizzare il testo non elaborato in formati prevedibili senza scrivere prompt lunghi un chilometro.

Il progetto si chiama Hyper-Extract. È un'utilità CLI e una libreria Python progettata per trasformare file non strutturati in strutture di dati tipizzate: da elenchi familiari e modelli Pydantic a ipergrafi e relazioni spazio-temporali.

Cosa non va nel RAG Standard

Un tipico RAG naive con frammentazione del testo in pezzi da 500 token e ricerca in un database vettoriale spesso produce un disastro. Le relazioni complesse tra le entità si perdono e il contesto degli eventi nel tempo diventa sfocato. Quando provi a fornire un report finanziario o un articolo scientifico a un modello, la ricerca vettoriale piatta raramente fornisce un quadro accurato delle interconnessioni.

Framework come GraphRAG o LightRAG hanno cercato di risolvere questo problema, ma integrarli nei tuoi progetti da zero può essere una seccatura. L'autore di Hyper-Extract ha deciso di confezionare i motori di estrazione della conoscenza in un'utilità da riga di comando compatta e una libreria con modelli pronti all'uso.

Cosa c'è dentro e come funziona

Sotto il cofano, la libreria si basa su un'architettura a tre livelli.

1. Otto tipi di strutture di dati. Questi includono modelli Pydantic, elenchi semplici, insiemi, grafici di conoscenza standard, ipergrafi, nonché grafici temporali e spazio-temporali.
2. Algoritmi di estrazione. Il framework supporta i motori KG-Gen, GraphRAG, LightRAG, Hyper-RAG e Cog-RAG.
3. Modelli pronti all'uso. Il repository contiene oltre 80 file YAML predefiniti per diversi domini: finanza, medicina, legge, documenti scientifici.

I modelli funzionano senza codice. Semplice prendi un preset pronto e specifichi quali campi e tipi di relazione estrarre. Ad esempio, per un grafico di relazioni, il modello assomiglia a un manifest YAML standard con definizioni di entità (entities) e relazione (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}'

Iniziare in un Paio di Minuti

L'utilità si installa tramite un gestore di pacchetti moderno uv letteralmente con un comando:

uv tool install hyperextract

Successivamente, devi configurare un provider di modelli. L'utilità funziona con OpenAI, Anthropic Claude, DeepSeek, Alibaba Cloud Bailian e istanze vLLM locali.

Se stai usando DeepSeek o Claude, tieni a mente un dettaglio: non hanno un'API di embedding propria, quindi per la ricerca vettoriale, dovrai configurare il modello di embedding separatamente (ad esempio, tramite un endpoint compatibile con OpenAI):

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

Per un funzionamento completamente locale senza inviare dati all'esterno, puoi avviare vLLM con modelli come 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 la configurazione è pronta, inizia ad analizzare il 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/

Come risultato dell'esecuzione del comando he show, viene generata un'interfaccia interattiva dove puoi esplorare i nodi e le relazioni risultanti.

Se scrivi in Python, puoi chiamare l'analisi a livello di programmazione tramite la 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()

Funzionalità Interessanti

Recentemente, il progetto ha aggiunto un paio di integrazioni utili che lo distinguono dagli ordinari script di analisi.

Innanzitutto, esportazione in Obsidian. Con un singolo comando he export obsidian ./output/ -o ./vault/, il grafo si trasforma in un insieme di note Markdown collegate tra loro tramite [[вики-ссылки]] standard. Questo è un toccasana per chi mantiene una base di conoscenza in Obsidian e non vuole trasferire manualmente le entità.

In secondo luogo, un server MCP integrato (Model Context Protocol). Eseguendo il comando he-mcp, apri l'accesso alla tua base di conoscenza per Claude Desktop o agenti IDE. Possono chiamare la ricerca, eseguire RAG e recuperare il contesto direttamente attraverso il protocollo standard.

Terzo, aggiornamenti incrementali. Se hai un nuovo documento, non devi ricostruire il grafo da zero. Basta inserire il nuovo file nella directory esistente e il database verrà integrato con nuovi nodi.

A chi è rivolto il progetto

Lo strumento si adatterà agli sviluppatori che costruiscono pipeline complesse su documenti aziendali e stanchi di combattere le allucinazioni LLM nelle risposte non strutturate. È anche utile per analisti e ricercatori per digitalizzare rapidamente centinaia di pagine PDF in una struttura comprensibile.

Il repository è ben organizzato, ha una documentazione chiara e utilizza la licenza Apache 2.0. Se stai cercando un modo per mettere ordine nel lavoro con i grafici di conoscenza e RAG, prova Hyper-Extract su un paio dei tuoi documenti. Puoi visualizzare il codice e i modelli nel repository GitHub del progetto.