{"id":50412343,"url":"https://github.com/cskwork/anything-rag","last_synced_at":"2026-05-31T04:04:56.819Z","repository":{"id":301526072,"uuid":"1006602309","full_name":"cskwork/anything-rag","owner":"cskwork","description":"LightRAG를 활용한 터미널 기반 문서 Q\u0026A 시스템입니다. 한국어와 영어 문서를 지원하며, OpenRouter, OpenAI, Ollama 등 다양한 LLM 서비스를 사용할 수 있습니다.","archived":false,"fork":false,"pushed_at":"2025-06-27T09:32:10.000Z","size":82,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-27T10:33:48.792Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cskwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T16:14:33.000Z","updated_at":"2025-06-23T04:11:23.000Z","dependencies_parsed_at":"2025-06-27T10:33:52.717Z","dependency_job_id":"b99ed629-736b-4531-adf5-297f62e1d117","html_url":"https://github.com/cskwork/anything-rag","commit_stats":null,"previous_names":["cskwork/anything-rag"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cskwork/anything-rag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fanything-rag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fanything-rag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fanything-rag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fanything-rag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cskwork","download_url":"https://codeload.github.com/cskwork/anything-rag/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fanything-rag/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T04:04:55.976Z","updated_at":"2026-05-31T04:04:56.813Z","avatar_url":"https://github.com/cskwork.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LightRAG Terminal Q\u0026A System\n\nLightRAG를 활용한 터미널 기반 문서 Q\u0026A 시스템입니다. 한국어와 영어 문서를 지원하며, OpenRouter, OpenAI, Ollama 등 다양한 LLM 서비스를 사용할 수 있습니다.\n\n## ✨ 특징\n\n- 🚀 **LightRAG 기반**: 빠르고 효율적인 검색 증강 생성 (Retrieval-Augmented Generation)\n- 🌐 **다중 LLM 지원**: OpenRouter, OpenAI, Ollama 자동 감지 및 선택\n- 📄 **다양한 문서 형식**: TXT, PDF, DOCX, MD, XLSX 지원\n- 🇰🇷 **한국어/영어 지원**: 자동 언어 감지 및 처리\n- 💻 **풍부한 터미널 UI**: Rich 라이브러리 기반 아름다운 인터페이스\n- 🔄 **스마트 문서 관리**: 파일 변경 감지 (MD5 해시) 및 증분 업데이트\n- 📝 **대화 히스토리**: 컨텍스트 유지 대화\n- 🛠️ **유연한 설정**: 환경 변수 기반 세부 설정\n\n## 🚀 빠른 시작\n\n### Windows\n\n```bash\nrun.bat\n```\n\n### Linux/Mac\n\n```bash\nchmod +x run.sh\n./run.sh\n```\n\n## 📦 수동 설치\n\n1. **Python 설치** (3.8 이상 권장)\n\n2. **가상환경 생성 및 활성화**\n\n```bash\npython -m venv .venv\n# Windows\n.venv\\Scripts\\activate\n# Linux/Mac\nsource .venv/bin/activate\n```\n\n3. **패키지 설치**\n\n```bash\npip install -r requirements.txt\n```\n\n4. **환경 설정**\n\n```bash\n# .env 파일 생성 및 편집\ncp .env.example .env  # 또는 수동으로 .env 파일 생성\n```\n\n5. **문서 준비**\n\n```bash\n# input/ 폴더에 분석할 문서 넣기\nmkdir -p input\n# 여기에 .txt, .pdf, .docx, .md, .xlsx 파일들을 넣으세요\n```\n\n6. **실행**\n\n```bash\npython main.py chat\n```\n\n## ⚙️ 환경 설정\n\n`.env` 파일에서 다음 설정을 구성하세요:\n\n### Ollama 사용 (기본값, 로컬 무료)\n\n```env\n# Ollama 설정\nOLLAMA_HOST=http://localhost:11434\nOLLAMA_MODEL=gemma3:1b\nOLLAMA_EMBEDDING_MODEL=bge-m3:latest\n\n# 시스템 설정\nLOG_LEVEL=INFO\nLANGUAGE=ko\n```\n\n### OpenAI 사용\n\n```env\n# OpenAI 설정\nOPENAI_API_KEY=your_openai_api_key_here\nOPENAI_MODEL=gpt-3.5-turbo\n\n# LightRAG 임베딩 모델\nLIGHTRAG_EMBEDDING_MODEL=text-embedding-3-small\n```\n\n### OpenRouter 사용\n\n```env\n# OpenRouter 설정\nOPENROUTER_API_KEY=your_openrouter_api_key_here\nOPENROUTER_MODEL=anthropic/claude-3-haiku\n\n# 또는 다른 모델들\n# OPENROUTER_MODEL=meta-llama/llama-3.1-8b-instruct:free\n# OPENROUTER_MODEL=openai/gpt-3.5-turbo\n```\n\n### 고급 설정\n\n```env\n# LightRAG 설정\nLIGHTRAG_WORKING_DIR=./rag_storage\nLIGHTRAG_CHUNK_SIZE=1200\nLIGHTRAG_CHUNK_OVERLAP=100\nLIGHTRAG_HISTORY_TURNS=3\n\n# 문서 처리 설정\nSUPPORTED_EXTENSIONS=.txt,.pdf,.docx,.md,.xlsx\nMAX_FILE_SIZE_MB=50\nENCODING=utf-8\n\n# LLM 매개변수\nMAX_TOKENS=2000\nTEMPERATURE=0.7\n\n# 디렉토리 설정\nINPUT_DIR=./input\nBACKUP_DIR=./backup\nLOGS_DIR=./logs\n```\n\n## 🎯 사용 방법\n\n### 기본 사용 흐름\n\n1. **문서 준비**: `input/` 폴더에 분석할 문서들을 넣기\n2. **대화형 모드 실행**: `python main.py chat`\n3. **질문하기**: 자연어로 질문 입력\n4. **특수 명령어**: 시스템 관리 명령어 활용\n\n### CLI 명령어\n\n```bash\n# 대화형 모드 (권장)\npython main.py chat\n\n# 문서 로드만 수행\npython main.py load\n\n# 모든 문서 강제 재로드\npython main.py load --force-reload\n\n# 단일 질의\npython main.py query \"LightRAG의 주요 특징은 무엇인가요?\"\n\n# 질의 모드 지정\npython main.py query \"질문\" --mode hybrid\n\n# 시스템 정보 확인\npython main.py info\n\n# 시스템 구성 요소 테스트\npython main.py test\n```\n\n### 대화형 모드 특수 명령어\n\n대화형 모드에서 다음 명령어들을 사용할 수 있습니다:\n\n- `/help` - 사용 가능한 명령어 목록 표시\n- `/info` - 현재 시스템 상태 및 인덱스 정보\n- `/reload` - 신규/변경된 문서만 다시 로드\n- `/reload-all` - 모든 문서 강제 재로드\n- `/reset` - 임베딩 상태 초기화 (다음 로드시 모든 파일 재처리)\n- `exit`, `quit`, `q` - 프로그램 종료\n\n### 질의 모드\n\nLightRAG는 4가지 질의 모드를 지원합니다:\n\n- **hybrid** (기본값): 로컬과 글로벌 검색을 결합한 최적의 방식\n- **naive**: 단순 벡터 유사도 검색\n- **local**: 로컬 지식 그래프 기반 검색\n- **global**: 글로벌 지식 그래프 기반 검색\n\n## 💡 실제 사용 예시\n\n### 첫 실행 과정\n\n```bash\n# 1. 프로젝트 클론 또는 다운로드\ngit clone \u003crepository-url\u003e\ncd anything-rag\n\n# 2. 환경 설정\npython -m venv .venv\nsource .venv/bin/activate  # Linux/Mac\n# .venv\\Scripts\\activate   # Windows\n\n# 3. 패키지 설치\npip install -r requirements.txt\n\n# 4. 환경 변수 설정 (.env 파일 생성)\necho \"OLLAMA_HOST=http://localhost:11434\" \u003e .env\necho \"OLLAMA_MODEL=gemma3:1b\" \u003e\u003e .env\necho \"LOG_LEVEL=INFO\" \u003e\u003e .env\n\n# 5. 문서 준비\nmkdir -p input\ncp your_documents.pdf input/\ncp your_text_files.txt input/\n\n# 6. 시스템 테스트\npython main.py test\n\n# 7. 대화형 모드 실행\npython main.py chat\n```\n\n### 대화형 모드 사용 예시\n\n```\n# 시스템 시작\npython main.py chat\n\n# 문서 자동 로드 후 질문하기\n질문: LightRAG의 주요 특징은 무엇인가요?\n답변: [문서 기반 상세 답변]\n\n# 특수 명령어 사용\n질문: /info\n답변: [시스템 정보 표시]\n\n질문: /help\n답변: [도움말 표시]\n\n# 새 문서 추가 후 리로드\n질문: /reload\n답변: [신규 문서만 로드]\n\n# 대화 맥락 활용\n질문: 앞서 말한 특징 중 가장 중요한 것은?\n답변: [이전 답변을 참고한 답변]\n\n# 종료\n질문: exit\n```\n\n### CLI 단일 명령어 사용 예시\n\n```bash\n# 문서 로드만 수행\npython main.py load\n# 출력: \"문서 로드 완료! 5개 파일 처리됨\"\n\n# 강제 전체 재로드\npython main.py load --force-reload\n# 출력: \"모든 문서 재처리 완료!\"\n\n# 단일 질의 (대화형 모드 없이)\npython main.py query \"프로젝트의 주요 기능은?\"\n# 출력: [즉시 답변 반환]\n\n# 특정 모드로 질의\npython main.py query \"성능 최적화 방법은?\" --mode local\n# 출력: [로컬 지식 그래프 기반 답변]\n\n# 시스템 정보 확인\npython main.py info\n# 출력: [설정 정보 테이블]\n```\n\n### 다양한 질문 유형 예시\n\n**기본 정보 질의:**\n```\n질문: \"이 문서에서 다루는 주요 주제는 무엇인가요?\"\n질문: \"프로젝트의 목적과 목표를 설명해주세요\"\n질문: \"주요 기능들을 나열해주세요\"\n```\n\n**구체적 정보 검색:**\n```\n질문: \"설치 방법을 단계별로 알려주세요\"\n질문: \"오류 해결 방법을 찾아주세요\"\n질문: \"성능 최적화 팁이 있나요?\"\n```\n\n**비교 및 분석:**\n```\n질문: \"Ollama와 OpenAI의 장단점을 비교해주세요\"\n질문: \"어떤 LLM 서비스를 선택해야 할까요?\"\n질문: \"각 질의 모드의 차이점은 무엇인가요?\"\n```\n\n**맥락 기반 대화:**\n```\n질문: \"LightRAG의 특징을 설명해주세요\"\n답변: [LightRAG 특징 설명]\n질문: \"그 중에서 가장 중요한 특징은 무엇인가요?\"\n답변: [이전 답변을 참고한 구체적 설명]\n```\n\n### 문제 상황별 대처법\n\n**새 문서 추가했을 때:**\n```bash\n# 방법 1: 대화형 모드에서\n질문: /reload\n\n# 방법 2: CLI에서\npython main.py load\n```\n\n**전체 재처리가 필요할 때:**\n```bash\n# 방법 1: 대화형 모드에서\n질문: /reload-all\n\n# 방법 2: CLI에서\npython main.py load --force-reload\n```\n\n**임베딩 상태 초기화:**\n```bash\n# 대화형 모드에서\n질문: /reset\n질문: y  # 확인\n\n# 그 다음 재로드\n질문: /reload-all\n```\n\n**시스템 문제 진단:**\n```bash\n# 1. 시스템 테스트\npython main.py test\n\n# 2. 설정 확인\npython main.py info\n\n# 3. 로그 확인\ntail -f logs/app.log\n```\n\n## 📁 프로젝트 구조\n\n```\nanything-rag/\n├── 📂 input/              # 📄 문서 입력 폴더 (여기에 파일을 넣으세요)\n├── 📂 rag_storage/        # 🗄️ LightRAG 인덱스 및 지식 그래프 저장소\n├── 📂 logs/               # 📋 로그 파일들\n├── 📂 backup/             # 💾 백업 파일들\n├── 📂 src/\n│   ├── 📂 Config/         # ⚙️ 설정 관리\n│   │   ├── __init__.py\n│   │   └── config.py      # 환경 변수 및 설정 클래스\n│   ├── 📂 Service/        # 🔧 핵심 서비스 로직\n│   │   ├── __init__.py\n│   │   ├── document_loader.py    # 문서 로딩 및 변경 감지\n│   │   ├── llm_service.py        # LLM 서비스 추상화\n│   │   └── rag_service.py        # RAG 메인 서비스\n│   ├── 📂 Utils/          # 🛠️ 유틸리티 함수들\n│   │   ├── __init__.py\n│   │   └── file_tracker.py       # 파일 변경 추적\n│   └── 📂 test/           # 🧪 테스트 코드\n│       ├── __init__.py\n│       ├── test_document_loader.py\n│       ├── test_llm_service.py\n│       └── test_rag_service.py\n├── 📄 .env                # 🔐 환경 설정 (사용자가 생성)\n├── 📄 .env.example        # 📋 환경 설정 예시\n├── 📄 requirements.txt    # 📦 Python 패키지 의존성\n├── 📄 main.py            # 🚪 메인 진입점 (CLI)\n├── 📄 run.bat            # 🪟 Windows 실행 스크립트\n├── 📄 run.sh             # 🐧 Linux/Mac 실행 스크립트\n└── 📄 README.md          # 📚 이 파일\n```\n\n## 🔧 문제 해결\n\n### Ollama 관련\n\n**연결 실패 시:**\n1. Ollama 설치: https://ollama.ai\n2. 모델 다운로드: `ollama pull gemma3:1b`\n3. 임베딩 모델: `ollama pull bge-m3:latest`\n4. 서비스 실행 확인: `ollama list`\n\n**모델 추천:**\n- 경량: `gemma3:1b` (1B 파라미터)\n- 균형: `llama3.2:3b` (3B 파라미터) \n- 고성능: `llama3.1:8b` (8B 파라미터)\n\n### 패키지 설치 문제\n\n```bash\n# 패키지 캐시 클리어 후 재설치\npip install --upgrade pip\npip install -r requirements.txt --no-cache-dir\n\n# Windows에서 특정 패키지 실패 시\npip install --upgrade setuptools wheel\n```\n\n### 문서 처리 문제\n\n**인코딩 오류:**\n- 한국어 문서는 UTF-8로 저장\n- 자동 인코딩 감지 실패 시 `ENCODING=utf-8` 설정\n\n**지원되지 않는 파일:**\n- `SUPPORTED_EXTENSIONS` 환경 변수로 확장자 추가 가능\n- 예: `SUPPORTED_EXTENSIONS=.txt,.pdf,.docx,.md,.xlsx,.html`\n\n**메모리 부족:**\n- `LIGHTRAG_CHUNK_SIZE` 값을 줄이기 (기본값: 1200)\n- `MAX_FILE_SIZE_MB` 값으로 파일 크기 제한 (기본값: 50MB)\n\n### 성능 최적화\n\n**임베딩 속도 향상:**\n- Ollama 사용 시 GPU 가속 활성화\n- `LIGHTRAG_CHUNK_SIZE` 조정으로 처리량 최적화\n\n**메모리 사용량 감소:**\n- `LIGHTRAG_CHUNK_OVERLAP` 값 감소\n- 불필요한 파일 `backup/` 폴더로 이동\n\n## 📊 주요 의존성\n\n- **lightrag-hku**: 핵심 RAG 엔진\n- **typer**: CLI 인터페이스\n- **rich**: 터미널 UI\n- **loguru**: 로깅 시스템\n- **pydantic**: 설정 관리\n- **ollama/openai**: LLM 서비스 클라이언트\n\n## 🔍 시스템 테스트\n\n시스템이 올바르게 설정되었는지 확인:\n\n```bash\npython main.py test\n```\n\n이 명령어는 다음을 검증합니다:\n- LLM 서비스 연결\n- 임베딩 서비스 동작\n- RAG 서비스 초기화\n- 문서 로드 기능\n\n## 🤝 기여하기\n\n1. 이슈 리포트: 버그나 개선사항을 GitHub Issues에 등록\n2. 코드 기여: Pull Request를 통한 기능 추가나 버그 수정\n3. 문서 개선: README나 코드 주석 개선\n\n## 📄 라이선스\n\nMIT License\n\n## 🙏 기반 프로젝트\n\n- [LightRAG](https://github.com/HKUDS/LightRAG) - Simple and Fast Retrieval-Augmented Generation\n- [Typer](https://typer.tiangolo.com/) - Modern CLI framework\n- [Rich](https://rich.readthedocs.io/) - Rich text and beautiful formatting\n\n---\n\n**Glossary (용어 설명)**\n- **RAG**: 검색 증강 생성. 문서에서 관련 정보를 찾아 더 정확한 답변을 생성하는 AI 기술\n- **임베딩**: 텍스트를 숫자 벡터로 변환하여 컴퓨터가 의미를 이해할 수 있게 하는 과정\n- **청크**: 긴 문서를 작은 단위로 나눈 조각. 검색과 처리를 효율적으로 하기 위함\n- **LLM**: Large Language Model. GPT, Claude 같은 대규모 언어 모델\n- **지식 그래프**: 정보들 간의 관계를 네트워크 형태로 표현한 데이터 구조\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fanything-rag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcskwork%2Fanything-rag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fanything-rag/lists"}