veyliss/ai-localbase

一个本地优先的AI知识库系统（RAG），用于把本地文档接入辅导搜索与大模型对话流程。目前支持md、txt、pdf（文本）、xlsx、cvs类型。支持mcp服务

AI LocalBase – 로컬 우선의 RAG 지식 기반 시스템

한 줄 요약

Go, React, Qdrant를 사용해 구축한 자체 호스팅 벡터 검색 + 대규모 모델 대화 플랫폼으로, 개인 또는 소규모 팀이 로컬 문서(TXT, Markdown, PDF, Excel, CSV 등)를 검색 증강 질문 응답(RAG)에 연결하고, Ollama 또는 OpenAI 호환 모델을 통해 대화를 수행할 수 있도록 지원합니다.

핵심 기술 스택

계층	기술	설명
백엔드	Go + Gin	고성능 HTTP API로 문서 해석, 벡터화, 검색, 세션 관리 등의 비즈니스 로직을 담당
프론트엔드	React + Vite + TypeScript	단일 페이지 웹 UI로 지식 기반 관리, 파일 업로드, 채팅 인터페이스 등을 제공
벡터 데이터베이스	Qdrant	오픈소스 벡터 데이터베이스로 문서 벡터를 저장하고, 하이브리드 검색, MMR 중복 제거 등의 고급 검색 기능을 지원
모델 연동	Ollama / OpenAI‑호환 API	통일된 Provider 설정을 통해 로컬 Ollama 모델 또는 OpenAI 호환 채팅/임베딩 모델을 사용 가능
지속성 저장	SQLite (채팅 기록) + JSON 파일 (설정)	외부 데이터베이스 없이도 가벼운 로컬 저장을 제공
배포	Docker‑Compose (권장)	프론트엔드, 백엔드, Qdrant 세 개의 컨테이너를 한 번에 시작 가능하며, 단일 프로세스 디버깅 방식도 제공
확장성	MCP Server (내장)	외부 Agent, 스크립트 또는 도구 시스템이 로컬 지식 기반, 검색, 평가 기능을 호출할 수 있는 HTTP/JSON‑RPC 인터페이스

주요 기능

지식 기반 관리 – 여러 지식 기반을 생성, 삭제, 탐색 가능하며, 각각 Qdrant collection과 대응됨.
문서 업로드 및 자동 인덱싱 – TXT, Markdown, PDF, xlsx, csv 지원; 자동 분할, 대량 임베딩 후 벡터 데이터베이스에 기록.
검색 증강 질문 응답 (RAG) – 검색 결과를 대화 컨텍스트에 삽입하며, 다음과 같은 기능 지원:
- 동적 재검색, 키워드 커버리지, MMR 중복 제거
- 낮은 신뢰도 시 재검색, 의미적 캐시, 하이브리드 검색, 의미 재정렬, 쿼리 재작성, 컨텍스트 압축
채팅 기록 지속성 – 모든 대화는 로컬 SQLite에 저장되며, 프론트엔드에서 이전 대화를 확인 가능.
설정 지속성 – 모델, 벡터 데이터베이스, 인증 설정 등은 로컬 JSON 파일에 저장되어 컨테이너 재시작 시 자동 복원.
MCP (모듈형 기능 제공자) – 외부 Agent에게 도구 목록, 호출 인터페이스, 권한 계층, 제한, 감사 로그 등을 제공하며, 비동기 임포트, 인덱스 재구성, 평가 데이터셋 생성 등의 워크플로우를 지원.
보안 및 인증 – 환경 변수로 웹 로그인, API‑Key 인증을 활성화 가능; 프로덕션 배포 시 기본적으로 활성화됨.

대표적인 사용 사례

개인 지식 기반: 노트, 기술 문서, PDF 매뉴얼 등을 로컬화하여 언제든지 채팅 방식으로 검색 가능.
소규모 팀 내부 문서 질문 응답: 회사 내부 네트워크에서 자체 호스팅하여 데이터가 외부로 유출되지 않도록 보장.
RAG 프로토타입 검증: 다양한 검색 전략, 하이브리드 검색 또는 재정렬 모델을 빠르게 구축하고 실험 가능.
모델 연동 테스트: Ollama 로컬 모델과 클라우드 OpenAI‑호환 모델의 성능 및 비용을 비교 가능.
Agent 백엔드: MCP를 통해 사용자 정의 AI Agent에게 '문서 읽기 → 검색 → 답변 생성' 기능 제공.
대량 문서 처리: 비동기 방식으로 대량 파일을 임포트하며, 진행 상황 조회 및 작업 취소 가능.

빠른 시작 (최소 단계)

# 환경 변수 템플릿 복사 후 모든 컨테이너 시작
cp .env.example .env
docker compose up --build

http://localhost:4173 접속 → Settings → Chat 및 Embedding 모델 설정 (예: Ollama qwen2.5:7b + bge-m3)
문서 업로드 → 대화 시작, 시스템이 자동으로 관련 조각을 검색하여 컨텍스트에 삽입합니다.

완전한 시작, 디버깅, 프로덕션 배포 세부 사항은 docs/getting-started.md, DOCKER_DEPLOY.md 등의 문서를 참조하세요.

배포 옵션

시나리오	추천 방식
로컬 체험	`docker compose up --build` (단일 머신)
프로덕션 자체 호스팅	`docker-compose.prod.yml` 사용, `ENABLE_AUTH=true` 활성화, 강력한 비밀번호 또는 `AUTH_SETUP_TOKEN` 설정, 필요 시 Qdrant를 `0.0.0.0`에 바인딩하고 API‑Key 구성
백엔드/프론트엔드만 실행	`docker-compose.dev.yml` 내 해당 서비스를 별도로 시작하여 코드 마운트로 디버깅 용이
사용자 정의 이미지	`AI_LOCALBASE_IMAGE_TAG=v1.4.6 docker compose -f docker-compose.prod.yml up -d`

오픈소스 라이선스 & 커뮤니티

라이선스: MIT (see LICENSE)
기여 방법: CONTRIBUTING.md에 안내됨
보안: SECURITY.md
변경 내역: CHANGELOG.md
커뮤니티: https://linux.do에서 토론 및 Discord https://discord.gg/YzFeYC66y5

적합한 독자

클라우드 서비스에 의존하지 않고 로컬에서 RAG 프로세스를 빠르게 실험하고 싶은 개발자.
자체 호스팅이 가능하고 확장성이 있는 문서 질문 응답 플랫폼이 필요한 소규모 팀.
검색 전략, 하이브리드 검색, 사용자 정의 도구 체인(MCP를 통해)을 평가하고 싶은 AI 연구자.

프로젝트에 도움이 되었다면 저장소에 ⭐를 눌러주세요