WeKnora: 텐센트가 공개한 LLM 기반 오픈소스 심층 문서 이해 및 RAG 프레임워크

9bow · 12월 22, 2025, 9:30오후

WeKnora 소개

WeKnora는 텐센트(Tencent) 위챗(WeChat) 팀이 공개한 오픈소스 프로젝트로, LLM(대규모 언어 모델)을 활용한 심층 문서 이해 및 의미론적 검색 프레임워크입니다. RAG(검색 증강 생성) 패러다임을 기반으로 구축된 이 시스템은 복잡하고 이질적인 문서들을 처리하여 문맥을 정확히 파악하고, 이를 바탕으로 고품질의 답변을 생성하도록 설계되었습니다.

이 프로젝트는 단순한 텍스트 매칭을 넘어, 문서를 깊이 있게 이해하고 외부 도구와 연동하여 추론할 수 있는 능력을 갖추고 있습니다. 특히 v0.2.0 업데이트를 통해 에이전트(Agent) 기능을 강화하여, ReACT(Reasoning + Acting) 방식을 통해 스스로 사고하고 웹 검색이나 MCP 도구를 사용하여 문제를 해결하는 지능형 시스템으로 진화했습니다. 기업 내부의 방대한 비정형 데이터를 구조화하고, 데이터 주권(Data Sovereignty)을 보장하는 로컬 배포 환경을 지원하는 것이 특징입니다.

초기 단계의 RAG 시스템은 사용자의 질문과 가장 유사한 문서 조각(Chunk)을 벡터 데이터베이스에서 찾아 단순히 LLM에 전달하는 방식에 그쳤습니다. 이 방식은 문서의 복잡한 구조나 표, 이미지 내 텍스트를 제대로 이해하지 못하거나, 단편적인 정보만을 조합하여 답변의 깊이가 부족한 경우가 많았습니다.

반면 WeKnora는 ReACT 에이전트 모드와 GraphRAG 기술을 도입하여 차별화를 둡니다. 에이전트 모드에서는 모델이 질문을 분석하여 필요한 도구(웹 검색, 지식 베이스 조회 등)를 스스로 선택하고, 반복적인 사고 과정을 통해 정보를 종합합니다. 또한, 단순 벡터 검색뿐만 아니라 지식 그래프(Knowledge Graph)와 키워드 검색(BM25)을 결합한 하이브리드 검색을 통해 정보의 연관성과 정확성을 획기적으로 높였습니다.

WeKnora 구조

WeKnora는 현대적인 모듈형 디자인을 채택하여 완전한 문서 이해 및 검색 파이프라인을 구축했습니다. 시스템은 크게 문서 파싱, 벡터 처리, 검색 엔진, 그리고 대규모 모델 추론이라는 핵심 모듈로 구성되며, 각 컴포넌트는 유연하게 설정하고 확장할 수 있습니다.

문서 파싱 (Document Parsing): 다양한 포맷의 문서를 읽어 들여 의미 있는 단위로 분해하고 구조화합니다.
벡터 처리 (Vector Processing): 텍스트를 임베딩 벡터로 변환하여 저장합니다.
검색 엔진 (Retrieval Engine): 사용자의 질의에 맞춰 가장 적합한 정보를 찾아냅니다.
LLM 추론 (LLM Inference): 검색된 정보를 바탕으로 최종 답변을 생성합니다.

WeKnora의 주요 기능

주요 기능

에이전트 모드 (Agent Mode): ReACT 에이전트 모드를 지원하여 내장 도구, MCP 도구, 웹 검색 도구를 사용하여 외부 서비스에 접근할 수 있습니다. 이를 통해 여러 번의 반복(iteration)과 성찰(reflection) 과정을 거쳐 포괄적인 요약 보고서를 제공합니다.
정밀한 문서 이해: PDF, Word 문서, 이미지 등 다양한 소스에서 구조화된 콘텐츠를 추출하여 통일된 의미론적 뷰(semantic view)로 변환합니다. 이미지 내 텍스트 추출(OCR)도 지원합니다.
지능형 추론: LLM을 활용하여 문서의 문맥과 사용자의 의도를 파악, 정확한 질의응답(Q&A)과 멀티턴 대화를 수행합니다.
멀티 타입 지식 베이스: FAQ형 지식 베이스와 문서형 지식 베이스를 모두 지원합니다. 폴더 가져오기, URL 가져오기, 태그 관리 및 온라인 항목 입력 기능을 제공합니다.
유연한 확장성: 파싱, 임베딩부터 검색, 생성에 이르는 모든 컴포넌트가 결합도가 낮게(decoupled) 설계되어 있어 커스터마이징이 용이합니다.
효율적인 검색: 키워드, 벡터, 지식 그래프를 결합한 하이브리드 검색 전략을 사용하며, 여러 지식 베이스에 걸친 교차 검색(cross-knowledge base retrieval)을 지원합니다.
웹 검색 연동: DuckDuckGo 검색 엔진이 내장되어 있으며, 확장 가능한 웹 검색 엔진을 지원합니다.
MCP 도구 통합: MCP(Model Context Protocol)를 통해 에이전트 기능을 확장할 수 있습니다. uvx, npx 런처가 내장되어 있으며 다양한 전송 방식을 지원합니다.
대화 전략 제어: 에이전트 모델, 일반 모드 모델, 검색 임계값, 프롬프트 등을 설정하여 멀티턴 대화의 동작을 정밀하게 제어할 수 있습니다.
사용자 친화적: 기술적 장벽 없는 직관적인 웹 인터페이스와 표준화된 API를 제공합니다.
보안 및 통제: 로컬 배포 및 프라이빗 클라우드를 지원하여 데이터 주권을 완벽하게 보장합니다.

기능 상세 매트릭스 (Feature Matrix)

WeKnora가 제공하는 상세 기술 스택과 지원 범위는 다음과 같습니다.

모듈	지원 내용	상세 설명
Agent Mode	ReACT Agent Mode	내장 도구, MCP 도구, 웹 검색을 활용하며, 지식 베이스 교차 검색 및 다중 반복 사고(iteration) 지원
Knowledge Base Types	FAQ / Document	FAQ 및 문서형 지식 베이스 생성 지원. 폴더/URL 가져오기, 태그 관리, 온라인 입력 기능 포함
Document Formats	PDF / Word / Txt / Markdown / Images	구조화/비구조화 문서 지원. 이미지 내 텍스트 추출(OCR/Caption) 포함
Model Management	중앙 집중식 설정, 모델 공유	지식 베이스 설정에서 모델 선택 가능, 멀티 테넌트 환경에서 내장 모델 공유 지원
Embedding Models	로컬 모델, BGE / GTE API 등	커스터마이징 가능한 임베딩 모델, 로컬 배포 및 클라우드 벡터 생성 API 호환
Vector DB Integration	PostgreSQL (pgvector), Elasticsearch	주류 벡터 인덱스 백엔드 지원, 검색 시나리오에 따라 유연한 전환 가능
Retrieval Strategies	BM25 / Dense Retrieval / GraphRAG	희소/밀집 검색 및 지식 그래프 강화 검색 지원. 검색-재순위화-생성(retrieve-rerank-generate) 파이프라인 커스텀 가능
LLM Integration	Qwen, DeepSeek 등 (Thinking 모드 지원)	Ollama 등을 통한 로컬 모델 또는 외부 API 서비스와 호환되며 유연한 추론 설정 가능
Conversation Strategy	모델, 임계값, 프롬프트 설정	에이전트/일반 모델 설정, 검색 임계값 조정, 온라인 프롬프트 설정 및 멀티턴 대화 정밀 제어
Web Search	확장형 검색 엔진, DuckDuckGo	DuckDuckGo 내장 및 확장 가능한 웹 검색 엔진 지원
MCP Tools	uvx, npx 런처, Stdio/HTTP/SSE	MCP를 통한 에이전트 기능 확장. 3가지 전송 방식(Stdio, HTTP Streamable, SSE) 및 런처 지원
QA Capabilities	문맥 인식, 멀티턴 대화, 프롬프트 템플릿	복잡한 의미 모델링, 지시어 제어, CoT(Chain-of-Thought) Q&A 지원. 프롬프트 및 컨텍스트 윈도우 설정 가능
E2E Testing	검색+생성 시각화 및 지표 평가	리콜 적중률, 답변 커버리지, BLEU/ROUGE 등의 지표를 평가하는 E2E 테스트 도구 제공
Deployment Modes	로컬 배포 / Docker 이미지	프라이빗/오프라인 배포 및 유연한 운영 요구사항 충족. 빠른 개발 모드 지원
User Interfaces	Web UI + RESTful API	대화형 인터페이스 및 표준 API 엔드포인트. 에이전트/일반 모드 전환 및 도구 호출 과정 시각화
Task Management	MQ 비동기 작업, DB 자동 마이그레이션	MQ 기반 비동기 작업 상태 관리, 버전 업그레이드 시 DB 스키마 및 데이터 자동 마이그레이션 지원

활용 시나리오 (Application Scenarios)

시나리오	활용 예시	핵심 가치
기업 지식 관리	사내 문서 검색, 정책 Q&A, 운영 매뉴얼 검색	지식 발견 효율성 증대, 교육 비용 절감
학술 연구 분석	논문 검색, 연구 보고서 분석, 학술 자료 정리	문헌 검토 가속화, 연구 의사결정 보조
제품 기술 지원	제품 매뉴얼 Q&A, 기술 문서 검색, 문제 해결(Troubleshooting)	고객 서비스 품질 향상, 지원 부서 부담 완화
법률 및 규정 준수	계약 조항 검색, 규제 정책 검색, 판례 분석	규정 준수 효율성 증대, 법적 리스크 감소
의료 지식 보조	의료 문헌 검색, 치료 가이드라인 검색, 사례 분석	임상 의사결정 지원, 진단 품질 향상

WeKnora 설치 및 사용

WeKnora는 복잡한 의존성 관리를 최소화하고 빠른 배포를 돕기 위해 Docker 및 Docker Compose 기반의 설치를 권장합니다. 로컬 환경에서 개인적인 지식 베이스를 구축하거나 테스트해 볼 수 있는 가장 빠른 방법입니다.

따라서 WeKnora를 설치해서 사용하기 위해서는 먼저 소스 코드 복제를 위한 Git과 함께 컨테이너 실행을 위한 Docker 및 Docker Compose가 설치되어 있어야 합니다. 또한, 로컬 GPU를 사용하여 모델을 구동할 경우에는 Nvidia Container Toolkit도 필요합니다.

설치는 다음의 단계들로 진행합니다:

WeKnora 설치 및 기본 설정

GitHub에서 소스 코드를 로컬 환경으로 내려받습니다.

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora

프로젝트 루트 디렉터리에 있는 예제 설정 파일을 복사하여 실사용 환경 설정 파일(.env)을 생성합니다.

cp .env.example .env

이후, 복사한 .env 파일을 열어 LLM_API_KEY, POSTGRES_PASSWORD 등 주요 보안 키와 데이터베이스 설정을 본인의 환경에 맞게 수정합니다. 만약 외부 LLM(DeepSeek, OpenAI 등)을 사용할 경우 해당 API 키를 입력하고, 로컬 LLM(Ollama 등)을 사용할 경우 연결 주소를 설정합니다.

이제 다음과 같은 명령어로 Docker Compose를 사용하여 백엔드, 프론트엔드, 벡터 DB 등 필요한 모든 서비스를 한 번에 실행합니다.

docker-compose up -d

최초 실행 시에는 필요한 Docker 이미지를 다운로드(Pull)하고 빌드하는 과정이 있어 시간이 다소 소요될 수 있습니다. 실행이 완료되면 브라우저를 열고 http://localhost:3000 (기본 설정인 경우)으로 접속하여 웹 UI를 확인할 수 있습니다. 이 때, 포트 번호는 docker-compose.yml 설정에 따라 다를 수 있으니 확인이 필요합니다.

기본 사용 가이드

1단계: 로그인 및 초기 설정: Weknora v0.1.3 버전부터 보안을 위해 로그인 기능이 도입되었습니다. 초기 계정 정보는 로그를 확인하거나 기본 설정 문서를 참고하여 로그인합니다.

2단계: 지식 베이스(Knowledge Base) 생성: 다음과 같은 단계를 통해 KB를 생성합니다:

대시보드에서 [Knowledge Base] 메뉴로 이동하여 'Create' 버튼을 클릭합니다.
유형 선택: 일반 문서(Document) 기반인지 FAQ 기반인지 선택합니다.
데이터 업로드: PDF, Word 파일을 드래그 앤 드롭하거나, 폴더 경로 또는 웹 URL을 입력하여 데이터를 수집(Import)합니다.
시스템이 자동으로 문서를 파싱하고 벡터 인덱싱을 수행합니다.

3단계: 대화 및 에이전트 모드 활용

[Chat] 메뉴로 이동하여 대화를 시작합니다.
에이전트 모드(Agent Mode) 활성화: 단순 답변이 아닌, 웹 검색이나 도구 사용이 필요한 경우 인터페이스 상단의 'Agent Mode' 스위치를 켭니다.
질문을 입력하면 WeKnora가 지식 베이스를 검색하거나, 필요시 DuckDuckGo 등을 통해 외부 정보를 검색하여 종합적인 답변을 생성합니다.

4단계: MCP 도구 확장 (심화)

필요한 경우 설정 메뉴에서 MCP(Model Context Protocol) 서버를 연동하여, 에이전트가 사용할 수 있는 커스텀 도구(예: 사내 API 호출, 특정 데이터 조회 도구)를 추가할 수 있습니다.

라이선스

WeKnora 프로젝트는 MIT License로 공개 및 배포 되고 있습니다. 하지만, WeKnora 프로젝트는 다수의 오픈소스 서드파티 컴포넌트(PaddlePaddle, gRPC, NumPy, Pandas, Vue.js 관련 라이브러리 등)를 함께 포함하고 있습니다. 이들 컴포넌트는 Apache-2.0, BSD, Python-2.0, MPL-2.0, CC-BY-4.0, ISC 등 각기 다른 라이선스 정책을 따릅니다. 따라서 재배포 또는 상업적 사용 전 관련 라이선스를 확인하고 준수하셔야 합니다.

WeKnora 홈페이지 (중국어)

WeKnora 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~