juanceresa/sift-kg문서 모음을 지식 그래프로 변환하세요. LLM을 통해 엔터티와 관계를 추출하고, 사용자 승인을 통해 중복을 제거합니다. 도메인을 매핑하고, 숨겨진 연결을 찾고, 문서 간 패턴을 발견하세요 — 지속되고 축적되는 지식, 당신과 당신의 AI 에이전트를 위한 것입니다. 모든 것을 CLI에서 할 수 있습니다.
모든 문서 컬렉션을 지식 그래프로 변환하세요.
코드, 데이터베이스, 인프라 없이 — CLI와 문서만 있으면 됩니다. PDF, 논문, 기사, 기록을 넣으면 — 모든 것이 어떻게 연결되어 있는지 보여주는 탐색 가능한 지식 그래프를 몇 분 만에 얻을 수 있습니다. sift-kg는 LLM을 통해 엔티티와 관계를 추출하고, 승인을 받아 중복을 제거한 후, 브라우저에서 탐색할 수 있는 대화형 뷰어를 생성합니다. 모든 것에 대한 개념 지도를 손끝에서 만나보세요.
시각화를 구동하는 동일한 그래프는 AI 두 번째 뇌로도 작동합니다. 모두가 Notion과 Obsidian에서 지식 베이스를 구축하는 데 몇 달을 보내고 있습니다. 그럴 시간이 누가 있나요? sift-kg는 2년 대신 2분 만에 구축하는 구조화된 메모리입니다. 문서를 가리키기만 하면 AI가 모든 것이 어떻게 연결되어 있는지 구조적으로 이해할 수 있습니다.
라이브 데모 → sift-kg로 완전히 생성된 그래프```bash pip install sift-kg
sift init # create sift.yaml + .env.example sift extract ./documents/ # extract entities & relations sift build # build knowledge graph sift resolve # find duplicate entities sift review # approve/reject merges interactively sift apply-merges # apply your decisions sift narrate # generate narrative summary sift view # interactive graph in your browser sift export graphml # export to Gephi, yEd, Cytoscape, SQLite, etc.
## 작동 방식```
Documents (PDF, DOCX, text, HTML, and 75+ formats)
↓
Text Extraction (Kreuzberg, local) — with optional OCR (Tesseract, EasyOCR, PaddleOCR, or Google Cloud Vision)
↓
Schema Discovery (LLM designs entity/relation types from your data — or use a predefined domain)
↓
Entity & Relation Extraction (LLM, using discovered or predefined schema)
↓
Knowledge Graph (NetworkX, JSON)
↓
Entity Resolution (LLM proposes → you review)
↓
Narrative Generation (LLM)
↓
Interactive Viewer (browser) / Export (GraphML, GEXF, CSV, SQLite)
모든 엔티티와 관계는 원본 문서와 구절로 연결됩니다. 병합할 대상을 사용자가 제어합니다. 그래프는 여러분의 것입니다.
sift.yaml을 넣어 지속적인 설정을 할 수 있습니다.discovered_domain.yaml로 저장합니다. 또는 구조화된 도메인(general, osint, academic)을 사용하여 고정 스키마를 사용하거나 YAML로 직접 정의할 수 있습니다.sift search "SBF"로 이름이나 별칭으로 엔티티를 찾고, 선택적으로 관계 및 설명 출력을 포함합니다.--neighborhood, --top, --community, --source-doc, --min-confidencesift-kg는 AI 에이전트가 직접 작업할 수 있는 구조화된 지식을 생성합니다.
sift를 문서, 노트 또는 프로젝트 파일에 지정하세요. 출력물인 JSON 지식 그래프는 모든 AI 에이전트에게 여러분 세계의 모든 것이 어떻게 연결되는지에 대한 지속적이고 구조화된 이해를 제공합니다. 수동 정리, 태깅, 위키 링크가 필요 없습니다. 구조는 콘텐츠에서 자연스럽게 나타납니다.```bash sift extract ./my-stuff/ sift build sift topology # structural overview (JSON, for agents) sift query "topic" # entity neighborhood subgraph (JSON, for agents) sift search "X" --json # entity lookup (JSON, for agents) sift info --json # project stats (JSON, for agents)
그래프는 세션 간에 지속되며 점진적으로 성장합니다. 새 문서를 동일한 출력 디렉터리에 추출하고 다시 빌드하세요. 엔터티 중복 제거는 그래프가 성장함에 따라 일관성을 유지하도록 보장합니다.
**이것이 에이전트에 제공하는 것:**
- **구조** — 텍스트 청크뿐만 아니라 엔터티, 관계, 커뮤니티 및 이들이 연결되는 방식
- **토폴로지** — 어떤 지식 클러스터가 존재하는지, 무엇이 이를 연결하는지, 무엇이 고립되어 있는지
- **내구성** — 그래프는 컨텍스트 창 초기화에도 유지됩니다. 에이전트가 매 세션마다 처음부터 시작하지 않게 됩니다.
**번들 에이전트 스킬:** sift-kg는 `.agents/skills/sift-kg/SKILL.md`에 있는 스킬과 함께 제공되며, 이 스킬은 에이전트에게 지식 그래프를 지속적 메모리로 사용하는 방법을 가르칩니다 — 세션 오리엔테이션, 엔터티 탐색, 링크-지식-고립 추론, 그리고 근거 기반 제안 생성.
## 번들 도메인
sift-kg는 즉시 사용할 수 있는 특화된 도메인과 함께 제공됩니다:```bash
sift domains # list available domains
sift extract ./docs/ --domain-name osint # use a bundled domain
sift.yaml 파일에 도메인을 설정하면 매번 플래그를 사용할 필요가 없습니다:```yaml
domain: academic
번들 이름(`schema-free`, `general`, `osint`, `academic`) 또는 사용자 정의 YAML 파일 경로와 함께 작동합니다.
| Domain | Focus | Key Entity Types | Key Relation Types |
|--------|-------|------------------|--------------------|
| `schema-free` | 데이터에서 자동 발견 (기본값) | *(LLM이 말뭉치별로 설계)* | *(LLM이 말뭉치별로 설계)* |
| `general` | 일반 문서 분석 | PERSON, ORGANIZATION, LOCATION, EVENT, DOCUMENT | ASSOCIATED_WITH, MEMBER_OF, LOCATED_IN |
| `osint` | 조사 및 정보공개청구(FOIA) | SHELL_COMPANY, FINANCIAL_ACCOUNT | BENEFICIAL_OWNER_OF, TRANSACTED_WITH, SIGNATORY_OF |
| `academic` | 문헌 검토 및 주제 매핑 | CONCEPT, THEORY, METHOD, SYSTEM, FINDING, PHENOMENON, RESEARCHER, PUBLICATION, FIELD, DATASET | SUPPORTS, CONTRADICTS, EXTENDS, IMPLEMENTS, EXPLAINS, PROPOSED_BY, USES_METHOD, APPLIED_TO, INVESTIGATES |
**academic** 도메인은 연구 분야의 지적 풍경을 매핑합니다 — 논문을 입력하면 이론, 방법, 시스템, 발견, 개념이 어떻게 연결되는지 그래프를 얻습니다. 추상적인 아이디어(THEORY, METHOD)와 구체적인 산출물(SYSTEM — 예: GPT-2, BERT, GLUE)을 구분합니다. 문헌 검토, 주제 매핑, 그리고 아이디어가 서로 일치, 모순 또는 기반을 둔 부분을 이해하기 위해 설계되었습니다.
**schema-free** 도메인(기본값)은 추출 전에 **스키마 발견** 단계를 실행합니다 — 한 번의 LLM 호출이 문서를 샘플링하고 말뭉치에 맞춘 엔터티 및 관계 유형을 설계합니다. 발견된 스키마는 `output/discovered_domain.yaml`에 저장되며 후속 실행에서 재사용되므로 유형이 모든 청크와 문서에서 일관되게 유지됩니다. 파일을 검사, 수동 편집 또는 복사하여 사용자 정의 도메인의 시작점으로 사용할 수 있습니다. `--force`를 사용하여 재발견합니다. ASSOCIATED_WITH와 같은 미리 정의된 범주로 관계를 강제하는 대신, FUNDED, TESTIFIED_AGAINST, ENROLLED_AT와 같은 특정 유형을 생성합니다. 사전에 정의한 고정 스키마를 원할 경우 `general` 또는 `osint`와 같은 구조화된 도메인을 사용하세요.
**general** 도메인은 PERSON, ORGANIZATION, LOCATION, EVENT, DOCUMENT 엔터티 유형과 공통 관계 유형이 포함된 고정 스키마를 제공합니다. 문서 전체에서 예측 가능하고 일관된 유형을 원할 때 유용합니다.
**osint** 도메인은 페이퍼 컴퍼니, 금융 계좌, 역외 관할권에 대한 엔터티 유형과 실질적 소유권 및 자금 흐름 추적을 위한 관계 유형을 추가합니다.
사용자의 승인 없이는 병합되지 않습니다 — LLM이 제안하면 사용자가 확인합니다. 모든 추출은 원본 문서와 구절로 다시 연결됩니다.
개념 그래프로 매핑된 12개의 기본 AI 논문(425개 엔터티, 약 $0.72)은 [`examples/transformers/`](https://github.com/juanceresa/sift-kg/blob/HEAD/examples/transformers/)에서, FTX 붕괴(9개 기사에서 431개 엔터티)는 [`examples/ftx/`](https://github.com/juanceresa/sift-kg/blob/HEAD/examples/ftx/)에서 확인하세요. [**라이브 데모 살펴보기**](https://juanceresa.github.io/sift-kg/) — 설치 불필요, API 키 불필요.
## Civic Table
포렌식 법적 분석 및 분석가 검증이 포함된 호스팅 플랫폼을 찾고 계신가요?
[**Civic Table**](https://github.com/juanceresa/forensic_analysis_platform)은 sift-kg 파이프라인을 기반으로 구축된 포렌식 인텔리전스 플랫폼입니다. AI가 추출한 사실이 증거로 취급되기 전에 분석가와 법학박사가 검증하는 4단계 검증 시스템, 법적 제출을 위한 LaTeX 문서 생성, 클라이언트 및 가족과 결과를 공유하기 위한 웹 인터페이스를 추가합니다. 재산 반환, 탐사 저널리즘 및 문서 출처가 중요한 모든 상황을 위해 구축되었습니다.
sift-kg는 오픈소스 CLI입니다. Civic Table은 전체 플랫폼이며, 출력물이 증거 가치를 가지기 전에 분석가와 법학박사가 검토하는 곳입니다.
## Installation
Python 3.11+가 필요합니다.```bash
pip install sift-kg
OCR 지원(스캔된 PDF, 이미지)의 경우:```bash
brew install tesseract # macOS sudo apt install tesseract-ocr # Ubuntu/Debian
Google Cloud Vision OCR을 대체 백엔드로 사용하려는 경우 (선택 사항):```bash
pip install sift-kg[ocr]
# Then use: sift extract ./docs/ --ocr --ocr-backend gcv
엔터티 해결 중 의미론적 클러스터링을 위한 (선택 사항, PyTorch의 경우 ~2GB):```bash pip install sift-kg[embeddings]
개발용:```bash
git clone https://github.com/juanceresa/sift-kg.git
cd sift-kg
pip install -e ".[dev]"
sift init # creates sift.yaml + .env.example cp .env.example .env # copy and add your API key
`sift init`는 `sift.yaml` 프로젝트 설정 파일을 생성하여 매 명령마다 플래그를 지정할 필요가 없도록 해줍니다:```yaml
# sift.yaml
domain: domain.yaml # or a bundled name like "osint"
model: openai/gpt-4o-mini
ocr: true # enable OCR for scanned PDFs
# extraction:
# backend: kreuzberg # kreuzberg (default, 75+ formats) | pdfplumber
# ocr_backend: tesseract # tesseract | easyocr | paddleocr | gcv
# ocr_language: eng
.env 파일에 API 키를 설정하세요:```
SIFT_OPENAI_API_KEY=sk-...
아니면 Anthropic, Mistral, Ollama 또는 모든 LiteLLM 제공자를 사용하세요:```
SIFT_ANTHROPIC_API_KEY=sk-ant-...
SIFT_MISTRAL_API_KEY=...
설정 우선순위: CLI 플래그 > 환경 변수 > .env > sift.yaml > 기본값. sift.yaml의 모든 것을 어떤 명령어의 플래그로 재정의할 수 있습니다.
sift extract ./my-documents/ sift extract ./my-documents/ --ocr # local OCR via Tesseract sift extract ./my-documents/ --ocr --ocr-backend gcv # Google Cloud Vision OCR sift extract ./my-documents/ --extractor pdfplumber # legacy pdfplumber backend
75개 이상의 문서 형식 — PDF, DOCX, XLSX, PPTX, HTML, EPUB, 이미지 등 — 을 읽습니다. 구성된 LLM을 사용하여 엔티티와 관계를 추출합니다. 결과는 `output/extractions/`에 JSON으로 저장됩니다.
`--ocr` 플래그는 스캔된 PDF에 대해 Tesseract를 통한 로컬 OCR을 활성화합니다 — API 키나 클라우드 서비스가 필요 없습니다. `--ocr-backend`로 OCR 엔진을 전환할 수 있습니다:```bash
sift extract ./docs/ --ocr # Tesseract (default, local)
sift extract ./docs/ --ocr --ocr-backend easyocr # EasyOCR (local)
sift extract ./docs/ --ocr --ocr-backend paddleocr # PaddleOCR (local)
sift extract ./docs/ --ocr --ocr-backend gcv # Google Cloud Vision (requires credentials)
어떤 PDF에 OCR이 필요한지 자동 감지합니다. 텍스트가 풍부한 PDF는 표준 추출을 사용하고, 거의 빈 페이지에만 OCR로 대체됩니다. 혼합 폴더에 안전합니다. --ocr 옵션이 없으면 sift는 PDF가 스캔된 것으로 보일 경우 경고합니다.
또한 --extractor pdfplumber를 사용하여 레거시 pdfplumber 백엔드(PDF/DOCX/TXT/HTML만 해당)로 추출 백엔드를 완전히 전환할 수 있습니다.
sift build
모든 추출 결과로부터 NetworkX 그래프를 구축합니다. 그래프 노드가 되기 전에 거의 동일한 엔터티 이름(복수형, 유니코드 변형, 대소문자 차이)을 자동으로 중복 제거합니다. LLM이 도메인 스키마와 반대로 소스/대상 유형을 바꾸는 경우, 잘못된 방향의 에지(edge)를 수정합니다. 검토를 위해 낮은 신뢰도의 관계에 플래그를 지정합니다. `output/graph_data.json`에 저장합니다.
### 4. 중복 엔터티 해결
전체 가이드는 아래의 [엔터티 해결 워크플로우](#entity-resolution-workflow)를 참조하세요. 특히 정확성이 중요한 족보, 법률, 수사 사례에서 중요합니다.
### 5. 탐색 및 내보내기
**대화형 뷰어** — 브라우저에서 개념 지도를 탐색하세요:```bash
sift view # full graph
sift view --neighborhood "Palantir Technologies" # 1-hop ego graph around an entity
sift view --neighborhood "Palantir" --depth 3 # 3-hop neighborhood
sift view --top 10 # top 10 hubs + their neighbors
sift view --community "Community 1" # focus on a specific community
sift view --source-doc palantir_nsa_surveillance # entities from one document
sift view --min-confidence 0.8 # hide low-confidence nodes/edges
브라우저에서 힘-방향 그래프(force-directed graph)를 엽니다. 개요에는 커뮤니티 영역 — 관련 엔티티를 그룹화하는 색상별 볼록 껍질(convex hull) — 이 표시되어 레이블 혼란 없이 그래프 구조를 한눈에 볼 수 있습니다. 노드 위에 마우스를 올리면 이름과 연결 관계를 미리 볼 수 있습니다. 검색, 유형/커뮤니티/관계 토글, 소스 문서 필터, 차수(degree) 필터, 상세 사이드바가 포함되어 있습니다.
사전 필터 플래그(--top, --neighborhood, --source-doc, --min-confidence)는 렌더링 전에 그래프를 줄입니다. --community는 사이드바에서 커뮤니티를 미리 선택합니다. --neighborhood는 엔티티 ID(person:alice) 또는 표시 이름(대소문자 구분 안 함)을 받습니다.
초점 모드: 엔티티를 두 번 클릭하면 해당 엔티티의 이웃이 격리됩니다. 방향키를 사용하여 연결을 하나씩 탐색합니다. 각 쌍은 레이블이 지정된 에지와 함께 격리되어 표시됩니다. Enter/오른쪽 키를 누르면 이웃으로 초점이 이동하고, Backspace/왼쪽 키를 누르면 경로를 따라 뒤로 이동하며, Escape 키를 누르면 종료합니다. 탐색 내역은 사이드바에 **경로 이동 경로(trail breadcrumb)**로 추적됩니다. 이는 방문한 모든 노드와 그 사이의 관계를 보여주는 지속적인 경로입니다. 경로 에지는 캔버스에서 강조 표시되어 그래프를 통과하는 경로를 볼 수 있습니다. 이것이 밀집 그래프를 탐색하기 위한 의도된 방법입니다. 중요한 부분에 확대하고, 연결을 추적하고, 증거를 읽으십시오.
CLI 검색 — 터미널에서 직접 엔티티를 쿼리합니다:```bash sift search "Sam Bankman" # search by name sift search "SBF" # search by alias sift search "Caroline" -r # show relations sift search "FTX" -d -t ORGANIZATION # descriptions + type filter
**Static exports** — 분석 도구 중 사용자 정의 레이아웃, 필터링 또는 스타일링을 원하는 경우:```bash
sift export graphml # → output/graph.graphml (Gephi, yEd, Cytoscape)
sift export gexf # → output/graph.gexf (Gephi native)
sift export sqlite # → output/graph.sqlite (SQL queries, DuckDB, Datasette)
sift export csv # → output/csv/entities.csv + relations.csv
sift export json # → output/graph.json
노드 크기, 간선 가중치, 사용자 정의 색 구성표를 제어하거나 전용 도구에서 그래프 알고리즘(중심성, 커뮤니티 탐지)을 적용하려면 GraphML/GEXF를 사용하세요. SQLite는 임시 SQL 쿼리, Datasette 게시, 또는 DuckDB로 로드하는 데 유용합니다.```bash sift narrate sift narrate --communities-only # regenerate community labels only (~$0.01)
`output/narrative.md`를 생성합니다. 이는 개요, 주요 개체 간의 주요 관계 체인, 타임라인(데이터에 날짜가 있는 경우), 그리고 주제별 커뮤니티(루뱅 커뮤니티 탐지를 통해 발견됨)별로 그룹화된 개체 프로필을 포함하는 산문 보고서입니다. 개체 설명은 역할 요약이 아닌 특정 동작을 포함한 능동태로 작성됩니다.
## 도메인 구성
sift-kg는 네 개의 번들 도메인과 함께 제공됩니다(자세한 내용은 위의 [번들 도메인](#bundled-domains) 참조). 기본값은 `schema-free`입니다.
번들 도메인 사용:```bash
sift extract ./docs/ --domain-name osint
또는 자신만의 domain.yaml을(를) 만드세요:```yaml
name: My Domain
fallback_relation: RELATED_TO # optional — catch-all for relations that don't fit defined types
entity_types:
PERSON:
description: People and individuals
extraction_hints:
- Look for full names with titles
COMPANY:
description: Business entities
DEPARTMENT:
description: Named departments within a company
canonical_names: # closed vocabulary — only these values allowed
- Engineering
- Sales
- Legal
- Marketing
canonical_fallback_type: ORGANIZATION # non-canonical names get retyped
relation_types:
EMPLOYED_BY:
description: Employment relationship
source_types: [PERSON]
target_types: [COMPANY]
OWNS:
description: Ownership relationship
symmetric: false
review_required: true
RELATED_TO: # define the fallback type if you use one
description: General relationship
**스키마 강제:** 도메인에서 정의된 엔터티 유형과 관계 유형은 닫힌 집합으로 취급됩니다 — LLM은 이러한 유형만 사용하도록 지시되며 새로운 유형을 생성하지 않습니다. `fallback_relation`이 설정된 경우, 정의된 유형에 맞지 않는 관계는 폴백에 매핑됩니다. 생략된 경우, LLM은 가장 가까운 일치하는 정의된 유형을 낮은 신뢰도로 사용합니다. 많은 관계가 폴백 유형으로 분류되는 경우, 스키마에 데이터가 필요로 하는 관계 유형이 누락되었을 가능성이 높습니다 — 추가하고 다시 추출하세요.
`canonical_names`가 있는 엔터티 유형은 닫힌 어휘를 강제합니다. 허용된 이름은 LLM 추출 프롬프트에 주입되어 정확히 일치하는 결과를 출력합니다. 안전망으로, 목록에 없는 추출된 이름은 그래프 구축 중 `canonical_fallback_type`으로 다시 유형화됩니다(또는 폴백이 설정되지 않은 경우 그대로 유지됩니다). 통제된 분류 체계(부서, 관할권, 미리 정의된 분류)에 유용합니다.```bash
sift extract ./docs/ --domain path/to/domain.yaml
Python에서 sift-kg 사용 — Jupyter 노트북, 스크립트, 웹 앱:```python from sift_kg import load_domain, run_extract, run_build, run_narrate, run_resolve, run_export, run_view from sift_kg import KnowledgeGraph from pathlib import Path
domain = load_domain() # or load_domain(bundled_name="osint")
results = run_extract( Path("./docs"), "openai/gpt-4o-mini", domain, Path("./output"), ocr=True, ocr_backend="tesseract", # enable OCR for scanned PDFs extractor="kreuzberg", # or "pdfplumber" concurrency=4, chunk_size=10000, )
kg = run_build(Path("./output"), domain) print(f"{kg.entity_count} entities, {kg.relation_count} relations")
merges = run_resolve(Path("./output"), "openai/gpt-4o-mini", domain=domain, use_embeddings=True)
run_export(Path("./output"), "sqlite")
run_narrate(Path("./output"), "openai/gpt-4o-mini", communities_only=True)
run_view(Path("./output")) # full graph run_view(Path("./output"), neighborhood="person:alice", depth=2) # ego graph run_view(Path("./output"), top_n=10) # top hubs
from sift_kg import run_pipeline run_pipeline(Path("./docs"), "openai/gpt-4o-mini", domain, Path("./output"))
## 프로젝트 구조
파이프라인을 실행한 후, 출력 디렉터리에는 다음이 포함됩니다:```
output/
├── extractions/ # Per-document extraction JSON
│ ├── document1.json
│ └── document2.json
├── discovered_domain.yaml # Auto-discovered schema (schema-free mode)
├── graph_data.json # Knowledge graph (native format)
├── merge_proposals.yaml # Entity merge proposals (DRAFT/CONFIRMED/REJECTED)
├── relation_review.yaml # Flagged relations for review
├── narrative.md # Generated narrative summary
├── entity_descriptions.json # Entity descriptions (loaded by viewer)
├── communities.json # Community assignments (shared by narrate + viewer)
├── graph.html # Interactive graph visualization
├── graph.graphml # GraphML export (if exported)
├── graph.gexf # GEXF export (if exported)
├── graph.sqlite # SQLite export (if exported)
└── csv/ # CSV export (if exported)
├── entities.csv
└── relations.csv
가족 기록, 법률 문서, 또는 정확성이 중요한 문서에서 지식 그래프를 구축할 때, 어떤 엔터티를 병합할지 완전히 제어하기를 원할 것입니다. sift-kg는 승인 없이 절대 병합하지 않습니다.
워크플로는 세 가지 계층으로 구성되며, 각 계층은 서로 다른 종류의 중복을 잡아냅니다:
sift build 중)엔터티가 그래프 노드가 되기 전에, sift는 결정론적으로 명백히 동일한 이름을 축소합니다. LLM은 사용되지 않으며, 비용도 없고, 검토도 필요 없습니다:
이 작업은 sift build를 실행할 때마다 자동으로 수행됩니다. 이는 사소한 경우들입니다 — 그래프를 복잡하게 만들 뿐 정보를 추가하지 않는 철자 변형들입니다.
sift resolve 중)LLM은 엔터티 배치를 보고 (DOCUMENT 유형 제외) 동일한 실제 대상을 가리킬 가능성이 있는 것들을 식별합니다. 또한 교차 유형 중복 (같은 이름, 다른 엔터티 유형)을 감지하고, 부모/자식 패턴을 발견하면 변형 관계 (EXTENDS)를 제안합니다. 결과는 merge_proposals.yaml (엔터티 병합)과 relation_review.yaml (변형 관계)로 전송되며, 모두 DRAFT로 시작됩니다:```bash
sift resolve # uses domain from sift.yaml
sift resolve --domain osint # or specify explicitly
도메인이 구성되어 있는 경우, LLM은 해당 컨텍스트를 사용하여 특정 분야의 엔티티 이름에 대해 더 나은 판단을 내립니다.
이렇게 생성되는 제안 예시:```yaml
proposals:
- canonical_id: person:samuel_benjamin_bankman_fried
canonical_name: Samuel Benjamin Bankman-Fried
entity_type: PERSON
status: DRAFT # ← you decide
members:
- id: person:bankman_fried
name: Bankman-Fried
confidence: 0.99
reason: Same person referenced with full name vs. surname only.
- canonical_id: person:stephen_curry
canonical_name: Stephen Curry
entity_type: PERSON
status: DRAFT # ← you decide
members:
- id: person:steph_curry
name: Steph Curry
confidence: 0.99
reason: Same basketball player referenced with nickname 'Steph' and full name 'Stephen'.
아직 병합되지 않았습니다. LLM이 제안하는 중이지, 결정하는 것이 아닙니다.
제안을 검토하는 두 가지 옵션이 있습니다:
옵션 A: 대화형 터미널 검토```bash sift review
각 `DRAFT` 제안을 하나씩 살펴봅니다. 각각에 대해 정식 엔티티, 제안된 병합 멤버, LLM의 신뢰도 및 추론을 확인할 수 있습니다. 승인, 거부 또는 건너뛸 수 있습니다. 높은 신뢰도의 제안(기본적으로 >0.85)은 자동 승인되고, 낮은 신뢰도의 관계(기본적으로 <=0.5)는 자동 거부됩니다:```bash
sift review # uses defaults: --auto-approve 0.85, --auto-reject 0.5
sift review --auto-approve 0.90 # raise the auto-approve threshold
sift review --auto-reject 0.3 # lower the auto-reject threshold
sift review --auto-approve 1.0 # disable auto-approve, review everything manually
옵션 B: YAML을 직접 편집
output/merge_proposals.yaml을 아무 텍스트 편집기에서 여세요. status: DRAFT를 CONFIRMED 또는 REJECTED로 변경합니다:```yaml
canonical_id: person:stephen_curry canonical_name: Stephen Curry entity_type: PERSON status: CONFIRMED # ← approve this merge members:
canonical_id: person:winklevoss_twins canonical_name: Winklevoss twins entity_type: PERSON status: REJECTED # ← these are distinct people, don't merge members:
**고정확도 사용 사례의 경우**(계보 연구, 법률 검토), YAML을 직접 편집하여 각 제안을 신중히 검토할 것을 권장합니다. 이 파일은 사람이 읽기 쉽게 설계되었습니다.
### 레이어 3b: 관계 검토
`sift build` 실행 중, 신뢰도 임계값(기본값 0.7) 미만의 관계 또는 도메인 구성에서 `review_required`로 표시된 유형의 관계가 `output/relation_review.yaml`에 플래그됩니다:```yaml
review_threshold: 0.7
relations:
- source_name: Alice Smith
target_name: Acme Corp
relation_type: WORKS_FOR
confidence: 0.45
evidence: "Alice mentioned she used to work near the Acme building."
status: DRAFT # ← you decide: CONFIRMED or REJECTED
flag_reason: Low confidence (0.45 < 0.7)
동일한 워크플로우: sift review로 검토하거나 YAML을 편집한 후 적용합니다.
모든 것을 검토한 후:```bash sift apply-merges
이것은 세 가지 작업을 수행합니다:
1. **확인된 엔티티 병합** — 구성원 엔티티가 정식 엔티티에 흡수됩니다. 모든 관계가 재연결됩니다. 원본 문서가 결합됩니다. 구성원 노드는 제거됩니다.
2. **거부된 관계** — 그래프에서 완전히 제거됩니다.
3. **초안 제안** — 건드리지 않고 남겨둡니다. 나중에 다시 검토할 수 있습니다.
그래프는 `output/graph_data.json`에 다시 저장됩니다. 정리된 그래프를 다시 내보내거나, 설명하거나, 시각화할 수 있습니다.
### 반복
엔티티 해결(resolution)은 항상 한 번에 완료되지 않습니다. 병합 후 새로운 중복이 드러날 수 있습니다. 다음을 다시 실행할 수 있습니다:```bash
sift resolve # find new duplicates in the cleaned graph
sift review # review the new proposals
sift apply-merges # apply again
각 실행은 누적됩니다 — merge_proposals.yaml의 이전 CONFIRMED/REJECTED 결정이 유지됩니다.
사전 중복 제거 및 LLM 배칭 기술은 @stochastic-sisyphus의 KGGen (NeurIPS 2025)에서 영감을 받았습니다. KGGen은 결정적 개체 중복 제거를 위해 SemHash를 사용하고, LLM 비교 전에 개체를 그룹화하기 위해 임베딩 기반 클러스터링을 사용합니다. sift-kg는 이를 인간-루프 검토 워크플로우에 적용합니다.
기본적으로 sift resolve는 개체를 알파벳순으로 정렬하고 LLM 비교를 위해 중첩 배치로 분할합니다. 이는 중복 항목의 철자가 유사할 때 잘 작동하지만 — "Robert Smith"(R)와 "Bob Smith"(B)는 다른 배치에 배치되어 비교되지 않습니다.```bash
pip install sift-kg[embeddings] # sentence-transformers + scikit-learn (~2GB, pulls PyTorch)
sift resolve --embeddings
이것은 알파벳순 배치를 문장 임베딩(all-MiniLM-L6-v2)에 대한 KMeans 클러스터링으로 대체합니다. 의미적으로 유사한 이름들은 철자와 관계없이 함께 클러스터링됩니다.
| | 기본값 (알파벳순) | `--embeddings` |
|---|---|---|
| 설치 크기 | 포함됨 | ~2GB (PyTorch) |
| 첫 실행 오버헤드 | 없음 | ~90MB 모델 다운로드 |
| 실행 당 오버헤드 | 정렬만 | 인코딩 (수백 개 엔터티에 대해 1초 미만) |
| 교차 알파벳 중복 | 다른 배치에 있으면 놓침 | 포착됨 |
| 작은 그래프 (<100/타입) | 동일한 결과 | 동일한 결과 |
의존성이 설치되지 않았거나 클러스터링이 실패하면 알파벳순 배치로 대체됩니다.
## License
MIT
--ocr 플래그), 선택적 Google Cloud Vision 폴백(--ocr-backend gcv)--max-cost를 설정하여 LLM 비용 상한선 지정| 사용 사례 | 제안된 방법 |
|---|
| 빠른 탐색 | sift review --auto-approve 0.85 — 높은 신뢰도는 승인, 나머지는 검토 |
| 계보/가족 기록 | YAML을 수동으로 편집하고 --auto-approve 1.0 — 모든 병합을 하나씩 검토 |
| 법률/수사 | sift resolve --embeddings, YAML 수동 편집, 라운드 사이에 sift view로 검사 |
| 대규모 코퍼스 (1000+ 개체) | 더 나은 배칭을 위해 sift resolve --embeddings, 그 다음 대화형 검토 |