WeKnora 쓰는 법
텐센트 오픈소스 WeKnora(v0.8.0)를 Docker Compose로 올려 RAG 질의응답·ReAct 에이전트·Wiki Mode까지 쓰는 셀프호스팅 가이드다. 클론 후 .env만 맞추면 localhost UI와 8080 API로 바로 지식 베이스 Q&A를 시작할 수 있다.
WeKnora(Tencent/WeKnora)는 문서를 올려 질의응답·에이전트·위키까지 이어 주는 오픈소스 LLM 지식 플랫폼이다. MIT 라이선스, 최신 릴리스 v0.8.0, GitHub 기준 약 2.9만 스타. 이 글은 Docker Compose로 셀프호스팅해 “WeKnora 쓰는 법”만 따라간다.
설치·포트·버전은 공식 README, 설치 문서, 빠른 시작, 릴리스 v0.8.0만 근거로 적는다. 공식 사이트: weknora.weixin.qq.com.
핵심 요약 (TL;DR)
- 무엇인가: 문서를 RAG 질의응답·ReAct 에이전트·Wiki Mode 위키로 바꾸는 셀프호스팅 지식 플랫폼.
- 요구사항: Docker 20.10+ · Docker Compose v2 · Git. 문서 권장 시작점 4코어 / 8GB RAM(모델 가중치 제외).
- 버전(작성 시점): v0.8.0. 라이선스 MIT.
- 한 줄 경로:
git clone→cp .env.example .env→docker compose pull && docker compose up -d→ 브라우저http://localhost. - 서비스 URL: Web UI
http://localhost, Backend APIhttp://localhost:8080, Langfuse(프로필 사용 시)http://localhost:3000.
할 수 있는 일
먼저 용어만 짧게 풀어 둔다.
- RAG(Retrieval-Augmented Generation): 지식 베이스에서 관련 조각을 찾아와 LLM이 답하게 하는 방식. WeKnora의 “빠른 질의응답(Quick Q&A)”이 여기에 해당한다.
- ReAct 에이전트: Reasoning + Acting. 검색·MCP 도구·스킬 샌드박스·웹 검색을 스스로 조합해 여러 단계 일을 처리한다.
- Wiki Mode: 원문 문서를 에이전트가 구조화·상호 링크된 마크다운 위키로 만들고, 지식 그래프·수정 이력·롤백까지 붙인 모드.
- MCP(Model Context Protocol): 외부 도구를 에이전트에 붙이는 표준. 공식 PyPI 패키지
tencent-weknora-mcp로 약 29개 도구를 제공한다. - Docker Compose: 여러 컨테이너(프론트·백엔드·DB·파서 등)를 한 번에 올리고 내리는 오케스트레이션 도구.
- 하네스(Harness): DeepSeek Harness처럼 에이전트 런타임에 플러그인을 꽂는 틀. WeKnora는 공식 플러그인
@wxg-prc-cpg/dsh-weknora를 제공한다.
공식 README 기준으로 바로 할 수 있는 일은 대략 이렇다.
- 문서 올려 RAG Q&A: PDF·Word·Markdown·HTML·이미지 등 10여 포맷을 올리고, 인용과 함께 빠르게 묻는다.
- ReAct 에이전트로 복잡한 일: 지식 검색 + MCP 도구 + 스킬 샌드박스(Docker / E2B / Cube) + 웹 검색을 조합한다. v0.8.0부터 테넌트 스킬 카탈로그·세션 지속 샌드박스·장기 기억이 강화됐다.
- Wiki Mode로 위키·지식 그래프 자동 생성: 원문을 상호 링크된 위키 페이지로 만들고, 브라우저에서 편집·이력·롤백한다.
- 폴더 트리·청크 편집: 업로드 디렉터리 구조를 유지하고, 검색 청크를 문서처럼 수정·diff·되돌린다.
- 데이터 소스 동기화: GitLab·Tencent IMA·Feishu(飞书)·Notion·Yuque(语雀)·DingTalk Docs·RSS 등(계속 확장).
- CLI / MCP / 임베드:
weknoraCLI, MCP 서버, 웹사이트 임베드 위젯, IM(WeCom·飞书·Slack 등) 채널.
필요한 것
| 항목 | 공식 근거 | 메모 |
|---|---|---|
| Docker | 설치 문서 | 20.10+ |
| Docker Compose | 설치 문서 / README | v2 권장 (v1도 스크립트가 자동 탐지) |
| Git | README Prerequisites | 클론용 |
| 하드웨어(시작점) | 설치 문서 | 4코어 / 8GB RAM 권장(Ollama 모델 가중치 제외). 선택 프로필 켜면 메모리 추가 |
| 버전 | Release / README 배지 | v0.8.0 (WEKNORA_VERSION) |
| 필수 env | 설치 문서 / .env.example | DB_USER/DB_PASSWORD/DB_NAME, REDIS_PASSWORD, JWT_SECRET, SYSTEM_AES_KEY 등 |
| LLM | 빠른 시작 | 대화 모델 + 임베딩 모델 최소 1개씩 (Ollama 또는 OpenAI 호환 API) |
| 라이선스 | LICENSE / README | MIT |
링크: GitHub · 설치 · 빠른 시작 · 트러블슈팅 · v0.8.0.
단계
1) 클론하고 .env 준비
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env # DB_*/REDIS_PASSWORD/JWT_SECRET/SYSTEM_AES_KEY 등 수정
.env가 없으면 compose 파싱이 실패한다. README·설치 문서 모두 cp .env.example .env를 먼저 하라고 한다. make start-all(scripts/start_all.sh)을 쓰면 Ollama 점검·env 자동 보완·샌드박스 이미지 미리 받기까지 묶여 있다. README 최소 경로는 docker compose 직접 호출이다.
2) 이미지 받고 올리기
docker compose pull # WEKNORA_VERSION에 맞는 이미지
docker compose up -d
docker compose ps # healthy/running 확인
브라우저에서 http://localhost 를 연다. 프론트 Nginx가 /api/를 백엔드로 프록시하므로 API도 http://localhost/api/v1로 갈 수 있다. 백엔드 포트는 호스트에 8080으로 매핑된다.
curl http://localhost:8080/health
# 기대: {"status":"ok"}
3) (선택) Compose 프로필
| 프로필 | 역할 | 예 |
|---|---|---|
| (기본) | 코어(프론트·앱·docreader·postgres·redis) | docker compose up -d |
full | 선택 기능 묶음 | docker compose --profile full up -d |
neo4j | 지식 그래프 | --profile neo4j |
minio | 객체 스토리지 | --profile minio |
langfuse | 트레이싱 UI (http://localhost:3000) | --profile langfuse |
프로필은 여러 개 같이 쓸 수 있다. 중지: docker compose down (-v는 데이터 볼륨까지 지우니 조심).
4) 가입 → 지식 베이스 → 모델
빠른 시작 문서 흐름이다.
- 첫 방문은 등록/로그인. 기본은 공개 등록 시 개인 워크스페이스 Owner가 된다. 기본 관리자 계정은 없다.
- 「지식 베이스」에서 새 라이브러리 생성(유형
document또는faq). - 초기화 마법사에서 대화 모델(LLM)과 임베딩 모델을 고르고 「테스트」로 연결을 확인한다.
- 컨테이너에서 호스트 Ollama를 쓸 때는
http://host.docker.internal:11434를 쓴다. 호스트에서 먼저ollama serve를 띄워야 한다(README 안내).
5) 문서 업로드하고 질문
파일을 드래그하거나 URL을 붙여 넣는다. 상태는 pending → processing → finalizing → completed로 진행된다. 대화 페이지에서 지식 베이스를 고르면 기본 「빠른 질의응답」에이전트가 조각을 찾아 인용과 함께 답한다.
더 복잡한 일은 에이전트(스마트 추론)로 전환하고, Wiki Mode로 위키·지식 그래프를 돌리면 된다.
6) 업그레이드
# .env의 WEKNORA_VERSION을 목표 버전(예: 0.8.0)으로 두거나 latest 유지
docker compose pull
docker compose up -d
up -d만 하면 로컬 캐시 이미지를 재사용해 UI 버전이 어긋날 수 있다. 반드시 pull을 먼저 한다.
7) (선택) MCP · CLI · DeepSeek 하네스
- MCP:
pip install tencent-weknora-mcp또는uvx --from tencent-weknora-mcp weknora-mcp-server. 설정은 mcp-server/MCP_CONFIG.md. 환경변수 예:WEKNORA_API_KEY,WEKNORA_BASE_URL=http://localhost:8080/api/v1. - CLI:
weknora profile add/auth login/kb list/doc upload/chat. 헤드리스는WEKNORA_API_KEY+WEKNORA_HOST. - DeepSeek 하네스 플러그인:
dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora후 배포를 가리키면 검색·문서 읽기·질문·KB 목록 도구가 붙는다.
막히는 지점
| 증상 | 원인(문서 기준) | 대응 |
|---|---|---|
| compose가 .env 없다고 실패 | env_file: [.env] 필수 | cp .env.example .env 후 재시도 |
| UI는 뜨는데 health 실패 | 앱/postgres/redis/docreader 미준비 | docker compose ps · docker compose logs --tail=200 app |
| 업로드·파싱이 멈춤 | 파서/큐 문제 | 문서 상세 실패 사유 → docreader·큐 로그(트러블슈팅 FAQ) |
| 에이전트가 “모델 미준비” | 연결된 모델 누락·설정 불완전 | 모델 관리에서 연결 테스트 후 저장 |
| Ollama 연결 안 됨 | 컨테이너 localhost ≠ 호스트 | 호스트에서 ollama serve + Base URL http://host.docker.internal:11434 |
| 업그레이드 후 UI 버전 불일치 | 캐시 이미지 재사용 | WEKNORA_VERSION 설정 → pull → up -d |
| 스킬은 카탈로그에 있는데 실행 불가 | 카탈로그 등록 ≠ 샌드박스 설치 | 설치 기록·에이전트 샌드박스·스킬 범위 확인 |
| Local 샌드박스를 못 찾음 | v0.8.0에서 local 백엔드 제거 | Docker(옵트인)·Cube·E2B로 재설정 |
.env 수정이 안 반영 | restart는 env 미재로드 | docker compose up -d <서비스>로 재생성 |
보안 메모(README): v0.1.3부터 로그인 인증이 있다. 프로덕션은 내부망에 두고 공개 인터넷에 직접 노출하지 말 것. 방화벽·접근 제어를 맞추고 최신 버전을 유지하라.
로그 확인 예(트러블슈팅):
docker compose ps
docker compose logs --tail=200 app
docker compose logs --tail=200 docreader
docker compose logs --tail=200 postgres redis
마치며
WeKnora는 “문서 올리면 끝나는” RAG를 넘어, ReAct 에이전트와 Wiki Mode까지 한 스택으로 묶은 셀프호스팅 지식 플랫폼이다. 오늘은 Docker Compose로 UI를 띄우고, 모델 두 개(대화·임베딩)만 붙인 뒤 문서 한 묶음으로 Q&A부터 확인하는 순서가 가장 덜 아프다. v0.8.0 기준으로 스킬 샌드박스·장기 기억·MCP가 더 두꺼워졌으니, 기본 경로가 안정되면 Wiki Mode와 에이전트 쪽을 열어 보자.
이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.