文件

概览

CrewAI 支持原生的多模态文件输入，让你可以直接把图片、PDF、音频、视频和文本文件传给 agents。系统会自动根据每个 LLM provider 的 API 要求来格式化文件。

文件类型

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

类型	类	使用场景
Image	`ImageFile`	照片、截图、图表、示意图
PDF	`PDFFile`	文档、报告、论文
Audio	`AudioFile`	录音、播客、会议
Video	`VideoFile`	屏幕录制、演示视频
Text	`TextFile`	代码文件、日志、数据文件
Generic	`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)

使用文件

文件可以在多个层级传入，越具体的层级优先级越高。

与 Crews 一起使用

在 kickoff crew 时传入文件：

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"),
    }
)

与 Tasks 一起使用

将文件附加到特定任务：

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"),
    }
)

与 Flows 一起使用

将文件传给 flow，它们会自动继承给 crews：

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")}
)

与独立 Agents 一起使用

直接在 agent 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 里的版本。

Provider 支持

不同 provider 支持的文件类型不同。CrewAI 会自动为每个 provider 的 API 格式化文件。

Provider	Image	PDF	Audio	Video	Text
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)	✓		✓

文件如何发送

CrewAI 会自动为每个 provider 选择最合适的文件发送方式：

方式	说明	使用时机
Inline Base64	文件直接嵌入请求中	小文件（通常 < 5MB）
File Upload API	文件单独上传，通过 ID 引用	超过阈值的大文件
URL Reference	直接把 URL 传给模型	文件源本身就是 URL

Provider 传输方式

Provider	Inline Base64	File Upload API	URL References
OpenAI	✓	✓ (> 5 MB)	✓
Anthropic	✓	✓ (> 5 MB)	✓
Google Gemini	✓	✓ (> 20 MB)	✓
AWS Bedrock	✓		✓ (S3 URIs)
Azure OpenAI	✓		✓

文件处理模式

当文件超过 provider 限制时，可以控制它们的处理方式：

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")

Provider 限制

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

OpenAI

Images: 最大 20 MB，每次请求最多 10 张图片
PDFs: 最大 32 MB，最多 100 页
Audio: 最大 25 MB，最长 25 分钟

Anthropic

Images: 最大 5 MB，最多 8000x8000 像素，最多 100 张图片
PDFs: 最大 32 MB，最多 100 页

Google Gemini

Images: 最大 100 MB
PDFs: 最大 50 MB
Audio: 最大 100 MB，最长 9.5 小时
Video: 最大 2 GB，最长 1 小时

AWS Bedrock

Images: 最大 4.5 MB，最多 8000x8000 像素
PDFs: 最大 3.75 MB，最多 100 页

在 Prompt 中引用文件

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

task = Task(
    description="""
    Analyze the provided materials:
    1. Review the chart in {sales_chart}
    2. Cross-reference with data in {quarterly_report}