Eclaire: 개인 데이터 관리를 위한 로컬 우선 AI 어시스턴트 구축하기

⏱️ 예상 읽기 시간: 15분

소개

데이터 프라이버시와 AI 기능이 점점 중요해지는 시대에, Eclaire는 인공지능의 힘과 로컬 우선 아키텍처의 보안성을 결합한 혁신적인 솔루션으로 등장했습니다. 이 오픈소스 AI 어시스턴트를 사용하면 작업, 노트, 문서, 사진, 북마크를 통합하면서도 모든 데이터를 완전히 비공개로 유지하고 사용자의 통제 하에 둘 수 있습니다.

외부 서버로 데이터를 전송하는 클라우드 기반 AI 어시스턴트와 달리, Eclaire는 완전히 로컬 머신에서 실행되어 민감한 정보가 절대 기기를 떠나지 않도록 보장합니다. 이 튜토리얼은 Eclaire를 설정, 구성, 사용하여 개인 및 업무 데이터 관리 방식을 혁신하는 완전한 과정을 안내합니다.

Eclaire란 무엇인가?

Eclaire는 개인 데이터 생태계를 정리하고 상호작용할 수 있도록 설계된 로컬 우선, 오픈소스 AI 어시스턴트입니다. 프라이버시를 핵심 원칙으로 구축되어 데이터 보안을 손상시키지 않으면서 지능적인 지원을 제공합니다.

주요 기능

🔒 프라이버시 우선 아키텍처

모든 데이터 처리가 로컬 머신에서 발생
핵심 기능에 대한 외부 API 호출이나 클라우드 의존성 없음
데이터와 AI 상호작용에 대한 완전한 통제권

🤖 고급 AI 기능

다양한 LLM 백엔드 지원 (llama.cpp, vLLM, MLX, Ollama)
지능적인 문서 처리 및 OCR
텍스트와 이미지를 위한 멀티모달 AI 지원
도구 호출 및 에이전트 기능

📊 통합 데이터 관리

작업 관리 및 노트 작성
문서 처리 및 아카이빙
AI 기반 분석을 통한 사진 정리
콘텐츠 추출을 통한 북마크 관리
모든 데이터 유형에 대한 전문 검색

🛠️ 개발자 친화적

확장성을 위한 RESTful API
명확한 관심사 분리를 통한 모듈식 아키텍처
쉬운 배포를 위한 Docker 지원
포괄적인 문서화 및 커뮤니티 지원

아키텍처 개요

Eclaire는 현대적이고 모듈식 아키텍처를 따릅니다:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   프론트엔드     │    │   백엔드 API    │    │ 백그라운드      │
│   (Next.js)     │◄──►│   (Node.js)     │◄──►│ 워커           │
│                 │    │                 │    │ (BullMQ/Redis)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌─────────────────┐
                    │   데이터 계층    │
                    │ PostgreSQL +    │
                    │ 파일 저장소     │
                    └─────────────────┘
                                 ▲
                    ┌─────────────────┐
                    │   AI 서비스     │
                    │ 로컬 LLM       │
                    │ 백엔드         │
                    └─────────────────┘

전제 조건 및 시스템 요구사항

Eclaire를 설치하기 전에 시스템이 다음 요구사항을 충족하는지 확인하세요:

하드웨어 요구사항

최소 구성:

RAM: 16GB (더 큰 모델을 위해 32GB 권장)
저장소: 50GB 여유 공간 (모델 및 데이터용)
CPU: 최신 멀티코어 프로세서 (Intel/AMD x64 또는 Apple Silicon)

권장 구성:

RAM: 32GB 이상
저장소: 100GB+ SSD
GPU: 선택사항이지만 더 빠른 추론을 위해 권장
CPU: Apple Silicon M1+ 또는 AVX2 지원하는 최신 Intel/AMD

소프트웨어 의존성

핵심 요구사항:

Node.js: 버전 18+
Docker: Docker Compose가 포함된 최신 버전
Git: 저장소 복제용

시스템 의존성 (자동으로 설치됨):

PostgreSQL 15+
Redis 7+
PM2 (프로세스 매니저)

향상된 기능을 위한 선택적 의존성:

LibreOffice (문서 처리용)
Poppler (PDF 처리용)
GraphicsMagick/ImageMagick (이미지 처리용)
Ghostscript (PostScript 처리용)
libheif (HEIC/HEIF 사진 처리용)

운영체제 지원

Eclaire는 다음 운영체제를 지원합니다:

macOS: 10.15+ (Catalina 이후)
Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+
Windows: WSL2가 포함된 Windows 10+

설치 가이드

1단계: 시스템 의존성 설치

macOS용:

# Homebrew가 설치되지 않은 경우 설치
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 필요한 의존성 설치
brew install node git docker
brew install --cask libreoffice
brew install poppler graphicsmagick imagemagick ghostscript libheif

# Docker Desktop 시작
open /Applications/Docker.app

Ubuntu/Debian용:

# 패키지 목록 업데이트
sudo apt update

# Node.js 18+ 설치
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Docker 설치
sudo apt-get install -y docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

# 추가 의존성 설치
sudo apt-get install -y libreoffice poppler-utils graphicsmagick imagemagick ghostscript libheif-examples

# Docker 그룹 변경사항이 적용되도록 로그아웃 후 다시 로그인

2단계: Eclaire 복제 및 설정

# 저장소 복제
git clone https://github.com/eclaire-labs/eclaire.git
cd eclaire

# 자동화된 설정 실행
npm run setup:dev

설정 스크립트는 다음을 수행합니다:

모든 시스템 의존성 확인
환경 구성 파일 복사
필요한 데이터 디렉토리 생성
모든 애플리케이션의 npm 의존성 설치
의존성 시작 (PostgreSQL, Redis, PM2를 통한 AI 모델)
샘플 데이터로 데이터베이스 초기화

참고: 첫 실행 시 AI 모델이 자동으로 다운로드되며, 인터넷 연결과 선택된 모델에 따라 5-10분이 소요될 수 있습니다.

3단계: 설정 진행 상황 모니터링

AI 모델 다운로드 및 설정 진행 상황을 모니터링할 수 있습니다:

# PM2 프로세스 확인
pm2 list

# AI 모델 로딩 로그 모니터링
pm2 logs llama_backend --lines 100

# 전체 시스템 상태 확인
pm2 monit

4단계: 개발 서버 시작

# 모든 개발 서버 시작
npm run dev

다음이 시작됩니다:

프론트엔드: http://localhost:3000
백엔드 API: http://localhost:3001
백그라운드 워커: PM2를 통해 실행

5단계: 설치 확인

브라우저를 열고 http://localhost:3000으로 이동하세요. Eclaire 인터페이스가 보여야 합니다.

백엔드 API 테스트:

curl http://localhost:3001/health

예상 응답:

{
  "status": "ok",
  "timestamp": "2025-10-03T10:30:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected",
    "ai_backend": "ready"
  }
}

구성 및 모델 선택

Eclaire의 AI 아키텍처 이해

Eclaire는 두 가지 유형의 AI 모델을 사용합니다:

백엔드 모델: AI 어시스턴트 대화 및 도구 호출용
워커 모델: 문서 처리 및 멀티모달 작업용

기본 모델 구성

기본적으로 Eclaire는 다음과 같이 구성됩니다:

백엔드: Qwen3 14B Q4_K_XL GGUF (대화용)
워커: Gemma3 4B Q4_K_XL GGUF (처리용)

이러한 모델들은 일반적인 개발 머신(32GB RAM이 있는 MacBook Pro M1+)에서 효율적으로 실행되도록 선택되었습니다.

현재 모델 확인

# 현재 구성된 모델 목록
./tools/model-cli/run.sh list

예상 출력:

┌─────────────────────────────────────────┬───────────┬─────────────────────────────────┬─────────────────────────────────┬──────────────────┬─────────────┐
│ ID                                      │ Provider  │ Short Name                      │ Model                           │ Context          │ Status      │
├─────────────────────────────────────────┼───────────┼─────────────────────────────────┼─────────────────────────────────┼──────────────────┼─────────────┤
│ llamacpp-qwen3-14b-gguf-q4-k-xl         │ llamacpp  │ qwen3-14b-gguf-q4_k_xl          │ qwen3-14b-gguf-q4_k_xl          │ backend          │ 🟢 ACTIVE   │
├─────────────────────────────────────────┼───────────┼─────────────────────────────────┼─────────────────────────────────┼──────────────────┼─────────────┤
│ llamacpp-gemma-3-4b-it-qat-gguf-q4-k-xl │ llamacpp  │ gemma-3-4b-it-qat-gguf-q4_k_xl  │ gemma-3-4b-it-qat-gguf-q4_k_xl  │ workers          │ 🟢 ACTIVE   │
└─────────────────────────────────────────┴───────────┴─────────────────────────────────┴─────────────────────────────────┴──────────────────┴─────────────┘

모델 변경

다른 모델을 사용하고 싶다면:

새 모델 가져오기:

# 예시: 더 큰 모델 가져오기
./tools/model-cli/run.sh import https://huggingface.co/mlx-community/Qwen3-30B-A3B-4bit-DWQ-10072025

PM2 구성 업데이트: 새 모델을 사용하도록 pm2.deps.config.js 편집:

{
  name: 'llama_backend',
  script: 'llama-server',
  args: '-hf your-new-model-repo:model-file --port 11434',
  // ... 기타 구성
}

로컬로 모델 다운로드:

# 첫 사용 시 지연을 피하기 위해 미리 다운로드
printf '' | llama-cli --hf-repo your-new-model-repo -n 0 --no-warmup

서비스 재시작:
```
pm2 restart pm2.deps.config.js
```

지원되는 LLM 백엔드

Eclaire는 여러 LLM 백엔드를 지원합니다:

llama.cpp: 기본값, GGUF 모델에 우수
vLLM: 고성능 추론 서버
MLX: Apple Silicon에 최적화
Ollama: 사용자 친화적인 모델 관리
사용자 정의 OpenAI 호환 엔드포인트

핵심 기능 및 사용법

1. AI 어시스턴트 대화

AI 어시스턴트는 Eclaire와 상호작용하는 주요 인터페이스입니다:

대화 시작하기:

http://localhost:3000에서 Eclaire 열기
채팅 인터페이스 클릭
질문이나 요청 입력

예시 상호작용:

사용자: "프로젝트 노트를 정리하는 데 도움을 주세요"
어시스턴트: 노트 정리를 도와드릴 수 있습니다. 다음 중 어떤 것을 원하시나요?
1. 기존 노트에 대한 카테고리 생성
2. 새 프로젝트 구조 설정
3. 특정 주제에 대한 현재 노트 검색

사용자: "'머신러닝'과 관련된 모든 문서 찾기"
어시스턴트: 머신러닝 콘텐츠에 대한 문서를 검색하겠습니다...
[요약과 함께 관련 문서 반환]

2. 문서 관리

문서 업로드:

문서 섹션으로 이동
파일을 드래그 앤 드롭하거나 업로드 버튼 사용
Eclaire가 자동으로 콘텐츠를 처리하고 인덱싱

지원 형식:

텍스트: TXT, MD, RTF
문서: PDF, DOC, DOCX, ODT
프레젠테이션: PPT, PPTX, ODP
스프레드시트: XLS, XLSX, ODS
이미지: JPG, PNG, GIF, HEIC, HEIF (OCR 포함)
웹: HTML, MHTML

문서 처리 기능:

OCR: 이미지와 스캔된 PDF에서 자동 텍스트 추출
메타데이터 추출: 작성자, 생성 날짜, 키워드
콘텐츠 요약: AI 생성 요약
전문 검색: 문서 콘텐츠 내 검색

3. 작업 관리

작업 생성:

// API를 통해
POST /api/tasks
{
  "title": "분기별 보고서 검토",
  "description": "Q3 성과 지표 분석",
  "priority": "high",
  "due_date": "2025-10-15",
  "tags": ["분기별", "분석"]
}

작업 기능:

우선순위 레벨 (낮음, 보통, 높음, 긴급)
마감일 및 알림
태그 기반 정리
AI 기반 작업 제안
진행 상황 추적

4. 노트 작성 시스템

노트 생성:

노트 인터페이스 사용
마크다운 형식으로 작성
정리를 위한 태그 추가
관련 문서나 작업에 링크

고급 기능:

양방향 링크: 관련 노트 연결
AI 요약: 노트 요약 생성
검색 통합: 콘텐츠로 노트 찾기
버전 기록: 노트 변경사항 추적

5. 사진 정리

사진 업로드 및 처리:

사진 섹션을 통해 사진 업로드
Eclaire가 자동으로 메타데이터 추출
AI가 태깅을 위한 콘텐츠 분석
이미지 내 텍스트에 대한 OCR 처리

AI 기반 기능:

객체 감지: 사람, 객체, 장면 식별
텍스트 추출: 사진 내 문서에 대한 OCR
스마트 태깅: 자동 태그 생성
중복 감지: 유사한 이미지 찾기

6. 북마크 관리

북마크 추가:

브라우저 확장 프로그램 사용 (사용 가능한 경우)
인터페이스를 통해 수동으로 URL 추가
브라우저 북마크 파일에서 가져오기

콘텐츠 처리:

페이지 아카이빙: 전체 페이지 콘텐츠 저장
메타데이터 추출: 제목, 설명, 키워드
콘텐츠 요약: AI 생성 요약
링크 분석: 관련 북마크 식별

고급 구성

환경 변수

주요 구성 파일:

apps/backend/.env: 백엔드 API 구성
apps/frontend/.env: 프론트엔드 애플리케이션 설정
apps/workers/.env: 백그라운드 워커 설정

중요한 변수:

# 데이터베이스 구성
DATABASE_URL=postgresql://eclaire:password@localhost:5432/eclaire

# Redis 구성  
REDIS_URL=redis://localhost:6379

# AI 모델 구성
AI_LOCAL_PROVIDER_URL=http://localhost:11434/v1
AI_WORKERS_PROVIDER_URL=http://localhost:11435/v1

# 보안
JWT_SECRET=your-secure-jwt-secret
ENCRYPTION_KEY=your-32-character-encryption-key

# 파일 저장소
STORAGE_PATH=./data/users
MAX_FILE_SIZE=100MB

데이터베이스 구성

PostgreSQL 설정:

-- Eclaire를 위한 권장 PostgreSQL 구성
-- postgresql.conf에 추가

shared_preload_libraries = 'pg_stat_statements'
max_connections = 100
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 4MB
maintenance_work_mem = 64MB

성능 최적화

더 나은 성능을 위해:

SSD 저장소: 데이터베이스와 파일 저장소에 SSD 사용
메모리 할당: 모델을 위한 충분한 RAM 할당
CPU 최적화: 사용 가능한 모든 CPU 코어 활성화
GPU 가속: 사용 가능한 경우 GPU 지원 모델 사용

모델 성능 튜닝:

# pm2.deps.config.js에서 모델 매개변수 조정
args: [
  '--model', 'your-model-path',
  '--ctx-size', '4096',        # 컨텍스트 윈도우 크기
  '--threads', '8',            # CPU 스레드
  '--gpu-layers', '35',        # GPU 가속
  '--batch-size', '512'        # 배치 처리
]

API 참조

인증

Eclaire는 JWT 기반 인증을 사용합니다:

// 로그인
POST /api/auth/login
{
  "username": "your-username",
  "password": "your-password"
}

// 응답
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "your-username",
    "email": "user@example.com"
  }
}

핵심 API 엔드포인트

문서:

// 문서 업로드
POST /api/documents
Content-Type: multipart/form-data

// 문서 가져오기
GET /api/documents?page=1&limit=20&search=query

// ID로 문서 가져오기
GET /api/documents/:id

// 문서 삭제
DELETE /api/documents/:id

작업:

// 작업 생성
POST /api/tasks
{
  "title": "작업 제목",
  "description": "작업 설명",
  "priority": "medium",
  "due_date": "2025-10-15T10:00:00Z"
}

// 작업 업데이트
PUT /api/tasks/:id
{
  "status": "completed"
}

// 작업 가져오기
GET /api/tasks?status=pending&priority=high

검색:

// 범용 검색
GET /api/search?q=query&type=documents&limit=10

// 고급 검색
POST /api/search/advanced
{
  "query": "머신러닝",
  "filters": {
    "type": ["documents", "notes"],
    "date_range": {
      "start": "2025-01-01",
      "end": "2025-10-03"
    },
    "tags": ["ai", "연구"]
  }
}

AI 어시스턴트:

// AI와 채팅
POST /api/chat
{
  "message": "AI에 관한 문서를 찾는 데 도움을 주세요",
  "context": {
    "conversation_id": "uuid-here",
    "user_preferences": {}
  }
}

// 응답
{
  "response": "AI에 관한 5개의 문서를 찾았습니다...",
  "actions": [
    {
      "type": "search_results",
      "data": [...]
    }
  ],
  "conversation_id": "uuid-here"
}

문제 해결

일반적인 문제 및 해결책

1. 모델이 로드되지 않음

# 모델 상태 확인
pm2 logs llama_backend

# 일반적인 해결책:
# - 충분한 RAM 확보 (16GB+ 권장)
# - 모델 파일 무결성 확인
# - Hugging Face 연결 확인
# - PM2 프로세스 재시작: pm2 restart all

2. 데이터베이스 연결 문제

# PostgreSQL 상태 확인
pm2 logs postgres

# 연결 확인
psql -h localhost -U eclaire -d eclaire

# 필요시 데이터베이스 재설정
npm run db:reset

3. 프론트엔드가 로드되지 않음

# 프론트엔드 로그 확인
npm run dev

# 일반적인 해결책:
# - 브라우저 캐시 지우기
# - 포트 3000 사용 가능 여부 확인
# - 백엔드 API 연결 확인
# - 개발 서버 재시작

4. 파일 업로드 실패

# 저장소 권한 확인
ls -la data/users/

# 디스크 공간 확인
df -h

# .env에서 파일 크기 제한 확인
MAX_FILE_SIZE=100MB

5. AI 처리 속도 느림

# 시스템 리소스 모니터링
top
htop

# 모델 매개변수 최적화
# pm2.deps.config.js 편집:
# - 컨텍스트 크기 줄이기
# - 스레드 수 조정
# - 사용 가능한 경우 GPU 활성화

성능 모니터링

시스템 상태 확인:

# 전체 시스템 상태
curl http://localhost:3001/health

# 상세 메트릭
curl http://localhost:3001/metrics

# PM2 모니터링
pm2 monit

# 데이터베이스 성능
psql -d eclaire -c "SELECT * FROM pg_stat_activity;"

로그 분석

중요한 로그 위치:

# 애플리케이션 로그
tail -f data/logs/backend.log
tail -f data/logs/workers.log
tail -f data/logs/frontend.log

# PM2 로그
pm2 logs --lines 100

# 시스템 로그 (Linux)
journalctl -u docker

보안 고려사항

데이터 프라이버시

로컬 우선 아키텍처의 이점:

모든 데이터 처리가 로컬에서 발생
핵심 기능에 대한 외부 API 호출 없음
데이터 액세스 및 보존에 대한 완전한 통제
개인정보보호 규정 준수 (GDPR, CCPA)

보안 모범 사례

1. 환경 보안:

# 강력한 비밀번호와 키 사용
JWT_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -base64 32)

# 파일 권한 제한
chmod 600 .env*
chmod 700 data/

2. 네트워크 보안:

# localhost에만 바인딩 (기본값)
HOST=127.0.0.1
PORT=3000

# 프로덕션에서 HTTPS 사용
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

3. 데이터베이스 보안:

-- 전용 데이터베이스 사용자 생성
CREATE USER eclaire WITH PASSWORD 'strong-password';
GRANT ALL PRIVILEGES ON DATABASE eclaire TO eclaire;

-- 행 수준 보안 활성화
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

백업 및 복구

자동화된 백업 스크립트:

#!/bin/bash
# backup-eclaire.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="./backups/$DATE"

mkdir -p "$BACKUP_DIR"

# 데이터베이스 백업
pg_dump -h localhost -U eclaire eclaire > "$BACKUP_DIR/database.sql"

# 사용자 데이터 백업
tar -czf "$BACKUP_DIR/user_data.tar.gz" data/users/

# 구성 백업
cp -r config/ "$BACKUP_DIR/"
cp .env* "$BACKUP_DIR/"

echo "백업 완료: $BACKUP_DIR"

복구 프로세스:

# 데이터베이스 복원
psql -h localhost -U eclaire eclaire < backup/database.sql

# 사용자 데이터 복원
tar -xzf backup/user_data.tar.gz -C ./

# 구성 복원
cp backup/.env* ./
cp -r backup/config/ ./

결론

Eclaire는 최신 대형 언어 모델의 힘과 로컬 우선 아키텍처의 보안성 및 프라이버시를 결합한 개인 AI 지원 분야의 중요한 진전을 나타냅니다. 이 포괄적인 튜토리얼을 따라하면 이제 다음을 갖게 됩니다:

자체 하드웨어에서 실행되는 완전히 기능적인 로컬 AI 어시스턴트
외부 의존성 없이 데이터에 대한 완전한 통제권
문서 처리, 작업 관리, 지능적 검색을 위한 고급 AI 기능
사용자 정의 및 확장을 위한 견고한 기반

달성된 주요 이점

프라이버시 보호: 민감한 데이터가 절대 기기를 떠나지 않음
성능: 로컬 처리로 네트워크 지연 시간 제거
사용자 정의: 모델과 구성에 대한 완전한 통제
비용 효율성: 지속적인 구독료나 API 비용 없음
신뢰성: 외부 서비스나 인터넷 연결에 대한 의존성 없음

다음 단계

즉시 실행할 작업:

일상적인 작업과 문서 관리에 Eclaire 사용 시작
기존 문서와 노트 업로드
필요에 가장 적합한 AI 모델을 찾기 위한 실험
데이터 보호를 위한 자동화된 백업 설정

고급 탐색:

API 통합: Eclaire의 REST API를 사용한 사용자 정의 애플리케이션 구축
모델 최적화: 특정 사용 사례에 맞는 모델 미세 조정
워크플로우 자동화: 문서 처리를 위한 자동화된 워크플로우 생성
커뮤니티 기여: 오픈소스 프로젝트에 기여

리소스 및 커뮤니티

공식 저장소: https://github.com/eclaire-labs/eclaire
문서: 포괄적인 가이드 및 API 참조
커뮤니티 지원: 질문과 버그 보고를 위한 GitHub Issues
기여: 모든 사람을 위한 Eclaire 개선 도움

Eclaire는 단순한 AI 어시스턴트 그 이상입니다. 개인 데이터 관리의 미래를 구축하기 위한 플랫폼입니다. 프라이버시, 보안, 확장성에 대한 강력한 기반을 통해 인공지능의 힘을 활용하면서 디지털 생활을 통제할 수 있는 충분한 준비가 되어 있습니다.

오늘부터 Eclaire로 탐색하고, 실험하고, 구축을 시작하세요. 여러분의 비공개적이고, 지능적이며, 강력한 AI 어시스턴트가 기다리고 있습니다!

소개