yifanfeng97/Hyper-Extract 딥다이브
— 문서를 '구조화된 지식'으로 바꾸는 LLM 추출 CLI

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

Hyper-Extract = "문서를 들이밀면, 사람이 읽지 않아도 컴퓨터가 다룰 수 있는 '지식 구조물'로 바꿔 주는 명령줄 도구." 우리가 가진 정보 대부분은 줄글(비정형 텍스트)이다. 사람은 읽으면 이해하지만, 프로그램은 줄글을 곧바로 계산·검색·연결하지 못한다. Hyper-Extract는 LLM에게 텍스트를 읽혀서, 미리 정해 둔 '틀(스키마)'에 맞는 강타입 데이터로 뽑아낸다. 그 결과물이 엔티티(노드)와 관계(엣지)로 이뤄진 지식 그래프, 또는 셋 이상을 한 번에 묶는 하이퍼그래프다.

핵심 정체성을 정리하면 세 가지다. ⑴ LLM으로 추출한다(규칙 기반 파서가 아니라 언어모델이 읽고 판단). ⑵ 결과가 강타입 구조물이다(리스트·모델·그래프·하이퍼그래프·시공간 그래프 등 8종). ⑶ 점진적으로 키운다 — 새 문서를 계속 먹이면(he feed) 기존 지식 베이스가 중복을 합치며 커진다(저자는 이를 '지식 진화, knowledge evolution'라 부른다).

2왜 주목받는가

TrendShift 일간 16위 — GraphRAG 도구가 쏟아지는 와중에 이게 눈에 띈 이유.

2024~2026년은 "RAG에서 GraphRAG로" 넘어가는 흐름이 뜨겁다. 단순히 문서 조각을 검색해 붙이는 RAG의 한계를 넘어, 지식을 그래프로 구조화해 추론까지 노리는 접근(Microsoft GraphRAG, LightRAG, KG-Gen 등)이 줄줄이 나왔다. Hyper-Extract는 그 경쟁의 한복판에서 다음 네 가지로 차별화한다.

① 그래프를 넘어 '하이퍼그래프'와 '시공간'까지

대부분의 도구는 둘씩 잇는 보통 그래프(binary graph)에서 멈춘다. Hyper-Extract는 셋 이상을 한 번에 묶는 하이퍼그래프, 그리고 시간·장소가 붙은 시공간 그래프까지 1급 시민으로 다룬다. README의 비교표에서 이 도구만 'Spatial Graph + Hypergraph + Domain Templates' 세 칸을 동시에 채운다고 주장한다 — 이게 가장 큰 세일즈 포인트다.

② "코드 0줄" 도메인 템플릿 80여 종

금융·법률·의료·한의학(TCM)·산업·일반 도메인에 맞춘 YAML 템플릿이 미리 들어 있다. 사용자는 파이썬을 한 줄도 안 쓰고 he parse 문서 -t finance/...처럼 템플릿 이름만 고르면 된다. "추출이 뭘 뽑아야 하는지"를 코드가 아니라 설정 파일로 갈아끼우는 설계다.

③ 10여 종 추출 엔진을 한 지붕 아래에

GraphRAG·LightRAG·iText2KG·KG-Gen 같은 유명 논문 방식들을 재구현해 methods/ 폴더에 모아 뒀다. he parse -m hyper_rag처럼 방법만 바꿔 끼우며 같은 입력에 여러 알고리즘을 비교할 수 있다. "여러 GraphRAG 구현을 각각 깔지 말고, 한 CLI에서 스위치로 돌려 보라"는 제안이다.

④ 데이터가 밖으로 안 나가는 '완전 로컬' 옵션

OpenAI뿐 아니라 vLLM 로컬 서버(예: Qwen3.5-9B + bge-m3 임베딩)를 1급으로 지원한다. 민감한 의료·법률 문서를 내 GPU 안에서만 처리할 수 있다는 점은 기업·연구실에 큰 매력이다.

3기술 스택 전체 지도

pyproject.toml · uv.lock · 소스를 직접 열어 확인한 실제 구성. 순수 파이썬 프로젝트다.

먼저 큰 그림 — Hyper-Extract는 웹 서버·프런트엔드가 없는 순수 파이썬 CLI다(Python ≥3.11, 빌드 백엔드 hatchling). 외부 서비스는 'LLM + 임베딩' 두 가지뿐이고, 나머지는 전부 파이썬 라이브러리다. 스택은 ⓐ LLM 오케스트레이션, ⓑ 저장·검색, ⓒ CLI/UX, ⓓ 저자 제작 핵심 엔진 네 묶음으로 나뉜다.

ⓐ LLM 오케스트레이션 — 텍스트를 모델에 먹이고 구조로 받기

ⓑ 저장·검색 — 뽑은 지식을 담고 다시 찾기

ⓒ CLI · UX · 설정

ⓓ 저자 제작 핵심 엔진 — 진짜 무게가 실린 곳

아래 세 라이브러리는 모두 같은 저자(Yifan Feng)가 만든 것으로, Hyper-Extract의 '심장부'다. 이 레포만 봐서는 안 보이는 알맹이가 여기 있다.

4아키텍처 심화 분석

텍스트 한 덩이가 그래프가 되기까지 — 그리고 '3층 구조'가 왜 영리한가.

아키텍처는 두 축으로 본다. (1) 가로축: 사용자 접근 3층(템플릿 → 엔진 → 자료형) — 쉬운 길과 유연한 길을 같은 엔진 위에 쌓은 구조. (2) 세로축: 추출 파이프라인 — 원본 텍스트가 LLM을 거쳐 색인된 그래프가 되는 흐름. 먼저 3층부터.

가로축 — 사용자 접근 3층

핵심은 세 층 모두 결국 같은 Auto-Type 엔진을 인스턴스화한다는 점이다. 템플릿(YAML)도, 메서드(엔진)도 내부적으론 AutoGraph·AutoHypergraph 같은 객체를 만들 뿐이다. 그래서 입문자가 템플릿으로 시작했다가 나중에 파이썬 API로 내려가도 개념이 그대로 이어진다.

세로축 — 추출 파이프라인 (텍스트 → 그래프)

핵심 설계 패턴 ① — 템플릿 메서드 패턴(Template Method)

추상 클래스 BaseAutoType이 위 파이프라인 '전체 골격'을 소유하고, 8개 자료형은 빈칸(훅)만 채운다. 예: _init_data_state(초기 상태), merge_batch_data(병합 방식), build_index(색인), search(검색), _default_prompt(기본 프롬프트). 실제 추출의 심장은 이 한 줄이다:

# BaseAutoType: 프롬프트와 '구조화 출력 LLM'을 파이프로 연결
self.data_extractor = self.prompt_template | self.llm_client.with_structured_output(self._data_schema)

# _extract_data: 짧으면 한 번, 길면 청크로 쪼개 동시 호출
if len(text) <= self.chunk_size:
    extracted = [self.data_extractor.invoke({"source_text": text})]
else:
    chunks = self.text_splitter.split_text(text)
    inputs = [{"source_text": c} for c in chunks]
    extracted = self.data_extractor.batch(inputs, config={"max_concurrency": self.max_workers})
extracted = self._filter_none_results(extracted)   # 실패분 제거
merged = self.merge_batch_data(extracted)           # ontomem 머저로 병합

핵심 설계 패턴 ② — 하이퍼그래프는 '노드/엣지 분리 저장 + 이중 색인'

보통 그래프와 하이퍼그래프의 차이는 개념이 아니라 코드에 박혀 있다. 하이퍼엣지는 둘이 아니라 참여자 전체를 담은 튜플이다. 그래서 중복을 합치려면 참여자를 정렬해 '순서 무관' 키를 만들어야 한다.

# 보통 그래프: 엣지 = (출발, 도착) 2-튜플
nodes_in_edge_extractor = lambda x: (x.source, x.target)

# 하이퍼그래프: 엣지 = 참여자 전원 튜플 (2개 이상)
nodes_in_edge_extractor = lambda x: tuple(x.members)
edge_key_extractor      = lambda x: f"{x.type}_{'_'.join(sorted(x.members))}"
# ↑ sorted(): {A,B,C}=={C,B,A} 로 보게 만들어 중복 제거가 동작

그리고 AutoHypergraph는 노드용 OMem과 엣지용 OMem을 따로 두고, FAISS 인덱스도 node_index/·edge_index/ 둘로 나눈다. 검색은 (노드들, 엣지들) 튜플을 돌려주고, RAG 챗은 이를 "=== 관련 노드 ===", "=== 관련 엣지 ===" 두 블록으로 나눠 모델에 보여 준다.

핵심 설계 패턴 ③ — 시공간 그래프는 '복합 키 + 관측 기준점 주입'

AutoSpatioTemporalGraph는 AutoGraph를 상속해 두 가지를 더한다. ⑴ 같은 관계라도 시간·장소가 다르면 다른 것으로 보도록 복합 키 "{관계} @ {시간} at {장소}"를 만든다. ⑵ 프롬프트에 observation_time(기본=오늘)·observation_location을 주입해, LLM이 "작년", "여기", "현재" 같은 상대 표현을 절대값으로 환산하게 한다. 또한 "시간을 노드로 뽑지 말라(시간은 관계의 속성이다)"를 명시한다.

5디렉토리 구조 해부

저장소를 클론하면 어디부터 봐야 하는가 — types/가 본체다.

공부 순서 추천: README.md → examples/(돌려보며 감 잡기) → hyperextract/types/base.py(파이프라인 골격) → types/hypergraph.py(간판 자료형) → utils/client.py(LLM 연결). 가장 중요한 폴더는 types/(8개 자료형)과 methods/(9개 엔진)다.

6학습 포인트 (기술별)

이 레포에서 실제로 무엇을 배울 수 있는가 — 기술별 + 실습 아이디어.

7시스템 요구사항

무엇이 있어야 돌릴 수 있나 — 도구 자체엔 GPU가 필요 없다.

좋은 소식 — Hyper-Extract 자체는 가벼운 순수 파이썬이다. faiss-cpu를 쓰고 무거운 연산(LLM·임베딩)은 외부 API/서버에 맡기므로, 도구를 돌리는 데 GPU가 필요 없다. GPU는 모델을 직접 자체 호스팅(vLLM)할 때만 필요하다.

8직접 해볼 수 있는 실습 과제

난이도별로 — 30초 퀵스타트부터 내 도메인 템플릿 제작까지.

먼저 설치와 30초 퀵스타트. 이게 전체 사용 흐름의 축소판이다.

# 설치 + API 키 등록
uv tool install hyperextract
he config init -k YOUR_OPENAI_API_KEY

# ① 추출: 테슬라 전기를 '인물 전기 그래프' 템플릿으로 → ./output/
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/

# 아주 단순화한 템플릿 골격(개념용)
type: graph
language: ko
node_schema:
  name: { type: str, desc: "엔티티 이름" }
  role: { type: str, desc: "세력/직책" }
edge_schema:
  source: ...
  target: ...
  relation: { type: str, desc: "동맹/적대 등" }

9관련 기술 심화 학습 로드맵

이 레포를 발판으로 'LLM 지식추출 + GraphRAG'까지 — 6주 계획.

10핵심 키워드 사전

문서·코드에 자주 나오는 용어 — 한 줄 정의.

11참고 링크

원문으로 더 깊이 — 공식 소스 위주.

• GitHub 저장소: github.com/yifanfeng97/Hyper-Extract
• PyPI 패키지: pypi.org/project/hyperextract (uv tool install hyperextract)
• 동봉 스킬 팩: 저장소 내 hyperextract-skills/ (brainstorm · graph-designer · yaml-validator · template-optimizer)
• 저자 제작 핵심 라이브러리: ontomem · ontosight · semhash (by Yifan Feng)
• 비교 대상 읽을거리: Microsoft GraphRAG · LightRAG
• 기반 기술: LangChain · FAISS · Pydantic
• TrendShift 페이지: trendshift.io/repositories/25420