文档索引
获取完整文档索引： https://docs.crewai.com.cn/llms.txt
在深入了解之前，请使用此文件来浏览所有可用页面。
CrewAI 支持原生多模态文件输入，允许你直接向 Agent 传递图片、PDF、音频、视频和文本文件。文件会自动根据每个 LLM 提供商的 API 要求进行格式化。
文件支持需要安装可选的 crewai-files 包。请使用以下命令安装：uv add 'crewai[file-processing]'
文件类型
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)
使用文件
文件可以在多个层级传递，层级越具体，优先级越高。
配合 Crew 使用
启动 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"),
}
)
配合任务使用
将文件附加到特定任务
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"),
}
)
配合流程使用
向流程 (Flow) 传递文件，流程中的文件会自动继承给 Crew
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")}
)
配合独立 Agent 使用
直接在 Agent 启动时传递文件
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
"chart" 的文件，则使用任务定义的版本。
提供商支持
不同提供商对文件类型的支持不同。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) | ✓ | | ✓ | | |
Google Gemini 模型支持所有文件类型，包括视频（最长 1 小时，2GB）。需要处理视频内容时，请选择 Gemini。
如果你传递了提供商不支持的文件类型（例如向 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 URI) |
| Azure OpenAI | ✓ | | ✓ |
你无需手动管理这些。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"),
}
)
