分析文件

添加并配置“分析文件”工具，使智能体能够使用 LLM 处理和推理文件内容。

分析文件工具使智能体可以使用 LLM 处理文件内容并对其进行推理。

添加“分析文件”工具

要将分析文件工具添加到您的智能体中，请执行以下步骤：

1. 定义文件输入。在数据管理器面板中，为智能体架构中的每个文件输入添加参数。

   图 1. 创建文件输入参数

   

   输入参数必须使用 {{exampleInput}} 语法在用户提示中显式引用。未引用的输入参数将被忽略，并可能会影响智能体的分数。

   • 对于单个文件，请将参数类型设置为文件，并在用户提示词中引用它。例如：“分析以下报告并总结关键分析结果：{{reportFile}}”。
   • 要传递多个文件，请将参数类型设置为 “Array”，将项目类型设置为“文件”，然后在用户提示词中按名称引用参数。您还可以为 Runtime 指令添加可选的 string 参数。例如:

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

   在此示例中，reportFiles是 Array of File 参数，analysisInstructions是可选的 string 参数。两者都必须在“数据管理器”面板中定义。

   

   

2. 将分析文件工具添加到智能体定义中：

   1. 在“工具”面板中选择“添加工具”。
   2. 从“内置工具”类别中，选择“分析文件”。
   3. 更新工具名称和描述，以帮助智能体更好地推断何时使用此工具。名称和描述会指导智能体的规划阶段，它们决定智能体何时调用工具，而非工具在运行时如何处理文件。

   

3. 设置工具的输入。此工具预配置了两个主要输入：

   • attachments (Array)：由提示词定义的输入，用于告诉智能体将哪些文件传递给工具。在此字段中，描述智能体应如何使用用户提示词中所引用的文件输入（例如{{reportFiles}}）。智能体在运行时会自动将这些引用的文件映射到此输入。示例：“使用用户提示词中提供的文件（例如 {{reportFiles}}）作为分析的输入源。”
   • analysisTask (string)：Runtime 指令，告诉 LLM 在调用工具后对文件执行什么操作，例如“分析这些报告。提取报告标题、执行摘要、按重要性排序的关键分析结果、可操作的建议以及整体情感。”它与工具名称和描述不同，会控制智能体何时调用工具。如果您的用例仅涉及一个文件，您可以对附件进行相应描述（例如“使用 {{reportFile}} 中提供的文件…”）。

4. 使用输入文件运行智能体。

   1. 打开“调试配置”窗口：
      1. 导航到“项目参数”选项卡。
      2. 上传绑定到您的 reportFiles 参数的输入文件。
   2. 选择“保存”，然后运行调试会话。

   

5. 运行智能体后，通过底部面板查看执行追踪记录。

“分析文件”工具现已添加到您的智能体，并已完成相关配置，以处理文件输入。在“执行历史纪录”面板中的执行追踪信息中，可以查看运行期间每个附件的具体处理情况。

文件附件追踪记录

使用分析文件工具时，所有文件输入和输出都捕获到“执行追踪”面板的“历史记录”选项卡中。追踪记录详细显示了智能体执行期间如何处理附件。

对于每个文件，追踪记录显示：

• ID：附件的唯一标识符。

• 名称：原始文件名称（例如 1.jpg）。

• MIME 类型：检测到的文件类型（例如 image/jpeg）。

  图 2. 执行追踪中的文件分析

  

从执行追踪记录中选择工具调用，然后导航到“文件”选项卡以下载文件。

图 3. 如何从追踪记录中下载文件

对文件内容进行 PII 掩码

在 AI Trust Layer 策略中启用 PII 实时掩码后，它会自动应用于通过“分析文件”工具处理的文件内容。在提取的文件内容中检测到的 PII 会在内容到达 LLM 之前进行假名化，并在 LLM 响应中予以还原。有关配置详细信息，请参阅PII 掩码。

支持以下文件格式：

• PDF
• DOCX
• CSV
• TXT
• JSON
• 图像

最佳实践和常见问题解答

备注：

有关使用 Maestro 流程、RPA 工作流或独立智能体运行中的文件的更多详细信息，请参阅“处理文件”。

通过分析文件工具，智能体可以使用 LLM 流程处理文档和图像。虽然功能强大，但在设计文件驱动的智能体时，需要注意一些重要的限制和行为。

文件限制

每个文件不得超过 30 MB。单次请求所包含的文件数量没有硬性限制。

提供程序的文件类型支持情况

文件支持取决于为智能体选择的 LLM 提供程序和模型。尽管多个提供程序支持 PDF、Word 文档、电子表格、HTML、文本、Markdown 和图像等格式，但每个提供程序在将内容发送给模型之前，可能会以不同的方式处理这些文件。不同提供程序和模型的结果可能有所不同，特别是包含图表、嵌入式图像、复杂布局、公式或大表格的文件。

下表显示了 UiPath 提供的最新模型所支持的格式：

提供程序/模型系列	支持的文档和文本格式	支持的图像格式
通过 AWS Bedrock 接入的 Anthropic 模型	.pdf、.csv、.doc、.docx、.xls、.xlsx、.html、.txt、.md	gif、.jpe、.jpeg、.pdf 和 .png、.tiff、.webp
OpenAI GPT 模型	.pdf、.csv、.doc、.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 设置。有关详细信息，请参阅“配置 LLM”。

文件支持由以下几项综合决定：

• 选定的提供程序，例如 Azure OpenAI、Amazon Web Services 或 Google Vertex
• 选定的模型系列和模型版本
• 配置的 API 类型，例如用于调用模型的提供程序端点
• 该提供程序端点提供的文件处理功能

即使两个模型均可通过 AI Trust Layer 使用，但适用于一个模型或提供程序的文件类型可能无法适用于另一个模型或提供程序。例如，对文档、电子表格、图像和 PDF 的支持可能会有所不同，具体取决于提供程序 API 是直接接受这些文件、从中提取文本、将文件转换为图像，还是应用提供程序特定的预处理步骤。

UiPath 会验证配置的 LLM 端点是否可访问且与所选产品配置兼容。使用自定义 LLM 配置时，您有责任确保配置的模型、提供程序和 API 类型支持“分析文件”用例所需的文件类型。

备注：

从 UiPath 托管模型切换为自定义 LLM 配置时，或更改提供程序、模型版本或 API 类型时，文件兼容性可能会发生变化。如果更改 LLM 配置后“分析文件”无法处理文件，请查看 AI Trust Layer 中配置的提供程序、模型和 API 类型。

文件处理的工作原理

将文件传递给 LLM 时，模型不会按原样接收原始文件。在将内容添加到模型上下文之前，大多数提供程序会应用预处理步骤。预处理行为取决于文件类型。

对于 OpenAI 文件输入：

• 在支持视觉功能的模型上，PDF 文件可以同时作为提取的文本和页面图像进行处理。
• 非 PDF 文档和文本文件仅作为提取的文本处理。
• 电子表格文件使用电子表格专用的增强流。OpenAI 会解析每张工作表中的前 1,000 行，并添加摘要和标头元数据，以便模型根据数据的结构化表示工作。

其他提供商（如 AWS Bedrock 和 Vertex AI）可能会使用类似的预处理方法，但具体实施细节因提供商而异，且可能并未完全文档化。

大型文件可能超过令牌上限

智能体通过将内容嵌入到 LLM 提示词中来处理文件，而提示词会受到模型令牌上限的约束。大型 PDF 或扫描图像文档可能会静默失败，或返回“出错”等模糊错误，尤其是超出模型的令牌预算时。

要减轻：

• 使用令牌容量较高的模型。
• 使用面向检索的功能，例如文件搜索或上下文锚定，特别是对于大型文件或多页文件。
• 通过自定义工具，在智能体运行之前或期间对文档进行预索引，并对其进行同步。

处理大型 PDF 文件

完整处理大型 PDF 文件时，可能会超过 LLM 的词元预算。在将 PDF 传递给智能体之前，建议先将其拆分为较小的区块或单独的页面。

LLM 调整图像大小

当图像文件（例如 .jpg、.png）作为 LLM 提示词的一部分发送时，大多数模型会自动调整它们的大小。这可能会导致纵横比失真或像素精确数据丢失。

避免依赖确切坐标、边界框或像素对齐比较的提示词（例如，需要特定 x/y 定位的图像差异）。有关更多信息，请参阅 OpenAI 的图像视觉指南，以了解模型专属的大小调整行为。

获得更好结果的提示

• 文件名称必须整洁：特别是 Anthropic 模型会拒绝包含特殊字符或重复空格的文件名称。
• 保持图像数量少：GPT-4o 等某些模型每个请求最多支持 10–50 个图像。
• 当布局、图表或示意图很重要时，请使用 PDF 格式。非 PDF 格式（例如 .docx）的嵌入图像和图表可能无法提取到模型上下文中。
• 使用基于文本的格式，例如 .txt、.md、或 .html 来完成简单的 Document Understanding 任务。
• 对于涉及汇总、连接、公式或图表的复杂电子表格分析，请在将结果传递给智能体之前，使用确定性处理步骤或专用数据处理工作流。