La plupart des connaissances d’une organisation restent prisonnieres de textes : articles, contrats, rapports, notes cliniques, manuels et comptes rendus. La recherche retrouve un passage, mais de nombreuses applications exigent davantage : entites typees, relations identifiees, evenements situes dans le temps et l’espace, et sorties validables par le logiciel.
Hyper-Extract est un framework et CLI Python 3.11+ sous Apache-2.0 qui transforme des documents non structures en Knowledge Abstracts persistants et fortement types. Il combine sorties structurees de LLM, schemas reutilisables, methodes d’extraction, mises a jour incrementales, recherche, visualisation, export Obsidian et acces MCP.
Son idee essentielle : tous les documents ne doivent pas devenir le meme graphe generique.
Un modele capture des champs previsibles ; listes et ensembles collectent des elements sans inventer de relations.
Un graphe relie deux entites. Un hypergraphe represente une relation impliquant plusieurs entites sans aretes artificielles.
Les graphes temporels, spatiaux et spatio-temporels repondent aux questions ou, quand et comment.
Une architecture en trois couches
Hyper-Extract separe la forme des connaissances, la methode d’extraction et la configuration du domaine.
1. Auto-Types
Huit familles de sorties sont proposees : Model, List, Set, Graph, Hypergraph, Temporal Graph, Spatial Graph et Spatio-Temporal Graph. Ces structures typees sont plus previsibles a valider et integrer qu’un JSON arbitraire.
Un modele convient aux champs fixes. Un graphe capture les relations par paires. Un hypergraphe represente une relation entre plusieurs entites. Les variantes temporelles et spatiales conservent un contexte qu’un graphe simple peut perdre.
2. Methodes d’extraction
Plusieurs moteurs sont disponibles, notamment des approches liees a GraphRAG, LightRAG, Hyper-RAG et KG-Gen. La methode controle decoupage, prompts, fusion et evolution de la structure.
Extraire un petit enregistrement type n’est pas le meme probleme que reconcilier entites et relations dans un long corpus.
3. Templates
Plus de 80 presets YAML couvrent les domaines general, finance, droit, medecine, medecine chinoise et industrie. Un template declare langue, champs, identifiants, types et comportement. Il permet de commencer sans Python puis d’adapter l’ontologie.
Les identifiants sont critiques : ils determinent si un nouveau document met a jour une connaissance existante ou cree un doublon.
Du document au Knowledge Abstract
uv tool install hyperextract
he config init -k YOUR_OPENAI_API_KEY
he parse report.pdf -t general/academic_graph -o ./knowledge/ -l fr
he search ./knowledge/ "Quels sont les resultats principaux ?"
he show ./knowledge/
he parse applique le template. Le Knowledge Abstract est persistant : de nouveaux documents peuvent l’etendre et l’affiner. he search fait la recherche semantique et he show ouvre la visualisation.
L’API Python suit le meme modele :
from hyperextract import Template
ka = Template.create("general/biography_graph")
result = ka.parse(document_text)
result.show()
Fournisseurs et deploiement local
Hyper-Extract exige un LLM capable de sortie structuree via JSON Schema ou function calling. Le README liste des modeles OpenAI, Anthropic, Alibaba Bailian et vLLM local. Les embeddings passent par une API compatible OpenAI.
Anthropic peut effectuer l’extraction mais ne fournit pas d’API d’embeddings ; il faut donc un fournisseur complementaire pour la recherche semantique. Pour les donnees privees, le projet documente Qwen et bge-m3 en local via vLLM.
Local ne signifie pas automatiquement securise : endpoints, logs, caches, dossiers de sortie et services de visualisation exigent controles d’acces et politiques de retention.
Evolution incrementale
Hyper-Extract accepte de nouveaux documents dans un Knowledge Abstract existant. Les strategies de fusion et identifiants stables reconcilient les extractions avec l’etat accumule.
Mais les noms varient, les faits se contredisent et un document recent peut remplacer une ancienne affirmation. Il faut definir deduplication, confiance, priorite des sources, validite temporelle et suppression. Un graphe plus grand n’est pas necessairement plus exact.
Hypergraphes, temps et espace
Un graphe classique relie deux noeuds. Certaines connaissances impliquent plusieurs parties : une intervention clinique relie patient, traitement, clinicien, pathologie et resultat ; une transaction relie acheteur, vendeur, actif, juridiction et date.
Un hypergraphe preserve cette relation comme une unite au lieu de la decomposer en paires. Les types temporels et spatiaux rendent lieu et temps explicites.
N’ajoutez cette complexite que si les requetes l’exigent. Un modele type ou une liste reste plus simple lorsque les relations ne comptent pas.
Obsidian et MCP
Hyper-Extract exporte un graphe en vault Obsidian avec notes Markdown et [[wikilinks]], transformant la structure generee en espace navigable pour les humains.
Le serveur MCP optionnel expose lecture et export :
pip install 'hyperextract[mcp]'
he-mcp
Les outils documentes couvrent templates, informations, recherche, questions RAG et export Obsidian. La portee lecture/export est prudente, mais le serveur peut tout de meme exposer des connaissances sensibles.
Cas d’usage
- articles scientifiques vers concepts, auteurs, methodes et citations ;
- rapports financiers vers entreprises, dirigeants, metriques et risques ;
- contrats vers clauses, parties, obligations, dates et exceptions ;
- textes cliniques vers entites et evenements temporels ;
- rapports industriels vers equipements, pannes, lieux et dependances ;
- collections de recherche vers notes Obsidian liees.
Pour une simple FAQ documentaire, un RAG chunks-vecteurs peut etre moins cher. Hyper-Extract se justifie lorsque la connaissance typee, la navigation de graphe, l’evolution multi-documents ou le contexte temporel/spatial sont des exigences.
Risques et evaluation
Une sortie structuree garantit la forme, pas la verite. Un LLM peut produire un JSON valide avec une entite inventee. Avant la production :
- Creez un jeu annote representatif.
- Mesurez precision et rappel des entites et relations separement.
- Conservez la source de chaque affirmation.
- Revoyez fusions, conflits et suppressions.
- Traitez les templates medicaux, juridiques et financiers comme points de depart.
- Estimez couts de tokens, embeddings et retraitement.
Testez aussi chaque fournisseur : limites de schema, fiabilite, contexte et function calling varient selon les modeles.
Conclusion
Hyper-Extract offre un chemin coherent du texte libre vers une connaissance typee et persistante. Sa force est la separation entre structures reutilisables, moteurs d’extraction et templates metier.
Une equipe peut commencer en une commande, choisir une sortie plus riche que des chunks, l’etendre sur plusieurs documents, la visualiser, l’exporter pour les humains et la rendre interrogeable par des agents via MCP.
Commencez par l’auto-type le plus simple, definissez des identifiants stables, validez sur des documents annotes et n’ajoutez graphe, hypergraphe, temps ou espace que si ces semantiques apportent une valeur mesurable.