Tencent 오픈 소스 · WeKnora v0.8.0 · 공식 문서
오픈 소스 지식 베이스 질의응답 시스템
WeKnora는 PDF, Word, 웹페이지와 Feishu / Notion / Yuque 등의 자료를 지식 베이스로 모아 검색 증강 질의응답을 제공하고, 답변에 추적 가능한 출처를 표시해요. 기본 질의응답뿐 아니라 Wiki 자동 편찬, ReAct 에이전트와 MCP 양방향 연동, 지식 그래프 강화 검색을 제공해요. 팀을 위한 공간별 격리, 4단계 RBAC, 범위가 지정된 API Key와 감사 로그도 지원해요. 완전한 프라이빗 배포가 가능하며 모델을 모두 로컬 추론으로 교체할 수 있어요.
이 문서는 배포와 설정, 기능 설명, 리소스별 API 레퍼런스, 커스텀 개발을 위한 확장 지점을 다뤄요.
파일, 웹페이지, 오디오, 이미지로 들어온 자료를 통합 파싱한 뒤 벡터, 키워드, Wiki, 지식 그래프 네 가지 색인에 병렬로 저장해요. 같은 지식 베이스와 에이전트를 10가지 클라이언트로 이용하므로 접근 경로가 바뀌어도 시스템을 바꿀 필요가 없어요.
PDF 한 개에서 출처 있는 답변까지
질의응답 품질이 낮다면 모델보다 처리 과정에 문제가 있는 경우가 많아요. 스캔본에서 글자를 읽지 못하거나, 표가 잘리거나, 검색한 문단이 질문과 맞지 않을 수 있어요. 아래 네 단계는 각각 이런 문제를 다루며 필요에 따라 구현을 교체할 수 있어요.
- 01
문서 이해
스캔본은 OCR로 읽고, 삽화는 비전 모델로 설명하고, 오디오는 음성 모델로 전사하며, Excel 병합 셀은 자동으로 채워요. 독립적인 docreader 서비스가 PDF, Office, 웹페이지, 이미지와 오디오를 단순한 텍스트가 아닌 레이아웃을 갖춘 텍스트로 복원해요.
- 02
지식 분할
문서 특성에 맞춰 제목, 휴리스틱, 재귀 세 가지 분할 전략 중 하나를 자동으로 선택해요. 부모·자식 청크를 사용해 작은 청크를 검색하되 모델에는 전체 맥락을 전달해요. 같은 문서를 벡터, 키워드, Wiki, 지식 그래프 네 가지 색인에 동시에 저장할 수 있어요.
- 03
정확한 근거 검색
의도를 파악하고 질의를 재작성한 뒤 벡터와 BM25로 후보를 병렬 검색해요. RRF로 결과를 합치고 리랭킹 모델로 순서를 정해요. 지식 그래프를 켜면 개체 관계 근거를 추가해 “A와 B는 어떤 관계인가요?” 같은 질문에도 답할 수 있어요.
- 04
검증 가능한 답변
일반적인 질문은 한 번의 검색으로 바로 답변을 생성해요. 복잡한 작업은 ReAct 에이전트가 검색 횟수, 호출할 도구, 데이터 분석 실행 여부를 스스로 결정해요. 답변을 스트리밍으로 전달하고 문단마다 출처를 표시하므로 원문을 열어 확인할 수 있어요.
기본 검색 질의응답을 넘어서는 기능
아래 기능은 WeKnora가 집중하는 영역으로, 기술을 선택할 때 비교 기준으로 삼을 수 있어요.
Wiki 모드
모델이 문서에서 개체와 개념을 추출해 서로 연결되고 출처가 표시된 페이지를 생성해요. 이를 목차 트리와 관계 그래프로 자동 구성해요. 자료가 흩어져 있고 전체 색인이 없을 때 유용해요.
유지보수성청크 단위 편집과 버전 관리
파싱 결과를 청크 단위로 직접 수정하고 저장하면 색인을 즉시 다시 만들어요. 수정할 때마다 이전 버전을 보관하며 롤백할 수 있어요. Wiki 페이지도 버전 이력을 제공하고 파이프라인, 에이전트, 수동 편집을 구분해요.
연결여러 채널 통합 연결
하나의 에이전트를 10개 IM 플랫폼, 자체 사이트의 임베드 위젯, 브라우저 확장 프로그램에 동시에 배포할 수 있어요. 세션, 권한, 지식 범위는 같은 설정을 사용해요.
도구 생태계MCP 양방향 연동
클라이언트로 외부 MCP 서비스에 연결하고 OAuth 인증, 도구 활성화·비활성화, 사람의 승인을 지원해요. 동시에 MCP Server로 외부에 검색 기능을 제공할 수 있어요.
기업 배포공간별 격리와 감사
작업 공간 단위 데이터 격리와 4단계 역할 체계를 제공해요. API Key는 기능과 지식 베이스 범위로 제한할 수 있어요. 작업을 감사 로그에 기록하고 백그라운드 작업 큐 대시보드와 질의응답 과정의 Langfuse 추적을 지원해요.
아키텍처교체 가능한 아키텍처
파싱 엔진, 청크 분할 전략, 검색 엔진, 모델 제공업체, 웹 검색 엔진과 저장소 백엔드를 모두 레지스트리로 연결해 설정에 따라 교체할 수 있어요. 지식 베이스마다 다른 벡터 데이터베이스와 저장소 인스턴스를 연결할 수 있어요.
검색지식 그래프 강화 검색
저장할 때 모델이 개체와 관계를 추출해 그래프 데이터베이스에 넣고, 질문할 때 관계를 따라 검색 결과를 보완해요. 벡터 검색이 다루기 어려운 “A와 B는 어떤 관계인가요?” 같은 질문에 답해요. 인물, 조직, 계약 조항처럼 관계가 많은 자료에 적합해요.
데이터 연결데이터 소스 지속 동기화
Feishu/Lark, GitLab, IMA, Notion, Yuque와 RSS를 일정에 따라 동기화해요. 처음에는 전체를 가져오고 이후에는 커넥터 규칙에 따라 변경분을 갱신해요. 삭제 감지를 지원하는 소스는 문서 삭제도 동기화해 지식 베이스를 최신 상태로 유지해요.
답변 품질FAQ 정확한 질의응답
반품 정책이나 비용 정산 절차처럼 답이 정해진 질문은 질문·답변 쌍으로 관리해요. 문서 조각 대신 “표준 질문 + 유사 질문 + 반례 질문”으로 질문을 매칭해요. 하나의 에이전트가 FAQ와 문서 베이스를 함께 검색해 표준 답변을 먼저 확인한 뒤 문서를 찾을 수 있어요.
10가지 클라이언트와 연동 경로
같은 지식 베이스와 에이전트 설정을 브라우저, IM, 자체 사이트, 터미널, 외부 에이전트에서 이용해요. 접근 경로마다 따로 구축할 필요가 없어요.
Web 콘솔
지식 베이스 관리, 대화, Wiki 탐색, 시스템 설정을 모두 제공하는 화면이에요.
Chrome 확장 프로그램
웹페이지 사이드바에서 질문하고, 본문 스크랩과 Markdown 메모를 지식 베이스에 저장할 수 있어요.
웹 임베드 위젯
script 한 줄로 자체 사이트에 플로팅 질의응답을 제공해요. 방문자는 로그인하지 않아도 돼요.
데스크톱 클라이언트
백엔드와 로컬 저장소를 포함해 단일 컴퓨터에서 실행하는 앱이에요. 아직 정식 출시 전이라 직접 빌드해야 해요.
IM 봇
WeCom, Feishu, DingTalk, Slack 등 10개 플랫폼의 공식 어댑터를 제공해요.
WeChat 미니 프로그램
모바일에서 웹페이지를 지식 베이스에 저장하고 질문할 수 있어요.
명령줄 weknora
문서 관리, 검색, 출처가 있는 스트리밍 질의응답을 제공해요. 기본 JSON 출력으로 스크립트 작성이 쉬워요.
REST API와 Go SDK
전체 /api/v1 인터페이스를 제공해요. API Key 권한은 기능과 지식 베이스 범위별로 설정할 수 있어요.
DeepSeek Harness
dsh에서 지식 베이스를 검색하고 문서 전체를 읽으며 WeKnora 질의응답을 호출해요.
MCP Server
WeKnora를 MCP 도구로 제공해 Claude, Cursor 등의 클라이언트에서 검색할 수 있어요.
6개 영역, 58개 문서
배포와 시작, 시스템 아키텍처, 기능 설명, 인터페이스 레퍼런스, 클라이언트, 커스텀 개발을 다뤄요.
시작하기
네 문서를 순서대로 읽으며 배포부터 첫 질의응답까지 진행해요.
아키텍처
시스템 전체 구조와 문서 저장, 검색 질의응답의 두 핵심 파이프라인을 살펴봐요.
기능 모듈
23개 기능의 설정 항목, 동작 규칙, 구현 경로를 살펴봐요.
API 레퍼런스
리소스별 인터페이스의 권한, 매개변수, 응답, curl 예제를 확인해요.
클라이언트
Web, CLI, SDK, 미니 프로그램, 데스크톱, 브라우저 확장 프로그램, Skill과 dsh 연동을 살펴봐요.
개발 가이드
로컬 개발 환경, 데이터베이스 마이그레이션, 9종의 교체 가능한 확장 지점을 살펴봐요.
배포 방식
표준 배포는 코드를 복제하고 키 두 개를 바꾼 뒤 명령어 하나로 전체 서비스를 실행해요. 로컬에서 체험할 때는 PostgreSQL과 Redis가 필요 없는 Lite 모드를 선택할 수 있어요.
- Docker Compose표준 배포, 선택 가능한 12개 profile로 인프라 구성
- HelmKubernetes 클러스터 오케스트레이션, 프로덕션 다중 복제본에 적합
- Lite(단일 바이너리 / 데스크톱 앱)SQLite + 프로세스 내부 큐, Docker나 외부 데이터베이스 없이 명령줄과 그래픽 인터페이스 제공 데스크톱 앱은 정식 출시 전이라 직접 빌드해야 해요
# 1 코드 가져오기
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
# 2 설정 준비: 최소한 JWT_SECRET과 SYSTEM_AES_KEY 변경
cp .env.example .env
# 3 전체 서비스 실행(처음에는 이미지를 내려받아야 함)
docker compose up -d --pull always
# 4 서비스 준비 상태 확인
docker compose ps
curl http://localhost:8080/health
# 5 프런트엔드 열기(기본 포트 80, FRONTEND_PORT로 변경 가능)
open http://localhost
# 중지: docker compose down 프런트엔드를 처음 열면 가입 페이지가 나와요. 가입 후 초기화 마법사에서 대화 모델과 벡터 모델을 설정하면 지식 베이스를 만들고 질문할 수 있어요. 백엔드 API는 프런트엔드와 같은 도메인의 http://localhost/api/v1을 사용해요. 전체 과정은 빠른 시작에서, 다른 배포 방식과 매개변수는 설치와 배포에서 확인해요.