KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

kotaemon

★ 25,699 Open GitHub ↗

문서와 채팅할 수 있는 오픈소스 RAG 기반 도구입니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# kotaemon

문서와 채팅할 수 있는 오픈소스의 깔끔하고 커스터마이징 가능한 RAG UI입니다. 최종 사용자와 개발자 모두를 고려하여 구축되었습니다.

![Preview](https://raw.githubusercontent.com/Cinnamon/kotaemon/main/docs/images/preview-graph.png)

[Live Demo #1](https://huggingface.co/spaces/cin-model/kotaemon) |
[Live Demo #2](https://huggingface.co/spaces/cin-model/kotaemon-demo) |
[Online Install](https://cinnamon.github.io/kotaemon/online_install/) |
[Colab Notebook (Local RAG)](https://colab.research.google.com/drive/1eTfieec_UOowNizTJA1NjawBJH9y_1nn)

[User Guide](https://cinnamon.github.io/kotaemon/) |
[Developer Guide](https://cinnamon.github.io/kotaemon/development/) |
[Feedback](https://github.com/Cinnamon/kotaemon/issues) |
[Contact](mailto:kotaemon.support@cinnamon.is)

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-31013/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
<a href="https://github.com/Cinnamon/kotaemon/pkgs/container/kotaemon" target="_blank">
<img src="https://img.shields.io/badge/docker_pull-kotaemon:latest-brightgreen" alt="docker pull ghcr.io/cinnamon/kotaemon:latest"></a>
![download](https://img.shields.io/github/downloads/Cinnamon/kotaemon/total.svg?label=downloads&color=blue)
<a href='https://huggingface.co/spaces/cin-model/kotaemon-demo'><img src='https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue'></a>
<a href="https://hellogithub.com/en/repository/d3141471a0244d5798bc654982b263eb" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=d3141471a0244d5798bc654982b263eb&claim_uid=RLiD9UZ1rEHNaMf&theme=small" alt="Featured｜HelloGitHub" /></a>

</div>

## Introduction

이 프로젝트는 자신의 문서에 대해 QA를 수행하려는 최종 사용자와 자신만의 RAG 파이프라인을 구축하려는 개발자 모두를 위한 기능적인 RAG UI 역할을 합니다.
<br>

```yml
+----------------------------------------------------------------------------+
| End users: Those who use apps built with `kotaemon`.                       |
| (You use an app like the one in the demo above)                            |
|     +----------------------------------------------------------------+     |
|     | Developers: Those who built with `kotaemon`.                   |     |
|     | (You have `import kotaemon` somewhere in your project)         |     |
|     |     +----------------------------------------------------+     |     |
|     |     | Contributors: Those who make `kotaemon` better.    |     |     |
|     |     | (You make PR to this repo)                         |     |     |
|     |     +----------------------------------------------------+     |     |
|     +----------------------------------------------------------------+     |
+----------------------------------------------------------------------------+
```

### 최종 사용자(end users)를 위한 기능

- **깔끔하고 미니멀한 UI**: RAG 기반 QA를 위한 사용자 친화적인 인터페이스.
- **다양한 LLM 지원**: LLM API 제공업체(OpenAI, AzureOpenAI, Cohere 등) 및 로컬 LLM(`ollama` 및 `llama-cpp-python`을 통해)과 호환됩니다.
- **간편한 설치**: 빠르게 시작할 수 있는 간단한 스크립트를 제공합니다.

### 개발자(developers)를 위한 기능

- **RAG 파이프라인 프레임워크**: 자신만의 RAG 기반 문서 QA 파이프라인을 구축하기 위한 도구들.
- **커스터마이징 가능한 UI**: <a href='https://github.com/gradio-app/gradio'>Gradio <img src='https://img.shields.io/github/stars/gradio-app/gradio'></a>로 구축된 제공 UI를 통해 RAG 파이프라인의 작동 모습을 확인할 수 있습니다.
- **Gradio 테마**: 개발에 Gradio를 사용하신다면, 여기에서 저희 테마를 확인해 보세요: [kotaemon-gradio-theme](https://github.com/lone17/kotaemon-gradio-theme).

## 주요 특징 (Key Features)

- **자체 문서 QA (RAG) 웹 UI 호스팅**: 멀티 사용자 로그인을 지원하며, 파일을 개인/공개 컬렉션으로 정리하고, 즐겨 찾는 채팅을 다른 사람과 협업 및 공유할 수 있습니다.

- **LLM 및 Embedding 모델 관리**: 로컬 LLM과 유명 API 제공업체(OpenAI, Azure, Ollama, Groq)를 모두 지원합니다.

- **하이브리드 RAG 파이프라인**: 최상의 검색 품질을 보장하기 위해 하이브리드(전체 텍스트 및 벡터) 검색기와 리랭킹(re-ranking)이 포함된 합리적인 기본 RAG 파이프라인을 제공합니다.

- **멀티모달 QA 지원**: 그림과 표 지원이 포함된 여러 문서에 대해 질의응답을 수행합니다. 멀티모달 문서 파싱을 지원하며 UI에서 옵션을 선택할 수 있습니다.

- **문서 미리보기가 포함된 고급 인용**: 기본적으로 시스템은 LLM 답변의 정확성을 보장하기 위해 상세한 인용을 제공합니다. 하이라이트가 표시된 _브라우저 내 PDF 뷰어_에서 인용구(관련성 점수 포함)를 직접 확인할 수 있습니다. 검색 파이프라인이 관련성이 낮은 문서를 반환할 때 경고를 표시합니다.

- **복잡한 추론 방법 지원**: 질문 분해(question decomposition)를 사용하여 복잡한/멀티홉 질문에 답할 수 있습니다. `ReAct`, `ReWOO` 및 기타 에이전트를 이용한 에이전트 기반 추론을 지원합니다.

- **설정 가능한 설정 UI**: 검색 및 생성 프로세스의 가장 중요한 측면들(프롬프트 포함)을 UI에서 조정할 수 있습니다.

- **확장성**: Gradio 기반으로 구축되어 원하는 대로 UI 요소를 커스터마이징하거나 추가할 수 있습니다. 또한 문서 인덱싱 및 검색을 위한 다양한 전략을 지원하는 것을 목표로 합니다. 예시로 `GraphRAG` 인덱싱 파이프라인이 제공됩니다.

![Preview](https://raw.githubusercontent.com/Cinnamon/kotaemon/main/docs/images/preview.png)

## 설치 (Installation)

> 개발자가 아니며 단순히 앱을 사용하고 싶으신 경우, 따라 하기 쉬운 [User Guide](https://cinnamon.github.io/kotaemon/)를 확인해 주세요. 최신 기능과 버그 수정을 적용하려면 [latest release](https://github.com/Cinnamon/kotaemon/releases/latest)에서 `.zip` 파일을 다운로드하세요.

### 시스템 요구 사항

1. [Python](https://www.python.org/downloads/) >= 3.10
2. [Docker](https://www.docker.com/): 선택 사항, [Docker로 설치](#with-docker-recommended)하려는 경우 필요합니다.
3. `.pdf`, `.html`, `.mhtml`, `.xlsx` 이외의 파일을 처리하려면 [Unstructured](https://docs.unstructured.io/open-source/installation/full-installation#full-installation)가 필요합니다. 설치 단계는 운영 체제에 따라 다릅니다. 링크를 방문하여 제공된 특정 지침을 따르십시오.

### Docker를 사용하는 방법 (권장)

1. `lite` 및 `full` 버전의 Docker 이미지를 모두 지원합니다. `full` 버전에는 `unstructured`의 추가 패키지가 설치되어 더 많은 파일 유형(`.doc`, `.docx`, ...)을 지원하지만, Docker 이미지 크기가 더 큽니다. 대부분의 사용자에게는 `lite` 이미지가 대부분의 경우 잘 작동할 것입니다.

- `full` 버전을 사용하려면:

```shell
     docker run \
     -e GRADIO_SERVER_NAME=0.0.0.0 \
     -e GRADIO_SERVER_PORT=7860 \
     -v ./ktem_app_data:/app/ktem_app_data \
     -p 7860:7860 -it --rm \
     ghcr.io/cinnamon/kotaemon:main-full
     ```

- _로컬 / 프라이빗 RAG_를 위해 Ollama가 포함된 `full` 버전을 사용하려면:

```shell
     # 이미지 이름을 다음과 같이 변경하세요
     docker run <...> ghcr.io/cinnamon/kotaemon:main-ollama
     ```

- `lite` 버전을 사용하려면:

```shell
    # 이미지 이름을 다음과 같이 변경하세요
    docker run <...> ghcr.io/cinnamon/kotaemon:main-lite
   ```

2. 현재 `linux/amd64` 및 `linux/arm64` (최신 Mac용) 두 가지 플랫폼을 지원하고 테스트합니다. `docker run` 명령에서 `--platform`을 전달하여 플랫폼을 지정할 수 있습니다. 예를 들어:

```shell
   # linux/arm64 플랫폼으로 docker를 실행하려면
   docker run \
   -e GRADIO_SERVER_NAME=0.0.0.0 \
   -e GRADIO_SERVER_PORT=7860 \
   -v ./ktem_app_data:/app/ktem_app_data \
   -p 7860:7860 -it --rm \
   --platform linux/arm64 \
   ghcr.io/cinnamon/kotaemon:main-lite
   ```

3. 모든 설정이 완료되면 `http://localhost:7860/`으로 이동하여 WebUI에 접속할 수 있습니다.

4. Docker 이미지를 저장하는 데 [GHCR](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)을 사용하며, 모든 이미지는 [여기서](https://github.com/Cinnamon/kotaemon/pkgs/container/kotaemon) 확인할 수 있습니다.

### Docker 없이 설치하는 방법

1. 저장소를 클론합니다:

```shell
   git clone https://github.com/Cinnamon/kotaemon
   cd kotaemon
   ```

2. 환경을 설정합니다:

- **옵션 1: [uv](https://docs.astral.sh/uv/getting-started/installation/) 사용 (권장)**

```shell
  uv sync --python 3.10
  source .venv/bin/activate
  ```

- **옵션 2: conda 사용**

```shell
  conda create -n kotaemon python=3.10
  conda activate kotaemon

pip install -e "libs/kotaemon[all]"
  pip install -e "libs/ktem"
  ```

3. 프로젝트 루트에 `.env` 파일을 생성하세요. `.env.example`을 템플릿으로 사용하세요.

`.env` 파일은 사용자가 앱을 시작하기 전에 모델을 사전 설정하려는 경우(예: HF hub에 앱 배포)를 위해 제공됩니다. 이 파일은 첫 실행 시 데이터베이스를 채우는 데만 사용되며, 이후 실행 시에는 더 이상 사용되지 않습니다.

4. (선택 사항) 브라우저 내 `PDF_JS` 뷰어를 활성화하려면, [PDF_JS_DIST](https://github.com/mozilla/pdf.js/releases/download/v4.0.379/pdfjs-4.0.379-dist.zip)를 다운로드하여 `libs/ktem/ktem/assets/prebuilt`에 압축을 푸세요.

5. 웹 서버를 시작합니다:

```shell
   python app.py
   ```

- 앱이 브라우저에서 자동으로 실행됩니다.
   - 기본 사용자 이름과 비밀번호는 모두 `admin`입니다. UI를 통해 추가 사용자를 직접 설정할 수 있습니다.

![Chat tab](https://raw.githubusercontent.com/Cinnamon/kotaemon/main/docs/images/chat-tab.png)

6. `Resources` 탭과 `LLMs and Embeddings`를 확인하여 `.env` 파일의 `api_key` 값이 올바르게 설정되었는지 확인하세요. 설정되어 있지 않다면 그곳에서 설정할 수 있습니다.

### GraphRAG 설정

> [!NOTE]
> 공식 MS GraphRAG 인덱싱은 OpenAI 또는 Ollama API에서만 작동합니다.
> 대부분의 사용자에게는 kotaemon과 간단하게 통합되는 NanoGraphRAG 구현을 권장합니다.

<summary>Nano GRAPHRAG 설정</summary>

- nano-GraphRAG 설치: `pip install nano-graphrag`
- `nano-graphrag` 설치 시 버전 충돌이 발생할 수 있습니다. [이 이슈](https://github.com/Cinnamon/kotaemon/issues/440)를 참조하세요.
  - 빠른 해결 방법: `pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib`
- `USE_NANO_GRAPHRAG=true` 환경 변수와 함께 Kotaemon을 실행하세요.
- Resources 설정에서 기본 LLM 및 Embedding 모델을 설정하면 NanoGraphRAG에서 자동으로 인식합니다.

</details>

<summary>LIGHTRAG 설정</summary>

- LightRAG 설치: `pip install git+https://github.com/HKUDS/LightRAG.git`
- `LightRAG` 설치 시 버전 충돌이 발생할 수 있습니다. [이 이슈](https://github.com/Cinnamon/kotaemon/issues/440)를 참조하세요.
  - 빠른 해결 방법: `pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib`
- `USE_LIGHTRAG=true` 환경 변수와 함께 Kotaemon을 실행하세요.
- Resources 설정에서 기본 LLM 및 Embedding 모델을 설정하면 LightRAG에서 자동으로 인식합니다.

</details>

<summary>MS GRAPHRAG 설정</summary>

- **Non-Docker 설치**: Docker를 사용하지 않는 경우, 다음 명령어로 GraphRAG를 설치하세요:

```shell
  pip install "graphrag<=0.3.6" future
  ```

- **API KEY 설정**: GraphRAG 검색 기능을 사용하려면 `GRAPHRAG_API_KEY` 환경 변수를 설정했는지 확인하세요. 환경 변수에 직접 설정하거나 `.env` 파일에 추가할 수 있습니다.
- **로컬 모델 및 커스텀 설정 사용**: `Ollama`와 같은 로컬 모델을 GraphRAG와 함께 사용하거나 기본 LLM 및 기타 설정을 커스터마이징하려는 경우, `USE_CUSTOMIZED_GRAPHRAG_SETTING` 환경 변수를 true로 설정하세요. 그런 다음 `settings.yaml.example` 파일에서 설정을 조정하세요.

</details>

### 로컬 모델 설정 (로컬/프라이빗 RAG용)

[Local model setup](docs/local_model.md)을 참조하세요.

### 멀티모달 문서 파싱 설정 (OCR, 테이블 파싱, 그림 추출)

다음 옵션들을 사용할 수 있습니다:

- [Azure Document Intelligence (API)](https://azure.microsoft.com/en-us/products/ai-services/ai-document-intelligence)
- [Adobe PDF Extract (API)](https://developer.adobe.com/document-services/docs/overview/pdf-extract-api/)
- [Docling (로컬, 오픈소스)](https://github.com/DS4SD/docling) – Kotaemon 전용 설정은 [integrations/docling.md](./docs/integrations/docling.md)를 참조하세요.
- [PaddleOCR (로컬, 오픈소스)](https://github.com/PADDLEPADDLE/PADDLEOCR) – Kotaemon 전용 설정은 [integrations/paddle_ocr.md](./docs/integrations/paddle_ocr.md)를 참조하세요.

`Settings -> Retrieval Settings -> File loader`에서 해당 로더를 선택하세요.

### 애플리케이션 커스터마이징

- 기본적으로 모든 애플리케이션 데이터는 `./ktem_app_data` 폴더에 저장됩니다. 이 폴더를 백업하거나 복사하여 설치 환경을 새 기기로 옮길 수 있습니다.

- 고급 사용자나 특정 사용 사례의 경우, 다음 파일들을 커스터마이징할 수 있습니다:

- `flowsettings.py`
  - `.env`

#### `flowsettings.py`

이 파일에는 애플리케이션의 설정이 포함되어 있습니다. [여기](flowsettings.py)에 있는 예시를 시작점으로 사용할 수 있습니다.

```python
# 선호하는 문서 저장소 설정 (전체 텍스트 검색 기능 포함)
KH_DOCSTORE=(Elasticsearch | LanceDB | SimpleFileDocumentStore)

# 선호하는 벡터 저장소 설정 (벡터 기반 검색용)
KH_VECTORSTORE=(ChromaDB | LanceDB | InMemory | Milvus | Qdrant)

# 멀티모달 QA 활성화 / 비활성화
KH_REASONINGS_USE_MULTIMODAL=True

# 새로운 추론 파이프라인을 설정하거나 기존 파이프라인을 수정하세요.
KH_REASONINGS = [
    "ktem.reasoning.simple.FullQAPipeline",
    "ktem.reasoning.simple.FullDecomposeQAPipeline",
    "ktem.reasoning.react.ReactAgentPipeline",
    "ktem.reasoning.rewoo.RewooAgentPipeline",
]
```

</details>

#### `.env`

이 파일은 모델과 인증 정보를 설정하는 또 다른 방법을 제공합니다.

- 또는 LLM에 연결하는 데 필요한 정보가 포함된 `.env` 파일을 통해 모델을 설정할 수 있습니다. 이 파일은 애플리케이션 폴더에 위치합니다. 파일이 보이지 않는다면 새로 생성하세요.

- 현재 다음과 같은 제공업체가 지원됩니다:

- **OpenAI**

`.env` 파일에서 `OPENAI_API_KEY` 변수에 OpenAI API 키를 설정하여 OpenAI 모델에 액세스할 수 있도록 하세요. 수정 가능한 다른 변수들도 있으니 상황에 맞게 편집하시기 바랍니다. 그렇지 않으면 기본 파라미터가 대부분의 사용자에게 적합할 것입니다.

```shell
    OPENAI_API_BASE=https://api.openai.com/v1
    OPENAI_API_KEY=<your OpenAI API key here>
    OPENAI_CHAT_MODEL=gpt-3.5-turbo
    OPENAI_EMBEDDINGS_MODEL=text-embedding-ada-002
    ```

- **Azure OpenAI**

Azure 플랫폼을 통한 OpenAI 모델의 경우, Azure 엔드포인트와 API 키를 제공해야 합니다. Azure 설정 방식에 따라 채팅 모델과 임베딩 모델의 배포 이름(deployment name)을 제공해야 할 수도 있습니다.

```shell
    AZURE_OPENAI_ENDPOINT=
    AZURE_OPENAI_API_KEY=
    OPENAI_API_VERSION=2024-02-15-preview
    AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-35-turbo
    AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT=text-embedding-ada-002
    ```

- **로컬 모델**

- `ollama` OpenAI 호환 서버 사용:

- [ollama](https://github.com/ollama/ollama)를 설치하고 애플리케이션을 시작하세요.

- 모델을 풀(pull) 하세요. 예:

```shell
        ollama pull llama3.1:8b
        ollama pull nomic-embed-text
        ```

- 웹 UI에서 모델 이름을 설정하고 기본값으로 지정하세요:

![Models](https://raw.githubusercontent.com/Cinnamon/kotaemon/main/docs/images/models.png)

- `llama-cpp-python`으로 `GGUF` 사용

[Hugging Face Hub](https://huggingface.co/models)에서 로컬에서 실행할 LLM을 검색하고 다운로드할 수 있습니다. 현재 다음과 같은 모델 형식이 지원됩니다:

- GGUF

장치 메모리보다 작은 크기의 모델을 선택하고 약 2GB 정도의 여유 공간을 남겨두어야 합니다. 예를 들어, 전체 RAM이 16GB이고 12GB를 사용할 수 있다면, 최대 10GB의 RAM을 차지하는 모델을 선택해야 합니다. 모델이 클수록 더 나은 생성 결과를 제공하는 경향이 있지만 처리 시간도 더 오래 걸립니다.

추천 모델과 메모리 사용량은 다음과 같습니다:

- [Qwen1.5-1.8B-Chat-GGUF](https://huggingface.co/Qwen/Qwen1.5-1.8B-Chat-GGUF/resolve/main/qwen1_5-1_8b-chat-q8_0.gguf?download=true): 약 2 GB

웹 UI에서 제공된 모델 이름으로 새로운 LlamaCpp 모델을 추가하세요.

</details>

### 자신만의 RAG 파이프라인 추가하기

#### 커스텀 추론 파이프라인 (Custom Reasoning Pipeline)

1. [여기](libs/ktem/ktem/reasoning/simple.py)에서 기본 파이프라인 구현을 확인하세요. 기본 QA 파이프라인의 작동 방식을 빠르게 조정할 수 있습니다.
2. `libs/ktem/ktem/reasoning/`에 새로운 `.py` 구현을 추가하고, 나중에 `flowssettings`에 포함시켜 UI에서 활성화하세요.

#### 커스텀 인덱싱 파이프라인 (Custom Indexing Pipeline)

- `libs/ktem/ktem/index/file/graph`에서 샘플 구현을 확인하세요.

> (추가 지침 준비 중).

## Citation

이 프로젝트를 다음과 같이 인용해 주세요.

```BibTeX
@misc{kotaemon2024,
    title = {Kotaemon - An open-source RAG-based tool for chatting with any content.},
    author = {The Kotaemon Team},
    year = {2024},
    howpublished = {\url{https://github.com/Cinnamon/kotaemon}},
}
```

## Star History

## Contribution

저희 프로젝트는 활발히 개발 중이므로, 여러분의 피드백과 기여를 매우 소중하게 생각합니다. 시작하시려면 [Contributing Guide](https://github.com/Cinnamon/kotaemon/blob/main/CONTRIBUTING.md)를 참조해 주세요. 모든 기여자분께 감사드립니다!

kotaemon

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README