> ## 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 (Markdown 変換) | 埋め込み画像を python-docx 経由で `[Figure N]` 位置マーカー付きで抽出 | テキスト抽出のみ; 画像は失われる | | **PPTX / PPT** | markitdown (各スライドのテキスト) | 埋め込み画像を python-pptx 経由で `[Figure N]` マーカーとスライド区切り付きで抽出 | テキスト抽出のみ; スライドビジュアルは失われる | | **XLSX / XLS** | markitdown (テーブル構造を保持) | テキストモードと同じ (テーブルはビジョンの恩恵を受けない) | 同じ | | **画像** (JPG, PNG, GIF, WebP) | N/A | `image_url` ビジョンコンテンツブロックとして送信 | `[Attached image: filename]` として注釈付け — モデルは認識していますがコンテンツを見ることはできません | | **テキストファイル** (TXT, MD, PY, JS, HTML, CSV, JSON) | 直接読み込み / 解析 | N/A (テキストはテキスト) | 同じ | **最大限の視覚的忠実度のために**、アップロード前に DOCX または PPTX ファイルを PDF にエクスポートしてください。PDF ビジョンモードは、テキスト、画像、グラフ、フォーマットのすべてを 1 つの画像でレンダリングします。 ## 仕組み ユーザーが会話にドキュメントをアップロードすると、FIM Oneはファイルタイプとモデル機能に基づいて処理パイプラインを実行します： システムはファイル拡張子とMIMEタイプでドキュメント形式を識別し、適切な抽出パイプラインを選択します。アップロードされた各ファイルはUUID `file_id` でタグ付けされ、メッセージコンテキストに注入されるため、エージェントは `read_uploaded_file` ツール経由で直接アクセスできます。 ビジョン対応の有無に関わらず、システムは常にテキストコンテンツを抽出します。PDFはpdfplumberを使用してページごとのテキストを抽出します。Officeフォーマットはmarkitdownを使用してMarkdown変換を行います。テキストファイルは直接読み込まれます。 モデルが `supports_vision=true` を持ち、ドキュメントがサポートされているタイプの場合： * **PDF（スマート処理）**: 各ページが分析され、テキストが豊富なページはテキストと埋め込み画像を別々に抽出し（トークン節約）、スキャンまたは画像のみのページは設定されたDPIで全ページPNGとしてレンダリングされます（最大の忠実度のため） * **DOCX / PPTX**: 埋め込み画像はドキュメントXMLから `[Figure N]` の位置マーカー付きで抽出されます * **画像**: ビジョンコンテンツブロックとして直接渡されます 抽出されたテキストとビジョンコンテンツはモデルが期待するメッセージ形式にアセンブルされます。テキストと画像はインターリーブされるため、モデルは視覚情報とテキスト情報を相互参照できます。 アップロードされたファイルからのビジョンコンテンツはメッセージメタデータに保存され、会話ターン全体で永続化されます。画像がユーザーアップロード写真から来たか、ドキュメントから抽出されたかに関わらず、後続のメッセージでモデルが参照できるように利用可能なままです。 ## ビジョンモード設定 ドキュメントの処理方法を制御する3つの方法があり、最も具体的なものから最も一般的なものへと列挙されています。 ### 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の1ページPDF | 1,000 -- 2,000トークン | | ビジョンモードの10ページPDF | 10,000 -- 20,000トークン | | 同じ10ページPDFをテキストのみで処理 | 2,000 -- 5,000トークン | | 埋め込まれた1つの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イメージに約4 GBを追加します。代わりに、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ページのみが画像としてレンダリングされます。残りのページはテキストとして抽出されたまま利用可能です。 * **画像品質が重要です。** スタンドアロン画像のアップロードの場合、可能な限り高解像度のオリジナルを使用してください。圧縮または低解像度の画像は、モデルが詳細を抽出する能力を低下させます。