ai-knowledge-graph: 비정형 텍스트에서 지식 그래프를 뽑아 시각화하는 파이썬 도구

9bow · 8월 11, 2026, 3:30오전

ai-knowledge-graph 소개

사내 위키나 회의록, 조사 보고서처럼 쌓여만 가는 문서 더미에서 "무엇이 무엇과 어떻게 연결되어 있는가"를 알아내려면 결국 사람이 읽어야 합니다. LLM에게 문서를 통째로 던져 요약을 받는 방법도 있지만, 요약은 다시 문장이라 관계를 눈으로 따라가기 어렵습니다. ai-knowledge-graph 는 그 중간 형태를 만듭니다. 비정형 텍스트를 입력받아 LLM으로 주어-서술어-목적어(Subject-Predicate-Object, SPO) 형태의 트리플을 뽑아내고, 그 관계망을 브라우저에서 돌려볼 수 있는 그래프로 그려 주는 파이썬 도구입니다.

문서에서 트리플을 뽑는 일 자체는 어렵지 않습니다. 문제는 그다음입니다. 문서를 청크로 나눠 처리하면 같은 대상이 청크마다 다른 이름으로 잡히고, 서로 이어져야 할 부분이 끊긴 섬으로 남습니다. ai-knowledge-graph는 이 지점을 추가 패스 로 해결합니다. 1차 추출 뒤에 엔티티 표준화 패스를 돌려 "AI", "artificial intelligence", "AI system" 처럼 같은 개념을 가리키는 표기를 하나로 모으고, 3차 관계 추론 패스에서 끊어진 커뮤니티 사이를 이어 줍니다. 두 패스 모두 설정에서 끌 수 있어서 LLM 호출량을 줄이고 싶으면 1차 추출만 쓸 수도 있습니다.

만든 사람은 Robert McDermott입니다. 특정 모델에 묶여 있지 않다는 점도 특징입니다. OpenAI 호환 API 엔드포인트라면 무엇이든 붙일 수 있어서 Ollama나 LM Studio로 노트북 안에서 끝낼 수도 있고, vLLM이나 LiteLLM을 거쳐 AWS Bedrock, Azure OpenAI, Anthropic 같은 서비스로 보낼 수도 있습니다. 이 글에서는 세 번의 패스가 실제로 무엇을 바꾸는지, 설정과 실행은 어떻게 하는지, 그리고 어떤 상황에 맞고 어떤 상황에는 부족한지를 정리합니다.

단일 추출 방식의 한계와 ai-knowledge-graph의 3단 처리

문서를 청크로 쪼개 LLM에 넘기는 순간, 각 청크는 서로를 모르는 채로 처리됩니다. 그래서 한 번의 추출만 거친 그래프에는 두 가지 문제가 남습니다. 하나는 같은 대상이 표기만 다른 여러 노드로 흩어지는 것이고, 다른 하나는 문서 전체에서는 이어지는 이야기인데 청크 경계에서 끊겨 그래프가 여러 조각으로 갈라지는 것입니다.

ai-knowledge-graph의 2차 패스는 앞의 문제를 다룹니다. 먼저 텍스트 정규화로 기본적인 표기 차이를 없애고, 설정에서 standardization.use_llm_for_entities 를 켜면 LLM이 그래프의 고유 엔티티 목록 전체를 훑어 같은 개념을 가리키는 묶음을 찾아냅니다.

3차 패스는 뒤의 문제를 다룹니다. 그래프에서 끊어진 커뮤니티를 식별한 뒤, 각 커뮤니티의 대표 엔티티를 LLM에 보여 주고 그럴듯한 관계를 추론하게 합니다. 여기에 전이 규칙(transitive inference)과 어휘 유사도 기반 규칙이 함께 적용됩니다. 추론된 관계는 원문에 명시된 관계가 아니므로, 시각화에서 점선으로 구분해 그립니다. 원문에 있던 사실과 도구가 채워 넣은 추정을 섞지 않고 보여 주는 셈입니다.

ai-knowledge-graph의 처리 단계별 결과

저장소에 함께 들어 있는 산업혁명 예제 문서를 돌린 결과가 README에 그대로 실려 있어, 각 패스가 숫자를 어떻게 바꾸는지 확인할 수 있습니다. 문서는 100단어 청크 13개로 나뉘었고, 1차 추출에서 트리플 216개가 나왔습니다. 2차 표준화는 고유 엔티티 201개를 181개 표준형으로 모아 최종 160개로 줄였습니다. 트리플 수는 그대로 216개였으니, 이 단계는 관계를 늘리는 것이 아니라 같은 것을 같은 이름으로 부르게 만드는 작업입니다.

숫자가 크게 변하는 곳은 3차 패스입니다. 9개의 끊어진 커뮤니티를 찾아 커뮤니티 사이와 내부의 관계를 추론하고 어휘 유사도로 88개를 더 이어 붙여, 최종 그래프는 트리플 564개가 됐습니다. 원래 관계 209개에 추론된 관계 355개가 더해진 결과이고, 노드는 161개, 커뮤니티는 9개입니다. 추론 관계가 원본보다 많아진 만큼 이 결과를 그대로 사실로 받아들이면 곤란하며, 추론 패스를 끄고 원문에 명시된 관계만 남기는 선택지가 설정에 있는 이유이기도 합니다.

ai-knowledge-graph의 설정과 실행

동작 방식은 저장소의 config.toml 한 파일로 조정합니다. 모델과 엔드포인트, 청크 크기와 겹침 단어 수, 표준화와 추론의 사용 여부가 모두 여기 모여 있습니다.

[llm]
model = "gemma3"  # Google open weight model
api_key = "sk-1234"
base_url = "http://localhost:11434/v1/chat/completions"
max_tokens = 8192
temperature = 0.2

[chunking]
chunk_size = 200  # Number of words per chunk
overlap = 20      # Number of words to overlap between chunks

[standardization]
enabled = true
use_llm_for_entities = true

[inference]
enabled = true
use_llm_for_inference = true
apply_transitive = true

실행에는 Python 3.11 이상이 필요합니다. 저장소를 받아 의존성을 설치하고 입력 파일과 출력 경로를 지정하면 끝입니다.

pip install -r requirements.txt
python generate-graph.py --input your_text_file.txt --output knowledge_graph.html

uv 를 쓴다면 uv run generate-graph.py, 모듈로 설치해 쓰려면 pip install --upgrade -e . 뒤에 generate-graph 명령을 사용합니다. 명령줄에서 설정을 덮어쓸 수도 있어서, --no-standardize 와 --no-inference 로 2차·3차 패스를 각각 끄고 --debug 로 LLM의 원본 응답과 추출된 JSON을 확인할 수 있습니다. 입력 파일 없이 결과물을 먼저 보고 싶으면 샘플 데이터로 시각화를 만드는 --test 가 있습니다.

ai-knowledge-graph의 시각화 결과

시각화는 NetworkX로 그래프를 다루고 PyVis로 HTML을 만드는 구조이며, 결과는 HTML 파일과 원본 JSON 두 가지로 저장됩니다. 노드 색은 Louvain 방식으로 검출한 커뮤니티를 구분하고, 노드 크기는 연결 중심성(degree), 매개 중심성(betweenness), 고유벡터 중심성(eigenvector)을 반영해 정해집니다. 앞서 말한 대로 원문에서 추출한 관계는 실선, 추론된 관계는 점선입니다.

화면 위쪽 버튼들이 보여 주듯 물리 시뮬레이션을 켜고 끄거나, 라벨을 감추거나, 필터를 걸어 볼 수 있고 밝은 테마와 어두운 테마를 전환할 수 있습니다. 저자가 공개한 산업혁명 지식 그래프 데모에서 설치 없이 조작해 볼 수 있습니다.

ai-knowledge-graph는 누구에게 유용한가

외부로 내보낼 수 없는 문서를 다루면서 그 안의 관계를 훑어보고 싶은 경우에 잘 맞습니다. Ollama로 로컬 모델을 띄우면 문서가 장비 밖으로 나가지 않고, 설정 파일 하나만 고치면 되므로 시도 비용이 낮습니다. 코드가 추출·표준화·추론·시각화 단계로 나뉘어 있고 프롬프트도 src/knowledge_graph/prompts 디렉토리에 모여 있어, 자기 도메인에 맞게 추출 지침을 고쳐 쓰기에도 부담이 적습니다.

반면 검색이나 질의응답 파이프라인에 바로 얹을 그래프 저장소를 찾고 있다면 맞지 않습니다. 결과물은 대화형 HTML과 JSON이고 그래프 데이터베이스 연동이나 증분 갱신은 다루지 않으므로, 그 뒤는 직접 만들어야 합니다. 추론 패스가 만들어 내는 관계의 비중이 큰 것도 감안할 점입니다. 문서에 무엇이 적혀 있는지 정확히 알아야 하는 용도라면 추론을 끄고 쓰는 편이 안전하고, 반대로 전체 구조를 빠르게 훑는 용도라면 켜 두는 쪽이 도움이 됩니다.

ai-knowledge-graph의 라이선스

ai-knowledge-graph는 Apache 라이선스 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

ai-knowledge-graph로 만든 산업혁명 지식 그래프 데모

https://robert-mcdermott.github.io/ai-knowledge-graph/

ai-knowledge-graph 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!