LEANN

KO | EN

gitlite — search

#javascript #python #react #ai #android #machine-learning #rust #deep-learning #macos #java #security #mcp #openai #open-source

(★ 12,786)

[MLsys2026]: LEANN을 활용한 RAG on Everything. 개인 기기에서 빠르고 정확하며 100% 프라이버시가 보장되는 RAG 애플리케이션을 실행하는 동시에 97%의 스토리지 절감 효과를 누리세요.

LEANN 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![LEANN Logo](assets/logo-text.png)

[![yichuan-w/LEANN | Trendshift](https://trendshift.io/api/badge/repositories/15049)](https://trendshift.io/repositories/15049)

![Python Versions](https://img.shields.io/badge/Python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)
![CI Status](https://github.com/yichuan-w/LEANN/actions/workflows/build-and-publish.yml/badge.svg)
![Platform](https://img.shields.io/badge/Platform-Ubuntu%20%26%20Arch%20%26%20WSL%20%7C%20macOS%20(ARM64%2FIntel)%20%7C%20Windows-lightgrey)
![MIT License](https://img.shields.io/badge/License-MIT-green.svg)
![MCP Integration](https://img.shields.io/badge/MCP-Native%20Integration-blue)
[![Join Slack](https://img.shields.io/badge/Slack-Join-4A154B?logo=slack&logoColor=white)](https://join.slack.com/t/leann-e2u9779/shared_invite/zt-3ol2ww9ic-Eg_kB8omwe6xmYVd0epr4Q)

[![Take Survey](https://img.shields.io/badge/📣_Community_Survey-Help_Shape_v0.4-007ec6?style=for-the-badge&logo=google-forms&logoColor=white)](https://forms.gle/rDbZf864gMNxhpTq8)

우리는 **어떠한 텔레메트리도 수집하지 않습니다**. 이 설문조사는 다음 업데이트로 **GPU 가속**이나 **더 많은 통합 기능** 중 무엇을 원하시는지 알려주실 수 있는 **유일한** 방법입니다.  
👉 [**투표하기 (2분 소요)**](https://forms.gle/rDbZf864gMNxhpTq8)

### 💬 Slack 커뮤니티에 참여하세요!

LEANN 커뮤니티의 일원이 되어주세요!  
👉 [**LEANN Slack 참여하기**](https://join.slack.com/t/leann-e2u9779/shared_invite/zt-3ol2ww9ic-Eg_kB8omwe6xmYVd0epr4Q)  
초대 링크가 만료되었거나 참여에 문제가 있는 경우 [이슈를 생성해 주시면](https://github.com/yichuan-w/LEANN/issues) 도와드리겠습니다!

## 세상에서 가장 작은 벡터 인덱스. LEANN으로 모든 것에 RAG를 적용하세요!

LEANN은 개인용 AI를 대중화하는 혁신적인 벡터 데이터베이스입니다. 노트북을 강력한 RAG 시스템으로 변환하여, 전통적인 솔루션 대비 \*\*정확도 손실 없이 97% 더 적은 스토리지\*\*를 사용하면서 수백만 개의 문서를 색인하고 검색할 수 있습니다.
LEANN은 모든 임베딩을 저장하는 대신 필요에 따라 동적으로 계산하는 \*고차 보존 프루닝(high-degree preserving pruning)\*이 적용된 \*그래프 기반 선택적 재계산(graph-based selective recomputation)\*을 통해 이를 달성합니다. [아키텍처 그림 보기 →](#️-architecture--how-it-works) | [논문 보기 →](https://arxiv.org/abs/2506.08276)
\*\*모든 것에 RAG를 적용할 준비가 되셨나요?\*\* 노트북을 \*\*[파일 시스템](#-personal-data-manager-process-any-documents-pdf-txt-md)\*\*, \*\*[이메일](#-your-personal-email-secretary-rag-on-apple-mail)\*\*, \*\*[브라우저 기록](#-time-machine-for-the-web-rag-your-entire-browser-history)\*\*, \*\*[채팅 기록](#-wechat-detective-unlock-your-golden-memories)\*\* ([WeChat](#-wechat-detective-unlock-your-golden-memories), [iMessage](#-imessage-history-your-personal-conversation-archive)), \*\*[에이전트 메모리](#-chatgpt-chat-history-your-personal-ai-conversation-archive)\*\* ([ChatGPT](#-chatgpt-chat-history-your-personal-ai-conversation-archive), [Claude](#-claude-chat-history-your-personal-ai-conversation-archive)), \*\*[실시간 데이터](#mcp-integration-rag-on-live-data-from-any-platform)\*\* ([Slack](#slack-messages-search-your-team-conversations), [Twitter](#-twitter-bookmarks-your-personal-tweet-library)), \*\*[코드베이스](#-claude-code-integration-transform-your-development-workflow)\\* 또는 외부 지식베이스(예: 60M 문서)에서 시맨틱 검색을 수행할 수 있는 개인용 AI 어시스턴트로 탈바꿈시키세요. 이 모든 것이 클라우드 비용 없이 완전한 프라이버시를 유지하며 노트북에서 가능합니다.
\\* Claude Code는 기본적인 `grep` 스타일의 키워드 검색만 지원합니다. \*\*LEANN\*\*은 \*\*Claude Code와 완벽히 호환되는 드롭인(drop-in) 시맨틱 검색 MCP 서비스\*\*로, 워크플로를 변경하지 않고도 지능형 검색 기능을 잠금 해제합니다. 🔥 [간편한 설정 방법 확인하기 →](packages/leann-mcp/README.md)
## 왜 LEANN인가요?

![LEANN vs Traditional Vector DB Storage Comparison](assets/effects.png)

> \*\*숫자가 모든 것을 말해줍니다:\*\* 201GB 대신 단 6GB에 6,000만 개의 텍스트 청크를 인덱싱하세요. 이메일에서 브라우저 기록까지, 모든 것이 노트북에 들어갑니다. [아래에서 다양한 애플리케이션의 상세 벤치마크를 확인하세요 ↓](#-storage-comparison)
🔒 \*\*프라이버시:\*\* 데이터가 노트북을 절대 벗어나지 않습니다. OpenAI도, 클라우드도, "서비스 약관"도 없습니다.
🪶 \*\*경량화:\*\* 그래프 기반 재계산으로 무거운 임베딩 저장을 없애고, 스마트 그래프 프루닝과 CSR 포맷으로 그래프 저장 오버헤드를 최소화합니다. 항상 더 적은 스토리지, 더 적은 메모리 사용량!
📦 \*\*휴대성:\*\* 최소한의 비용으로 전체 지식 베이스를 기기 간에(다른 사람과도) 전송하세요. 개인용 AI 메모리가 당신과 함께 이동합니다.
📈 \*\*확장성:\*\* 전통적인 벡터 DB를 다운시키게 만드는 지저분한 개인 데이터를 처리하며, 늘어나는 개인화된 데이터와 에이전트 생성 메모리를 손쉽게 관리합니다!
✨ \*\*정확도 손실 없음:\*\* 97% 더 적은 스토리지를 사용하면서도 무거운 솔루션과 동일한 검색 품질을 유지합니다.
## 설치
### 📦 사전 요구사항: uv 설치
[Install uv](https://docs.astral.sh/uv/getting-started/installation/#installation-methods)가 없다면 먼저 설치하세요. 일반적으로 다음 명령어로 설치할 수 있습니다:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 🚀 빠른 설치
모든 예제에 접근하고 멋진 애플리케이션을 사용해 보려면 리포지토리를 복제하고,
```bash
git clone https://github.com/yichuan-w/LEANN.git leann
cd leann
```
[PyPI](https://pypi.org/project/leann/)에서 LEANN을 설치하여 즉시 실행하세요:
```bash
uv venv
source .venv/bin/activate
uv pip install leann
# CPU 전용 (Linux): `cpu` 옵션 사용 (예: `leann[cpu]`)
```

**🔧 소스 코드에서 빌드하기 (개발용으로 권장)**
```bash
git clone https://github.com/yichuan-w/LEANN.git leann
cd leann
git submodule update --init --recursive
```
\*\*macOS:\*\*
참고: DiskANN은 macOS 13.3 이상이 필요합니다.
```bash
brew install libomp boost protobuf zeromq pkgconf
uv sync --extra diskann
```
\*\*Linux (Ubuntu/Debian):\*\*
참고: Ubuntu 20.04에서는 DiskANN 빌드를 위해 더 최신 버전의 Abseil을 빌드하고 Protobuf를 고정(예: v3.20.x)해야 할 수 있습니다. 단계별 안내는 [Issue #30](https://github.com/yichuan-w/LEANN/issues/30)을 참조하세요.
DiskANN을 위해 `libmkl-full-dev` 대신 [Intel oneAPI MKL](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html)을 수동으로 설치할 수 있습니다. 또한 아래 명령어에서 `--extra diskann`을 제거하여 HNSW 빌드 전용으로 `libopenblas-dev`를 사용할 수도 있습니다.
```bash
sudo apt-get update && sudo apt-get install -y \
libomp-dev libboost-all-dev protobuf-compiler libzmq3-dev \
pkg-config libabsl-dev libaio-dev libprotobuf-dev \
libmkl-full-dev
uv sync --extra diskann
```
\*\*Linux (Arch Linux):\*\*
```bash
sudo pacman -Syu && sudo pacman -S --needed base-devel cmake pkgconf git gcc \
boost boost-libs protobuf abseil-cpp libaio zeromq
# DiskANN에서 MKL을 사용하기 위함
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/paru-bin.git
cd paru-bin && makepkg -si
paru -S intel-oneapi-mkl intel-oneapi-compiler
source /opt/intel/oneapi/setvars.sh
uv sync --extra diskann
```
\*\*Linux (RHEL / CentOS Stream / Oracle / Rocky / AlmaLinux):\*\*
자세한 내용은 [Issue #50](https://github.com/yichuan-w/LEANN/issues/50)을 참조하세요.
```bash
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y libomp-devel boost-devel protobuf-compiler protobuf-devel \
abseil-cpp-devel libaio-devel zeromq-devel pkgconf-pkg-config
# DiskANN에서 MKL을 사용하기 위함
sudo dnf install -y intel-oneapi-mkl intel-oneapi-mkl-devel \
intel-oneapi-openmp || sudo dnf install -y intel-oneapi-compiler
source /opt/intel/oneapi/setvars.sh
uv sync --extra diskann
```
\*\*Windows:\*\*
\*\*C++ 데스크톱 개발\*\* 워크로드와 [vcpkg](https://github.com/microsoft/vcpkg)가 포함된 [Visual Studio 2022 Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)가 필요합니다.
```powershell
# 툴체인 설치 (설치되어 있지 않은 경우)
choco install cmake swig pkgconfiglite nuget.commandline -y
# vcpkg를 통해 C++ 종속성 설치
vcpkg install zeromq:x64-windows openblas:x64-windows lapack:x64-windows `
boost-program-options:x64-windows protobuf:x64-windows
# 환경 변수 설정 (VCPKG\_ROOT를 본인의 vcpkg 경로로 조정하세요)
$env:CMAKE\_PREFIX\_PATH = "$env:VCPKG\_ROOT\installed\x64-windows"
$env:PKG\_CONFIG\_PATH = "$env:VCPKG\_ROOT\installed\x64-windows\lib\pkgconfig"
$env:PKG\_CONFIG\_EXECUTABLE = "C:\ProgramData\chocolatey\bin\pkg-config.exe"
$env:OPENBLAS\_LIB = "$env:VCPKG\_ROOT\installed\x64-windows\lib\openblas.lib"
$env:PATH += ";$env:VCPKG\_ROOT\installed\x64-windows\bin"
$env:PATH += ";$env:VCPKG\_ROOT\installed\x64-windows\tools\protobuf"
uv sync --extra diskann
```
## 빠른 시작 (Quick Start)
LEANN의 선언형 API를 사용하면 설정 파일 작성만큼이나 쉽게 RAG를 구축할 수 있습니다.
[demo.ipynb](demo.ipynb)를 확인하거나 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yichuan-w/LEANN/blob/main/demo.ipynb)를 클릭하세요.
```python
from leann import LeannBuilder, LeannSearcher, LeannChat
from pathlib import Path
INDEX\_PATH = str(Path("./").resolve() / "demo.leann")
# 인덱스 구축
builder = LeannBuilder(backend\_name="hnsw")
builder.add\_text("LEANN saves 97% storage compared to traditional vector databases.")
builder.add\_text("Tung Tung Tung Sahur called—they need their banana‑crocodile hybrid back")
builder.build\_index(INDEX\_PATH)
# 검색
searcher = LeannSearcher(INDEX\_PATH)
results = searcher.search("fantastical AI-generated creatures", top\_k=1)
# 데이터와 채팅하기
chat = LeannChat(INDEX\_PATH, llm\_config={"type": "hf", "model": "Qwen/Qwen3-0.6B"})
response = chat
```

.ask("How much storage does LEANN save?", top\_k=1)
```
## RAG on Everything!
LEANN은 문서(`.pdf`, `.txt`, `.md`), Apple Mail, Google Search History, WeChat, ChatGPT 대화, Claude 대화, iMessage 대화를 포함한 다양한 데이터 소스와, Slack, Twitter 등을 포함한 \*\*MCP (Model Context Protocol) 서버를 통한 모든 플랫폼의 라이브 데이터\*\*를 지원합니다.
### 생성 모델 설정
#### LLM 백엔드
LEANN은 텍스트 생성을 위해 다양한 LLM 제공업체(HuggingFace, Ollama, Anthropic 및 OpenAI 호환 API)를 지원합니다.
**🔑 OpenAI API 설정 (기본값)**
OpenAI API 키를 환경 변수로 설정합니다:
```bash
export OPENAI\_API\_KEY="your-api-key-here"
```
CLI를 사용할 때는 반드시 `--llm openai` 플래그를 사용하세요.
`--llm-model` 플래그를 사용하여 모델 이름을 지정할 수도 있습니다.

**🛠️ 지원되는 LLM 및 임베딩 제공업체 (OpenAI 호환성 지원)**
OpenAI API 형식의 광범위한 채택 덕분에, LEANN은 다양한 LLM 및 임베딩 제공업체와 즉시 호환됩니다. 선호하는 서비스에 연결하려면 `OPENAI\_BASE\_URL` 및 `OPENAI\_API\_KEY` 환경 변수를 설정하기만 하면 됩니다.
```sh
export OPENAI\_API\_KEY="xxx"
export OPENAI\_BASE\_URL="http://localhost:1234/v1" # base url of the provider
```
CLI 인터페이스에서 OpenAI 호환 엔드포인트를 사용하려면:
텍스트 생성에 사용하는 경우, `--llm openai` 플래그를 사용하고 `--llm-model` 플래그로 모델 이름을 지정해야 합니다.
임베딩에 사용하는 경우, `--embedding-mode openai` 플래그를 설정하고 `--embedding-model`로 모델 이름을 지정하세요.
-----
시작하는 데 도움이 되도록 주요 제공업체의 기본 URL 목록을 아래에 제공합니다.
### 🖥️ 로컬 인퍼런스 엔진 (완전한 프라이버시를 위해 권장)
| Provider | Sample Base URL |
| ---------------- | --------------------------- |
| \*\*Ollama\*\* | `http://localhost:11434/v1` |
| \*\*LM Studio\*\* | `http://localhost:1234/v1` |
| \*\*vLLM\*\* | `http://localhost:8000/v1` |
| \*\*llama.cpp\*\* | `http://localhost:8080/v1` |
| \*\*SGLang\*\* | `http://localhost:30000/v1` |
| \*\*LiteLLM\*\* | `http://localhost:4000` |
-----
### ☁️ 클라우드 제공업체
> \*\*🚨 프라이버시 관련 참고 사항:\*\* 클라우드 제공업체를 선택하기 전에 해당 업체의 프라이버시 및 데이터 보관 정책을 신중하게 검토하세요. 약관에 따라, 귀하의 데이터가 인간 검토 및 모델 학습을 포함하여 자체적인 목적으로 사용될 수 있으며, 제대로 다루지 않을 경우 심각한 결과로 이어질 수 있습니다.
| Provider | Base URL |
| ---------------- | ---------------------------------------------------------- |
| \*\*OpenAI\*\* | `https://api.openai.com/v1` |
| \*\*OpenRouter\*\* | `https://openrouter.ai/api/v1` |
| \*\*Gemini\*\* | `https://generativelanguage.googleapis.com/v1beta/openai/` |
| \*\*x.AI (Grok)\*\* | `https://api.x.ai/v1` |
| \*\*Groq AI\*\* | `https://api.groq.com/openai/v1` |
| \*\*DeepSeek\*\* | `https://api.deepseek.com/v1` |
| \*\*SiliconFlow\*\* | `https://api.siliconflow.cn/v1` |
| \*\*Zhipu (BigModel)\*\* | `https://open.bigmodel.cn/api/paas/v4/` |
| \*\*Mistral AI\*\* | `https://api.mistral.ai/v1` |
| \*\*Anthropic\*\* | `https://api.anthropic.com/v1` |
| \*\*Jina AI\*\* (Embeddings) | `https://api.jina.ai/v1` |
> \*\*💡 팁: 별도의 임베딩 제공업체 사용\*\*
>
> LLM에는 다른 제공업체를 사용하면서 임베딩에는 다른 제공업체(예: Jina AI)를 사용하려면 `--embedding-api-base` 및 `--embedding-api-key`를 사용하세요:
> ```bash
> leann build my-index --docs ./docs \
> --embedding-mode openai \
> --embedding-model jina-embeddings-v3 \
> --embedding-api-base https://api.jina.ai/v1 \
> --embedding-api-key $JINA\_API\_KEY
> ```
사용하려는 제공업체가 이 목록에 없더라도 걱정하지 마세요! 해당 업체의 문서에서 OpenAI 호환 엔드포인트를 확인해보세요. 높은 확률로 OpenAI 호환을 지원할 것입니다!

**🔧 Ollama 설정 (완벽한 프라이버시를 위해 권장)**
\*\*macOS:\*\*
먼저 [macOS용 Ollama 다운로드](https://ollama.com/download/mac)를 진행하세요.
```bash
# Pull a lightweight model (recommended for consumer hardware)
ollama pull llama3.2:1b
```
\*\*Linux:\*\*
```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# Start Ollama service manually
ollama serve &
# Pull a lightweight model (recommended for consumer hardware)
ollama pull llama3.2:1b
```
## ⭐ 유연한 설정
LEANN은 사용자의 특정 요구에 맞추어 임베딩 모델, 검색 전략, 데이터 처리를 위한 유연한 파라미터를 제공합니다.
📚 \*\*설정 모범 사례가 필요하신가요?\*\* 상세한 최적화 팁, 모델 선택 조언, 느린 임베딩이나 저조한 검색 품질 같은 일반적인 문제에 대한 해결책은 [Configuration Guide](docs/configuration-guide.md)에서 확인하세요.
**📋 클릭하여 펼치기: 공통 파라미터 (모든 예제에서 사용 가능)**
모든 RAG 예제들은 이러한 공통 파라미터를 공유합니다. \*\*대화형 모드(Interactive mode)\*\*는 모든 예제에서 사용할 수 있습니다. `--query` 없이 실행하기만 하면 여러 개의 질문을 할 수 있는 연속 Q&A 세션이 시작됩니다. 종료하려면 'quit'을 입력하세요.
```bash
# Environment Variables (GPU Device Selection)
LEANN\_EMBEDDING\_DEVICE # GPU for embedding model (e.g., cuda:0, cuda:1, cpu)
LEANN\_LLM\_DEVICE # GPU for HFChat LLM (e.g., cuda:1, or "cuda" for multi-GPU auto)
# Core Parameters (General preprocessing for all examples)
--index-dir DIR # Directory to store the index (default: current directory)
--query "YOUR QUESTION" # Single query mode. Omit for interactive chat (type 'quit' to exit), and now you can play with your index interactively
--max-items N # Limit data preprocessing (default: -1, process all data)
--force-rebuild # Force rebuild index even if it exists
# Embedding Parameters
--embedding-model MODEL # e.g., facebook/contriever, text-embedding-3-small, mlx-community/Qwen3-Embedding-0.6B-8bit or nomic-embed-text
--embedding-mode MODE # sentence-transformers, openai, mlx, or ollama
# LLM Parameters (Text generation models)
--llm TYPE # LLM backend: openai, ollama, hf, or anthropic (default: openai)
--llm-model MODEL # Model name (default: gpt-4o) e.g., gpt-4o-mini, llama3.2:1b, Qwen/Qwen2.5-1.5B-Instruct
--thinking-budget LEVEL # Thinking budget for reasoning models: low/medium/high (supported by o3, o3-mini, GPT-Oss:20b, and other reasoning models)
# Search Parameters
--top-k N # Number of results to retrieve (default: 20)
--search-complexity N # Search complexity for graph traversal (default: 32)
# Chunking Parameters
--chunk-size N # Size of text chunks (default varies by source: 256 for most, 192 for WeChat)
--chunk-overlap N # Overlap between chunks (default varies: 25-128 depending on source)
# Index Building Parameters
--backend-name NAME # Backend to use: hnsw or diskann (default: hnsw)
--graph-degree N # Graph degree for index construction (default: 32)
--build-complexity N # Build complexity for index construction (default: 64)
--compact / --no-compact # Use compact storage (default: true). Must be `no-compact` for `no-recompute` build.
--recompute / --no-recompute # Enable/disable embedding recomputation (default: enabled). Should not do a `no-recompute` search in a `recompute` build.
```
### 📄 개인 데이터 매니저: 모든 문서 처리 (`.pdf`, `.txt`, `.md`)!
개인 PDF, 문서, 그리고 파일이 포함된 모든 디렉토리에 대해 직접 질문하세요!

![LEANN Document Search Demo](videos/paper_clear.gif)

아래의 예시는 논문 요약에 관한 질문을 던지는 것으로(`data/` 디렉터리의 기본 데이터를 사용합니다. 이 디렉터리는 다양한 데이터 소스, 즉 두 편의 논문, 오만과 편견(Pride and Prejudice), 그리고 화웨이(Huawei)의 중국어 LLM 기술 보고서를 포함하고 있습니다), 여기서 실행하기에 \*\*가장 쉬운 예시\*\*입니다:
```bash
source .venv/bin/activate # Don't forget to activate the virtual environment
python -m apps.document\_rag --query "What are the main techniques LEANN explores?"
```
**📋 클릭하여 펼치기: 문서 전용 인수**
#### 매개변수
```bash
--data-dir DIR # Directory containing documents to process (default: data)
--file-types .ext .ext # Filter by specific file types (optional - all LlamaIndex supported types if omitted)
```
#### 예제 명령어
```bash
# Process all documents with larger chunks for academic papers
python -m apps.document\_rag --data-dir "~/Documents/Papers" --chunk-size 1024
# Filter only markdown and Python files with smaller chunks
python -m apps.document\_rag --data-dir "./docs" --chunk-size 256 --file-types .md .py
# Enable AST-aware chunking for code files
python -m apps.document\_rag --enable-code-chunking --data-dir "./my\_project"
# Or use the specialized code RAG for better code understanding
python -m apps.code\_rag --repo-dir "./my\_codebase" --query "How does authentication work?"
```
### 🎨 ColQwen: 비전-언어 모델을 활용한 멀티모달 PDF 검색
ColQwen2/ColPali 모델을 사용하여 텍스트와 시각적 이해를 모두 활용해 PDF를 검색하세요. 연구 논문, 기술 문서, 그리고 복잡한 레이아웃, 그림 또는 다이어그램이 포함된 모든 PDF에 완벽합니다.
> \*\*🍎 Mac 사용자\*\*: ColQwen은 더 빠른 추론을 위해 MPS 가속을 사용하여 Apple Silicon에 최적화되어 있습니다!
```bash
# Build index from PDFs
python -m apps.colqwen\_rag build --pdfs ./my\_papers/ --index research\_papers
# Search with text queries
python -m apps.colqwen\_rag search research\_papers "How does attention mechanism work?"
# Interactive Q&A
python -m apps.colqwen\_rag ask research\_papers --interactive
```
**📋 클릭하여 펼치기: ColQwen 설정 및 사용법**
#### 사전 요구 사항
```bash
# Install dependencies
uv pip install colpali\_engine pdf2image pillow matplotlib qwen\_vl\_utils einops seaborn
brew install poppler # macOS only, for PDF processing
```
#### 인덱스 구축
```bash
python -m apps.colqwen\_rag build \
--pdfs ./pdf\_directory/ \
--index my\_index \
--model colqwen2 # or colpali
```
#### 검색
```bash
python -m apps.colqwen\_rag search my\_index "your question here" --top-k 5
```
#### 모델
- \*\*ColQwen2\*\* (`colqwen2`): 성능이 향상된 최신 비전-언어 모델
- \*\*ColPali\*\* (`colpali`): 검증된 멀티모달 검색기
자세한 사용법은 [ColQwen Guide](docs/COLQWEN\_GUIDE.md)를 참조하세요.
### 📧 나만의 개인 이메일 비서: Apple Mail을 이용한 RAG!
> \*\*참고:\*\* 아래 예시는 현재 macOS만 지원합니다. Windows 지원은 곧 제공될 예정입니다.

![LEANN Email Search Demo](videos/mail_clear.gif)

아래 예시를 실행하기 전에, 시스템 설정(System Preferences) → 개인정보 보호 및 보안(Privacy & Security) → 전체 디스크 접근 권한(Full Disk Access)에서 터미널(Terminal)/VS Code에 전체 디스크 접근 권한을 부여해야 합니다.
```bash
python -m apps.email\_rag --query "What's the food I ordered by DoorDash or Uber Eats mostly?"
```
\*\*78만 개의 이메일 청크 → 78MB 저장소.\*\* 드디어 Google을 검색하듯 이메일을 검색할 수 있습니다.
**📋 클릭하여 펼치기: 이메일 전용 인수**
#### 매개변수
```bash
--mail-path PATH # Path to specific mail directory (auto-detects if omitted)
--include-html # Include HTML content in processing (useful for newsletters)
```
#### 예제 명령어
```bash
# Search work emails from a specific account
python -m apps.email\_rag --mail-path "~/Library/Mail/V10/WORK\_ACCOUNT"
# Find all receipts and order confirmations (includes HTML)
python -m apps.email\_rag --query "receipt order confirmation invoice" --include-html
```

**📋 Click to expand: 시도해 볼 수 있는 예시 쿼리**
인덱스가 구축되면 다음과 같은 질문을 할 수 있습니다:
- "상사가 보낸 마감일 관련 이메일 찾아줘"
- "John이 프로젝트 일정에 대해 뭐라고 했지?"
- "출장 경비 관련 이메일 보여줘"
### 🔍 웹을 위한 타임머신: 전체 Chrome 브라우저 기록을 RAG하기!

![LEANN Browser History Search Demo](videos/google_clear.gif)

```bash
python -m apps.browser\_rag --query "Tell me my browser history about machine learning?"
```
\*\*38K개의 브라우저 항목 → 6MB 저장소.\*\* 브라우저 기록이 나만의 개인 검색 엔진이 됩니다.
**📋 Click to expand: 브라우저 전용 인수**
#### 매개변수
```bash
--chrome-profile PATH # Chrome 프로필 디렉토리 경로 (생략 시 자동 감지)
```
#### 예시 명령어
```bash
# 브라우징 기록에서 학술 연구 검색
python -m apps.browser\_rag --query "arxiv papers machine learning transformer architecture"
# 업무 프로필에서 경쟁사 분석 추적
python -m apps.browser\_rag --chrome-profile "~/Library/Application Support/Google/Chrome/Work Profile" --max-items 5000
```

**📋 Click to expand: Chrome 프로필을 찾는 방법**
기본 Chrome 프로필 경로는 일반적인 macOS 설정에 맞춰 구성되어 있습니다. 본인만의 특정 Chrome 프로필을 찾아야 하는 경우:
1. 터미널(Terminal)을 엽니다.
2. 다음을 실행합니다: `ls ~/Library/Application\ Support/Google/Chrome/`
3. "Default", "Profile 1", "Profile 2" 등의 폴더를 찾습니다.
4. 전체 경로를 `--chrome-profile` 인수로 사용합니다.
\*\*일반적인 Chrome 프로필 위치:\*\*
- macOS: `~/Library/Application Support/Google/Chrome/Default`
- Linux: `~/.config/google-chrome/Default`

**💬 Click to expand: 시도해 볼 수 있는 예시 쿼리**
인덱스가 구축되면 다음과 같은 질문을 할 수 있습니다:
- "머신러닝에 대해 어떤 웹사이트들을 방문했지?"
- "프로그래밍에 대한 검색 기록 찾아줘"
- "최근에 시청한 YouTube 동영상이 뭐지?"
- "여행 계획과 관련해 방문했던 웹사이트 보여줘"
### 💬 WeChat 탐정: 소중한 추억을 열어보세요!

![LEANN WeChat Search Demo](videos/wechat_clear.gif)

```bash
python -m apps.wechat\_rag --query "Show me all group chats about weekend plans"
```
\*\*40K개의 메시지 → 64MB 저장소\*\* 어떤 언어로든 수년간의 채팅 기록을 검색하세요.
**🔧 Click to expand: 설치 요구 사항**
먼저 [WeChat exporter](https://github.com/sunnyyoung/WeChatTweak-CLI)를 설치해야 합니다.
```bash
brew install sunnyyoung/repo/wechattweak-cli
```
또는 수동으로 설치합니다 (Homebrew에 문제가 있는 경우):
```bash
sudo packages/wechat-exporter/wechattweak-cli install
```
\*\*문제 해결:\*\*
- \*\*설치 문제\*\*: [WeChatTweak-CLI 이슈 페이지](https://github.com/sunnyyoung/WeChatTweak-CLI/issues/41)를 확인하세요.
- \*\*내보내기 오류\*\*: 아래 오류가 발생하는 경우 WeChat을 재시작해 보세요.
```bash
Failed to export WeChat data. Please ensure WeChat is running and WeChatTweak is installed.
Failed to find or export WeChat data. Exiting.
```

**📋 Click to expand: WeChat 전용 인수**
#### 매개변수
```bash
--export-dir DIR # 내보낸 WeChat 데이터를 저장할 디렉토리 (기본값: wechat\_export\_direct)
--force-export # 데이터가 존재하더라도 강제로 다시 내보내기
```
#### 예시 명령어
```bash
# 단체 채팅에서 논의된 여행 계획 검색
python -m apps.wechat\_rag --query "travel plans" --max-items 10000
# 최근 채팅 다시 내보내기 및 검색 (새 메시지 수신 후 유용함)
python -m apps.wechat\_rag --force-export --query "work schedule"
```

**💬 Click to expand: Example queries you can try**
인덱스가 구축되면 다음과 같은 질문을 할 수 있습니다:
- "我想买魔术师约翰逊的球衣，给我一些对应聊天记录?" (중국어: Magic Johnson 유니폼 구매와 관련된 채팅 기록을 보여주세요)
### 🤖 ChatGPT Chat History: Your Personal AI Conversation Archive!
ChatGPT 대화를 검색 가능한 지식베이스로 변환하세요! 코딩, 연구, 브레인스토밍 등에 대한 모든 ChatGPT 토론 내용을 검색할 수 있습니다.
```bash
python -m apps.chatgpt\_rag --export-path chatgpt\_export.html --query "How do I create a list in Python?"
```
\*\*AI 대화 기록을 잠금 해제하세요.\*\* ChatGPT 토론에서 얻은 소중한 인사이트를 다시는 잃어버리지 마세요.
**📋 Click to expand: How to Export ChatGPT Data**
\*\*단계별 내보내기 프로세스:\*\*
1. \*\*ChatGPT에 로그인\*\*합니다.
2. 우측 상단의 \*\*프로필 아이콘을 클릭\*\*합니다.
3. \*\*Settings\*\* → \*\*Data Controls\*\*로 이동합니다.
4. Export Data 아래의 \*\*클릭 "Export"\*\*를 누릅니다.
5. 내보내기 요청을 \*\*확인\*\*합니다.
6. 이메일 링크에서 \*\*ZIP 파일을 다운로드\*\*합니다 (24시간 후 만료됨).
7. LEANN과 함께 \*\*압축을 해제하거나 직접 사용\*\*합니다.
\*\*지원되는 형식:\*\*
- ChatGPT 내보내기 파일인 `.html` 파일
- ChatGPT의 `.zip` 아카이브
- 여러 개의 내보내기 파일이 포함된 디렉토리

**📋 Click to expand: ChatGPT-Specific Arguments**
#### Parameters
```bash
--export-path PATH # Path to ChatGPT export file (.html/.zip) or directory (default: ./chatgpt\_export)
--separate-messages # Process each message separately instead of concatenated conversations
--chunk-size N # Text chunk size (default: 512)
--chunk-overlap N # Overlap between chunks (default: 128)
```
#### Example Commands
```bash
# Basic usage with HTML export
python -m apps.chatgpt\_rag --export-path conversations.html
# Process ZIP archive from ChatGPT
python -m apps.chatgpt\_rag --export-path chatgpt\_export.zip
# Search with specific query
python -m apps.chatgpt\_rag --export-path chatgpt\_data.html --query "Python programming help"
# Process individual messages for fine-grained search
python -m apps.chatgpt\_rag --separate-messages --export-path chatgpt\_export.html
# Process directory containing multiple exports
python -m apps.chatgpt\_rag --export-path ./chatgpt\_exports/ --max-items 1000
```

**💡 Click to expand: Example queries you can try**
ChatGPT 대화가 인덱싱되면 다음과 같은 쿼리로 검색할 수 있습니다:
- "What did I ask ChatGPT about Python programming?"
- "Show me conversations about machine learning algorithms"
- "Find discussions about web development frameworks"
- "What coding advice did ChatGPT give me?"
- "Search for conversations about debugging techniques"
- "Find ChatGPT's recommendations for learning resources"
### 🤖 Claude Chat History: Your Personal AI Conversation Archive!
Claude 대화를 검색 가능한 지식베이스로 변환하세요! 코딩, 연구, 브레인스토밍 등에 대한 모든 Claude 토론 내용을 검색할 수 있습니다.
```bash
python -m apps.claude\_rag --export-path claude\_export.json --query "What did I ask about Python dictionaries?"
```
\*\*AI 대화 기록을 잠금 해제하세요.\*\* Claude 토론에서 얻은 소중한 인사이트를 다시는 잃어버리지 마세요.
**📋 Click to expand: How to Export Claude Data**
\*\*단계별 내보내기 프로세스:\*\*
1. 브라우저에서 \*\*Claude를 엽니다\*\*.\
2. \*\*Settings\*\*로 이동합니다 (톱니바퀴 아이콘 또는 설정 메뉴 찾기).\
3. 계정 설정에서 \*\*Export/Download\*\* 옵션을 찾습니다.\
4. \*\*대화 데이터를 다운로드\*\*합니다 (보통 JSON 형식).\
5. \*\*파일을 프로젝트 디렉토리에 배치\*\*합니다.\
\*참고: Claude 내보내기 방법은 사용 중인 인터페이스에 따라 다를 수 있습니다. 가장 최신 내보내기 안내는 Claude의 도움말 문서를 확인하세요.*\
\*\*지원되는 형식:\*\*
- `.json` 파일 (권장)
- JSON 데이터가 포함된 `.zip` 아카이브
- 여러 개의 내보내기 파일이 포함된 디렉토리

**📋 클릭하여 펼치기: Claude 전용 인수**
#### 매개변수
```bash
--export-path PATH # Path to Claude export file (.json/.zip) or directory (default: ./claude\_export)
--separate-messages # Process each message separately instead of concatenated conversations
--chunk-size N # Text chunk size (default: 512)
--chunk-overlap N # Overlap between chunks (default: 128)
```
#### 예제 명령어
```bash
# Basic usage with JSON export
python -m apps.claude\_rag --export-path my\_claude\_conversations.json
# Process ZIP archive from Claude
python -m apps.claude\_rag --export-path claude\_export.zip
# Search with specific query
python -m apps.claude\_rag --export-path claude\_data.json --query "machine learning advice"
# Process individual messages for fine-grained search
python -m apps.claude\_rag --separate-messages --export-path claude\_export.json
# Process directory containing multiple exports
python -m apps.claude\_rag --export-path ./claude\_exports/ --max-items 1000
```

**💡 클릭하여 펼치기: 시도해 볼 수 있는 예시 쿼리**
Claude 대화가 색인되면 다음과 같은 쿼리로 검색할 수 있습니다:
- "내가 Claude에게 Python 프로그래밍에 대해 뭐라고 물었지?"
- "머신러닝 알고리즘에 대한 대화를 보여줘"
- "소프트웨어 아키텍처 패턴에 대한 토론을 찾아줘"
- "Claude가 어떤 디버깅 조언을 해주었지?"
- "자료 구조에 대한 대화를 검색해줘"
- "학습 리소스에 대한 Claude의 추천을 찾아줘"
### 💬 iMessage 기록: 나만의 개인 대화 아카이브!
iMessage 대화를 검색 가능한 지식 베이스로 변환하세요! 모든 문자 메시지, 단체 채팅, 그리고 친구, 가족, 동료와의 대화를 검색할 수 있습니다.
```bash
python -m apps.imessage\_rag --query "What did we discuss about the weekend plans?"
```
\*\*메시지 기록의 잠금을 해제하세요.\*\* iMessage 기록에 있는 중요한 대화, 공유된 링크, 기억하고 싶은 순간들을 절대 잃어버리지 마세요.
**📋 클릭하여 펼치기: iMessage 데이터에 접근하는 방법**
\*\*iMessage 데이터 위치:\*\*
iMessage 대화는 Mac의 다음 SQLite 데이터베이스에 저장됩니다:
```
~/Library/Messages/chat.db
```
\*\*중요 설정 요구사항:\*\*
1. 터미널 또는 IDE에 \*\*전체 디스크 접근 권한(Full Disk Access)\*\* 부여:
- \*\*시스템 환경설정(System Preferences)\*\* → \*\*보안 및 개인 정보 보호(Security & Privacy)\*\* → \*\*개인 정보 보호(Privacy)\*\* 열기
- 왼쪽 사이드바에서 \*\*전체 디스크 접근(Full Disk Access)\*\* 선택
- \*\*+\*\* 버튼을 클릭하고 터미널 앱(Terminal, iTerm2) 또는 IDE(VS Code 등) 추가
- 권한을 부여한 후 터미널/IDE 재시작
2. \*\*대안: 백업 데이터베이스 사용\*\*
- Time Machine 백업 또는 데이터베이스의 수동 복사본이 있는 경우
- 사용자 지정 위치를 지정하려면 `--db-path` 사용
\*\*지원되는 형식:\*\*
- `~/Library/Messages/chat.db`에 직접 접근 (기본값)
- `--db-path`를 사용한 사용자 지정 데이터베이스 경로
- 데이터베이스 백업 복사본과 함께 작동

**📋 클릭하여 펼치기: iMessage 전용 인수**
#### 매개변수
```bash
--db-path PATH # Path to chat.db file (default: ~/Library/Messages/chat.db)
--concatenate-conversations # Group messages by conversation (default: True)
--no-concatenate-conversations # Process each message individually
--chunk-size N # Text chunk size (default: 1000)
--chunk-overlap N # Overlap between chunks (default: 200)
```
#### 예제 명령어
```bash
# Basic usage (requires Full Disk Access)
python -m apps.imessage\_rag
# Search with specific query
python -m apps.imessage\_rag --query "family dinner plans"
# Use custom database path
python -m apps.imessage\_rag --db-path /path/to/backup/chat.db
# Process individual messages instead of conversations
python -m apps.imessage\_rag --no-concatenate-conversations
# Limit processing for testing
python -m apps.imessage\_rag --max-items 100 --query "weekend"
```

**💡 클릭하여 펼치기: 시도해 볼 수 있는 예시 쿼리**
iMessage 대화 내용이 색인화되면 다음과 같은 쿼리로 검색할 수 있습니다:
- "휴가 계획에 대해 무엇을 논의했지?"
- "레스토랑 추천에 대한 메시지 찾아줘"
- "프로젝트에 대해 John과 나눈 대화 보여줘"
- "기술과 관련된 공유 링크 검색해줘"
- "주말 이벤트에 대한 단체 채팅 토론 찾아줘"
- "가족 모임에 대해 엄마가 뭐라고 하셨지?"
### MCP 통합: 모든 플랫폼의 실시간 데이터 기반 RAG
Model Context Protocol(MCP)을 통해 실시간 데이터 소스에 연결하세요. 이제 LEANN은 표준화된 MCP 서버를 통해 Slack, Twitter 등의 플랫폼에서 실시간 RAG를 지원합니다.
\*\*주요 장점:\*\*
- \*\*실시간 데이터 액세스\*\*: 수동 내보내기 없이 실시간 데이터 가져오기
- \*\*표준화된 프로토콜\*\*: 모든 MCP 호환 서버 사용
- \*\*간편한 확장\*\*: 최소한의 코드로 새로운 플랫폼 추가
- \*\*보안 액세스\*\*: MCP 서버에서 인증 처리
#### 💬 Slack 메시지: 팀 대화 내용 검색
Slack 워크스페이스를 검색 가능한 지식 베이스로 변환하세요! 모든 채널에서 토론, 결정 사항 및 공유된 지식을 찾아보세요.
```bash
# Test MCP server connection
python -m apps.slack\_rag --mcp-server "slack-mcp-server" --test-connection
# Index and search Slack messages
python -m apps.slack\_rag \
--mcp-server "slack-mcp-server" \
--workspace-name "my-team" \
--channels general dev-team random \
--query "What did we decide about the product launch?"
```
\*\*📖 종합 설정 가이드\*\*: 자세한 설정 지침, 일반적인 문제 해결("users cache is not ready yet" 등), 고급 구성 옵션은 [\*\*Slack 설정 가이드\*\*](docs/slack-setup-guide.md)를 참고하세요.
\*\*빠른 설정:\*\*
1. Slack MCP 서버 설치 (예: `npm install -g slack-mcp-server`)
2. Slack App을 생성하고 API 자격 증명 얻기 (위의 상세 가이드 참고)
3. 환경 변수 설정:
```bash
export SLACK\_BOT\_TOKEN="xoxb-your-bot-token"
export SLACK\_APP\_TOKEN="xapp-your-app-token" # Optional
```
4. `--test-connection` 플래그로 연결 테스트
\*\*인수:\*\*
- `--mcp-server`: Slack MCP 서버를 시작하기 위한 명령어
- `--workspace-name`: 구성을 위한 Slack 워크스페이스 이름
- `--channels`: 색인할 특정 채널 (선택 사항)
- `--concatenate-conversations`: 채널별 메시지 그룹화 (기본값: true)
- `--max-messages-per-channel`: 채널당 메시지 제한 (기본값: 100)
- `--max-retries`: 캐시 동기화 문제에 대한 최대 재시도 횟수 (기본값: 5)
- `--retry-delay`: 재시도 간 초기 지연 시간(초) (기본값: 2.0)
#### 🐦 Twitter 북마크: 나만의 트윗 라이브러리
Twitter 북마크를 검색하세요! 나중에 보려고 저장해 둔 완벽한 기사, 스레드 또는 인사이트를 찾아보세요.
```bash
# Test MCP server connection
python -m apps.twitter\_rag --mcp-server "twitter-mcp-server" --test-connection
# Index and search Twitter bookmarks
python -m apps.twitter\_rag \
--mcp-server "twitter-mcp-server" \
--max-bookmarks 1000 \
--query "What AI articles did I bookmark about machine learning?"
```
\*\*설정 요구 사항:\*\*
1. Twitter MCP 서버 설치 (예: `npm install -g twitter-mcp-server`)
2. Twitter API 자격 증명 얻기:
- [developer.twitter.com](https://developer.twitter.com)에서 Twitter 개발자 계정 신청
- Twitter 개발자 포털에서 새 앱 생성
- "읽기(Read)" 권한이 있는 API 키 및 액세스 토큰 생성
- 북마크 액세스를 위해 적절한 범위가 지정된 Twitter API v2가 필요할 수 있음
```bash
export TWITTER\_API\_KEY="your-api-key"
export TWITTER\_API\_SECRET="your-api-secret"
export TWITTER\_ACCESS\_TOKEN="your-access-token"
export TWITTER\_ACCESS\_TOKEN\_SECRET="your-access-token-secret"
```
3. `--test-connection` 플래그로 연결 테스트
\*\*인수:\*\*
- `--mcp-server`: Twitter MCP 서버를 시작하기 위한 명령어
- `--username`: 사용자 이름으로 북마크 필터링 (선택 사항)
- `--max-bookmarks`: 가져올 최대 북마크 수 (기본값: 1000)
- `--no-tweet-content`: 트윗 내용 제외, 메타데이터만 포함
- `--no-metadata`: 제외

참여 메타데이터

**💡 Click to expand: Example queries you can try**
\*\*Slack Queries:\*\*
- "What did the team discuss about the project deadline?"
- "Find messages about the new feature launch"
- "Show me conversations about budget planning"
- "What decisions were made in the dev-team channel?"
\*\*Twitter Queries:\*\*
- "What AI articles did I bookmark last month?"
- "Find tweets about machine learning techniques"
- "Show me bookmarked threads about startup advice"
- "What Python tutorials did I save?"
**🔧 Using MCP with CLI Commands**
\*\*Want to use MCP data with regular LEANN CLI?\*\* 일반 LEANN CLI와 함께 MCP 데이터를 사용하고 싶으신가요? MCP 앱을 CLI 명령어와 결합하여 사용할 수 있습니다:
```bash
# Step 1: Use MCP app to fetch and index data
python -m apps.slack\_rag --mcp-server "slack-mcp-server" --workspace-name "my-team"
# Step 2: The data is now indexed and available via CLI
leann search slack\_messages "project deadline"
leann ask slack\_messages "What decisions were made about the product launch?"
# Same for Twitter bookmarks
python -m apps.twitter\_rag --mcp-server "twitter-mcp-server"
leann search twitter\_bookmarks "machine learning articles"
```
\*\*MCP vs Manual Export:\*\*
- \*\*MCP\*\*: 실시간 데이터, 자동 업데이트, 서버 설정 필요
- \*\*Manual Export\*\*: 일회성 설정, 오프라인 작동, 수동 데이터 내보내기 필요

**🔧 새로운 MCP 플랫폼 추가하기**
다른 플랫폼에 대한 지원을 추가하고 싶으신가요? LEANN의 MCP 통합은 쉽게 확장할 수 있도록 설계되어 있습니다:
1. 플랫폼용 \*\*MCP 서버를 찾거나 생성\*\*합니다.
2. `apps/slack\_data/slack\_mcp\_reader.py`의 패턴을 따라 \*\*리더 클래스를 생성\*\*합니다.
3. `apps/slack\_rag.py`의 패턴을 따라 \*\*RAG 애플리케이션을 생성\*\*합니다.
4. \*\*테스트를 거치고 커뮤니티에 기여\*\*하세요!
\*\*살펴볼 만한 인기 MCP 서버:\*\*
- GitHub 리포지토리 및 이슈
- Discord 메시지
- Notion 페이지
- Google Drive 문서
- 이외에도 MCP 생태계의 다양한 서버들!
### 🚀 Claude Code 통합: 개발 워크플로우를 혁신하세요!
**AST 인식 코드 청킹(AST‑Aware Code Chunking)**
LEANN은 Python, Java, C#, TypeScript에 대해 시맨틱 경계(함수, 클래스, 메서드)를 보존하는 지능형 코드 청킹 기능을 제공하여, 텍스트 기반 청킹에 비해 코드 이해도를 향상시킵니다.
📖 [AST 청킹 가이드 →](docs/ast\_chunking\_guide.md) 읽기
\*\*코드 어시스턴트의 미래가 여기에 있습니다.\*\* Claude Code를 위한 LEANN의 네이티브 MCP integration으로 개발 워크플로우를 혁신하세요. 전체 코드베이스를 색인화하고 IDE에서 직접 지능형 코드 지원을 받으세요.
\*\*주요 기능:\*\*
- 🔍 프로젝트 전체에 걸친 \*\*시맨틱 코드 검색\*\*, 완전한 로컬 인덱스 및 경량화
- 🧠 코드 구조(함수, 클래스)를 보존하는 \*\*AST 인식 청킹\*\*
- 📚 디버깅 및 개발을 위한 \*\*컨텍스트 인식 지원\*\*
- 🚀 자동 언어 감지를 통한 \*\*제로 설정(Zero-config) 설치\*\*
```bash
# Install LEANN globally for MCP integration
uv tool install leann-core --with leann
claude mcp add --scope user leann-server -- leann\_mcp
# Setup is automatic - just start using Claude Code!
```
자동 쿼리 재작성, 시맨틱 검색 계획 등을 갖춘 완전 에이전트(agentic) 파이프라인을 체험해 보세요:
![LEANN MCP Integration](https://raw.githubusercontent.com/StarTrail-org/LEANN/main/assets/mcp\_leann.png)
\*\*🔥 코딩 능력을 극대화할 준비가 되셨나요?\*\* [전체 설치 가이드 →](packages/leann-mcp/README.md)
## 명령줄 인터페이스 (Command Line Interface)
LEANN에는 문서 처리와 검색을 위한 강력한 CLI가 포함되어 있습니다. 빠른 문서 색인화와 대화형 채팅에 적합합니다.
### 설치 (Installation)
빠른 시작(Quick Start)을 따랐다면, `leann`이 이미 가상 환경에 설치되어 있을 것입니다:
```bash
source .venv/bin/activate
leann --help
```
\*\*전역(Global)으로 사용 가능하게 만들려면:\*\*
```bash
# Install the LEANN CLI globally using uv tool
uv tool install leann-core --with leann
# Now you can use leann from anywhere without activating venv
leann --help
```
> \*\*참고\*\*: Claude Code 통합을 위해서는 전역 설치가 필요합니다. `leann\_mcp` 서버는 전역으로 사용 가능한 `leann` 명령에 의존합니다.
### 사용 예시 (Usage Examples)
```bash
# build from a specific directory, and my\_docs is the index name(Here you can also build from multiple dict or multiple files)
leann build my-docs --docs ./your\_documents
# Search your documents
leann search my-docs "machine learning concepts"
# Interactive chat with your documents
leann ask my-docs --interactive
# Ask a single question (non-interactive)
leann ask my-docs "Where are prompts configured?"
# Detect file changes since last build/watch checkpoint
leann watch my-docs
# List all your indexes
leann list
# Remove an index
leann remove my-docs
```
\*\*주요 CLI 기능:\*\*
- 문서 형식 자동 감지 (PDF, TXT, MD, DOCX, PPTX + 코드 파일)
- Python, Java, C#, TypeScript 파일을 위한 \*\*🧠 AST 인식 청킹\*\*
- 기타 모든 콘텐츠를 위한 오버랩 지원 스마트 텍스트 청킹
- Merkle 트리 스냅샷을 통한 \*\*📂 파일 변경 감지\*\* (`leann watch`)
- 다중 LLM 제공자 지원 (Ollama, OpenAI, HuggingFace)
- `.leann/indexes/`에 체계적인 인덱스 저장 (프로젝트 로컬)
- 고급 검색 파라미터 지원
**📋 클릭하여 확장: 전체 CLI 참조**
`leann --help` 또는 `leann build --help`, `leann search --help`, `leann watch --help`, `leann ask --help`, `leann list --help`, `leann remove --help`를 사용하여 전체 CLI 참조를 확인할 수 있습니다.
\*\*빌드 명령어:\*\*
```

bash
leann build INDEX\_NAME --docs DIRECTORY|FILE [DIRECTORY|FILE ...] [OPTIONS]
Options:
--backend {hnsw,diskann} 사용할 백엔드 (기본값: hnsw)
--embedding-model MODEL 임베딩 모델 (기본값: facebook/contriever)
--graph-degree N 그래프 차수 (기본값: 32)
--complexity N 빌드 복잡도 (기본값: 64)
--force 기존 인덱스 강제 재구축
--compact / --no-compact 컴팩트 스토리지 사용 여부 (기본값: true). `no-recompute` 빌드의 경우 반드시 `no-compact`여야 합니다.
--recompute / --no-recompute 재계산 활성화 (기본값: true)
```
\*\*검색 명령어 (Search Command):\*\*
```bash
leann search INDEX\_NAME QUERY [OPTIONS]
Options:
--top-k N 결과 개수 (기본값: 5)
--complexity N 검색 복잡도 (기본값: 64)
--recompute / --no-recompute 임베딩 재계산 활성화/비활성화 (기본값: 활성화). `recompute` 빌드에서는 `no-recompute` 검색을 수행하지 않아야 합니다.
--pruning-strategy {global,local,proportional}
```
\*\*감시 명령어 (Watch Command):\*\*
```bash
leann watch INDEX\_NAME
# 현재 파일 시스템 상태를 마지막 체크포인트(Merkle 트리 스냅샷)와 비교하여
# 추가, 제거 또는 수정된 파일과 해당 청크 ID를 보고합니다.
#
# - 변경 사항을 감지한 후 자동으로 새 체크포인트를 저장합니다.
# - 이후의 각 실행은 가장 최근 체크포인트와 비교합니다.
# - 파일 변경 감지는 Merkle 트리를 통한 SHA-256 콘텐츠 해싱을 사용합니다.
#
# 출력 예시:
# === 마지막 체크포인트 이후의 변경 사항 ===
# modified (1):
# - /path/to/file.py
# chunks: 42, 43, 44
```
\*\*질의 명령어 (Ask Command):\*\*
```bash
leann ask INDEX\_NAME [OPTIONS]
Options:
--llm {ollama,openai,hf,anthropic} LLM 제공자 (기본값: ollama)
--model MODEL 모델 이름 (기본값: qwen3:8b)
--interactive 대화형 채팅 모드
--top-k N 검색 개수 (기본값: 20)
```
\*\*목록 명령어 (List Command):\*\*
```bash
leann list
# 상태 표시자와 함께 모든 프로젝트의 모든 인덱스를 나열합니다:
# ✅ - 인덱스가 완료되어 사용할 준비가 됨
# ❌ - 인덱스가 불완전하거나 손상됨
# 📁 - CLI로 생성된 인덱스 (.leann/indexes/)
# 📄 - 앱으로 생성된 인덱스 (\*.leann.meta.json 파일)
```
\*\*제거 명령어 (Remove Command):\*\*
```bash
leann remove INDEX\_NAME [OPTIONS]
Options:
--force, -f 확인 없이 강제 제거
# 스마트 제거: 자동으로 인덱스를 찾아 안전하게 제거합니다.
# - 프로젝트 전반의 모든 일치하는 인덱스를 표시합니다.
# - 프로젝트 간 제거 시 확인이 필요합니다.
# - 여러 개가 일치할 경우 대화형 선택을 지원합니다.
# - CLI 및 앱 생성 인덱스를 모두 지원합니다.
```
## 🚀 고급 기능 (Advanced Features)
### 🎯 메타데이터 필터링 (Metadata Filtering)
LEANN은 날짜/유형별 문서 필터링, 파일 확장자별 코드 검색, 사용자 정의 기준에 따른 콘텐츠 관리와 같은 고도화된 유스케이스를 지원하기 위해 간단한 메타데이터 필터링 시스템을 제공합니다.
```python
# 인덱싱 중에 메타데이터 추가
builder.add\_text(
"def authenticate\_user(token): ...",
metadata={"file\_extension": ".py", "lines\_of\_code": 25}
)
# 필터로 검색
results = searcher.search(
query="authentication function",
metadata\_filters={
"file\_extension": {"==": ".py"},
"lines\_of\_code": {"<": 100}
}
)
```
\*\*지원되는 연산자 (Supported operators\*\*): `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`, `not\_in`, `contains`, `starts\_with`, `ends\_with`, `is\_true`, `is\_false`
📖 \*\*[전체 메타데이터 필터링 가이드 → (Complete Metadata filtering guide →)](docs/metadata\_filtering.md)\*\*
### 🔍 Grep 검색 (Grep Search)
의미 기반 검색 대신 정확한 텍스트 일치를 위해 `use\_grep` 매개변수를 사용하세요:
```python
# 정확한 텍스트 검색
results = searcher.search("banana‑crocodile", use\_grep=True, top\_k=1)
```
\*\*유스케이스 (Use cases\*\*): 의미 유사성이 필요 없는 특정 코드 패턴, 오류 메시지, 함수 이름 또는 정확한 문구 찾기.
📖 \*\*[전체 grep 검색 가이드 → (Complete grep search guide →)](docs/grep\_search.md)\*\*
## 🏗️ 아키텍처 및 작동 원리 (Architecture & How It Works)

![LEANN Architecture](assets/arch.png)

\*\*핵심 포인트:\*\* 대부분의 벡터 DB는 모든 단일 임베딩을 저장하므로 비용이 많이 듭니다. LEANN은 가지치기된 그래프 구조를 저장하고(저렴함) 필요할 때만 임베딩을 다시 계산합니다(빠름).
\*\*핵심 기술:\*\*
- \*\*그래프 기반 선택적 재계산:\*\* 검색 경로에 있는 노드에 대해서만 임베딩을 계산합니다.
- \*\*고차수 보존 가지치기:\*\* 중복 연결을 제거하면서 중요한 "허브" 노드를 유지합니다.
- \*\*동적 배치 처리:\*\* GPU 활용을 위해 임베딩 연산을 효율적으로 배치 처리합니다.
- \*\*2단계 검색:\*\* 유망한 노드를 우선시하는 스마트 그래프 탐색
\*\*백엔드:\*\*
- \*\*HNSW\*\* (기본값): 완전한 재계산을 통한 최대 저장 공간 절감으로 대부분의 데이터셋에 이상적입니다.
- \*\*DiskANN\*\*: 최고의 속도와 정확도 절감 효과를 위해 실시간 재순랭킹과 함께 PQ 기반 그래프 탐색을 사용하는, 뛰어난 검색 성능을 제공하는 고급 옵션입니다.
## 벤치마크
\*\*[DiskANN 대 HNSW 성능 비교 →](benchmarks/diskann\_vs\_hnsw\_speed\_comparison.py)\*\* - 두 백엔드 간의 검색 성능을 비교합니다.
\*\*[간단한 예제: LEANN 대 FAISS 비교 →](benchmarks/compare\_faiss\_vs\_leann.py)\*\* - 실제 저장 공간 절감 효과를 확인하세요.
### 📊 저장 공간 비교
| 시스템 | DPR (2.1M) | Wiki (60M) | Chat (400K) | Email (780K) | Browser (38K) |
|--------|-------------|------------|-------------|--------------|---------------|
| 기존 벡터 데이터베이스 (예: FAISS) | 3.8 GB | 201 GB | 1.8 GB | 2.4 GB | 130 MB |
| LEANN | 324 MB | 6 GB | 64 MB | 79 MB | 6.4 MB |
| 절감률 | 91% | 97% | 97% | 97% | 95% |
## 결과 재현하기
```bash
uv run benchmarks/run\_evaluation.py # 평가 데이터를 자동으로 다운로드하고 벤치마크를 실행합니다.
uv run benchmarks/run\_evaluation.py benchmarks/data/indices/rpj\_wiki/rpj\_wiki --num-queries 2000 # 데이터를 다운로드한 후, 가장 큰 인덱스로 벤치마션을 실행할 수 있습니다.
```
평가 스크립트는 첫 실행 시 데이터를 자동으로 다운로드합니다. 마지막 세 가지 결과는 일부 개인 데이터로 테스트되었으며, 사용자 자신의 데이터로 이를 재현할 수 있습니다!
## 🔬 논문
Leann이 유용하다고 생각하신다면 다음을 인용해 주세요:
\*\*[LEANN: A Low-Storage Vector Index](https://arxiv.org/abs/2506.08276)\*\*
```bibtex
@misc{wang2025leannlowstoragevectorindex,
title={LEANN: A Low-Storage Vector Index},
author={Yichuan Wang and Shu Liu and Zhifei Li and Yongji Wu and Ziming Mao and Yilong Zhao and Xiao Yan and Zhiying Xu and Yang Zhou and Ion Stoica and Sewon Min and Matei Zaharia and Joseph E. Gonzalez},
year={2025},
eprint={2506.08276},
archivePrefix={arXiv},
primaryClass={cs.DB},
url={https://arxiv.org/abs/2506.08276},
}
```
## ✨ [상세 기능 →](docs/features.md)
## 🤝 [기여하기 →](docs/CONTRIBUTING.md)
## ❓ [FAQ →](docs/faq.md)
## 📈 [로드맵 →](docs/roadmap.md)
## 📄 라이선스
MIT 라이선스 - 자세한 내용은 [LICENSE](LICENSE)를 참조하세요.
## 🙏 감사의 글
핵심 기여자: [Yichuan Wang](https://yichuan-w.github.io/) & [Zhifei Li](https://github.com/andylizf).
활성 기여자: [Gabriel Dehan](https://github.com/gabriel-dehan), [Aakash Suresh](https://github.com/ASuresh0524)
더 많은 기여자를 환영합니다! 이슈를 열거나 PR을 제출해 주세요.
이 작업은 [\*\*Berkeley Sky Computing Lab\*\*](https://sky.cs.berkeley.edu/)에서 수행되었습니다.
## 스타 히스토리
[![Star History Chart](https://api.star-history.com/svg?repos=yichuan-w/LEANN&type=Date)](https://www.star-history.com/#yichuan-w/LEANN&Date)

**⭐ 연구나 애플리케이션에 Leann이 유용하다면 GitHub에서 스타를 눌러주세요!**

Leann 팀이 ❤️를 담아 만들었습니다.

## 🤖 AI로 LEANN 탐색하기
LEANN은 [DeepWiki](https://deepwiki.com/yichuan-w/LEANN)에 색인되어 있으므로, Deep Research를 사용하여 LLM에 질문함으로써 코드베이스를 탐색하고 새로운 기능을 추가하는 데 도움을 받을 수 있습니다.

LEANN

LEANN 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

LEANN

LEANN 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README