ファイルを分析

Analyze Files ツールを使用すると、エージェントは LLM を使用してファイルの内容を処理し、推論を行うことができます。

ファイルの分析ツールを追加します

Analyze Files ツールをエージェントに追加するには、次の手順を実行します。

1. ファイル入力を定義します。[データ マネージャー] パネルで、エージェント スキーマの各ファイル入力に対して引数を追加します。

   図 1. ファイル入力引数の作成

   

   入力引数は、{{exampleInput}} という構文を使用してユーザー プロンプトで明示的に参照する必要があります。参照されていない入力引数は無視されるため、エージェントのスコアに影響を与える可能性があります。

   • ファイルが 1 つの場合は、引数の種類を [File] に設定し、ユーザー プロンプトで参照します。たとえば、「次のレポートを分析して主な結果を要約してください: {{reportFile}}」とします。
   • 複数のファイルを渡すには、引数の種類を Array に、項目の種類を File に設定してから、ユーザー プロンプトでその引数を名前で参照します。さらに、実行時の指示に任意の文字列引数を追加することもできます。以下に例を示します。

   Analyze the following report files and summarize the key findings.
   
   ## Inputs
   - Report files: {{reportFiles}}
   - Additional instructions (optional): {{analysisInstructions}}
   

   この例では、reportFiles は File の Array 型の引数、analysisInstructions は String 型の引数 (任意) です。両方を [データ マネージャー] パネルで定義する必要があります。

   

   

2. Analyze Files ツールをエージェント定義に追加します。

   1. [ツール] パネルで [ツールを追加] を選択します。
   2. [組み込みツール] カテゴリから [Analyze Files] を選択します。
   3. ツールの名前と説明を更新して、エージェントがツールをいつ使用すべきかをより適切に判断できるようにします。名前と説明は、エージェントの計画フェーズのガイドです。つまり、エージェントがいつツールを呼び出すべきかを決定します。実行時にツールがファイルをどのように処理するかを決定するものではありません。

   

3. ツールの入力を設定します。このツールは、次の 2 つの主要な入力で事前設定されています。

   • attachments (配列): ツールに渡すファイルをエージェントに指示する、プロンプトで定義された入力です。このフィールドには、ユーザー プロンプトで参照されているファイル入力 ({{reportFiles}} など) をエージェントがどのように使用すべきかの説明を入力します。エージェントは実行時に、参照されているそれらのファイルを、この入力に自動的にマッピングします。例: 「ユーザー プロンプトで指定されているファイル (例: {{reportFiles}}) を分析の入力として使用してください。」
   • analysisTask (文字列): ツールが呼び出された後に、ファイルを処理する方法を LLM に指示する実行時の指示です (例: 「これらのレポートを分析してください。レポートのタイトル、事業計画概要、重要度別の主な知見、実用的な推奨事項、全体的な感情を抽出してください」)。これはツールの名前や説明とは異なります。ツールの名前や説明では、エージェントがツールを呼び出すタイミングを制御します。ユース ケースに含まれるファイルが 1 つだけである場合は、それに応じて添付ファイルを説明できます (例: 「{{reportFile}} で提供されているファイルを使用してください...」)。

4. 入力ファイルを使用してエージェントを実行します。

   1. 次の手順を実行して [デバッグ設定] ウィンドウを開きます。
      1. [プロジェクトの引数] タブに移動します。
      2. reportFiles 引数にバインドされている入力ファイルをアップロードします。
   2. [保存] を選択してデバッグ セッションを実行します。

   

5. エージェントの実行後、下部のパネルで実行トレースを確認します。

これで Analyze Files ツールがエージェントに追加され、ファイル入力を処理するように設定されます。[実行証跡] パネルの実行トレースに、実行中に各添付ファイルがどのように処理されたかが表示されます。

添付ファイルのトレース

Analyze Files ツールを使用すると、すべてのファイルの入力と出力が [実行証跡] パネルの [履歴] タブにキャプチャされます。このトレースにより、エージェントの実行中に添付ファイルがどのように処理されたかを詳細に可視化できます。

ファイルごとに、トレースには以下が表示されます。

• ID: 添付ファイルの一意の識別子です。

• 名前: 元のファイル名です (例: 1.jpg)。

• MIME タイプ: 検出されたファイルの種類です ( image/jpegなど)。

  図 2. [実行証跡] でのファイルの分析

  

実行トレースから [ツールの呼び出し] を選択し、[ファイル] タブに移動してファイルをダウンロードします。

図 3.トレースからファイルをダウンロードする方法

ファイル内容の PII のマスク

AI Trust Layer のポリシーで PII の機内マスクを有効化すると、ファイルの分析ツールで処理されるファイルの内容に自動的に適用されます。抽出されたファイルの内容で検出された PII は、LLM に到達する前に仮名化され、LLM の応答でリハイドレートされます。設定について詳しくは、「 個人情報 (PII) のマスク」をご覧ください。

次のファイル形式がサポートされています。

• PDF
• DOCX
• CSV
• TXT
• JSON
• 画像

ベスト プラクティスとよくある質問

注:

Maestro プロセス、RPA ワークフロー、またはスタンドアロンのエージェントの実行からのファイルの使用について詳しくは、「ファイルを操作する」をご覧ください。

Analyze Files ツールを使用すると、エージェントは LLM を使用してドキュメントや画像を処理できます。これは強力な機能ですが、ファイル駆動型エージェントを設計する際に注意すべき重要な制限事項と動作がいくつかあります。

ファイルの制限

各ファイルは 30 MB を超えてはなりません。要求あたりのファイル数に適用される制限はありません。

プロバイダー別のファイルの種類のサポート

ファイルのサポートは、エージェントに対して選択した LLM プロバイダーとモデルによって異なります。PDF、Word 文書、スプレッドシート、HTML、テキスト、Markdown、画像などの形式は複数のプロバイダーによってサポートされていますが、コンテンツをモデルに送信する前に、プロバイダーごとにファイルの処理が異なる場合があります。結果はプロバイダーやモデルによって異なる場合があります。特に、グラフ、埋め込み画像、複雑なレイアウト、数式、大きな表を含むファイルの場合です。

以下の表は、UiPath によって公開されている最新モデルでサポートされている形式を示しています。

プロバイダー/モデル ファミリ	サポートされているドキュメントとテキストの形式	サポートされている画像形式
AWS Bedrock を使用した Anthropic モデル	.pdf、.csv、。ドキュメント。Docx。Xls。Xlsx。Html。Txt。Md	.gif、.jpe、。Jpeg。Pdf。Png。Tiff.webp
OpenAI GPT モデル	.pdf、.csv、。ドキュメント。Docx。Xls。Xlsx。Html。Txt。Md	.gif、.jpe、。Jpeg。Pdf。Png。Tiff.webp
Vertex AI を使用した Gemini モデル	.csv、.txt、。Md。Html	.gif、.jpe、。Jpeg。Pdf。Png。Tiff.webp

注:

サポートは、選択したモデルとプロバイダーの機能によって異なります。一部のモデルでは、API レベルではファイル拡張子がサポートされていますが、ファイルの内部処理方法が異なるため、応答の品質に影響が出る場合があります。

カスタム LLM 構成のファイルのサポート

AI Trust Layer を通じて [独自の LLM を使用する] 機能を使用する場合、[ファイルを分析] でサポートされるファイルの種類は、設定された LLM の設定によって異なります。AI Trust Layer の管理については「 LLM を設定する」を参照してください。

ファイルのサポートは、次の組み合わせによって決まります。

• 選択したプロバイダー (Azure OpenAI、Amazon Web Services、Google Vertex など)
• 選択したモデル ファミリとモデル バージョン
• 設定された API の種類です (モデルの呼び出しに使用されるプロバイダー エンドポイントなど)
• そのプロバイダー エンドポイントによって公開されるファイル処理機能

あるモデルまたはプロバイダーで動作するファイルの種類は、両方のモデルが AI Trust Layer を通じて利用可能な場合でも、別のモデルでは機能しない場合があります。たとえば、ドキュメント、スプレッドシート、画像、PDF のサポートは、プロバイダー API がこれらのファイルを直接受け入れるか、ファイルからテキストを抽出するか、画像に変換するか、プロバイダー固有の前処理手順を適用するかによって異なります。

UiPath は、設定された LLM エンドポイントが到達可能であり、選択した製品設定と互換性があることを検証します。LLM のカスタム設定を使用する場合、設定済みのモデル、プロバイダー、API の種類が、ファイルのユース ケースで必要なファイルの種類に対応していることを確認する責任があります。

注:

UiPath で管理されるモデルからカスタム LLM の設定に切り替える場合や、プロバイダー、モデル バージョン、API の種類を変更する場合、ファイルの対応 OS は変更される場合があります。LLM の設定を変更した後に [ファイルを分析] がファイルの処理に失敗した場合は、AI Trust Layer で設定したプロバイダー、モデル、API の種類を確認します。

ファイル処理の仕組み

ファイルが LLM に渡されても、モデルは元のファイルをそのままは受け取りません。ほとんどのプロバイダーは、コンテンツがモデル コンテキストに追加される前に前処理手順を適用します。前処理の動作は、ファイルの種類によって異なります。

OpenAI ファイル入力の場合:

• PDF ファイルは、Vision 対応モデルで抽出テキストとページ画像の両方として処理できます。
• PDF 以外のドキュメントとテキスト ファイルは、抽出テキストとしてのみ処理されます。
• スプレッドシート・ファイルは、スプレッドシート固有の拡張フローを使用します。OpenAI は、シートあたり最大 1,000 行を解析し、要約とヘッダーのメタデータを追加して、モデルがデータの構造化された表現から作業できるようにします。

AWS Bedrock や Vertex AI などの他のプロバイダーでも同様の前処理アプローチが使用される場合がありますが、正確な実装の詳細はプロバイダー固有であり、完全には文書化されていない可能性があります。

大きなファイルはトークンの制限を超過する可能性がある

エージェントは、その内容を LLM プロンプトに埋め込むことでファイルを処理しますが、LLM プロンプトはモデルのトークン制限による制約を受けます。大きな PDF やスキャンされた画像ドキュメントは、特にモデルのトークン予算を超えた場合に、警告なしに失敗したり、「エラーが発生しました」などの曖昧なエラーを返したりすることがあります。

この問題を軽減するには、以下の手順に従います。

• トークン容量の大きいモデルを使用します。
• ファイル検索やコンテキスト グラウンディングなどの取得指向の機能を特に使用する (特に、サイズの大きいファイルや複数ページのファイルの場合)。
• ドキュメントを事前にインデックス化し、カスタム ツールを使用してエージェントの実行前または実行中に同期します。

大きな PDF を処理する

サイズの大きな PDF を完全に処理すると、LLM のトークンのバジェットを超える可能性があります。PDF を小さなチャンクまたは個々のページに分割してから、エージェントに渡します。

LLM により画像のサイズが変更される

画像ファイル (.jpg、 .png など) を LLM プロンプトの一部として送信すると、ほとんどのモデルで自動的にサイズが変更されます。これにより、アスペクト比が歪んだり、ピクセル単位のデータが失われたりする可能性があります。

正確な座標、境界ボックス、またはピクセル配置された比較に依存するプロンプト (たとえば、特定の X/Y 位置を必要とする画像の差分) は避けてください。モデル固有のサイズ変更動作の詳細については、 OpenAI の画像ビジョン ガイド をご覧ください。

より良い結果を得るためのヒント

• ファイル名はクリーンである必要があります。特に Anthropic モデルでは、特殊文字や空白の繰り返しが含まれるファイル名は拒否されます。
• 画像数を少なくします。GPT-4o などの一部のモデルでは、1 回の要求で最大 10 〜 50 の画像がサポートされています。
• レイアウト、グラフ、または図が重要な場合は、PDF 形式を使用します。PDF 以外の形式 (.docx など) の埋め込み画像とグラフはモデルのコンテキストに抽出されない場合があります。
• .txt や。Mdまたは .html単純な Document Understanding タスクの場合
• 集計、結合、数式、グラフ作成を含む複雑なスプレッドシート分析の場合は、結果をエージェントに渡す前に、確定的な処理ステップまたは専用のデータ処理ワークフローを使用します。