AI 多模态输入怎样按文件类型分配处理路径

当一个 AI 服务同时接收图片、音频、视频和文档时，最容易失控的地方不是提示词，而是“这个文件到底应该以什么输入对象进入模型”。文件名后缀只能提供线索，真正应该进入路由判断的是 MIME 类型、文件大小和是否需要复用。

先给结论：把扩展名解析成 MIME 类型后，分别映射到 image、audio、video 或 document 内容对象；小文件、单次调用可以使用内联数据，较大的文件或需要多次调用的文件应先上传到 Files API，再把 URI 放入请求。

官方地址：https://ai.google.dev/gemini-api/docs/

下面以 Gemini API 的多模态输入模型为例，讲清一套路由层。它是工程化示例，具体可用模型、配额和 MIME 支持范围仍应以当前官方文档为准。

先把文件类型变成可判断的 MIME 路由

路由层至少要回答三个问题：输入是什么媒体类型、API 需要哪一种内容对象、这个对象应该携带字节还是 URI。不要直接用文件后缀拼请求，也不要把所有未知文件都当成图片。

Gemini 的输入模型把文本、图片、音频、视频和文档作为不同的内容类型。图片可以使用 image/png、image/jpeg、image/webp 等类型；音频、视频和 PDF 也有各自的 MIME 范围。一个集中映射表能让业务代码不再散落一堆 if filename.endswith(...)。

from pathlib import Path
import mimetypes

ROUTE_BY_MIME = {
    # 这些前缀对应 Gemini Interactions API 的媒体内容对象。
    "image/": "image",
    "audio/": "audio",
    "video/": "video",
    # PDF 使用 document；不要把 PDF 伪装成普通文本。
    "application/pdf": "document",
}

def classify_file(path: str) -> tuple[str, str]:
    """返回内容对象类型和 MIME；无法判断时明确拒绝。"""
    guessed, _ = mimetypes.guess_type(Path(path).name)
    if not guessed:
        raise ValueError(f"无法判断 MIME 类型: {path}")

    for prefix, content_type in ROUTE_BY_MIME.items():
        # application/pdf 是精确匹配，媒体类型按前缀匹配。
        if guessed == prefix or (prefix.endswith("/") and guessed.startswith(prefix)):
            return content_type, guessed

    # 拒绝未知类型比把错误内容交给模型更容易排查。
    raise ValueError(f"暂不支持的 MIME 类型: {guessed}")

这里的返回值不是模型响应，而是路由契约：content_type 决定请求字段的语义，mime_type 告诉服务端如何解释数据。生产环境还应在上传前用文件内容探测工具复核 MIME，避免用户把可执行文件改名成 .jpg 后绕过类型判断。

图片、音频、视频和 PDF 应该怎样组装

分类完成后，统一把文本提示和媒体对象放进同一个输入数组。提示词要明确媒体的任务，例如“读取发票中的总额”或“找出视频中第一个报警画面”，不要只写“分析这个文件”。

def build_inline_content(path: str, prompt: str) -> list[dict]:
    content_type, mime_type = classify_file(path)
    raw = Path(path).read_bytes()

    # data 只适合较小、一次性的文件；真实项目应先检查大小上限。
    import base64
    encoded = base64.b64encode(raw).decode("ascii")
    return [
        {"type": "text", "text": prompt},
        {
            "type": content_type,
            "data": encoded,
            "mime_type": mime_type,
        },
    ]

# 每个代码块只演示输入形状；API 密钥由 SDK 配置读取，不写入文章。
input_items = build_inline_content("invoice.pdf", "提取发票号码和价税合计，并说明字段所在页面。")

对 PDF 要特别注意：文档理解和普通文本抽取不是一回事。官方文档说明 PDF 可以保留页面视觉信息；TXT、Markdown、HTML 等文档虽然也能作为输入，但通常会按纯文本抽取，图表、排版和 HTML 标签不应被当成视觉内容依赖。若任务需要读表格版式或图形，优先使用 PDF 或图像，并在提示词中说明要关注页面结构。

字段检查：type 表示内容对象类别，mime_type 表示真实媒体类型，data 表示内联字节的 Base64。使用上传文件时，把 data 换成 uri，不要同时塞入两套载荷。

小文件内联，还是先走 Files API

输入载体的选择可以固定成一条简单规则：小文件且只调用一次时内联；文件较大、会重复使用，或者需要让请求体保持轻量时使用 Files API。当前官方文件输入文档建议，总请求体超过 100 MB 时使用 Files API；PDF 通过简单内联方式还有 50 MB 的限制，因此不要把阈值写死成“所有文件都能直接 Base64”。

def choose_input_method(size_bytes: int, reusable: bool, is_pdf: bool) -> str:
    # 这里的 100 MB 是当前文档给出的总请求体参考，不等于所有模型的永久配额。
    request_limit = 100 * 1024 * 1024
    if reusable or size_bytes >= request_limit:
        return "files_api"
    if is_pdf and size_bytes > 50 * 1024 * 1024:
        # 这种 PDF 不应继续走简单内联路径。
        return "files_api"
    return "inline_data"

上传后的请求形状类似下面这样。Files API 负责保存和处理文件，互动请求只携带 URI 和 MIME 类型；同一个文件需要多次分析时，可以复用这个 URI，避免每次重新编码和上传。

from google import genai

client = genai.Client()
uploaded = client.files.upload(
    file="meeting.mp3",
    config={"mime_type": "audio/mpeg"},
)

# URI 让请求保持轻量，mime_type 仍然要与上传文件一致。
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "整理这段录音中的待办事项。"},
        {"type": "audio", "uri": uploaded.uri, "mime_type": uploaded.mime_type},
    ],
)
print(interaction.output_text)

不要把“上传成功”当成“可以无限复用”。文件保留时间、模型支持、项目配额和权限都属于外部约束，应用应保存文件名、MIME、大小、上传时间和 URI 状态，过期或失败时重新走上传分支。

把路由层和请求层分开

更稳的代码结构是三层：第一层识别和拒绝不支持的类型，第二层决定内联或 URI，第三层只负责组装模型请求。这样当模型 SDK 的字段变化时，不需要重写业务文件分类。

• 识别层：记录原始文件名、真实 MIME、文件大小和校验结果。
• 载体层：根据大小与复用频率返回 data 或 uri，并统一保留 mime_type。
• 请求层：把文本提示放在媒体对象旁边，给每个媒体绑定清晰的任务描述。

这套分层还能减少敏感数据风险：日志记录路由结果和文件 ID 即可，不要记录 Base64 正文、访问令牌和完整音视频内容。对用户上传的文件，先做大小、权限和恶意文件检查，再交给模型服务。

常见问题与发布前检查

为什么扩展名正确仍然报错？扩展名只是猜测，可能和真实 MIME 不一致。把探测结果、上传时声明的 mime_type 和请求对象的 type 放在同一条日志里，优先检查三者是否一致。

为什么把 CSV 当 document 后结果不理想？文档对象并不意味着所有格式都保留版式。对表格任务要明确列名、行范围和输出格式；若依赖视觉排版，考虑转换成可读 PDF 或图片。

什么时候不该用 inline data？文件较大、同一文件要重复问多个问题、或者请求体已经接近上限时，不要重复 Base64。先走 Files API，记录 URI 生命周期，再用 URI 发起后续请求。

最后记住：先判断 MIME，再选内容对象；先判断大小和复用频率，再选内联或 Files API。路由层只做可解释的输入决策，请求层只组装已经确认的内容对象，后续更换模型或 SDK 时才不会把文件分类逻辑一起拖坏。