문서 채팅

문서 채팅을 사용하면 Libre WebUI가 업로드된 문서를 검색하고 관련 발췌문을 채팅 문맥에 전달할 수 있습니다.

지원 파일

현재 지원되는 업로드:

PDF(페이지별 출처 포함)
평문 및 로그
Markdown(.md, .markdown, .mdx, 섹션별 출처 포함)
HTML
Word 문서(.docx)
프레젠테이션(.pptx, 슬라이드별 출처 포함)
스프레드시트(.xlsx, 시트별 출처 포함) 및 CSV/TSV
소스 코드(TypeScript, Python, Go, Rust, SQL, YAML 및 기타 일반 언어)
이미지(.png, .jpg, .webp, .gif) — 설정한 비전 모델(설정 → 기본값 → 비전 모델)이 텍스트를 읽습니다.
오디오(.wav, .webm) — 음성 입력과 동일한 STT 접근 게이트 뒤에서 음성 인식 제공자를 통해 전사합니다.
최대 파일 크기: 10 MB

Office 형식은 저장소 내의 제한된 파서로 압축을 해제합니다. 서버 프로세스에서 제3자 문서 라이브러리를 실행하지 않습니다. 같은 범위에 동일한 바이트를 다시 업로드하면 두 번 처리하지 않고 중복 제거합니다.

이미지와 오디오 추출은 이미 설정한 제공자로 라우팅됩니다. 로컬 OCR 또는 음성 엔진은 포함되지 않으며, 선택한 모델 호출 외에는 인스턴스 밖으로 아무것도 나가지 않습니다. 텍스트 레이어가 없는 PDF(스캔)도 같은 방식으로 처리합니다. 포함된 JPEG 페이지 이미지를 복구하고 페이지별 출처와 함께 비전 모델로 읽습니다. 다른 이미지 인코딩(CCITT fax, JBIG2)으로 저장된 스캔에서는 여전히 텍스트를 얻지 못합니다. 비전 모델 또는 STT 제공자가 설정되지 않으면 업로드가 실패로 표시되고 설정 → 문서에 이유가 나타납니다.

파일은 백엔드에서 처리되어 나머지 애플리케이션 데이터와 함께 저장됩니다.

검색 모드

Libre WebUI는 두 가지 검색 모드를 지원합니다.

모드	사용 조건	참고
키워드 검색	항상 사용 가능	BM25 순위. 임베딩 모델 불필요
하이브리드 검색	설정에서 임베딩 활성화	reciprocal-rank fusion으로 벡터 순위와 BM25 결합

임베딩을 활성화하면 모든 쿼리가 두 순위를 모두 실행해 병합합니다. 정확한 용어 일치는 의미상 비슷하지만 모호한 청크보다 높은 순위를 얻을 수 있고, 아직 임베딩이 생성 중인 청크도 어휘 검색을 통해 접근할 수 있습니다. 임베딩이 실패하거나 비활성화되면 문서 검색은 순수 키워드 일치로 대체됩니다.

어휘 점수는 접근 가능한 청크를 대상으로 프로세스 내에서 계산합니다. Libre는 문서 청크용 디스크 전문 인덱스를 의도적으로 유지하지 않습니다. 청크 텍스트가 암호화되어 저장되므로 토큰 인덱스는 암호문 옆에 평문을 영구 저장하게 되기 때문입니다. 청크가 어휘 순위에 들어가려면 쿼리 단어 하나 이상을 완전히 포함해야 합니다. 따라서 ALPHA_BETA_GAMMA 같은 복합 식별자는 일부 조각만 공유하는 텍스트를 표시하지 않습니다.

공유받은 지식 컬렉션은 두 순위에 자동으로 참여합니다. 접근 제어는 벡터 쿼리 안에서 강제됩니다. 권한이 인덱스 ACL에 게시되므로 공유를 취소하면 다시 임베딩할 필요 없이 다음 검색부터 해당 문서가 숨겨집니다.

의미 검색 활성화

임베딩 모델을 설치합니다.

ollama pull nomic-embed-text

그런 다음 설정에서 임베딩을 활성화합니다. 로컬 Ollama 임베딩 모델 또는 임베딩 기능을 가진 제공자 플러그인을 사용할 수 있습니다.

기본 임베딩 설정:

모델: nomic-embed-text
청크 크기: 1000자
청크 겹침: 200자
유사도 임계값: 0.3

인용 및 전체 문서 모드

검색된 발췌문에는 출처 파일명, 청크 인덱스, 검색 점수와, 구간 맵이 있는 형식의 경우 발췌문이 나온 페이지·슬라이드·시트·Markdown 섹션이 포함됩니다. 채팅 문맥은 각 발췌문에 위치를 표시하고, 대화의 출처 영역은 문서 아래에 인용 위치를 나열합니다.

각 채팅은 출처 영역에서 전체 문서 모드로 전환할 수도 있습니다. 검색된 발췌문 대신 범위 안의 모든 문서에서 추출한 전체 내용을 메시지와 함께 보냅니다. 토큰 보호 장치(FULL_DOCUMENT_CONTEXT_MAX_TOKENS, 기본값 32000)가 모델의 문맥 창을 보호합니다. 첨부 문서가 이를 넘으면 검색 방식으로 대체되고 출처 영역에 이유가 표시됩니다.

업로드 및 검색

문서 컨트롤에서 지원 파일을 업로드합니다.
처리가 끝날 때까지 기다립니다.
채팅에서 질문합니다.
Libre WebUI가 해당 세션의 관련 청크를 검색해 문맥으로 포함합니다.

프롬프트 예:

Summarize the uploaded document in five bullets.
What deadlines are mentioned in the PDF?
Find the section that talks about pricing.
Compare the uploaded policy with this proposed change.

API 엔드포인트

엔드포인트	용도
`POST /api/documents/upload`	지원 문서 업로드
`GET /api/documents`	업로드된 문서 목록
`GET /api/documents/session/:sessionId`	채팅 세션의 문서 목록
`POST /api/documents/search`	문서 검색
`DELETE /api/documents/:documentId`	문서 삭제
`GET /api/documents/embeddings/status`	임베딩 상태 보기
`POST /api/documents/embeddings/regenerate`	임베딩 다시 생성

권장 사항

현재 작업에 필요한 업로드만 유지하세요.
텍스트 기반 PDF를 우선하세요. 스캔 PDF도 비전 모델로 처리되지만 페이지마다 모델 호출 비용이 듭니다.
임베딩 모델을 바꾼 후 임베딩을 다시 생성하세요.
의미 검색에서 유용한 문맥을 놓치면 유사도 임계값을 낮추세요.
결과에 잡음이 많으면 임계값을 높이세요.

지원 파일​

검색 모드​

의미 검색 활성화​

인용 및 전체 문서 모드​

업로드 및 검색​

API 엔드포인트​

권장 사항​

관련 문서​