Jak zamienić stos chaotycznych dokumentów w rygorystyczne grafy wiedzy

Niedawno natknąłem się na narzędzie, które rozwiązuje jedno z najbardziej żmudnych zadań przy pracy z dużymi modelami językowymi. Chodzi o parsowanie surowego tekstu do przewidywalnych formatów bez pisania kilometrowych promptów.

Projekt nazywa się Hyper-Extract. To narzędzie CLI i biblioteka Pythona zaprojektowane do przekształcania nieustrukturyzowanych plików w typizowane struktury danych: od znajomych list i modeli Pydantic po hipergrafy i relacje czasoprzestrzenne.

Co jest nie tak ze standardowym RAG

Typowy naiwny RAG z podziałem tekstu na kawałki po 500 tokenów i wyszukiwaniem w wektorowej bazie danych często daje bałagan. Złożone relacje między encjami się tracą, a kontekst zdarzeń w czasie się zaciera. Kiedy próbujesz wprowadzić raport finansowy lub dokument naukowy do modelu, płaskie wyszukiwanie wektorowe rzadko daje dokładny obraz połączeń.

Frameworki takie jak GraphRAG czy LightRAG próbowały to naprawić, ale ich integracja od zera może być kłopotliwa. Autor Hyper-Extract postanowił spakować silniki ekstrakcji wiedzy w kompaktowe narzędzie wiersza poleceń i bibliotekę z gotowymi szablonami.

Co jest w środku i jak to działa

Pod maską biblioteka opiera się na trójwarstwowej architekturze.

1. Osiem typów struktur danych. Obejmują one modele Pydantic, proste listy, zbiory, standardowe grafy wiedzy, hipergrafy, a także grafy czasowe i czasoprzestrzenne.
2. Algorytmy ekstrakcji. Framework wspiera silniki KG-Gen, GraphRAG, LightRAG, Hyper-RAG i Cog-RAG.
3. Gotowe szablony. Repozytorium zawiera ponad 80 gotowych plików YAML dla różnych dziedzin: finanse, medycyna, prawo, dokumenty naukowe.

Szablony działają bez kodu. Po prostu bierzesz gotowy preset i określasz, które pola i typy relacji wyodrębnić. Na przykład dla grafu relacji szablon wygląda jak standardowy manifest YAML z definicjami encji (entities) i relacji (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}'

Pierwsze kroki w kilka minut

Narzędzie instaluje się przez nowoczesny menedżer pakietów uv dosłownie jednym poleceniem:

uv tool install hyperextract

Następnie musisz skonfigurować dostawcę modelu. Narzędzie współpracuje z OpenAI, Anthropic Claude, DeepSeek, Alibaba Cloud Bailian oraz lokalnymi instancjami vLLM.

Jeśli używasz DeepSeek lub Claude, miej na uwadze jedną rzecz: nie mają własnego API osadzania, więc dla wyszukiwania wektorowego musisz skonfigurować model osadzania osobno (na przykład przez punkt końcowy kompatybilny z OpenAI):

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

Do całkowicie lokalnej pracy bez wysyłania danych na zewnątrz możesz uruchomić vLLM z modelami takimi jak Qwen i 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

Kiedy konfiguracja jest gotowa, rozpocznij parsowanie dokumentu:

# Извлекаем граф связей из биографии
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/

W rezultacie uruchomienia polecenia he show generuje się interaktywny interfejs, gdzie możesz eksplorować wynikowe węzły i relacje.

Jeśli piszesz w Pythonie, możesz programowo wywołać parsowanie przez klasę 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()

Przydatne funkcje

Ostatnio projekt dodał kilka przydatnych integracji, które wyróżniają go spośród zwykłych skryptów parsujących.

Po pierwsze, eksport do Obsidian. Jednym poleceniem he export obsidian ./output/ -o ./vault/ graf zamienia się w zbiór połączonych notatek Markdown przez standardowe [[вики-ссылки]]. To ratunek dla osób, które prowadzą bazę wiedzy w Obsidian i nie chcą ręcznie przenosić encji.

Po drugie, wbudowany serwer MCP (Model Context Protocol). Uruchamiając polecenie he-mcp, otwierasz dostęp do bazy wiedzy dla Claude Desktop lub agentów IDE. Mogą oni wywoływać wyszukiwanie, uruchamiać RAG i pobierać kontekst bezpośrednio przez standardowy protokół.

Po trzecie, przyrostowe aktualizacje. Jeśli masz nowy dokument, nie musisz przebudowywać grafu od zera. Po prostu wprowadź nowy plik do istniejącego katalogu, a baza zostanie uzupełniona o nowe węzły.

Dla kogo jest ten projekt

Narzędzie sprawdzi się u programistów budujących złożone potoki na dokumentach korporacyjnych i znużonych walką z halucynacjami LLM w nieustrukturyzowanych odpowiedziach. Przydaje się też analitykom i badaczom do szybkiego digitalizowania setek stron PDF do zrozumiałej struktury.

Repozytorium jest starannie zorganizowane, ma przejrzystą dokumentację i korzysta z licencji Apache 2.0. Jeśli szukasz sposobu na uporządkowanie pracy z grafami wiedzy i RAG, wypróbuj Hyper-Extract na kilku własnych dokumentach. Kod i szablony znajdziesz w repozytorium GitHub projektu.