> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt > Use this file to discover all available pages before exploring further. # 문서 > 문서 처리 프로파일, 콘텐츠 추출, 임베딩 엔진, 검색 파라미터를 구성합니다. 관리자 › 설정 › 문서 지식 기반(KBSphere)의 문서 처리 품질은 이 설정에 의해 결정됩니다. * 콘텐츠 추출 엔진, 텍스트 분할 방식, 임베딩 모델을 올바르게 구성해야 RAG 검색 정확도가 보장됩니다. 문서 설정 탭 *** ## 추출 엔진 페이지 상단의 **추출 엔진** 섹션에서 문서 텍스트 추출에 사용할 **엔진 인스턴스**를 등록·관리합니다. * 추출은 "엔진 하나를 전역으로 고르는" 방식이 아니라, **이름 붙은 인스턴스를 등록해 두고 프로파일에서 확장자별로 골라 쓰는** 구조입니다. **추출 엔진** 섹션의 **"+" 버튼**으로 인스턴스를 추가하고, 이름과 엔진 유형(Default, LLM 비전, Document Intelligence 등 — 유형별 설명은 [콘텐츠 추출](#콘텐츠-추출) 참고)을 지정합니다. 같은 유형으로 설정이 다른 인스턴스를 여러 개 등록할 수 있습니다. 인스턴스를 **Primary**로 지정합니다. 프로파일에서 특정 확장자를 개별 인스턴스에 매핑하지 않으면, Primary 인스턴스가 기본 추출기로 사용됩니다. 등록된 인스턴스는 `이름 - Primary` 형태로 표시되며(예: `Default - Primary`, `LLM Semantic - Primary`), 프로파일의 확장자 매핑에서 이 이름으로 참조됩니다. *** ## 문서 처리 프로파일 **신규 기능** — 문서 추출 방식과 청킹 전략을 묶어 **프로파일**로 관리할 수 있습니다. 여러 프로파일을 만들어두고 지식 기반(KB)별로 선택하여 사용합니다. ### 프로파일이란? 기존에는 전역으로 하나의 추출/청킹 설정만 가능했습니다. 프로파일을 사용하면 **용도별로 서로 다른 설정 묶음**을 정의하고, KB마다 적합한 프로파일을 선택할 수 있습니다. 각 프로파일은 **파일 확장자별 추출 엔진 매핑**(예: `.pdf → Default - Primary`)과 **청킹 설정**으로 구성됩니다. ``` 예시: • "기본 추출" → 기본 엔진 + 고정 크기 청킹 • "고정밀 OCR" → Document Intelligence + 테이블 보존 • "LLM 비전 + 문맥보존" → Vision LLM 추출 + 시맨틱 청킹 + Contextual Chunking ``` ### 프로파일 관리 문서 설정 페이지 상단의 **문서 처리 프로파일** 섹션에서 프로파일을 생성하고 관리합니다. **+ 새 프로파일** 버튼을 클릭하여 프로파일 생성 모달을 엽니다. | 설정 항목 | 설명 | 기본값 | | -------------- | ---------------------------------------------------------------------------------------- | :-------: | | **이름** | 프로파일 식별 이름 | — | | **확장자별 추출 엔진** | 파일 확장자(.pdf, .docx, .xls 등)별로 사용할 [추출 엔진 인스턴스](#추출-엔진)를 매핑. 매핑하지 않은 확장자는 Primary 인스턴스 사용 | Primary | | **PDF 이미지 추출** | PDF 내 이미지 텍스트 추출 여부 | OFF | | **텍스트 분할 방식** | 청킹 전략 (고정 크기 / 시맨틱) | Character | | **청크 크기** | 분할할 청크의 크기 | 1000 | | **청크 오버랩** | 청크 간 중복 크기 | 100 | | **고급 설정** | 테이블 보존, 문맥 보존, 엔진별 상세 설정 | — | 프로파일 목록에서 **기본값으로 설정** 버튼을 클릭하면, 해당 프로파일의 설정이 **전역 기본값**으로 동기화됩니다. 프로파일을 지정하지 않은 KB는 이 기본 프로파일로 처리됩니다. **워크스페이스 > 지식 기반** 편집 화면에서 문서 처리 프로파일을 선택합니다. 미선택 시 기본 프로파일이 적용됩니다. 기본 프로파일은 삭제할 수 없습니다. 다른 프로파일을 기본값으로 설정한 후에 삭제하세요. *** ## 콘텐츠 추출 [추출 엔진](#추출-엔진) 인스턴스로 만들 수 있는 **엔진 유형**입니다. * 각 유형을 인스턴스로 등록한 뒤, 프로파일에서 확장자별로 매핑해 사용합니다. | 엔진 | 특징 | 적합한 경우 | 추가 설정 | | ------------------------- | ------------------------------ | ---------------------- | -------------------------------------- | | **기본 (Default)** | 내장 텍스트 추출기 | 간단한 텍스트 문서 | PDF Extract Images 토글 | | **Tika** | Apache Tika 서버 기반 | 다양한 파일 포맷 지원 필요 | Server URL (기본: `http://tika:9998`) | | **Docling** | 고급 문서 처리 엔진 | 복잡한 레이아웃의 문서 | Server URL (기본: `http://docling:5001`) | | **Document Intelligence** | Azure AI Document Intelligence | Azure 환경, 정확한 OCR 필요 | Endpoint + API Key | | **Document AI** | Google Cloud Document AI | 표, 양식, 다단 레이아웃 | Project ID + Processor ID + Location | | **Mistral OCR** | Mistral 기반 OCR | 이미지 기반 문서 | Mistral API Key | | **LLM 비전** | Vision LLM 기반 추출 | 복잡한 레이아웃, 차트/이미지 속 텍스트 | Vision 모델 ID + 프롬프트 (선택) | 대부분의 텍스트 기반 문서(PDF, DOCX, TXT)는 기본 엔진으로 충분합니다. 스캔 문서나 이미지가 많은 PDF가 주요 대상이라면 **Document Intelligence** 또는 **Mistral OCR**을 권장합니다. ### LLM 비전 추출 **신규 기능** — Vision을 지원하는 LLM(GPT-4o, Claude 등)에게 페이지 이미지를 직접 보내 마크다운 텍스트로 추출하는 방식입니다. 기존 OCR 엔진 대비 **복잡한 레이아웃, 이미지 속 텍스트, 차트 설명**에서 높은 정확도를 제공합니다. **동작 흐름:** 1. PDF를 페이지별 이미지로 변환 (300DPI급) 2. 각 페이지 이미지를 Vision LLM에 병렬 전송 3. LLM이 표/리스트/제목 구조를 유지한 마크다운으로 반환 4. 인접 페이지 경계의 끊긴 문장을 자동 보정 | 설정 항목 | 설명 | | ------------- | -------------------------------------- | | **Vision 모델** | 시스템에 등록된 Vision 지원 모델 선택 (예: `gpt-4o`) | | **추출 프롬프트** | 커스텀 프롬프트 (빈 값이면 기본 프롬프트 사용) | LLM 비전은 **페이지 수 × LLM 호출**이 발생합니다. 10페이지 PDF → 약 19회 호출(추출 10회 + 경계 보정 9회). 대용량 문서는 처리 시간과 비용을 고려하세요. LLM 비전은 **PyMuPDF** 패키지가 필요합니다. 미설치 시 이 엔진을 선택한 문서 업로드가 실패합니다. 배포 환경에서 PyMuPDF 설치 여부를 확인하세요. *** ## 텍스트 분할 추출된 텍스트를 검색에 적합한 크기로 분할하는 방식을 설정합니다. | 설정 | 기본값 | 설명 | | ----------------- | :-------: | ------------------------------------------------------------------------- | | **Text Splitter** | Character | `Character`: 문자 수 기준 분할. `Token`: Tiktoken 토큰 기준 분할. `Semantic`: 의미 기반 분할 | | **Chunk Size** | 1000 | 분할할 청크의 크기 (문자 수 또는 토큰 수). Semantic 모드에서는 참고값 | | **Chunk Overlap** | 100 | 청크 간 중복 크기 (문맥 연결 유지) | | 크기 | 장점 | 단점 | 권장 상황 | | :----------: | -------- | ----------- | ----------------- | | 작게 (500 이하) | 정밀한 검색 | 문맥이 잘릴 수 있음 | FAQ, 짧은 문단 | | 중간 (1000) | 균형 잡힌 성능 | — | **대부분의 경우 (기본값)** | | 크게 (2000 이상) | 넓은 문맥 유지 | 검색 정밀도 저하 | 긴 서술형 문서 | 청크 경계에서 문장이 잘리면 검색 시 관련 내용을 놓칠 수 있습니다. 오버랩을 설정하면 앞뒤 청크가 일부 텍스트를 공유하여 문맥 연결을 유지합니다. 기본값 100은 대부분의 경우 적절합니다. **Bypass Embedding and Retrieval** 옵션을 활성화하면 텍스트 분할과 임베딩을 건너뛰고 문서 전체를 LLM 컨텍스트에 직접 주입합니다. 소규모 문서에서만 사용하세요 — 대용량 문서는 토큰 한도를 초과할 수 있습니다. ### 시맨틱 청킹 **신규 기능** — 고정 크기 대신 **문장 간 의미 유사도**를 기준으로 청크를 분리하는 방식입니다. Text Splitter를 **Semantic**으로 설정하면, 문장을 임베딩 벡터로 변환한 후 인접 문장 간 유사도가 급격히 떨어지는 지점에서 청크 경계를 자동 결정합니다. | | 고정 크기 (Character/Token) | 시맨틱 (Semantic) | | --------- | ----------------------- | --------------------- | | **분리 기준** | 글자 수 / 토큰 수 | 의미 유사도 변화 | | **장점** | 빠르고 예측 가능 | 주제 경계에서 분리, 검색 정확도 향상 | | **단점** | 문장/문단 중간 절단 가능 | 임베딩 엔진 필요, 처리 시간 증가 | | **권장** | 일반적인 문서 | 주제가 자주 전환되는 긴 문서 | 시맨틱 청킹은 임베딩 엔진이 설정되어 있어야 동작합니다. 임베딩 엔진이 미설정 상태에서 Semantic을 선택하면 오류가 발생합니다. ### 테이블 보존 **신규 기능** — 문서 내 테이블(HTML/마크다운 형식)을 분리하지 않고 통째로 보존하는 기능입니다. 일반 청킹 시 테이블이 여러 청크로 나뉘어 행/열 정보가 유실될 수 있습니다. **테이블 보존**을 활성화하면: 1. 문서에서 테이블(HTML ``, 마크다운 `|...|`)을 자동 탐지 2. 텍스트 부분만 일반 청킹 수행 3. **테이블은 가장 인접한 텍스트 청크에 통째로 붙임** 4. 청크 크기를 초과하는 대형 테이블은 헤더를 유지하면서 행 단위로 분할 프로파일 고급 설정의 **테이블 보존 (Preserve Tables)** 옵션으로 제어합니다 (기본값: 활성). 표가 많은 재무보고서, 기술 사양서 등에서 특히 효과적입니다. 테이블 내 특정 셀 값으로 검색 시 정확도가 크게 향상됩니다. ### 문맥 보존 (Contextual Chunking) **신규 기능** — 각 청크에 전체 문서의 맥락 요약을 LLM이 생성하여 앞에 추가합니다. Anthropic의 Contextual Retrieval 기법을 구현한 기능입니다. 긴 문서의 뒷부분 청크에서는 앞부분의 맥락 정보가 소실되어 검색 매칭이 실패할 수 있습니다. 문맥 보존을 활성화하면: 1. 청킹 완료 후 각 청크에 대해 LLM 호출 2. "이 청크가 전체 문서에서 어떤 위치와 맥락인지" 요약을 생성 3. 요약을 청크 앞에 추가하여 벡터화 ``` [문맥 보존 전] 청크: "결론적으로 초기 가설이 확인되었다." → "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 및 검색 파라미터 설정 지식 기반 메타데이터 필터 설정