文件

将图像、PDF、音频、视频和文本文件传递给智能体，以进行多模态处理。

概述

CrewAI 支持原生多模态文件输入，允许你将图像、PDF、音频、视频和文本文件直接传递给智能体。文件会自动按照每个 LLM 服务商的 API 要求进行格式化。

NOTE

文件支持需要可选的 crewai-files 包。使用以下命令安装：

uv add 'crewai[file-processing]'

NOTE

文件处理 API 目前处于早期访问阶段。

文件类型

CrewAI 支持五种特定文件类型，以及一个可自动检测类型的通用 File 类：

类型	类	使用场景
图像	ImageFile	照片、截图、示意图、图表
PDF	PDFFile	文档、报告、论文
音频	AudioFile	录音、播客、会议
视频	VideoFile	屏幕录制、演示文稿
文本	TextFile	代码文件、日志、数据文件
通用	File	根据内容自动检测类型

from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile

image = ImageFile(source="screenshot.png")
pdf = PDFFile(source="report.pdf")
audio = AudioFile(source="meeting.mp3")
video = VideoFile(source="demo.mp4")
text = TextFile(source="data.csv")

file = File(source="document.pdf")

文件来源

source 参数接受多种输入类型，并自动检测合适的处理器：

从路径

from crewai_files import ImageFile

image = ImageFile(source="./images/chart.png")

从 URL

from crewai_files import ImageFile

image = ImageFile(source="https://example.com/image.png")

从字节

from crewai_files import ImageFile, FileBytes

image_bytes = download_image_from_api()
image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png"))
image = ImageFile(source=image_bytes)

使用文件

文件可以在多个层级传递，更具体的层级优先。

与团队一起使用

启动团队时传递文件：

from crewai import Crew
from crewai_files import ImageFile

crew = Crew(agents=[analyst], tasks=[analysis_task])

result = crew.kickoff(
    inputs={"topic": "Q4 Sales"},
    input_files={
        "chart": ImageFile(source="sales_chart.png"),
        "report": PDFFile(source="quarterly_report.pdf"),
    }
)

与任务一起使用

将文件附加到特定任务：

from crewai import Task
from crewai_files import ImageFile

task = Task(
    description="Analyze the sales chart and identify trends in {chart}",
    expected_output="A summary of key trends",
    input_files={
        "chart": ImageFile(source="sales_chart.png"),
    }
)

与流程一起使用

将文件传递给流程，流程会自动继承到团队：

from crewai.flow.flow import Flow, start
from crewai_files import ImageFile

class AnalysisFlow(Flow):
    @start()
    def analyze(self):
        return self.analysis_crew.kickoff()

flow = AnalysisFlow()
result = flow.kickoff(
    input_files={"image": ImageFile(source="data.png")}
)

与独立智能体一起使用

直接将文件传递给智能体 kickoff：

from crewai import Agent
from crewai_files import ImageFile

agent = Agent(
    role="Image Analyst",
    goal="Analyze images",
    backstory="Expert at visual analysis",
    llm="gpt-4o",
)

result = agent.kickoff(
    messages="What's in this image?",
    input_files={"photo": ImageFile(source="photo.jpg")},
)

文件优先级

当在多个层级传递文件时，更具体的层级会覆盖更宽泛的层级：

Flow input_files < Crew input_files < Task input_files

例如，如果 Flow 和 Task 都定义了名为 "chart" 的文件，则使用 Task 的版本。

服务商支持

不同服务商支持不同的文件类型。CrewAI 会自动按照每个服务商的 API 格式化文件。

服务商	图像	PDF	音频	视频	文本
OpenAI (completions API)	✓
OpenAI (responses API)	✓	✓	✓
Anthropic (claude-3.x)	✓	✓
Google Gemini (gemini-1.5, 2.0, 2.5)	✓	✓	✓	✓	✓
AWS Bedrock (claude-3)	✓	✓
Azure OpenAI (gpt-4o)	✓		✓

NOTE

Google Gemini 模型支持所有文件类型，包括视频（最长 1 小时、2GB）。当你需要处理视频内容时，请使用 Gemini。

NOTE

如果你传递了服务商不支持的文件类型（例如将视频传给 OpenAI），你将收到 UnsupportedFileTypeError。请根据你需要处理的文件类型选择服务商。

文件如何发送

CrewAI 会自动选择将文件发送给每个服务商的最佳方式：

方法	描述	使用时机
内联 Base64	文件直接嵌入请求中	小文件（通常 < 5MB）
文件上传 API	文件单独上传，并通过 ID 引用	超过阈值的大文件
URL 引用	将直接 URL 传递给模型	文件来源已经是 URL

服务商传输方法

服务商	内联 Base64	文件上传 API	URL 引用
OpenAI	✓	✓ (> 5 MB)	✓
Anthropic	✓	✓ (> 5 MB)	✓
Google Gemini	✓	✓ (> 20 MB)	✓
AWS Bedrock	✓		✓ (S3 URIs)
Azure OpenAI	✓		✓

NOTE

你不需要自行管理这一点。CrewAI 会根据文件大小和服务商能力自动使用最高效的方法。没有文件上传 API 的服务商会对所有文件使用内联 base64。

文件处理模式

控制文件超出服务商限制时的处理方式：

from crewai_files import ImageFile, PDFFile

image = ImageFile(source="large.png", mode="strict")
image = ImageFile(source="large.png", mode="auto")
image = ImageFile(source="large.png", mode="warn")
pdf = PDFFile(source="large.pdf", mode="chunk")

服务商限制

每个服务商对文件大小和尺寸都有特定限制：

OpenAI

• 图像：最大 20 MB，每次请求最多 10 张图像
• PDF：最大 32 MB，最多 100 页
• 音频：最大 25 MB，最长 25 分钟

Anthropic

• 图像：最大 5 MB，最大 8000x8000 像素，最多 100 张图像
• PDF：最大 32 MB，最多 100 页

Google Gemini

• 图像：最大 100 MB
• PDF：最大 50 MB
• 音频：最大 100 MB，最长 9.5 小时
• 视频：最大 2 GB，最长 1 小时

AWS Bedrock

• 图像：最大 4.5 MB，最大 8000x8000 像素
• PDF：最大 3.75 MB，最多 100 页

在提示词中引用文件

在任务描述中使用文件的键名来引用文件：

task = Task(
    description="""
    Analyze the provided materials:
    1. Review the chart in {sales_chart}
    2. Cross-reference with data in {quarterly_report}
    3. Summarize key findings
    """,
    expected_output="Analysis summary with key insights",
    input_files={
        "sales_chart": ImageFile(source="chart.png"),
        "quarterly_report": PDFFile(source="report.pdf"),
    }
)