WeKnora는 복잡하고 이질적인 문서를 다루는 데 특화된, LLM 기반의 심층 문서 이해 및 시맨틱 검색 프레임워크입니다.
멀티모달 전처리, 시맨틱 벡터 인덱싱, 지능형 검색, 대규모 언어 모델 추론을 결합한 모듈형 아키텍처를 채택했습니다. 핵심적으로 WeKnora는 RAG(Retrieval-Augmented Generation) 패러다임을 따르며, 관련 문서 조각과 모델 추론을 결합해 문맥을 반영한 고품질 답변을 제공합니다.
웹사이트: https://weknora.weixin.qq.com
v0.3.5 하이라이트:
- Telegram, DingTalk & Mattermost IM 통합: Telegram 봇(webhook/롱폴링, editMessageText 스트리밍), DingTalk 봇(webhook/Stream 모드, AI 카드 스트리밍), Mattermost 어댑터를 신규 추가. IM 채널이 기업WeChat, Feishu, Slack, Telegram, DingTalk, Mattermost 6개 플랫폼으로 확대
- IM 슬래시 커맨드 및 QA 큐: 플러그인 방식 슬래시 커맨드 프레임워크(/help, /info, /search, /stop, /clear), 유계 QA 워커 풀, 사용자별 레이트 리밋, Redis 기반 멀티 인스턴스 분산 조정
- 추천 질문: Agent가 연결된 지식베이스를 기반으로 컨텍스트 맞춤 추천 질문을 자동 생성해 채팅 화면에 표시; 이미지 지식은 질문 생성 작업을 자동 큐 등록
- VLM을 통한 MCP 도구 이미지 자동 설명: MCP 도구가 이미지를 반환하면 설정된 VLM 모델로 텍스트 설명을 자동 생성해 텍스트 전용 LLM에서도 이미지 내용 활용 가능
- Novita AI 프로바이더: OpenAI 호환 API로 chat, embedding, VLLM 모델 타입을 지원하는 신규 LLM 프로바이더
- MCP 도구명 안정성: UUID 대신 service.Name 기반 도구명(재연결 후에도 안정), 고유명 제약 및 충돌 방지 추가; 프론트엔드에서 snake_case를 사람이 읽기 쉬운 형태로 변환
- 채널 추적: 지식 항목과 메시지에 channel 필드 추가(web/api/im/browser_extension)로 출처 추적 가능
- 주요 버그 수정: 지식베이스 미설정 시 Agent 빈 응답, 한국어/이모지 문서 요약의 UTF-8 잘림, 테넌트 설정 업데이트 시 API 키 암호화 손실, vLLM 스트리밍 추론 콘텐츠 누락, Rerank 빈 패시지 오류 수정
v0.3.4 하이라이트:
- IM 봇 통합: 기업WeChat, Feishu, Slack IM 채널 지원, WebSocket/Webhook 모드, 스트리밍 및 지식베이스 통합
- 멀티모달 이미지 지원: 이미지 업로드 및 멀티모달 이미지 처리, 세션 관리 강화
- 수동 지식 다운로드: 수동 지식 콘텐츠를 파일로 다운로드, 파일명 정리 및 포맷 처리
- NVIDIA 모델 API: NVIDIA 채팅 모델 API 지원, 커스텀 엔드포인트 및 VLM 모델 설정
- Weaviate 벡터 데이터베이스: 지식 검색을 위한 Weaviate 벡터 데이터베이스 백엔드 추가
- AWS S3 스토리지: AWS S3 스토리지 어댑터 통합, 설정 UI 및 데이터베이스 마이그레이션
- AES-256-GCM 암호화: API 키를 AES-256-GCM으로 정적 암호화하여 보안 강화
- 내장 MCP 서비스: 내장 MCP 서비스 지원으로 Agent 기능 확장
- 하이브리드 검색 최적화: 타겟 그룹화 및 쿼리 임베딩 재사용으로 검색 성능 향상
- Final Answer 도구: 새로운 final_answer 도구 및 Agent 소요 시간 추적으로 워크플로우 개선
이전 릴리스
v0.3.3 하이라이트:
- 부모-자식 청킹: 계층적 부모-자식 청킹 전략으로 컨텍스트 관리 및 검색 정확도 강화
- 지식베이스 고정: 자주 사용하는 지식베이스를 고정하여 빠른 접근 지원
- 폴백 응답: 관련 결과가 없을 때 폴백 응답 처리 및 UI 표시기
- Rerank 패시지 클리닝: Rerank 모델의 패시지 클리닝 기능으로 관련성 점수 정확도 향상
- 버킷 자동 생성: 스토리지 엔진 연결 확인 강화, 버킷 자동 생성 지원
- Milvus 벡터 데이터베이스: 지식 검색을 위한 Milvus 벡터 데이터베이스 백엔드 추가
v0.3.0 하이라이트:
- 🏢 공유 공간: 멤버 초대, 멤버 간 지식베이스/에이전트 공유, 테넌트 격리 검색을 지원하는 공유 공간
- 🧩 Agent Skills: 스마트 추론 에이전트를 위한 사전 로드 스킬과 샌드박스 기반 보안 격리 실행 환경 제공
- 🤖 커스텀 에이전트: 지식베이스 선택 모드(전체/지정/비활성화)와 함께 커스텀 에이전트 생성, 설정, 선택 지원
- 🧠 사고 모드: LLM과 에이전트의 사고 모드 지원 및 사고 내용 지능형 필터링
- 🔍 웹 검색 제공자: DuckDuckGo 외에 Bing, Google 검색 제공자 추가
- ☸️ Helm Chart: Neo4j GraphRAG 지원을 포함한 Kubernetes 배포용 완전한 Helm Chart 제공
- 🔒 보안 강화: SSRF 안전 HTTP 클라이언트, 향상된 SQL 검증, MCP stdio 전송 보안
v0.2.0 하이라이트:
- 🤖 Agent 모드: 내장 도구, MCP 도구, 웹 검색을 호출할 수 있는 새로운 ReACT Agent 모드 추가. 다중 반복 및 리플렉션을 통해 종합 요약 리포트 제공
- 📚 다중 지식베이스 타입: FAQ/문서 지식베이스 타입 지원 및 폴더 임포트, URL 임포트, 태그 관리, 온라인 입력 기능 추가
- ⚙️ 대화 전략: Agent 모델, 일반 모드 모델, 검색 임계값, 프롬프트 설정 지원. 멀티턴 대화 동작을 정밀 제어
- 🌐 웹 검색: 확장 가능한 웹 검색 엔진 지원, DuckDuckGo 검색 엔진 내장
- 🔌 MCP 도구 통합: MCP를 통한 Agent 기능 확장 지원, uvx/npx 런처 내장, 다양한 전송 방식 지원
- 🎨 새 UI: Agent/일반 모드 전환, 도구 호출 과정 표시, 지식베이스 관리 인터페이스 전면 개선
- ⚡ 인프라 업그레이드: MQ 비동기 작업 관리 도입, 자동 DB 마이그레이션 및 고속 개발 모드 지원
중요: v0.1.3부터 WeKnora는 시스템 보안 강화를 위해 로그인 인증 기능을 포함합니다. 운영 환경 배포 시 아래 사항을 강력히 권장합니다.
- WeKnora 서비스를 공용 인터넷이 아닌 내부/사설 네트워크 환경에 배포
- 잠재적 정보 유출 방지를 위해 서비스를 공용 네트워크에 직접 노출하지 않기
- 배포 환경에 적절한 방화벽 규칙 및 접근 제어 구성
- 보안 패치와 개선 사항 적용을 위해 최신 버전으로 정기 업데이트
WeKnora는 완전한 문서 이해 및 검색 파이프라인을 구축하기 위해 현대적인 모듈형 설계를 채택했습니다. 시스템은 주로 문서 파싱, 벡터 처리, 검색 엔진, 대형 모델 추론 모듈로 구성되며, 각 구성 요소는 유연하게 설정 및 확장할 수 있습니다.
- 🤖 Agent 모드: 내장 도구로 지식베이스를 검색하고 MCP 도구/웹 검색 도구를 호출해 외부 서비스에 접근. 다중 반복 및 리플렉션을 통해 종합 요약 리포트 제공
- 🔍 정밀 이해: PDF, Word, 이미지 등에서 구조화된 내용을 추출해 통합 시맨틱 뷰 구성
- 🧠 지능형 추론: LLM으로 문서 문맥과 사용자 의도를 이해하여 정확한 Q&A와 멀티턴 대화 지원
- 📚 다중 지식베이스 타입: FAQ/문서 지식베이스 타입, 폴더 임포트, URL 임포트, 태그 관리, 온라인 입력 지원
- 🔧 유연한 확장성: 파싱-임베딩-검색-생성 전 과정을 분리해 손쉬운 커스터마이징 가능
- ⚡ 고효율 검색: 키워드/벡터/지식 그래프를 결합한 하이브리드 검색 및 교차 지식베이스 검색 지원
- 🌐 웹 검색: 확장 가능한 웹 검색 엔진 지원, DuckDuckGo 기본 제공
- 🔌 MCP 도구 통합: MCP를 통한 Agent 기능 확장, uvx/npx 런처 내장, 다중 전송 방식 지원
- ⚙️ 대화 전략: Agent 모델, 일반 모드 모델, 검색 임계값, 프롬프트 설정 지원으로 멀티턴 대화 정밀 제어
- 🎯 사용 편의성: 직관적인 Web UI와 표준 API 제공으로 진입 장벽 최소화
- 🔒 보안 및 통제: 로컬/프라이빗 클라우드 배포 지원으로 데이터 주권 보장
| 시나리오 | 적용 사례 | 핵심 가치 |
|---|---|---|
| 기업 지식 관리 | 내부 문서 검색, 규정 Q&A, 운영 매뉴얼 조회 | 지식 탐색 효율 향상, 교육 비용 절감 |
| 학술 연구 분석 | 논문 검색, 연구 리포트 분석, 학술 자료 정리 | 문헌 조사 가속, 연구 의사결정 지원 |
| 제품 기술 지원 | 제품 매뉴얼 Q&A, 기술 문서 검색, 트러블슈팅 | 고객 지원 품질 향상, 지원 부담 감소 |
| 법무/컴플라이언스 검토 | 계약 조항 검색, 규제 정책 조회, 사례 분석 | 컴플라이언스 효율 향상, 법적 리스크 감소 |
| 의료 지식 지원 | 의학 문헌 검색, 진료 가이드라인 조회, 증례 분석 | 임상 의사결정 지원, 진단 품질 향상 |
| 모듈 | 지원 범위 | 설명 |
|---|---|---|
| Agent 모드 | ✅ ReACT Agent Mode | 내장 도구로 지식베이스 검색, MCP 도구 및 웹 검색 호출; 교차 지식베이스 검색 및 다중 반복 추론 |
| 지식베이스 타입 | ✅ FAQ / Document | FAQ/문서 지식베이스, 폴더 임포트, URL 임포트, 태그 관리, 온라인 입력, 지식 이동 지원 |
| 문서 포맷 | ✅ PDF / Word / Txt / Markdown / HTML / 이미지 (OCR + Caption) | 구조화/비구조화 문서 파싱; OCR 이미지 텍스트 추출; VLM 이미지 캡션 생성 |
| IM 채널 통합 | ✅ WeChat Work / Feishu / Slack / Telegram / DingTalk / Mattermost | WebSocket·Webhook 모드, 스트리밍 답변, 슬래시 커맨드(/help, /info, /search, /stop, /clear), 사용자별 레이트 리밋, Redis 기반 멀티 인스턴스 분산 조정 |
| 모델 관리 | ✅ 중앙 설정, 내장 모델 공유 | 지식베이스별 모델 선택 포함 중앙 모델 관리; 멀티테넌트 내장 모델 공유 |
| 임베딩 모델 | ✅ 로컬 모델(Ollama), BGE / GTE / OpenAI 호환 API | 커스텀 임베딩 모델, 로컬 배포 및 클라우드 벡터 생성 API 호환 |
| 벡터 DB 연동 | ✅ PostgreSQL (pgvector) / Elasticsearch / Milvus / Weaviate / Qdrant | 5종 벡터 인덱스 백엔드, 검색 시나리오별 유연한 전환 |
| 오브젝트 스토리지 | ✅ 로컬 / MinIO / AWS S3 / Volcengine TOS | 플러그인 방식 스토리지 어댑터; 시작 시 버킷 자동 생성 |
| 검색 전략 | ✅ BM25 / Dense Retrieval / GraphRAG | 희소/밀집 검색, 지식 그래프 강화 검색; 검색-리랭크-생성 파이프라인 조합 가능 |
| LLM 연동 | ✅ Qwen / DeepSeek / MiniMax / NVIDIA / Novita AI / OpenAI 호환 | 로컬 모델(Ollama) 또는 외부 API, 사고/비사고 모드 전환, vLLM 스트리밍 추론 콘텐츠 지원 |
| 대화 전략 | ✅ Agent 모델, 일반 모드 모델, 검색 임계값, 프롬프트 설정 | 온라인 프롬프트 편집, 검색 임계값 조정, 멀티턴 대화 동작 정밀 제어 |
| 웹 검색 | ✅ DuckDuckGo / Bing / Google (확장 가능) | 플러그인 방식 검색 엔진; 대화별 웹 검색 켜기/끄기 |
| MCP 도구 | ✅ uvx / npx 런처, Stdio / HTTP Streamable / SSE | MCP로 Agent 기능 확장; 안정적인 도구명 관리(충돌 방지); 도구 반환 이미지 VLM 자동 설명 |
| 추천 질문 | ✅ 지식베이스 기반 질문 추천 | Agent가 채팅 전 추천 질문 표시; 이미지 지식이 질문 생성 자동 트리거 |
| QA 역량 | ✅ 문맥 인식, 멀티턴 대화, 프롬프트 템플릿 | 복잡한 시맨틱 모델링, 지시 제어, 체인형 Q&A; 프롬프트/컨텍스트 윈도우 설정 |
| 보안 | ✅ AES-256-GCM 정적 암호화, SSRF 방어 | API 키 정적 암호화; 원격 API 호출 SSRF 안전 검증; Agent 스킬 샌드박스 실행 |
| E2E 테스트 | ✅ 검색+생성 과정 시각화 및 지표 평가 | 리콜 적중률, 답변 커버리지, BLEU/ROUGE 지표 평가 종단간 테스트 도구 |
| 배포 모드 | ✅ 로컬 / Docker / Kubernetes (Helm) | 프라이빗/오프라인 배포; 핫 리로드 고속 개발 모드; Kubernetes용 Helm Chart |
| 사용자 인터페이스 | ✅ Web UI + RESTful API | 상호작용 UI와 표준 API; Agent/일반 모드 전환; 도구 호출 과정 표시 |
| 작업 관리 | ✅ MQ 비동기 작업, 자동 DB 마이그레이션 | MQ 기반 비동기 작업 상태 유지; 버전 업그레이드 시 스키마/데이터 자동 마이그레이션 |
다음 도구가 시스템에 설치되어 있는지 확인하세요:
# 메인 저장소 클론
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
# 예시 환경 파일 복사
cp .env.example .env
# .env 파일을 수정해 필요한 값을 설정
# 모든 변수는 .env.example 주석에 설명되어 있습니다
.env 파일에서 시작해야 하는 이미지를 확인하세요.
./scripts/start_all.sh
또는
make start-all
ollama serve > /dev/null 2>&1 &
- 최소 코어 서비스
docker compose up -d
- 전체 기능 활성화
docker-compose --profile full up -d
- 트레이싱 로그 필요 시
docker-compose --profile jaeger up -d
- Neo4j 지식 그래프 필요 시
docker-compose --profile neo4j up -d
- Minio 파일 스토리지 필요 시
docker-compose --profile minio up -d
- 여러 옵션 조합
docker-compose --profile neo4j --profile minio up -d
./scripts/start_all.sh --stop
# 또는
make stop-all
서비스 시작 후 아래 주소로 접속할 수 있습니다:
- Web UI:
http://localhost - 백엔드 API:
http://localhost:8080 - Jaeger 트레이싱:
http://localhost:16686
WeKnora는 WeChat 대화 오픈 플랫폼의 핵심 기술 프레임워크로 사용되며, 보다 간편한 사용 방식을 제공합니다:
- 노코드 배포: 지식을 업로드하기만 하면 WeChat 생태계에서 지능형 Q&A 서비스를 빠르게 배포하여 "질문 즉시 응답" 경험을 구현
- 효율적인 질문 관리: 고빈도 질문의 분류 관리 지원, 풍부한 데이터 도구를 통해 정확하고 신뢰할 수 있으며 유지보수하기 쉬운 답변 제공
- WeChat 생태계 통합: WeChat 공식계정, 미니프로그램 등 다양한 시나리오에 WeKnora의 Q&A 역량을 자연스럽게 통합
git clone https://github.com/Tencent/WeKnora
설정은 MCP 설정 가이드를 직접 참고하는 것을 권장합니다.
MCP 클라이언트에서 서버 연결을 설정합니다:
{
"mcpServers": {
"weknora": {
"args": [
"path/to/WeKnora/mcp-server/run_server.py"
],
"command": "python",
"env":{
"WEKNORA_API_KEY":"WeKnora 인스턴스에서 개발자 도구를 열고, sk로 시작하는 요청 헤더 x-api-key를 확인",
"WEKNORA_BASE_URL":"http(s)://your-weknora-address/api/v1"
}
}
}
}
stdio 명령으로 직접 실행:
pip install weknora-mcp-server python -m weknora-mcp-server
사용자가 다양한 모델을 빠르게 설정하고 시행착오 비용을 줄일 수 있도록, 기존 설정 파일 초기화 방식을 개선하고 Web UI 기반 설정 인터페이스를 추가했습니다. 사용 전에 코드가 최신 버전인지 확인하세요. 절차는 아래와 같습니다. 프로젝트를 처음 사용하는 경우 ①② 단계를 건너뛰고 ③④로 바로 진행해도 됩니다.
./scripts/start_all.sh --stop
make clean-db
./scripts/start_all.sh
처음 접속하면 자동으로 회원가입/로그인 페이지로 이동합니다. 가입 완료 후 새 지식베이스를 생성하고 설정 페이지에서 필요한 항목을 구성하세요.
지식베이스 관리 | 대화 설정 |
Agent 모드 도구 호출 과정 | |
지식베이스 관리: FAQ/문서 지식베이스 타입 생성 지원, 드래그 앤 드롭/폴더/URL 임포트 등 다양한 방식 지원. 문서 구조를 자동 식별하고 핵심 지식을 추출해 인덱스를 구축합니다. 태그 관리와 온라인 입력을 지원하며, 처리 진행 상황과 문서 상태를 명확히 표시해 효율적인 지식베이스 운영을 돕습니다.
Agent 모드: ReACT Agent 모드를 지원하며, 내장 도구로 지식베이스 검색, 사용자 설정 MCP 도구 및 웹 검색 도구 호출을 통해 외부 서비스 접근이 가능합니다. 다중 반복과 리플렉션을 통해 종합 요약 리포트를 제공합니다. 교차 지식베이스 검색도 지원하여 여러 지식베이스를 동시에 검색할 수 있습니다.
대화 전략: Agent 모델, 일반 모드 모델, 검색 임계값, 온라인 프롬프트 설정을 지원하여 멀티턴 대화 동작과 검색 실행 방식을 정밀하게 제어할 수 있습니다. 입력창에서 Agent/일반 모드 전환, 웹 검색 활성화/비활성화, 대화 모델 선택을 지원합니다.
WeKnora는 문서를 지식 그래프로 변환해 문서 내 서로 다른 섹션 간 관계를 시각화할 수 있습니다. 지식 그래프 기능을 활성화하면 문서 내부의 시맨틱 연관 네트워크를 분석/구성하여 문서 이해를 돕고, 인덱싱과 검색에 구조화된 지원을 제공해 검색 결과의 관련성과 폭을 향상시킵니다.
자세한 설정은 지식 그래프 설정 가이드를 참고하세요.
필요한 설정은 MCP 설정 가이드를 참고하세요.
문제 해결 FAQ: 문제 해결 FAQ
상세 API 문서: API Docs
제품 계획 및 예정 기능: Roadmap
코드를 자주 수정해야 한다면 매번 Docker 이미지를 다시 빌드할 필요가 없습니다. 고속 개발 모드를 사용하세요.
# 방법 1: Make 명령 사용 (권장)
make dev-start # 인프라 시작
make dev-app # 백엔드 시작 (새 터미널)
make dev-frontend # 프론트엔드 시작 (새 터미널)
# 방법 2: 원클릭 시작
./scripts/quick-dev.sh
# 방법 3: 스크립트 사용
./scripts/dev.sh start # 인프라 시작
./scripts/dev.sh app # 백엔드 시작 (새 터미널)
./scripts/dev.sh frontend # 프론트엔드 시작 (새 터미널)
개발 장점:
- ✅ 프론트엔드 변경 자동 핫리로드(재시작 불필요)
- ✅ 백엔드 변경 빠른 재시작(5~10초, Air 핫리로드 지원)
- ✅ Docker 이미지 재빌드 불필요
- ✅ IDE 브레이크포인트 디버깅 지원
상세 문서: 개발 환경 빠른 시작
WeKnora/ ├── client/ # go client ├── cmd/ # Main entry point ├── config/ # Configuration files ├── docker/ # docker images files ├── docreader/ # Document parsing app ├── docs/ # Project documentation ├── frontend/ # Frontend app ├── internal/ # Core business logic ├── mcp-server/ # MCP server ├── migrations/ # DB migration scripts └── scripts/ # Shell scripts
커뮤니티 기여를 환영합니다! 제안, 버그, 기능 요청은 Issue로 등록하거나 Pull Request를 직접 생성해 주세요.
- 🐛 버그 수정: 시스템 결함 발견 및 수정
- ✨ 새 기능: 새로운 기능 제안 및 구현
- 📚 문서 개선: 프로젝트 문서 품질 향상
- 🧪 테스트 케이스: 단위/통합 테스트 작성
- 🎨 UI/UX 개선: 사용자 인터페이스와 경험 개선
- 프로젝트를 Fork 해서 본인 GitHub 계정으로 가져오기
- 기능 브랜치 생성
git checkout -b feature/amazing-feature - 변경사항 커밋
git commit -m 'Add amazing feature' - 브랜치 푸시
git push origin feature/amazing-feature - Pull Request 생성 후 변경 내용을 자세히 설명
- Go Code Review Comments 준수
gofmt로 코드 포맷팅- 필요한 단위 테스트 추가
- 관련 문서 업데이트
Conventional Commits 규칙 사용:
feat: 문서 일괄 업로드 기능 추가 fix: 벡터 검색 정확도 문제 수정 docs: API 문서 업데이트 test: 검색 엔진 테스트 케이스 추가 refactor: 문서 파싱 모듈 리팩터링
멋진 기여자 여러분께 감사드립니다:
이 프로젝트는 MIT License로 배포됩니다. 적절한 저작권 고지를 유지하는 조건으로 코드를 자유롭게 사용, 수정, 배포할 수 있습니다.
