빠른 시작

계정 가입, 지식 베이스 생성, 모델 설정, 문서 업로드, 질문을 통해 첫 지식 베이스 질의응답을 완료하고 답변에서 원문 인용을 확인할 수 있습니다. 아래 단계는 웹 화면을 사용하며, 문서 끝에 대응하는 API 예제를 제공합니다.

사용하기 전에 설치 및 배포를 완료하고, 사용 가능한 대화 모델과 벡터 모델을 준비해야 합니다.

시작하기 전에

서비스 시작: 설치 및 배포에 따라 시작하면 프런트엔드는 http://localhost, 백엔드는 http://localhost:8080에 있습니다.
모델 연결 정보 준비: 로컬 Ollama(컨테이너 내 기본 주소 http://host.docker.internal:11434) 또는 OpenAI 호환 서비스의 base_url + api_key를 준비합니다. 대화 모델과 벡터(embedding) 모델이 최소 하나씩 필요합니다.
백엔드 상태 확인: curl http://localhost:8080/health가 {"status":"ok"}를 반환해야 합니다.

가입 및 로그인

처음 접속하면 로그인 페이지가 표시됩니다. 공개 가입(self_serve)을 허용한 배포에서는 가입 탭이 표시됩니다. 시스템에는 기본 계정이 없습니다. 기본 설정에서 가입하면 개인 작업 공간이 생성되고 새 사용자가 해당 공간의 Owner로 지정됩니다.

가입 요구 사항과 배포별 차이:

사용자 이름은 2–50자, 비밀번호는 8–32자이며 영문자와 숫자를 포함해야 합니다. 복잡한 비밀번호 정책을 활성화하면 대문자, 소문자, 특수 문자도 모두 포함해야 합니다. 화면과 API는 동일한 정책을 사용합니다.
팀 배포에서는 공개 가입을 비활성화한 후 초대 링크로 멤버를 추가할 수 있습니다. DISABLE_REGISTRATION=true를 설정하거나(시작 시 가입 모드를 invite_only로 강제), 시스템 관리자가 '설정 → 시스템'에서 auth.registration_mode를 invite_only로 변경할 수 있습니다(즉시 적용, 재시작 불필요).
배포의 기본 공간 정책이 tenantless(auth.default_tenant_mode)이면 가입 후 공간을 자동으로 생성하지 않습니다. 대신 /onboarding/workspace로 안내하며, 공간을 직접 만들거나 초대를 수락하여 공간에 참여해야 계속할 수 있습니다.
데스크톱 / Lite 버전은 가입 없이 시작 시 로컬 계정을 자동 생성합니다.

공간 권한과 플랫폼 권한

공간 Owner는 해당 공간의 멤버, 모델, 지식 베이스를 관리해요. 전역 시스템 설정, 플랫폼 작업 큐, 공간 간 감사에는 시스템 관리자 권한이 필요하며, 두 권한은 별도로 부여해요.

처음 시스템 관리자를 설정할 때는 먼저 계정을 등록하고, app 서비스에 WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL=<해당 계정 이메일>을 설정한 뒤 재시작하세요. 배포에 시스템 관리자가 아직 없을 때만 적용돼요. 전체 단계와 제한 사항은 플랫폼 관리와 시스템 관리자를 참고하세요.

지식 베이스 생성 및 모델 설정

'지식 베이스' 페이지에서 지식 베이스를 생성하면 초기 설정 마법사가 해당 베이스에서 사용할 모델 설정을 안내합니다. 모델은 지식 베이스마다 개별적으로 선택합니다.

'지식 베이스' 페이지에서 새로 만들기를 누르고 이름을 입력한 뒤 유형을 선택합니다. document(일반 문서 베이스) 또는 faq(질의응답 쌍 베이스)를 선택할 수 있습니다.
나타나는 초기 설정 마법사에서 모델을 선택합니다.
- 대화 모델(LLM): 답변을 생성합니다.
- 벡터 모델(Embedding): 문서를 벡터로 변환합니다. 변경 후에는 인덱스를 재구축해야 합니다.
- 리랭킹 Rerank, 이미지 이해 VLM, 음성 전사 ASR, 지식 그래프 추출, 질문 생성은 자료 유형과 사용 요구에 따라 설정할 수 있습니다.
마법사의 '테스트' 버튼으로 모델 연결이 정상인지 확인한 뒤 저장합니다.

컨테이너에서 Ollama에 연결하기

백엔드 컨테이너 내부의 localhost는 컨테이너 자신을 가리켜요. 호스트의 Ollama에 연결하려면 http://host.docker.internal:11434를 사용하세요.

문서 업로드

지식 베이스에 들어가 파일을 끌어 놓거나 웹페이지 URL을 붙여 넣습니다. 업로드 확인 대화상자에서 이번 파일 묶음에 적용할 태그와 파싱 옵션을 설정할 수 있습니다.

PDF, Word, Excel, PPT, Markdown, HTML, EPUB, 이미지, 음성 등의 형식을 지원합니다. 전체 목록은 문서 파싱 서비스를 참고하세요.

업로드한 문서는 비동기로 파싱되며, 상태는 pending → processing → finalizing → completed 순서로 바뀝니다. PDF 스캔본이나 큰 파일은 시간이 더 걸릴 수 있으며, 목록 페이지에서 진행 상황을 실시간으로 갱신합니다.

질문하기

대화 페이지에서 지식 베이스를 선택하면 질문할 수 있습니다. 기본 '빠른 질의응답' 에이전트가 관련 청크를 검색하고 답변을 생성하며, 인용을 누르면 원문을 확인할 수 있습니다.

답변이 정상적으로 표시되고 인용을 열 수 있다면, 이번 문서 등록 및 질의응답 과정이 완료된 것입니다.

추가 설정

에이전트 설정: 지능형 추론으로 다단계 질문을 처리하고, 필요에 따라 인터넷 검색과 MCP 도구를 활성화합니다.
청크 조정 및 검색 매개변수: 문서 구조와 검색 결과에 따라 설정을 조정합니다.
데이터 소스 연결: Feishu, Notion, Yuque 또는 RSS 콘텐츠를 지속적으로 동기화합니다.
IM 연결 또는 웹페이지 임베드: 사용자가 기존 채널에서 질문하도록 합니다.

API로 첫 질의응답 완료하기

다음 예제는 가입, 로그인, 베이스 생성, 모델 초기 설정, 업로드, 질의응답 순서로 API를 호출합니다. 모든 경로는 /api/v1 접두사를 사용합니다.

bash

BASE=http://localhost:8080/api/v1

# 1) 가입(최초 배포 시. 사용자 이름 2–50자, 비밀번호 8–32자에 영문자와 숫자 포함. 복잡한 정책은 추가 요구 사항 있음)
curl -s -X POST $BASE/auth/register -H "Content-Type: application/json" \
  -d '{"username":"admin","email":"admin@example.com","password":"pass123456"}'

# 2) 로그인하여 JWT 받기
TOKEN=$(curl -s -X POST $BASE/auth/login -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"pass123456"}' | jq -r '.token')
AUTH="Authorization: Bearer $TOKEN"

# 3) 지식 베이스 생성
KB_ID=$(curl -s -X POST $BASE/knowledge-bases -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"내 지식 베이스","description":"demo","type":"document"}' | jq -r '.data.id')

# 4) 지식 베이스 초기 설정(로컬 Ollama 예제. 원격 모델은 source/baseUrl/apiKey 변경)
curl -s -X POST $BASE/initialization/initialize/$KB_ID -H "$AUTH" -H "Content-Type: application/json" -d '{
  "llm":       {"source":"local","modelName":"qwen3:8b"},
  "embedding": {"source":"local","modelName":"bge-m3","dimension":1024},
  "rerank":    {"enabled":false},
  "multimodal":{"enabled":false},
  "documentSplitting":{"chunkSize":512,"chunkOverlap":50,"separators":["\n\n","\n","。"]},
  "nodeExtract":{"enabled":false},
  "questionGeneration":{"enabled":false}}'

# 5) 문서 업로드(multipart, 필드 이름 file)
curl -s -X POST $BASE/knowledge-bases/$KB_ID/knowledge/file -H "$AUTH" \
  -F "file=@./demo.pdf"
# 파싱 상태 폴링: parse_status=completed가 될 때까지 GET /knowledge-bases/$KB_ID/knowledge

# 6) 세션 생성
SESSION_ID=$(curl -s -X POST $BASE/sessions -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"title":"첫 대화"}' | jq -r '.data.id')

# 7) 지식 질의응답(SSE 스트리밍 출력)
curl -N -X POST $BASE/knowledge-chat/$SESSION_ID -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"query":"이 문서는 어떤 내용을 다루나요?","knowledge_base_ids":["'$KB_ID'"]}'

# 7b) Agent 대화(동일하게 SSE. agent_id에 내장 builtin-smart-reasoning 사용 가능)
curl -N -X POST $BASE/agent-chat/$SESSION_ID -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"query":"문서의 핵심 내용을 요약하고 근거를 나열해주세요","agent_enabled":true,"agent_id":"builtin-smart-reasoning","knowledge_base_ids":["'$KB_ID'"]}'

# 8) 생성 없이 검색만 수행(구조화된 JSON 결과)
curl -s -X POST $BASE/knowledge-search -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"query":"키워드","knowledge_base_ids":["'$KB_ID'"]}'

질의응답 요청 본문은 knowledge_ids(단일 문서로 제한), web_search_enabled, summary_model_id, mcp_service_ids, skill_names, images / attachment_uploads(멀티모달 첨부 파일) 등의 필드도 지원합니다. 전체 설명은 API 참조: 세션과 채팅을 참고하세요.

세 가지 인증 방식

방식	요청 헤더	용도
JWT	`Authorization: Bearer <token>`	브라우저 / 대화형 호출, 로그인 API에서 발급
API Key	`X-API-Key: <key>`	서버 측 연동. '공간 설정' 또는 `POST /api/v1/tenants/:id/api-keys`에서 생성하며, 세분화된 기능 권한(`retrieve`/`chat`/`ingest`/`manage_kbs` 등)을 지원합니다
공간 지정	`X-Tenant-ID: <id>`	여러 공간에 속한 사용자가 현재 작업 공간 전환

서버 측 연동에는 JWT 대신 API Key를 권장합니다.

bash

# Owner 권한으로 API Key 생성(TENANT_ID는 로그인 응답에서 가져옴)
curl -s -X POST $BASE/tenants/$TENANT_ID/api-keys -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"ci-bot","full_access":true}'
# 이후 모든 요청은 다음 방식으로 변경:
curl -s $BASE/knowledge-bases -H "X-API-Key: <생성 시 반환된 key>"

초기 설정 마법사에 대응하는 API

화면의 마법사 단계마다 독립된 엔드포인트가 있으므로 자체 관리 백엔드를 만들 때 직접 재사용할 수 있습니다.

단계	엔드포인트	설명
현재 설정 읽기	`GET /api/v1/initialization/config/:kbId`	llm / embedding / rerank / multimodal / documentSplitting / nodeExtract / questionGeneration 각 섹션과 `hasFiles` 반환(기존 파일이 있으면 embedding 변경 제한)
Ollama 확인	`GET /api/v1/initialization/ollama/status`, `GET /api/v1/initialization/ollama/models`	Ollama 사용 가능 여부 및 설치된 모델 확인
Ollama 모델 다운로드	`POST /api/v1/initialization/ollama/models/download` → `GET /api/v1/initialization/ollama/download/progress/:taskId`	비동기 다운로드 및 진행 상황 폴링
원격 모델 테스트	`POST /api/v1/initialization/remote/check`, `/initialization/embedding/test`, `/initialization/rerank/check`, `/initialization/asr/check`, `/initialization/multimodal/test`	저장 전 연결 검증
지식 그래프 시험 추출	`POST /api/v1/initialization/extract/text-relation`(`fabri-text` / `fabri-tag`와 함께 예제 생성)	엔터티/관계 추출 결과 미리보기
설정 저장	`POST /api/v1/initialization/initialize/:kbId`(최초) / `PUT /api/v1/initialization/config/:kbId`(업데이트)	데이터베이스에 저장: Model 레코드 생성/업데이트 및 KnowledgeBase 설정 기록

source는 local(Ollama) 또는 원격 공급업체 식별자(openai, deepseek, aliyun, zhipu, siliconflow 등)를 사용합니다. chunkSize의 유효 범위는 100–10000입니다.

전체 과정에서 일어나는 일

문제가 생겼을 때

증상	확인 사항
업로드 후 계속 `processing` 상태	`docker logs WeKnora-docreader` 확인. 큰 파일은 `MAX_FILE_SIZE_MB`(기본 50)와 `WEKNORA_DOCUMENT_PROCESS_TIMEOUT`(기본 2h)의 제한을 받습니다
초기 설정 중 Ollama 확인 실패	컨테이너 내 기본 주소 `http://host.docker.internal:11434`(`OLLAMA_BASE_URL`) 확인. Linux에서는 `extra_hosts: host.docker.internal:host-gateway` 적용 여부를 확인해야 합니다
답변에 인용이 없음 / 검색 결과가 비어 있음	지식 파싱 상태가 `completed`인지 확인하고, `vector_threshold`를 낮추며, embedding 모델이 베이스 생성 당시와 동일한지 확인합니다
가입 탭이 사라짐	`GET /auth/config`의 `registration_mode`를 확인합니다. 값은 `DISABLE_REGISTRATION`뿐 아니라 '설정 → 시스템'의 데이터베이스 설정에서 올 수 있습니다. 초대 링크와 OIDC 최초 로그인은 별도 경로이므로 영향을 받지 않습니다
API Key 요청에서 403 반환	Key의 capabilities에 필요한 기능이 없거나 `knowledge_base_ids` 허용 목록에 대상 베이스가 포함되지 않았습니다

다음 단계: 세부 조정은 설정 상세 안내, 시스템 동작 방식은 전체 아키텍처를 참고하세요.

빠른 시작 ​

시작하기 전에 ​

가입 및 로그인 ​

지식 베이스 생성 및 모델 설정 ​

문서 업로드 ​

질문하기 ​

추가 설정 ​

API로 첫 질의응답 완료하기 ​

세 가지 인증 방식 ​

초기 설정 마법사에 대응하는 API ​

전체 과정에서 일어나는 일 ​

문제가 생겼을 때 ​