WeKnora: 문서 이해·검색·RAG 프레임워크 한눈에 정리
핵심 요약
WeKnora는 복잡한 문서를 이해하고, 의미 기반으로 검색한 뒤, RAG 방식으로 답변을 만들어주는 LLM 기반 프레임워크다. 에이전트 모드, 지식 그래프, 웹 검색, MCP 연동 등 확장 기능이 풍부하며, 로컬/도커 기반으로 손쉽게 배포·개발할 수 있다. (tencent)
WeKnora가 무엇인지 한 줄로 이해하기
WeKnora는 PDF·Word·이미지 등 다양한 문서를 읽어 구조화하고, 이를 벡터/키워드/그래프 기반으로 검색한 뒤, LLM이 문맥을 활용해 답변을 생성하는 "문서용 ChatGPT 플랫폼"에 가깝다.
기업 내부 문서 검색, FAQ 봇, 연구 논문 탐색, 법률 문서 분석 등 "문서를 잘 읽고 이해해야 하는" 모든 상황에서 쓸 수 있도록 설계된 범용 RAG/에이전트 프레임워크라고 이해하면 된다.
전체 아키텍처 개념 이해하기
WeKnora는 크게 네 단계의 파이프라인으로 동작한다: 문서 파싱, 임베딩 및 색인, 검색, LLM 추론이다.
문서 파싱 단계에서는 PDF·Word·텍스트·이미지(OCR/캡션)를 읽어 단락, 제목, 표 등 구조를 최대한 보존한 "통일된 표현"으로 바꾼다.
임베딩 단계에서는 선택한 임베딩 모델(BGE, GTE, 로컬 모델 등)로 문서를 벡터화하고, pgvector나 Elasticsearch 같은 벡터DB·검색엔진에 저장한다.
검색 단계에서는 BM25(키워드), 벡터 검색(의미), GraphRAG(지식 그래프) 등을 조합해 최적의 관련 문맥을 찾는다.
마지막으로 LLM 추론 단계에서 Qwen, DeepSeek, Ollama 등 설정된 모델이 검색된 문맥을 기반으로 답변을 생성하며, 필요 시 에이전트가 도구를 호출해 여러 번에 걸쳐 추론을 개선한다.
위 다이어그램은 각 모듈(문서 파서, 벡터 인덱스, 검색 엔진, LLM, 웹 UI 등)이 어떻게 연결되는지 한눈에 보여준다.
핵심 기능 한 번에 훑어보기
WeKnora의 기능은 크게 네 축으로 볼 수 있다: 지식베이스 관리, 검색·생성(RAG), 에이전트 모드, 운영·개발 편의성이다.
지식베이스는 FAQ형과 문서형 두 종류를 지원하며, 폴더/URL/드래그·드롭/온라인 입력으로 데이터를 넣고 태그로 관리할 수 있다.
검색은 BM25 키워드 검색, 벡터 기반 의미 검색, 그래프 기반 검색(그래프RAG)을 필요에 따라 조합해 쓸 수 있어 "빠른 키워드 검색"부터 "정밀 의미 검색"까지 모두 커버한다.
에이전트 모드는 ReACT 패턴을 사용해 지식베이스 조회, 웹 검색, MCP 도구를 순차적으로 호출하며 여러 번 생각·수정하는 방식으로 리포트나 종합 답변을 만들어낸다.
운영 측면에서는 멀티 테넌트 모델 설정, MQ 기반 비동기 작업, 자동 DB 마이그레이션, E2E 평가 도구 등 실제 서비스 운영에 필요한 기능들이 들어 있다.
에이전트 모드 vs 일반 모드 이해하기
일반 모드는 "질문 → 문서 검색 → 답변 생성"이라는 단순 RAG 흐름으로, FAQ 챗봇이나 문서 질의응답에 적합하다.
에이전트 모드는 그 위에 "도구 호출"과 "반복적 추론"이 추가된 형태로, ReACT 전략을 사용해 생각(Reasoning)과 행동(Action)을 번갈아 수행한다.
예를 들어 "우리 회사 제품 A와 경쟁사 B를 비교해서 장단점을 표로 정리해줘" 같은 질문이 들어오면, 에이전트는 내부 지식베이스 검색 후 부족한 정보는 웹 검색 또는 MCP 도구로 보완한 뒤, 최종 비교 리포트를 작성한다.
이 과정에서 에이전트는 여러 지식베이스를 동시에 검색할 수 있고, DuckDuckGo 기반 웹 검색이나 MCP로 확장된 외부 시스템(예: 사내 API, 분석 도구)을 연쇄적으로 사용한다.
지식베이스 타입과 문서 처리 방식
WeKnora는 지식베이스를 크게 FAQ형과 문서형으로 나눈다.
FAQ형은 "질문–답변" 쌍을 직접 관리하는 방식으로, 고객센터 고정 질문, 자주 묻는 질문 모음 등에 유용하다.
문서형은 매뉴얼, 정책 문서, 논문, 보고서처럼 긴 문서를 쪼개어 구조화한 뒤 색인하고, 질문 시 관련 문단을 찾아 답변에 활용한다.
입력 방식은 폴더 단위 업로드, 개별 파일 드래그·드롭, URL 크롤링, 웹 UI에서 직접 텍스트 입력 등 다양하게 제공되며, 이미지 안의 텍스트도 OCR·캡션을 통해 추출할 수 있다.
지식베이스에는 태그를 붙여 관리할 수 있고, FAQ 항목은 CSV로 내보내거나 태그 추천·일괄 처리 기능을 이용해 대량 관리가 가능하다.
검색 전략과 모델 구성의 유연성
WeKnora에서는 검색 전략과 모델 구성을 세밀하게 조절할 수 있다.
검색 측면에서는 BM25 기반 키워드 검색, 벡터 기반 의미 검색, 지식 그래프를 활용한 GraphRAG 방식을 조합해 "정확한 키워드 매칭"과 "넓은 의미 검색"을 동시에 추구한다.
임베딩 모델은 로컬 모델(예: Ollama), BGE/GTE API, 그 외 벤더 API를 사용할 수 있어, 온프레미스 환경부터 클라우드까지 상황에 맞춰 선택할 수 있다.
LLM은 Qwen, DeepSeek 등 다양한 모델을 지원하며, "생각 모드(Chain-of-thought)"와 "일반 모드"를 선택해 성능·비용·속도 간 균형을 맞출 수 있다.
지식베이스·대화 전략 설정에서 "에이전트 모델", "일반 대화 모델", "검색 임계값", "프롬프트 템플릿"을 각각 설정해, 같은 시스템 안에서도 다양한 응답 스타일과 비용 정책을 적용할 수 있다.
보안과 배포 전략
WeKnora는 v0.1.3부터 로그인 인증 기능을 기본으로 포함하고 있으며, 운영 환경에서는 내부망·사설망 배포를 권장한다.
실서비스에서는 방화벽, 접근 제어, 정기 업데이트를 통해 정보 유출 위험을 최소화해야 하고, 특히 API 및 관리자 UI를 인터넷에 그대로 노출하지 않는 것이 중요하다.
배포는 Docker와 Docker Compose를 기준으로 하며, 최소 코어 서비스만 띄우는 구성부터 Neo4j(지식 그래프), Minio(파일 저장), Jaeger(추적) 등을 포함한 풀 옵션까지 프로파일 조합으로 쉽게 구성할 수 있다.
예를 들어 테스트 환경에서는 docker compose up -d만으로 핵심 기능을 확인할 수 있고, 고급 기능이 필요하면 --profile neo4j, --profile minio 등을 필요에 따라 추가한다.
설치 및 실행 기본 흐름
로컬에서 WeKnora를 시작하는 흐름은 다음과 같이 정리할 수 있다.
먼저 Git으로 저장소를 클론하고 프로젝트 디렉터리로 이동한다.
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora이후 .env.example을 복사해 .env를 만든 뒤, 주석에 따라 필요한 환경 변수를 채운다.
cp .env.example .env
# .env 내용을 편집해서 DB, 모델, 포트 등 설정그 다음 ./scripts/start_all.sh 또는 make start-all로 서비스를 올린다.
./scripts/start_all.sh
# 또는
make start-all필요하다면 Ollama를 별도로 기동해 로컬 LLM을 사용할 수 있다.
ollama serve > /dev/null 2>&1 &서비스가 올라가면 브라우저에서 http://localhost로 접속해 회원가입·로그인을 하고, 지식베이스를 생성해 초기 설정을 진행한다.
지식 그래프와 고급 검색
WeKnora의 문서 지식 그래프 기능은 긴 문서 속의 문단·섹션·개념을 노드로 만들고 이들 사이의 관계를 엣지로 표현하는 방식이다.
예를 들어 제품 매뉴얼의 "기능 A 소개", "기능 A 설정 방법", "기능 A 문제 해결" 섹션을 서로 연결해두면, 사용자가 "기능 A가 안 된다"고 질문했을 때 단순히 해당 문장뿐 아니라 관련된 설정·문제 해결 섹션까지 함께 검색해 올 수 있다.
이 기능은 Neo4j 프로파일을 활성화해 사용할 수 있으며, 설정 방법과 사용 전략은 별도의 지식 그래프 문서에서 자세히 설명된다.
검색 관점에서 지식 그래프는 "연관 문맥을 넓게 끌어오는" 역할을 하므로, FAQ 중심 서비스보다 복잡한 기술 문서·규정·논문 등에서 특히 효과가 크다.
MCP·웹 검색·WeChat 연동으로 확장하기
WeKnora는 자체 기능뿐 아니라 외부 도구와의 연동을 통해 에이전트 능력을 크게 확장할 수 있다.
웹 검색은 DuckDuckGo를 기본으로 제공하며, 검색 엔진을 교체할 수 있는 구조라 회사 내부 검색 시스템이나 다른 공용 검색 엔진으로 바꾸는 것도 가능하다.
MCP 연동을 통해서는 "weknora-mcp-server"를 설치하고 MCP 클라이언트 설정에 서버 정보를 추가하면, 외부 도구(예: 코드 실행, 데이터베이스 조회, 사내 API 호출)를 에이전트가 호출할 수 있다.
{
"mcpServers": {
"weknora": {
"command": "python",
"args": ["path/to/WeKnora/mcp-server/run_server.py"],
"env": {
"WEKNORA_API_KEY": "x-api-key 값",
"WEKNORA_BASE_URL": "http(s)://your-weknora-address/api/v1"
}
}
}
}또한 WeKnora는 "WeChat 대화 오픈 플랫폼"의 핵심 엔진으로 사용되고 있어, WeChat 공식 계정·미니프로그램에 지식 기반 챗봇을 구축하려는 경우 별도의 코드 없이 지식 업로드만으로 서비스를 구성할 수 있다.
개발 환경과 디렉터리 구조 이해하기
개발자는 "빠른 개발 모드"를 활용하면 매번 도커 이미지를 다시 빌드하지 않고도 서버·프론트엔드 코드를 빠르게 수정·테스트할 수 있다.
추천되는 방식은 make dev-start로 인프라를 띄운 뒤, 다른 터미널에서 make dev-app, make dev-frontend로 백엔드와 프론트엔드를 각각 실행하는 것이다.
make dev-start # 인프라 (DB, MQ 등)
make dev-app # Go 백엔드
make dev-frontend # Vue 프론트엔드프로젝트 구조는 역할별로 잘 분리되어 있다. 예를 들어 cmd/는 메인 진입점, internal/은 핵심 비즈니스 로직, docreader/는 문서 파서, frontend/는 웹 UI, mcp-server/는 MCP 서버, migrations/는 DB 마이그레이션 스크립트를 담고 있다.
Go 코드 스타일은 표준 Go 스타일과 Code Review Comments를 따르며, 커밋 메시지는 Conventional Commits 규칙(feat:, fix:, docs: 등)을 권장한다.
인사이트
WeKnora는 "바로 가져다 쓰는 제품"이자 동시에 "마음껏 뜯어고칠 수 있는 프레임워크"라는 두 얼굴을 가진 도구다.
단순히 도커로 올려서 지식베이스를 만들어 쓰기만 해도 강력한 RAG 챗봇을 빠르게 만들 수 있고, 더 나아가 에이전트, MCP, 지식 그래프, 커스텀 모델을 조합해 자사 도메인에 특화된 AI 어시스턴트를 구축할 수 있다.
실제 도입을 고민한다면, 먼저 작은 범위(예: 한 팀의 FAQ, 한 제품의 매뉴얼)로 시작해 검색 품질·프롬프트·대화 전략을 튜닝한 뒤, 점차 조직 전체 지식으로 확장하는 접근을 추천한다.