Hyper-Extract는 논문, 리포트, 도메인 문서 같은 비정형 텍스트를 강타입 지식 구조로 변환하는 Python 기반 지식 추출 CLI다. 단순 청크 검색용 인덱스를 만드는 데 그치지 않고, 리스트·Pydantic 모델·지식 그래프·하이퍼그래프·시간 그래프·공간 그래프·시공간 그래프 같은 “지식 추상(Knowledge Abstract)”을 생성해 검색, 시각화, Obsidian 내보내기까지 이어준다.
GitHub: https://github.com/yifanfeng97/Hyper-Extract 문서: https://yifanfeng97.github.io/Hyper-Extract/latest/
어떤 문제를 푸는가?
일반적인 rag 파이프라인은 문서를 청크로 나눈 뒤 임베딩 검색을 붙이는 방식으로 시작한다. 이 접근은 빠르게 만들 수 있지만, 문서 안의 엔티티, 관계, 시간 순서, 공간 관계, 다자 관계를 명시적 구조로 보존하기 어렵다.
Hyper-Extract는 인제스트 단계에서 LLM의 구조화 출력(json_schema 또는 function calling)을 활용해 문서를 목적에 맞는 데이터 구조로 추출한다. 결과물은 단순 텍스트 요약이 아니라 반복 검색·시각화·내보내기에 쓸 수 있는 지식 베이스에 가깝다.
핵심 기능
| 기능 | 설명 |
|---|---|
| 8가지 지식 구조 | Model, List, Set, Graph, Hypergraph, Temporal Graph, Spatial Graph, Spatio-Temporal Graph 지원 |
| 10개 이상 추출 엔진 | GraphRAG, LightRAG, Hyper-RAG, KG-Gen 등 그래프 기반 추출 방식을 템플릿화 |
| 80개 이상 YAML 템플릿 | 금융, 법률, 의료, 산업, 일반 도메인용 사전 정의 템플릿 제공 |
| 점진적 진화 | 새 문서를 추가해 기존 지식 추상을 확장·정제할 수 있음 |
| Obsidian 내보내기 | 그래프를 [[wikilinks]] 기반 Markdown 노트 묶음으로 변환 |
| MCP 서버 | he-mcp로 Claude Desktop, IDE 에이전트가 지식 추상을 검색·질의할 수 있음 |
아키텍처
Hyper-Extract는 세 층으로 구성된다.
| 층 | 역할 |
|---|---|
| Auto-Types | 결과물을 어떤 강타입 구조로 저장할지 정의한다. 예: Graph, Hypergraph, Temporal Graph |
| Methods | 실제 추출 알고리즘을 선택한다. 예: KG-Gen, GraphRAG, lightrag, Hyper-RAG |
| Templates | 도메인별 스키마와 프롬프트를 YAML로 묶는다. 예: 학술 논문 그래프, 실적 발표 엔티티 추출 |
이 구조 때문에 사용자는 매번 프롬프트와 Pydantic 모델을 직접 짜지 않고, “문서 종류와 원하는 구조”를 고르는 방식으로 추출 파이프라인을 시작할 수 있다.
빠른 시작
설치는 uv tool 기반이 가장 간단하다.
uv tool install hyperextract
he config init -k YOUR_OPENAI_API_KEY문서를 그래프 템플릿으로 파싱하고 검색·시각화한다.
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/Obsidian 지식 베이스로 내보낼 수도 있다.
he export obsidian ./output/ -o ./vault/Python API에서는 템플릿을 직접 생성해 사용할 수 있다.
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()모델과 배포 옵션
Hyper-Extract는 LLM의 구조화 출력 성능에 의존한다. README 기준 검증 모델은 OpenAI gpt-4o, gpt-4o-mini, gpt-5, Anthropic claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5, Alibaba Bailian qwen-plus, qwen-turbo, deepseek-r1, 로컬 vllm 기반 Qwen3.5-9B 등이다.
임베딩은 OpenAI 호환 엔드포인트를 사용할 수 있다. Anthropic Claude를 LLM으로 쓸 때도 임베딩은 OpenAI 호환 모델과 함께 조합해야 한다.
from hyperextract import create_client
llm, emb = create_client(
llm="vllm:Qwen3.5-9B@http://localhost:8000/v1",
embedder="vllm:bge-m3@http://localhost:8001/v1",
api_key="dummy",
)온프레미스 문서나 민감한 내부 지식 베이스라면 이 로컬 vLLM 조합이 특히 중요하다. 문서 원문을 외부 API로 보내지 않고도 그래프 추출과 검색을 구성할 수 있기 때문이다.
기존 RAG 도구와의 차이
| 항목 | 일반 벡터 RAG | Graph RAG 구현체 | Hyper-Extract |
|---|---|---|---|
| 기본 출력 | 청크 + 벡터 | 엔티티·관계 그래프 | 강타입 지식 추상 |
| 구조 범위 | 텍스트 청크 중심 | 그래프 중심 | 리스트, 모델, 그래프, 하이퍼그래프, 시공간 그래프 |
| 사용 방식 | 앱에 직접 통합 | RAG 파이프라인 구축 | CLI·Python API·MCP·Obsidian export |
| 적합한 작업 | 문서 Q&A | 멀티홉 관계 검색 | 문서에서 재사용 가능한 지식 구조 추출 |
Hyper-Extract는 graph-rag를 대체한다기보다, 여러 그래프·추출 방식을 템플릿화해 “문서에서 어떤 구조를 뽑아낼지”를 빠르게 실험하는 도구에 가깝다.
누구에게 유용한가?
- 연구자: 논문에서 개념, 저자, 인용, 방법론 관계를 그래프로 추출하고 탐색할 때
- 금융·법률·의료 분석가: 긴 리포트에서 엔티티, 지표, 조항, 리스크 요인을 구조화할 때
- 지식 관리 담당자: 추출 결과를 Obsidian vault나 MCP 서버로 연결해 에이전트가 검색 가능한 지식 베이스를 만들 때
- RAG 개발자: lightrag, GraphRAG, KG-Gen 같은 접근을 같은 인터페이스에서 비교하고 템플릿화할 때
한계와 주의점
Hyper-Extract의 품질은 선택한 LLM, 템플릿 스키마, 문서 도메인에 크게 좌우된다. 구조화 출력이 약한 모델을 쓰면 그래프 누락이나 잘못된 관계가 생길 수 있고, 템플릿이 너무 느슨하면 검색 가능한 지식 구조가 아니라 장황한 요약으로 흐를 수 있다.
따라서 프로덕션 지식 베이스에 바로 투입하기보다는, 먼저 작은 문서 묶음에서 템플릿별 추출 품질을 비교하고 도메인별 식별자(identifier)와 관계 타입을 조정하는 방식이 현실적이다.
라이선스
Apache-2.0 라이선스로 공개되어 상업적 사용과 수정이 가능하다.
관련 문서
- rag — 외부 지식을 LLM에 주입하는 검색 증강 생성 기술
- graph-rag — 관계 인식 검색으로 멀티홉 질문에 답하는 RAG 패러다임
- lightrag — 지식 그래프 기반의 빠르고 단순한 RAG 시스템
- rag-anything — 텍스트·이미지·표·수식을 통합 처리하는 올인원 멀티모달 RAG 시스템
- vllm — 로컬·온프레미스 LLM 추론 서버 구성
- obsidian-second-brain — Obsidian을 지식 베이스로 활용하는 AI 에이전트 워크플로
참고 자료
- yifanfeng97/Hyper-Extract — GitHub 공식 저장소
- Hyper-Extract Documentation — 공식 문서