Cómo Convertir una Montaña de Documentos Caóticos en Grafos de Conocimiento Rigurosos
Hace poco me encontré con una utilidad que resuelve una de las tareas más tediosas al trabajar con modelos de lenguaje grandes. Se trata de analizar texto sin formato en formatos predecibles sin escribir prompts de un kilómetro de largo.
El proyecto se llama Hyper-Extract. Es una utilidad CLI y biblioteca Python diseñada para convertir archivos no estructurados en estructuras de datos tipadas: desde listas familiares y modelos Pydantic hasta hipergrafos y relaciones espacio-temporales.
¿Qué Problema Hay con RAG Estándar?
Un RAG ingenuo típico con fragmentación de texto en piezas de 500 tokens y búsqueda en base de datos vectorial a menudo produce un desastre. Las relaciones complejas entre entidades se pierden, y el contexto de los eventos a lo largo del tiempo se difumina. Cuando intentas alimentar un informe financiero o artículo científico a un modelo, la búsqueda vectorial plana rara vez da una imagen precisa de las interconexiones.
Frameworks como GraphRAG o LightRAG intentaron solucionar esto, pero integrarlos en tus proyectos desde cero puede ser una molestia. El autor de Hyper-Extract decidió empaquetar los motores de extracción de conocimiento en una utilidad de línea de comandos compacta y una biblioteca con plantillas listas para usar.
Qué Hay Dentro y Cómo Funciona
Debajo del capó, la biblioteca se basa en una arquitectura de tres niveles.
- Ocho tipos de estructuras de datos. Estos incluyen modelos Pydantic, listas simples, conjuntos, grafos de conocimiento estándar, hipergrafos, así como grafos temporales y espacio-temporales.
- Algoritmos de extracción. El framework soporta motores KG-Gen, GraphRAG, LightRAG, Hyper-RAG y Cog-RAG.
- Plantillas listas para usar. El repositorio contiene más de 80 archivos YAML prehechos para diferentes dominios: finanzas, medicina, derecho, artículos científicos.
Las plantillas funcionan sin código. Simplemente tomas un preset listo para usar y especificas qué campos y tipos de relaciones extraer. Por ejemplo, para un grafo de relaciones, la plantilla parece un manifiesto YAML estándar con definiciones de entidad (entities) y relación (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}'
Comenzar en un Par de Minutos
La utilidad se instala a través de un gestor de paquetes moderno uv en literalmente un comando:
uv tool install hyperextract
A continuación, necesitas configurar un proveedor de modelos. La utilidad funciona con OpenAI, Anthropic Claude, DeepSeek, Alibaba Cloud Bailian e instancias locales de vLLM.
Si estás usando DeepSeek o Claude, ten en cuenta un detalle: no tienen su propia API de embedding, así que para búsqueda vectorial, necesitarás configurar el modelo de embedding por separado (por ejemplo, a través de un endpoint compatible 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
Para operación completamente local sin enviar datos externamente, puedes iniciar vLLM con modelos como Qwen y 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
Cuando la configuración esté lista, comienza a analizar el 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 ejecutar el comando he show, se genera una interfaz interactiva donde puedes explorar los nodos y relaciones resultantes.
Si estás escribiendo en Python, puedes llamar al análisis programáticamente a través de la clase 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()
Características Interesantes
Recientemente, el proyecto agregó un par de integraciones útiles que lo distinguen de los scripts de análisis ordinarios.
Primero, exportación a Obsidian. Con un solo comando he export obsidian ./output/ -o ./vault/, el grafo se convierte en un conjunto de notas Markdown vinculadas entre sí a través de [[вики-ссылки]] estándar. Esto es un salvavidas para quienes mantienen una base de conocimiento en Obsidian y no quieren transferir entidades manualmente.
Segundo, un servidor MCP integrado (Model Context Protocol). Al ejecutar el comando he-mcp, abres acceso a tu base de conocimiento para Claude Desktop o agentes de IDE. Pueden llamar a búsqueda, ejecutar RAG y obtener contexto directamente a través del protocolo estándar.
Tercero, actualizaciones incrementales. Si tienes un nuevo documento, no necesitas reconstruir el grafo desde cero. Solo alimenta el nuevo archivo al directorio existente, y la base de datos se complementará con nuevos nodos.
Para Quién Es Este Proyecto
La herramienta servirá para desarrolladores que construyen pipelines complejos sobre documentos corporativos y están cansados de luchar contra las alucinaciones de LLM en respuestas no estructuradas. También es útil para analistas e investigadores para digitalizar rápidamente cientos de páginas PDF en una estructura comprensible.
El repositorio está bien organizado, tiene documentación clara y usa la licencia Apache 2.0. Si estás buscando una forma de poner orden en el trabajo con grafos de conocimiento y RAG, prueba Hyper-Extract con un par de tus propios documentos. Puedes ver el código y las plantillas en el repositorio de GitHub del proyecto.
Proyectos relacionados