Knowhere – 비구조화 문서를 AI 에이전트용 메모리로 변환

무엇인가요

Knowhere는 모든 종류의 비구조화 파일(PDF, PowerPoint, Word, 이미지, markdown 등)을 수집하고 파싱하여 AI 에이전트가 쿼리할 수 있는 계층 네이티브 메모리 그래프에 저장하는 오픈소스 백엔드입니다.

• 듀얼 트랙 파싱 – 신뢰할 수 있는 텍스트 구조를 유지하는 텍스트 트랙과, 시각 언어 모델을 사용하여 복잡한 페이지(스캔된 PDF나 슬라이드 데크 등)를 이해하는 비전 트랙. 두 트랙 모두 동일한 청크 및 메타데이터 스키마를 출력합니다.
• 에이전트 중립적 검색 – 시스템은 아웃라인 탐색, 구조 필터, 정확/퍼지 검색 및 전체 페이지 읽기 도구를 갖춘 단일 코퍼스 API를 제공합니다. 에이전트는 이러한 도구를 언제 어떻게 호출할지 결정합니다.
• 문서 간 그래프 – 추출된 엔티티, 표, 이미지는 관련 문서를 연결하는 노드가 되어 "지식 그래프 스타일"의 검색을 가능하게 합니다.
• 인용 준비 완료 – 모든 결과는 원본 문서, 섹션, 페이지 번호 및 시각적 증거와 연결됩니다.

왜 중요한가요

기존의 RAG 파이프라인은 문서를 독립적인 텍스트 청크로 평탄화하여 계층, 인용 및 시각적 맥락을 잃어버립니다. Knowhere는 원본 구조를 유지하고 시각적 이해를 추가하여 에이전트가 다음을 수행할 수 있도록 합니다:

• 인간처럼 문서를 탐색(장 → 섹션 → 페이지).
• 페이지 번호와 이미지가 포함된 정확한 증거를 검색.
• OCR만으로는 어려운 초장문 PDF나 슬라이드 데크를 효율적으로 처리.

핵심 구성 요소 (저장소 설명 기준)

구성 요소	역할
API (apps/api)	파일 업로드, 파싱 작업 시작 및 메모리 그래프 쿼리를 위한 HTTP 엔드포인트.
Worker (apps/worker)	파싱 파이프라인(텍스트 또는 비전)을 실행하고 계층 그래프를 구축하는 백그라운드 프로세서.
Dashboard (별도 저장소)	컬렉션 관리, 파싱된 계층 보기 및 검색 테스트를 위한 Web UI.
셀프 호스팅 스택 (Docker-Compose)	API, Worker, Postgres, Redis 및 선택적 S3 스토리지를 위한 빠른 로컬 배포.
SDKs (Python/Node)	통합을 쉽게 하기 위해 API를 래핑한 경량 클라이언트 라이브러리.

시작하기 (빠른 시작 단계)

1. 의존성 설치 – Python 3.11+, uv, Docker-Compose.
2. Python 패키지 동기화: uv sync --all-packages.
3. 구성 – API 및 Worker용 .env.example 파일을 복사한 후 다음을 입력합니다:
   • DB/Redis 연결 정보
   • S3 호환 스토리지 자격 증명
   • 최소 하나 이상의 LLM 제공자 키(예: DeepSeek-Flash, OpenAI, Qwen 등)
   • 비전 트랙을 위한 비전 모델 자격 증명.
4. 스택 실행: ./deploy/local-dev/start-dev.sh (Postgres, Redis, LocalStack 등 시작).
5. 마이그레이션 실행 후 별도의 터미널에서 API와 Worker를 시작합니다.
6. API 사용 – V2 Jobs 엔드포인트를 통해 문서를 업로드합니다. 시스템이 적절한 트랙으로 라우팅하고 계층을 구축하여 검색 가능하게 만듭니다.

AI 에이전트의 일반적인 워크플로우

1. 수집 – 에이전트가 Knowhere API로 파일을 전송합니다.
2. 파싱 – Worker가 텍스트 또는 비전 파이프라인을 실행하고 출력을 공통 스키마로 정규화합니다.
3. 저장 – 노드(섹션, 페이지, 이미지, 표)가 메타데이터(경로, 인용, 엔티티)와 함께 영구 저장됩니다.
4. 검색 – 에이전트가 검색 API를 호출하여 outline, search, read_page와 같은 도구를 사용하여 그래프를 탐색합니다.
5. 인용 – 결과에는 정확한 출처 참조가 포함되어 신뢰할 수 있는 답변이 가능합니다.

README에서 강조된 주요 기능

• 시각적 페이지 이해 – 완벽한 OCR 불필요; VLM이 페이지 전체를 요약 가능.
• 초장문 PDF 지원 – 수백 페이지 및 아틀라스 스타일 문서 처리.
• 문서 간 메모리 그래프 – 타입화된 엔티티가 네임스페이스를 넘어 관련 문서를 연결.
• 벤치마크 – 내부 테스트 결과, 원본 문서 기준 대비 첫 시도 정확도 +36%, 재현율 +11% 향상.
• 텔레메트리 – 익명화된 사용 데이터가 PostHog로 전송됨(환경 변수로 옵트아웃 가능).

누가 사용하나요

• 구조화되고 인용 가능한 맥락이 필요한 에이전트형 RAG 시스템을 구축하는 개발자.
• 대규모 내부 문서 라이브러리(매뉴얼, 슬라이드 데크, 연구 PDF)를 보유하고 검색 가능한 지식 베이스를 원하는 기업.
• 재현 가능한 문서 파싱 파이프라인이 필요하고 정확한 페이지를 인용하려는 연구자.

라이선스 및 커뮤니티

• Apache 2.0 라이선스.
• 활발한 GitHub Discussions, 이슈 트래커 및 기여 가이드.
• Docker 이미지는 GitHub Container Registry에 게시됨.
• 이 프로젝트는 2026년 5월부터 오픈 소스로 공개되었으며, 빠른 체험을 위한 관리형 클라우드 서비스도 제공합니다.

---

위의 모든 세부 정보는 저장소의 README에서 직접 가져온 것이며, 추가적인 주장은 포함되지 않았습니다.