> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 지능형 문서 처리
> FIM One이 업로드된 문서를 AI 에이전트가 이해할 수 있도록 처리하는 방식, PDF, Office 파일 및 이미지에 대한 자동 비전 지원 포함.
FIM One은 업로드된 문서를 자동으로 처리하여 AI 에이전트가 콘텐츠를 이해할 수 있도록 합니다. 모델이 비전을 지원하는 경우, 문서는 완전한 시각적 충실도로 처리됩니다. PDF 페이지는 이미지로 렌더링되고, Office 문서에 포함된 이미지는 위치 참조와 함께 추출됩니다. 비전을 사용할 수 없는 경우, 시스템은 텍스트 추출로 폴백합니다.
비전 콘텐츠는 대화 턴 전체에 걸쳐 유지되므로, 모델은 파일이 업로드된 턴뿐만 아니라 전체 대화 동안 업로드된 문서의 시각적 컨텍스트를 유지합니다.
비전 모드는 기본적으로 자동입니다. 구성한 모델에 비전 지원이 활성화되어 있으면, 업로드된 문서는 해당 형식에 사용 가능한 가장 풍부한 처리 파이프라인을 사용합니다.
## 형식 지원 매트릭스
각 문서 형식에는 전용 처리 파이프라인이 있습니다. 모델이 비전을 지원하는지 여부에 따라 동작이 변경됩니다.
| 형식 | 텍스트 추출 | 비전 모드 (`supports_vision=ON`) | 폴백 (`supports_vision=OFF`) |
| --------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **PDF** | pdfplumber (페이지별 텍스트) | 스마트 처리: 텍스트가 풍부한 페이지는 텍스트 + 임베드된 이미지 추출 (토큰 효율적); 스캔/이미지 전용 페이지는 PyMuPDF를 통해 전체 페이지 PNG로 렌더링 | 텍스트 추출만 수행; 에이전트가 `read_uploaded_file` 도구를 통해 읽음 |
| **DOCX / DOC** | markitdown (마크다운 변환) | python-docx를 통해 `[Figure N]` 위치 마커로 임베드된 이미지 추출 | 텍스트 추출만 수행; 이미지 손실 |
| **PPTX / PPT** | markitdown (각 슬라이드의 텍스트) | python-pptx를 통해 `[Figure N]` 마커 및 슬라이드 구분자로 임베드된 이미지 추출 | 텍스트 추출만 수행; 슬라이드 시각 자료 손실 |
| **XLSX / XLS** | markitdown (테이블 구조 보존) | 텍스트 모드와 동일 (테이블은 비전의 이점을 얻지 못함) | 동일 |
| **이미지** (JPG, PNG, GIF, WebP) | 해당 없음 | `image_url` 비전 콘텐츠 블록으로 전송 | `[Attached image: filename]`으로 주석 처리됨 — 모델이 인식하지만 콘텐츠를 볼 수 없음 |
| **텍스트 파일** (TXT, MD, PY, JS, HTML, CSV, JSON) | 직접 읽기 / 파싱 | 해당 없음 (텍스트는 텍스트) | 동일 |
**최대 시각적 충실도를 위해**, DOCX 또는 PPTX 파일을 업로드하기 전에 PDF로 내보내세요. PDF 비전 모드는 전체 페이지 레이아웃 — 텍스트, 이미지, 차트 및 서식 — 을 모두 하나의 이미지로 렌더링합니다.
## 작동 방식
사용자가 대화에 문서를 업로드하면 FIM One은 파일 유형과 모델 기능을 기반으로 처리 파이프라인을 실행합니다:
시스템은 파일 확장자와 MIME 유형으로 문서 형식을 식별한 후 적절한 추출 파이프라인을 선택합니다. 업로드된 각 파일에는 UUID `file_id`가 태그되며, 이는 메시지 컨텍스트에 주입되어 에이전트가 `read_uploaded_file` 도구를 통해 직접 접근할 수 있습니다.
비전 지원 여부와 관계없이 시스템은 항상 텍스트 콘텐츠를 추출합니다. PDF는 페이지별 텍스트 추출을 위해 pdfplumber를 사용합니다. Office 형식은 Markdown 변환을 위해 markitdown을 사용합니다. 텍스트 파일은 직접 읽습니다.
모델이 `supports_vision=true`를 가지고 있고 문서가 지원되는 유형인 경우:
* **PDF (스마트 처리)**: 각 페이지를 분석합니다 — 텍스트가 풍부한 페이지는 텍스트와 포함된 이미지를 별도로 추출하고(토큰 절약), 스캔되거나 이미지만 있는 페이지는 최대 충실도를 위해 구성된 DPI에서 전체 페이지 PNG로 렌더링합니다
* **DOCX / PPTX**: 포함된 이미지를 문서 XML에서 `[Figure N]` 위치 마커와 함께 추출합니다
* **이미지**: 비전 콘텐츠 블록으로 직접 전달됩니다
추출된 텍스트와 비전 콘텐츠를 모델이 예상하는 메시지 형식으로 조립합니다. 텍스트와 이미지는 인터리빙되어 모델이 시각적 정보와 텍스트 정보를 연관시킬 수 있습니다.
업로드된 파일의 비전 콘텐츠는 메시지 메타데이터에 저장되고 대화 턴 전체에서 지속됩니다. 이미지가 사용자가 업로드한 사진에서 나왔든 문서에서 추출되었든 간에, 모델이 후속 메시지에서 참조할 수 있도록 계속 사용 가능합니다.
## 비전 모드 구성
문서 처리 방식을 제어하는 세 가지 방법이 있으며, 가장 구체적인 것부터 가장 일반적인 것 순서로 나열되어 있습니다.
### 1. 모델별 토글
**Admin > Models > Edit > Advanced**로 이동하여 **Vision Support** 체크박스를 토글합니다. 이것이 주요 제어 방식입니다 — 특정 모델이 이미지 콘텐츠를 수락할 수 있는지 여부를 시스템에 알립니다.
### 2. 전역 환경 변수
환경에서 `DOCUMENT_PROCESSING_MODE`를 설정하여 시스템 전체의 기본 동작을 재정의합니다:
```bash theme={null}
# Use vision when the model supports it (default)
DOCUMENT_PROCESSING_MODE=auto
# Always attempt vision processing, regardless of model config
DOCUMENT_PROCESSING_MODE=vision
# Never use vision — text extraction only
DOCUMENT_PROCESSING_MODE=text
```
### 3. 요청별 매개변수
채팅 API에서 `doc_mode` 매개변수를 전달하여 단일 요청에 대한 처리를 제어합니다:
```json theme={null}
{
"message": "Analyze this financial report",
"doc_mode": "vision",
"attachments": [...]
}
```
`auto` 모드(기본값)는 모델이 `supports_vision=true`를 **가지고 있고** 문서가 비전 처리의 이점을 얻는 유형일 때 비전을 사용합니다. 이것은 대부분의 배포에 권장되는 설정입니다.
## 환경 변수
| 변수 | 기본값 | 설명 |
| --------------------------- | ------ | ------------------------------------------------------------------- |
| `DOCUMENT_PROCESSING_MODE` | `auto` | 처리 전략: `auto` (사용 가능할 때 비전 사용), `vision` (항상 렌더링), `text` (렌더링 안 함) |
| `DOCUMENT_VISION_DPI` | `150` | PDF 렌더링 해상도(인치당 도트 수). 높은 값은 더 나은 품질을 제공하지만 더 많은 토큰을 소비합니다 |
| `DOCUMENT_VISION_MAX_PAGES` | `20` | 이미지로 렌더링할 최대 PDF 페이지 수. 이 한계를 초과하는 페이지는 텍스트 추출로 대체됩니다 |
## 토큰 비용 고려사항
비전 콘텐츠는 일반 텍스트보다 훨씬 더 많은 토큰을 소비합니다. 비용 트레이드오프를 이해하면 시스템을 적절하게 구성하는 데 도움이 됩니다.
**대략적인 추정:**
| 시나리오 | 대략적인 토큰 비용 |
| -------------------- | ------------------- |
| 150 DPI의 PDF 한 페이지 | 1,000 -- 2,000 토큰 |
| 비전 모드의 10페이지 PDF | 10,000 -- 20,000 토큰 |
| 동일한 10페이지 PDF (텍스트만) | 2,000 -- 5,000 토큰 |
| 포함된 DOCX 이미지 하나 | 500 -- 1,500 토큰 |
대용량 문서의 경우, 비전 모드는 텍스트 전용 처리에 비해 비용을 4--10배 증가시킬 수 있습니다. `DOCUMENT_VISION_MAX_PAGES`를 사용하여 이미지로 렌더링되는 페이지 수를 제한하고, 비용에 민감한 워크플로우의 경우 `text` 모드 사용을 고려하세요.
### 비용 최적화 팁
* **`DOCUMENT_VISION_MAX_PAGES`를 합리적인 수준(예: 10)으로 설정** - 일반적인 사용에 적합합니다
* **`DOCUMENT_VISION_DPI`를 150에서 100으로 낮추기** - 이미지 품질이 허용 가능한 경우, 토큰 소비를 약 40% 줄입니다
* **레이아웃이 중요하지 않은 문서에는 `text` 모드 사용** (예: 일반 텍스트 보고서, 스프레드시트)
* **레이아웃이 중요한 문서에는 `vision` 모드 선택적 사용** (예: 송장, 양식, 다이어그램)
## 설계 결정 사항 및 제한 사항
### LibreOffice를 전체 페이지 렌더링에 사용하지 않는 이유
LibreOffice는 DOCX 및 PPTX 파일의 픽셀 완벽한 페이지 렌더링을 생성할 수 있지만, Docker 이미지에 약 4GB를 추가합니다. 대신 FIM One은 python-docx 및 python-pptx를 사용하여 문서 XML에서 직접 임베드된 이미지를 추출합니다. 이 두 라이브러리는 이미 markitdown의 전이적 종속성이므로 추가 설치 오버헤드가 없습니다.
**트레이드오프:** 실제 임베드된 이미지를 전체 품질로 얻을 수 있지만 페이지 레이아웃 컨텍스트는 손실됩니다. `[Figure N]` 위치 표시자는 LLM이 텍스트와 이미지를 연관시키는 데 도움이 되지만, 공간 관계는 정확하기보다는 대략적입니다.
### LibreOffice 없이 손실되는 것
| 손실 요소 | 영향 |
| ------------------------------ | -------------------------------------- |
| 텍스트 서식 (굵게, 기울임, 글꼴 크기) | LLM이 일반 텍스트만 수신 |
| 이미지-텍스트 공간 배치 | `[Figure N]` 마커가 근사하지만 정확한 배치를 표시하지 않음 |
| Office에서 생성한 차트 (이미지로 포함되지 않음) | XML 정의 차트가 추출되지 않음 |
| DOCX의 페이지 머리글 및 바닥글 | markitdown에 의해 부분적으로 보존됨 |
### PDF Vision vs. DOCX/PPTX Vision
비전 처리의 품질은 형식에 따라 다릅니다:
* **PDF** — 스마트한 페이지별 처리. 텍스트가 풍부한 페이지는 텍스트 콘텐츠와 포함된 이미지를 별도로 추출하므로 토큰 효율성이 훨씬 높습니다. 스캔되거나 이미지만 있는 페이지(예: 촬영된 문서, 스캔된 계약서)는 최대 시각적 충실도를 위해 전체 페이지 PNG 이미지로 렌더링됩니다. 이 적응형 접근 방식은 품질과 토큰 비용의 균형을 자동으로 맞춥니다.
* **DOCX / PPTX** — 텍스트 콘텐츠와 추출된 포함 이미지. 대부분의 비즈니스 문서에 적합하지만 페이지 레이아웃과 형식은 보존되지 않습니다.
**권장사항:** 시각적 레이아웃이 중요한 문서(양식, 송장, 복잡한 그래픽이 있는 슬라이드 덱)의 경우 업로드하기 전에 PDF로 내보내십시오.
### 자동 폴백
모델이 비전 지원으로 구성되었지만 런타임에 실제로 이미지 콘텐츠를 거부하는 경우, 시스템은 자동으로 문서 이미지 없이 요청을 다시 시도합니다. 사용자가 업로드한 이미지(예: 사용자가 첨부한 스크린샷)는 재시도 시 유지되며, 문서에서 파생된 이미지만 제거됩니다.
이 폴백 메커니즘은 잘못 구성된 비전 설정으로 인한 작업 실패를 방지합니다. 모델이 지속적으로 폴백되는 것을 확인하면 **Admin > Models**에서 해당 비전 지원 구성을 확인하세요.
## 안전 가드레일
### 파일 무결성 보호
에이전트가 파일을 읽을 수 없을 때(예: 비전이 활성화되지 않은 이미지 기반 PDF), 시스템 수준의 보호장치는 에이전트가 다른 파일의 콘텐츠를 대체하는 것을 방지합니다. 이 보호 없이는 에이전트가 접근 가능한 다른 파일을 읽고 그 콘텐츠를 대상 문서에서 온 것처럼 제시할 수 있습니다. 보호장치는 파일을 읽을 수 없을 때 에이전트가 관련 없는 출처에서 답변을 만들어내는 대신 제한 사항을 정직하게 보고하도록 보장합니다.
### 설명적 오류 안내
`read_uploaded_file` 도구로 파일을 읽을 수 없을 때 오류 메시지에는 다음이 포함됩니다:
* 감지된 파일 유형 및 처리할 수 없는 이유
* 파일이 이미지 기반인 경우 모델에서 비전을 활성화하도록 제안
* 사용자가 시도할 수 있는 대체 접근 방식 (예: 다른 형식으로 내보내기)
이는 사용자가 시행착오 없이 파일 처리 문제를 이해하고 해결하는 데 도움이 됩니다.
## 모범 사례
### 관리자용
* **선택적으로 비전 활성화.** `supports_vision`을 실제로 이미지 입력을 지원하는 모델에만 활성화하세요. 잘못된 구성은 폴백 재시도 사이클에서 토큰을 낭비합니다.
* **`auto` 모드로 시작.** 기본 동작은 대부분의 배포에 적합합니다 — 비전은 유용하고 사용 가능할 때 사용됩니다.
* **토큰 사용량 모니터링.** 비전을 활성화한 후 토큰 소비 대시보드를 확인하세요. 비용이 예상치 않게 급증하면 `DOCUMENT_VISION_MAX_PAGES` 또는 `DOCUMENT_VISION_DPI`를 조정하세요.
* **미리 빌드된 샌드박스 이미지 사용.** `Dockerfile.sandbox`는 문서에 대한 AI 코드 실행에 필요한 일반적인 데이터 과학 패키지(pdfplumber, Pillow, pandas 등)를 포함합니다. `docker compose`를 통해 또는 `docker build -f Dockerfile.sandbox -t fim-sandbox .`로 수동으로 빌드하여 `--network=none` 컨테이너에서 코드 실행이 작동하는지 확인하세요.
### 최종 사용자용
* **PDF가 최고의 결과를 제공합니다.** 시각적 충실도가 중요한 경우 Office 문서를 PDF로 내보낸 후 업로드하세요.
* **스프레드시트는 그대로 사용해도 됩니다.** XLSX 파일은 구조화된 테이블로 추출되므로 비전이 추가 이점을 제공하지 않습니다.
* **큰 PDF는 잘릴 수 있습니다.** 문서가 `DOCUMENT_VISION_MAX_PAGES` 제한을 초과하면 처음 N개 페이지만 이미지로 렌더링됩니다. 나머지 페이지는 여전히 추출된 텍스트로 사용 가능합니다.
* **이미지 품질이 중요합니다.** 독립형 이미지 업로드의 경우 가능하면 고해상도 원본을 사용하세요. 압축되거나 저해상도 이미지는 모델의 세부 정보 추출 능력을 감소시킵니다.