pub_soft/WeKnora

Fork 0

mirror of https://github.com/Tencent/WeKnora.git synced 2026-06-04 13:30:32 +08:00

Files

Windfarer c1816fe6d6 add oidc

2026-03-30 11:13:44 +08:00

25 KiB

Raw Blame History

| English | 简体中文 | 한국어 |

개요 • 아키텍처 • 핵심 기능 • 시작하기 • API 레퍼런스 • 개발자 가이드

💡 WeKnora - LLM 기반 문서 이해 및 검색 프레임워크

📌 개요

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 주석에 설명되어 있습니다

③ 서비스 시작(Ollama 포함)

.env 파일에서 시작해야 하는 이미지를 확인하세요.

./scripts/start_all.sh

또는

make start-all

③.0 ollama 서비스 시작(선택)

ollama serve > /dev/null 2>&1 &

③.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

🔌 WeChat 대화 오픈 플랫폼 사용

WeKnora는 WeChat 대화 오픈 플랫폼의 핵심 기술 프레임워크로 사용되며, 보다 간편한 사용 방식을 제공합니다:

노코드 배포: 지식을 업로드하기만 하면 WeChat 생태계에서 지능형 Q&A 서비스를 빠르게 배포하여 "질문 즉시 응답" 경험을 구현
효율적인 질문 관리: 고빈도 질문의 분류 관리 지원, 풍부한 데이터 도구를 통해 정확하고 신뢰할 수 있으며 유지보수하기 쉬운 답변 제공
WeChat 생태계 통합: WeChat 공식계정, 미니프로그램 등 다양한 시나리오에 WeKnora의 Q&A 역량을 자연스럽게 통합

🔗 MCP 서버로 WeKnora 접속

1️⃣ 저장소 클론

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

2️⃣ MCP 서버 설정

설정은 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

④ Web UI 접속

http://localhost

처음 접속하면 자동으로 회원가입/로그인 페이지로 이동합니다. 가입 완료 후 새 지식베이스를 생성하고 설정 페이지에서 필요한 항목을 구성하세요.

📱 인터페이스 소개

Web UI 인터페이스

지식베이스 관리	대화 설정
Agent 모드 도구 호출 과정

지식베이스 관리: FAQ/문서 지식베이스 타입 생성 지원, 드래그 앤 드롭/폴더/URL 임포트 등 다양한 방식 지원. 문서 구조를 자동 식별하고 핵심 지식을 추출해 인덱스를 구축합니다. 태그 관리와 온라인 입력을 지원하며, 처리 진행 상황과 문서 상태를 명확히 표시해 효율적인 지식베이스 운영을 돕습니다.

Agent 모드: ReACT Agent 모드를 지원하며, 내장 도구로 지식베이스 검색, 사용자 설정 MCP 도구 및 웹 검색 도구 호출을 통해 외부 서비스 접근이 가능합니다. 다중 반복과 리플렉션을 통해 종합 요약 리포트를 제공합니다. 교차 지식베이스 검색도 지원하여 여러 지식베이스를 동시에 검색할 수 있습니다.

대화 전략: Agent 모델, 일반 모드 모델, 검색 임계값, 온라인 프롬프트 설정을 지원하여 멀티턴 대화 동작과 검색 실행 방식을 정밀하게 제어할 수 있습니다. 입력창에서 Agent/일반 모드 전환, 웹 검색 활성화/비활성화, 대화 모델 선택을 지원합니다.

문서 지식 그래프

WeKnora는 문서를 지식 그래프로 변환해 문서 내 서로 다른 섹션 간 관계를 시각화할 수 있습니다. 지식 그래프 기능을 활성화하면 문서 내부의 시맨틱 연관 네트워크를 분석/구성하여 문서 이해를 돕고, 인덱싱과 검색에 구조화된 지원을 제공해 검색 결과의 관련성과 폭을 향상시킵니다.

자세한 설정은 지식 그래프 설정 가이드를 참고하세요.

MCP 서버

필요한 설정은 MCP 설정 가이드를 참고하세요.

📘 API 레퍼런스

문제 해결 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: 문서 파싱 모듈 리팩터링

👥 기여자

멋진 기여자 여러분께 감사드립니다:

25 KiB Raw Blame History Unescape Escape