Carrel – AI 에이전트를 위한 온톨로지 강화 지식 베이스

개요

문서 모음(PDF, Word, 코드, 이미지 등)에서 AI 에이전트가 최신 정보를 검색할 수 있는 자체 호스팅 서비스입니다.
파일을 파싱하고, 벡터 및 키워드 인덱스를 생성하고, 선택적으로 지식 그래프를 구축하며, 에이전트가 구절, 이미지, 그래프 증거를 쿼리할 수 있는 REST API를 노출합니다.

주요 기능

기능	설명
문서 파싱	PDF, Word, PowerPoint, 스프레드시트, HTML, Markdown, 소스 코드, 이미지를 지원합니다. MinerU 및 네이티브 파서를 사용하여 파일을 검색에 적합한 청크로 분할합니다.
자동 업데이트	지정된 폴더를 감시하고, 변경된 파일을 다시 파싱하고, 일정에 따라 인덱스와 그래프를 업데이트합니다.
하이브리드 검색	밀집 벡터 검색, 키워드 검색, 그래프 탐색, 시각적 검색을 결합하고 결과를 재순위화할 수 있습니다.
지식 그래프	채팅 모델을 통해 텍스트에서 엔터티, 관계, 타임스탬프, 충돌 플래그를 추출하여 Neo4j에 저장합니다.
에이전트 친화적 API	소스 구절, 원본 이미지, 연결된 그래프 사실을 반환합니다. 페이지네이션, 인용 메타데이터, 선택적 인증을 지원합니다.
웹 콘솔	지식 베이스, 모델 엔드포인트, 예약 작업, 서비스 상태를 관리하는 UI(영어/중국어).
모델 통합	노출하는 모든 임베딩, 비전-언어, 채팅 모델(로컬 Docker 컨테이너 또는 원격 엔드포인트)과 작동합니다.

작동 방식

수집 – runtime/mirror/<folder>/ 아래에 있는 파일이 파싱되고 청크로 분할됩니다.
인덱싱 – 청크는 Qdrant(벡터) 및 OpenSearch(키워드) 저장소로 전송됩니다.
그래프 구축 – 활성화된 경우 채팅 모델이 엔터티/관계를 추출하여 Neo4j에 저장합니다.
검색 API – 에이전트가 질문과 함께 POST /search를 호출하면 서비스가 벡터, 키워드, 그래프 저장소의 결과를 병합하고 텍스트 스니펫, 이미지 URL, 그래프 증거를 포함한 JSON 페이로드를 반환합니다.
피드백 루프 – 에이전트는 최종 답변을 생성하기 전에 더 많은 컨텍스트를 요청하거나 그래프 엣지를 따라갈 수 있습니다.

일반적인 사용 사례

코딩 어시스턴트(예: Claude, Codex)에 내부 제품 매뉴얼, 계약서, 회의 노트에 대한 접근 권한을 부여합니다.
인용 및 엔터티 관계가 중요한 연구 논문을 위한 검색 가능한 RAG 시스템을 구축합니다.
텍스트 검색과 함께 스캔된 PDF 또는 설계 다이어그램에 대한 시각적 검색을 활성화합니다.

빠른 시작

# 1. 스택을 클론하고 배포합니다(가능한 경우 Docker + systemd).
git clone https://github.com/FengZhenfei/carrel.git && cd carrel
./deploy.sh                     # OS를 감지하고 Qdrant, OpenSearch, Neo4j 등을 시작합니다.

# 2. config/knowledge-base.env에서 모델 엔드포인트(임베딩, 비전, 채팅)를 구성합니다.
#    – 선택 사항: ./deploy.sh --with-local-models로 번들 모델을 로컬에서 실행합니다.

# 3. 문서 추가
#    runtime/mirror/<my_kb>/ 아래에 파일을 놓고 웹 UI(http://127.0.0.1:9800)에서 폴더를 활성화합니다.

# 4. 번들 스킬 또는 curl로 쿼리
curl -sS http://127.0.0.1:9810/search \
  -H 'Content-Type: application/json' \
  -d '{"question":"What are the delivery and acceptance requirements?","top_k":8}'

응답에는 일치하는 구절과 사용 가능한 경우 그래프 노드 또는 이미지 참조가 포함됩니다.

설치 요구 사항

Python 3.12+ 및 Docker 25+(Compose v2).
선택적 로컬 모델 서비스를 위한 GPU(NVIDIA) + 컨테이너 도구 키트. 원격 모델 API를 가리키면 CPU 전용으로 작동합니다.
외부 서비스: Qdrant(벡터), OpenSearch(키워드), Neo4j(그래프), SQLite(메타데이터).
모델 엔드포인트: 텍스트 임베딩, 비전-언어(이미지 캡션용), 채팅 모델(그래프 추출용).

문서 및 확장성

구성 – 모델 URL, 폴더 설정, 접근 제어에 대한 자세한 가이드.
아키텍처 – 파싱 파이프라인, 스토리지 선택, 검색 흐름을 설명합니다.
검색 및 API – 요청 형식, 인증, 응답 스키마, 인용 처리.
운영 – 콘솔 사용법, CLI, systemd 타이머, Docker Compose 프로필, 테스트.
스킬 – 동일한 API를 따르는 에이전트를 위한 즉시 사용 가능한 carrel-search 스킬.

라이선스

코드는 MIT 라이선스입니다. 타사 종속성 및 모델 가중치는 각각 고유한 라이선스를 가집니다(NOTICE.md 참조).

Carrel은 온톨로지 수준의 증거로 검색을 강화하는 풀스택 온프레미스 지식 베이스 플랫폼으로, 신뢰할 수 있는 최신 소스 자료가 필요한 모든 AI 에이전트에 적합합니다.

FengZhenfei/carrel

Carrel – AI 에이전트를 위한 온톨로지 강화 지식 베이스

관련