문서 - Cloosphere Guide

관리자 › 설정 › 문서

지식 기반(KBSphere)의 문서 처리 품질은 이 설정에 의해 결정됩니다.

콘텐츠 추출 엔진, 텍스트 분할 방식, 임베딩 모델을 올바르게 구성해야 RAG 검색 정확도가 보장됩니다.

문서 설정 탭 — 관리자 > 설정 > 문서에서 RAG 파이프라인의 모든 설정을 관리합니다

추출 엔진

페이지 상단의 추출 엔진 섹션에서 문서 텍스트 추출에 사용할 엔진 인스턴스를 등록·관리합니다.

추출은 “엔진 하나를 전역으로 고르는” 방식이 아니라, 이름 붙은 인스턴스를 등록해 두고 프로파일에서 확장자별로 골라 쓰는 구조입니다.

엔진 인스턴스 등록

추출 엔진 섹션의 ”+” 버튼으로 인스턴스를 추가하고, 이름과 엔진 타입을 지정합니다. 선택할 수 있는 엔진 타입은 Tika · Docling · Document Intelligence · Mistral OCR · Google Cloud Document AI · LLM 비전 6종입니다(유형별 설명은 콘텐츠 추출 참고). 같은 타입으로 설정이 다른 인스턴스를 여러 개 등록할 수 있습니다.

프로파일에서 사용

등록한 인스턴스는 문서 처리 프로파일에서 기본 엔진으로 고르거나, 확장자 → 엔진 매핑에서 특정 확장자에 연결해 사용합니다.

인스턴스 이름은 등록할 때 직접 짓는 값입니다. 화면 예시의 Default - Primary, LLM Semantic - Primary 처럼 이름에 - Primary 가 붙어 있는 경우가 있는데, 이는 운영자가 그렇게 이름을 지은 것일 뿐 시스템이 붙이는 표시가 아닙니다. Cloosphere 에는 인스턴스를 “Primary”로 지정하는 기능이 없습니다 — 매핑에 없는 확장자가 쓸 엔진은 프로파일마다 기본 엔진 으로 지정합니다.

문서 처리 프로파일

신규 기능 — 문서 추출 방식과 청킹 전략을 묶어 프로파일로 관리할 수 있습니다. 여러 프로파일을 만들어두고 지식 기반(KB)별로 선택하여 사용합니다.

프로파일이란?

기존에는 전역으로 하나의 추출/청킹 설정만 가능했습니다. 프로파일을 사용하면 용도별로 서로 다른 설정 묶음을 정의하고, KB마다 적합한 프로파일을 선택할 수 있습니다. 각 프로파일은 기본 엔진, 파일 확장자별 추출 엔진 매핑, 청킹 설정으로 구성됩니다.

예시:
 • "기본 추출" → 기본 내장 엔진 + 고정 크기 청킹
 • "고정밀 OCR" → Document Intelligence + 테이블 보존
 • "LLM 비전 + 문맥보존" → Vision LLM 추출 + 시맨틱 청킹 + Contextual Chunking

프로파일 관리

문서 설정 페이지 상단의 문서 처리 프로파일 섹션에서 프로파일을 생성하고 관리합니다.

프로파일 생성

+ 새 프로파일 버튼을 클릭하여 프로파일 생성 모달을 엽니다.

프로파일마다 기본 엔진과 확장자 매핑, 청킹 설정을 지정합니다 — Primary 지정 단계는 없습니다

설정 항목	설명	기본값
이름	프로파일 식별 이름	—
기본 엔진	아래 매핑에 등록되지 않은 확장자가 사용할 엔진. `기본 내장 엔진` 또는 등록해 둔 추출 엔진 인스턴스 중 선택	기본 내장 엔진
확장자 → 엔진 매핑	`확장자 추가` 로 행을 만들어 포맷 그룹(PDF · Word · Excel · PowerPoint · Image · HTML · Text · Email · EPUB) 또는 직접 입력한 확장자마다 엔진을 지정. 행에서도 `기본 내장 엔진` 을 고를 수 있음	비어 있음
텍스트 나누기	청킹 전략 (`기본값(캐릭터)` / `토큰(Tiktoken)` / `시맨틱`)	기본값(캐릭터)
Chunk 크기	분할할 청크의 크기	1000
Chunk 오버랩	청크 간 중복 크기	100
청크당 최소 토큰	이보다 작은 청크는 다음 청크와 병합. 비우거나 `0` 이면 비활성	비어 있음
청크당 최대 토큰	이 토큰 수를 넘는 청크는 임베딩 전에 다시 분할. 비우면 전역 기본값, `0` 은 비활성	비어 있음
테이블 보존	청킹 시 표를 쪼개지 않고 앞 텍스트 청크에 붙여 유지	켜짐
문맥 보존 청킹	청크마다 문맥 요약을 덧붙여 검색 정확도를 높임(처리 비용 증가)	아래 주의 참고

문맥 보존 청킹은 문맥 모델 을 함께 지정해야 실제로 동작합니다. 새 프로파일에서는 스위치가 켜진 상태로 표시되지만 모델이 비어 있어 적용되지 않습니다. 사용하려면 모델을 고른 뒤 저장하세요. 또한 채팅에 그때그때 첨부하는 파일에는 적용되지 않고, 지식 기반에 적재하는 문서에만 적용됩니다.

기본 프로파일 설정

프로파일 목록에서 기본값으로 설정 버튼을 클릭하면, 해당 프로파일의 설정이 전역 기본값으로 동기화됩니다. 프로파일을 지정하지 않은 KB는 이 기본 프로파일로 처리됩니다.

KB에서 프로파일 선택

워크스페이스 > 지식 기반 편집 화면에서 문서 처리 프로파일을 선택합니다. 미선택 시 기본 프로파일이 적용됩니다.

기본 프로파일은 삭제할 수 없습니다. 다른 프로파일을 기본값으로 설정한 후에 삭제하세요.

콘텐츠 추출

추출 엔진 인스턴스로 등록할 수 있는 엔진 타입 6종입니다.

인스턴스로 등록한 뒤, 프로파일의 기본 엔진 또는 확장자 → 엔진 매핑 에서 골라 씁니다.

엔진 타입	특징	적합한 경우	추가 설정
Tika	Apache Tika 서버 기반	다양한 파일 포맷 지원 필요	Server URL
Docling	고급 문서 처리 엔진	복잡한 레이아웃의 문서	Server URL
Document Intelligence	Azure AI Document Intelligence	Azure 환경, 정확한 OCR 필요	Endpoint + API Key
Google Cloud Document AI	Google Cloud Document AI	표, 양식, 다단 레이아웃	Location + Processor ID + 서비스 계정 키(JSON). Project ID·Processor Version 은 선택
Mistral OCR	Mistral 기반 OCR	이미지 기반 문서	Mistral API Key
LLM 비전	Vision LLM 기반 추출	복잡한 레이아웃, 차트/이미지 속 텍스트	Vision 모델 + 추출 프롬프트(선택)

기본 내장 엔진은 이 목록에 없습니다. 인스턴스로 등록하는 대상이 아니라, 프로파일의 기본 엔진 셀렉트와 매핑 행에서 기본 내장 엔진 으로 직접 고르는 항목입니다. 추출 엔진을 하나도 등록하지 않으면 모든 문서가 이 내장 엔진으로 처리됩니다.

대부분의 텍스트 기반 문서(PDF, DOCX, TXT)는 기본 내장 엔진으로 충분합니다. 스캔 문서나 이미지가 많은 PDF가 주요 대상이라면 Document Intelligence 또는 Mistral OCR을 권장합니다.

LLM 비전 추출

신규 기능 — Vision을 지원하는 LLM(GPT-4o, Claude 등)에게 페이지 이미지를 직접 보내 마크다운 텍스트로 추출하는 방식입니다.

기존 OCR 엔진 대비 복잡한 레이아웃, 이미지 속 텍스트, 차트 설명에서 높은 정확도를 제공합니다. 동작 흐름:

PDF를 페이지별 이미지로 변환 (2배 해상도 렌더링 — 약 144DPI 수준)
각 페이지 이미지를 Vision LLM에 병렬 전송
LLM이 표/리스트/제목 구조를 유지한 마크다운으로 반환
페이지별로 따로 추출하느라 어긋난 제목 단계(##, ###)를 문서 전체 기준으로 정규화

설정 항목	설명
Vision 모델	시스템에 등록된 Vision 지원 모델 선택 (예: `gpt-4o`)
추출 프롬프트	커스텀 프롬프트 (빈 값이면 기본 프롬프트 사용)

LLM 비전은 페이지마다 LLM 호출이 발생합니다. 10페이지 PDF → 약 11회 호출(페이지 추출 10회 + 제목 단계 정규화 1회). 대용량 문서는 처리 시간과 비용을 고려하세요.

제목 단계 정규화는 본문 전체가 아니라 제목 줄만 모아 LLM에 보내고, 돌려받은 단계 값만 반영합니다. 제목 문구 자체는 바뀌지 않으며, 이 호출이 실패해도 추출 결과는 그대로 유지됩니다. 페이지가 1장뿐이면 이 단계는 건너뜁니다.

LLM 비전은 pypdfium2 패키지가 필요합니다. 미설치 시 이 엔진을 선택한 PDF 업로드가 실패합니다. 처리 대상은 PDF와 이미지 파일이며, PPTX·DOCX 같은 오피스 파일은 이 엔진으로 추출할 수 없습니다.

텍스트 분할

추출된 텍스트를 검색에 적합한 크기로 분할하는 방식을 설정합니다.

설정	기본값	설명
Text Splitter	Character	`Character`: 문자 수 기준 분할. `Token`: Tiktoken 토큰 기준 분할. `Semantic`: 의미 기반 분할
Chunk Size	1000	분할할 청크의 크기 (문자 수 또는 토큰 수). Semantic 모드에서는 참고값
Chunk Overlap	100	청크 간 중복 크기 (문맥 연결 유지)

Chunk Size를 어떻게 정해야 하나요?

크기	장점	단점	권장 상황
작게 (500 이하)	정밀한 검색	문맥이 잘릴 수 있음	FAQ, 짧은 문단
중간 (1000)	균형 잡힌 성능	—	대부분의 경우 (기본값)
크게 (2000 이상)	넓은 문맥 유지	검색 정밀도 저하	긴 서술형 문서

Chunk Overlap은 왜 필요한가요?

청크 경계에서 문장이 잘리면 검색 시 관련 내용을 놓칠 수 있습니다. 오버랩을 설정하면 앞뒤 청크가 일부 텍스트를 공유하여 문맥 연결을 유지합니다. 기본값 100은 대부분의 경우 적절합니다.

Bypass Embedding and Retrieval 옵션을 활성화하면 텍스트 분할과 임베딩을 건너뛰고 문서 전체를 LLM 컨텍스트에 직접 주입합니다. 소규모 문서에서만 사용하세요 — 대용량 문서는 토큰 한도를 초과할 수 있습니다.

시맨틱 청킹

신규 기능 — 고정 크기 대신 문장 간 의미 유사도를 기준으로 청크를 분리하는 방식입니다.

Text Splitter를 Semantic으로 설정하면, 문장을 임베딩 벡터로 변환한 후 인접 문장 간 유사도가 급격히 떨어지는 지점에서 청크 경계를 자동 결정합니다.

	고정 크기 (Character/Token)	시맨틱 (Semantic)
분리 기준	글자 수 / 토큰 수	의미 유사도 변화
장점	빠르고 예측 가능	주제 경계에서 분리, 검색 정확도 향상
단점	문장/문단 중간 절단 가능	임베딩 엔진 필요, 처리 시간 증가
권장	일반적인 문서	주제가 자주 전환되는 긴 문서

시맨틱 청킹은 임베딩 엔진이 설정되어 있어야 동작합니다. 임베딩 엔진이 미설정 상태에서 Semantic을 선택하면 오류가 발생합니다.

테이블 보존

신규 기능 — 문서 내 테이블(HTML/마크다운 형식)을 분리하지 않고 통째로 보존하는 기능입니다.

일반 청킹 시 테이블이 여러 청크로 나뉘어 행/열 정보가 유실될 수 있습니다. 테이블 보존을 활성화하면:

문서에서 테이블(HTML <table>, 마크다운 |...|)을 자동 탐지
텍스트 부분만 일반 청킹 수행
테이블은 가장 인접한 텍스트 청크에 통째로 붙임
청크 크기를 초과하는 대형 테이블은 헤더를 유지하면서 행 단위로 분할

프로파일 고급 설정의 테이블 보존 (Preserve Tables) 옵션으로 제어합니다 (기본값: 활성).

표가 많은 재무보고서, 기술 사양서 등에서 특히 효과적입니다. 테이블 내 특정 셀 값으로 검색 시 정확도가 크게 향상됩니다.

문맥 보존 (Contextual Chunking)

신규 기능 — 각 청크에 전체 문서의 맥락 요약을 LLM이 생성하여 앞에 추가합니다. Anthropic의 Contextual Retrieval 기법을 구현한 기능입니다.

긴 문서의 뒷부분 청크에서는 앞부분의 맥락 정보가 소실되어 검색 매칭이 실패할 수 있습니다. 문맥 보존을 활성화하면:

청킹 완료 후 각 청크에 대해 LLM 호출
“이 청크가 전체 문서에서 어떤 위치와 맥락인지” 요약을 생성
요약을 청크 앞에 추가하여 벡터화

[문맥 보존 전]
  청크: "결론적으로 초기 가설이 확인되었다."
  → "A 가설"이 뭔지 알 수 없음 → 검색 실패

[문맥 보존 후]
  청크: "이 청크는 A 가설 검증 보고서의 결론부이며, 50개 실험 결과를
  종합한 최종 판단을 담고 있다.

  결론적으로 초기 가설이 확인되었다."
  → 맥락 포함 → 검색 성공

설정 항목	설명
Contextual Chunking	활성/비활성 토글
모델	문맥 요약에 사용할 LLM 모델

청크 수만큼 LLM 호출이 발생합니다. 100개 청크 문서 → 100회 LLM 호출. 대용량 문서를 다수 업로드하면 API 비용이 크게 증가할 수 있습니다. 소규모 문서나 중요 문서에 선별적으로 사용하세요.

임베딩 설정

문서를 벡터로 변환하는 임베딩 엔진과 모델을 설정합니다.

설정 항목	기본값	설명
임베딩 모델 엔진	SentenceTransformers	벡터 변환에 사용할 서비스
임베딩 모델	`all-MiniLM-L6-v2`	사용할 모델 이름
배치 크기	32	한 번에 처리할 문서 수 (Ollama, OpenAI, Azure만 표시)
임베딩 차원	0 (자동)	벡터 차원 수. 0이면 모델 기본값 사용

임베딩 모델을 변경하면 기존 문서의 벡터와 호환되지 않습니다. 모델 변경 후 모든 지식 기반을 재인덱싱해야 합니다.

지원 엔진:

로컬 환경에서 실행되는 오픈소스 임베딩 엔진입니다.

설정 항목	설명
모델	HuggingFace 모델명 (예: `sentence-transformers/all-MiniLM-L6-v2`)

설정 항목	설명
API URL	OpenAI API Endpoint
API Key	API 인증 키
모델	예: `text-embedding-3-small`

설정 항목	설명
API URL	Azure OpenAI Endpoint
API Key	Azure 인증 키
API Version	API 버전

설정 항목	설명
API URL	Ollama 서버 주소
모델	예: `nomic-embed-text`

설정 항목	설명
Project ID	Google Cloud 프로젝트 ID
Location	리전 (기본: `us-central1`)
Service Account Key	Global 키 또는 Custom JSON 키

Google Gemini 임베딩 API를 사용합니다.

설정 항목	설명
API Key	Gemini API 인증 키
모델	임베딩 모델명 (예: `text-embedding-004`)

파일 업로드 제한

설정 항목	기본값	설명
최대 파일 크기	무제한	단일 파일 업로드 최대 크기 (MB 단위)
최대 파일 수	무제한	채팅 1회에 동시 사용 가능한 파일 수
허용 파일 확장자	전체 허용	콤마로 구분 (예: `pdf, docx, txt`). 빈 값 = 모든 확장자 허용
PDF 변환 확장자	비활성	LibreOffice로 PDF 변환할 확장자 (예: `pptx, docx, xlsx`). LibreOffice 설치 필요

질의예시 생성 (Question Generation)

문서 청크마다 “사용자가 할 법한 질문”을 LLM이 미리 생성하여 검색 정확도를 높이는 기능입니다.

설정	기본값	설명
활성화	OFF	토글로 켜기
모델	—	질문 생성에 사용할 LLM 선택
청크당 최대 질문 수	10	1~20 범위
질문 벡터 가중치	0.5	0.0(콘텐츠만) ~ 1.0(질문만). 0.5 = 동등 가중

활성화하면 문서 처리 시 LLM 호출이 추가됩니다. 처리 시간과 비용이 증가하므로, 검색 정확도가 부족한 경우에만 사용하세요.

클라우드 스토리지 연동

외부 클라우드 스토리지에서 지식 기반에 문서를 가져올 수 있습니다.

이 설정은 토글만 제공하며, 실제 인증 정보는 환경 변수로 설정해야 합니다.

스토리지	토글	필요한 환경 변수
Google Drive	ON/OFF	`GOOGLE_DRIVE_CLIENT_ID`, `GOOGLE_DRIVE_API_KEY`
OneDrive	ON/OFF	`ONEDRIVE_CLIENT_ID`
SharePoint	ON/OFF	`ONEDRIVE_CLIENT_ID_BUSINESS`, `SHAREPOINT_TENANT_ID`, `SHAREPOINT_SITE_URL`

환경 변수가 설정되어 있어야 토글을 켤 수 있습니다. 토글을 켜면 지식 기반의 “내용 추가” 메뉴에 해당 클라우드 소스가 표시됩니다.

재인덱싱 및 초기화

아래 작업은 되돌릴 수 없습니다. 실행 전 반드시 확인하세요.

작업	설명	영향 범위
지식 기반 재인덱싱	모든 지식 기반의 벡터 인덱스를 재구축	지식 기반 전체 (시간 소요)
벡터 스토리지 초기화	Vector DB의 모든 데이터 삭제	모든 벡터 삭제 → 재인덱싱 필요
업로드 디렉토리 초기화	서버에 업로드된 파일 전체 삭제	원본 파일 삭제

재인덱싱이 필요한 경우

임베딩 모델을 변경했을 때
검색 엔진(Vector DB)을 변경했을 때
청크 크기/오버랩을 변경했을 때
문서 처리에 문제가 발생했을 때

지식 기반

지식 기반 생성 및 문서 관리 — KB별 프로파일 선택

검색 엔진

Vector DB 및 검색 파라미터 설정

동적 필터

지식 기반 메타데이터 필터 설정

​추출 엔진

​문서 처리 프로파일

​프로파일이란?

​프로파일 관리

​콘텐츠 추출

​LLM 비전 추출

​텍스트 분할

​시맨틱 청킹

​테이블 보존

​문맥 보존 (Contextual Chunking)

​임베딩 설정

​파일 업로드 제한

​질의예시 생성 (Question Generation)

​클라우드 스토리지 연동

​재인덱싱 및 초기화

​재인덱싱이 필요한 경우

​관련 페이지

지식 기반

검색 엔진

동적 필터

추출 엔진

문서 처리 프로파일

프로파일이란?

프로파일 관리

콘텐츠 추출

LLM 비전 추출

텍스트 분할

시맨틱 청킹

테이블 보존

문맥 보존 (Contextual Chunking)

임베딩 설정

파일 업로드 제한

질의예시 생성 (Question Generation)

클라우드 스토리지 연동

재인덱싱 및 초기화

재인덱싱이 필요한 경우

관련 페이지