登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  科技周边 >  人工智能

Gemini API 怎样把文件输入和文本提示放在同一请求

来源:17golang原创

时间:2026-11-16 20:33:16 164浏览 收藏

如果你已经把 PDF、图片或音频上传到 Gemini Files API,下一步不需要把文件内容再拼进长字符串。正确做法是保留上传返回的文件 URI 和 MIME 类型,再把它们与文本提示放进同一个请求内容集合中。这样模型拿到的是“我要做什么”和“要参考哪个文件”两部分信息。

官方资料:https://ai.google.dev/gemini-api/docs/file-prompting-strategies

文本提示负责描述任务,文件 URI 负责指向输入对象,MIME 类型负责说明对象格式;三者应作为同一次请求的不同内容项传递。调用前还要确认文件已经处于 ACTIVE 状态,并把 Files API 的临时生命周期纳入重试和缓存设计。
  • 文件较小且只用一次:可以考虑内联数据,避免额外的文件资源管理。
  • 文件较大或会被多次引用:使用 Files API,保存返回的 name、uri 和 mimeType。
  • 请求组成:文本提示与 document、image 或 audio 文件内容项放在同一个输入数组里。
  • 调用前检查:PROCESSING 不能直接推理,FAILED 需要处理错误,过期文件要重新上传。

先选对文件输入方式

Gemini 的文件输入可以分成两种思路:把字节随当前请求发送,或者先上传成 Files API 资源,再在请求中引用 URI。前者适合小文件和一次性调用;后者适合文件较大、同一文件要用于多次请求,或者希望把上传耗时从推理请求中拆开的场景。不要为了“统一”而所有文件都走上传接口,输入方式应和文件大小、复用次数以及生命周期一起决定。

Files API 返回的对象里,name 是资源标识,uri 是后续请求要引用的地址,mimeType 描述文件格式。上传时如果 SDK 不能可靠判断类型,可以在上传配置中明确指定 MIME 类型,例如 PDF 使用 application/pdf,纯文本使用 text/plain。扩展名只是文件名的一部分,不能替代请求里的类型信息。

文本提示、File URI 和 MIME 类型组成同一 Gemini 请求的静态结构说明图
图1:静态结构说明图,展示文本提示与文件引用在同一请求中的组成关系,不是运行截图。

同一个请求里放入文本和文件

下面示例使用 Python SDK 表达核心关系:先上传文件,再把文本项和文件项放进同一个输入列表。示例不把 API Key 写入代码,实际项目应通过环境变量或密钥管理服务提供认证信息。

from google import genai

client = genai.Client()

# 上传阶段明确文件类型,后续请求直接复用返回的 URI。
uploaded = client.files.upload(
    file="materials/design.pdf",
    config={"mime_type": "application/pdf"},
)

# 文本项描述任务,document 项引用同一个文件资源。
contents = [
    {"type": "text", "text": "请提取文档中的三个设计约束,并按 JSON 输出。"},
    {"type": "document", "uri": uploaded.uri, "mime_type": uploaded.mime_type},
]

# 同一次调用同时提交文本提示和文件输入。
response = client.interactions.create(
    model="gemini-3.8-flash",
    input=contents,
)

print(response.output_text)

这里的关键不是列表变量的名字,而是输入项的职责分离:文本项描述问题,文件项提供被引用对象。对于图片、音频等内容,保持相同思路,按接口要求把内容类型、URI 和 MIME 类型放进对应的内容项;不要把文件 URI 当成普通提示文本拼接。

调用前先处理文件状态和生命周期

上传成功不等于文件已经可以立即推理。Files API 的资源有处理状态,PROCESSING 表示文件仍在处理,ACTIVE 才是可用于推理的状态,FAILED 则需要读取错误信息并决定是修正输入还是重新上传。业务代码可以先读取文件元数据,再决定是否进入模型请求。

from google import genai

client = genai.Client()
file_info = client.files.get(name=uploaded.name)

# 只有 ACTIVE 才进入推理;其他状态交给上层重试或失败处理。
if file_info.state != "ACTIVE":
    raise RuntimeError(f"文件暂不可用:{file_info.state}")

# 读取服务端返回的 MIME 类型,避免只相信本地扩展名。
file_part = {
    "type": "document",
    "uri": file_info.uri,
    "mime_type": file_info.mime_type,
}

生命周期也要写进任务设计。官方 Files API 资料说明上传文件是临时存储,文件会自动删除;因此不要把 files/... 资源名当成永久资产 ID 写入长期业务表。需要长期保存的原始资料,应放在自己的对象存储中,在每次需要时重新上传,或按官方支持的云存储注册方式管理。

Gemini 文件元数据、PROCESSING ACTIVE FAILED 状态和重新上传处置的静态生命周期结构图
图2:静态生命周期结构图,展示文件元数据、处理状态与处置动作的关系,不是运行截图。

常见问题

为什么文件 URI 放进提示词后模型仍然不能读取?

先确认你传递的是接口要求的文件内容项,而不是把 URI 当普通字符串写进文本;再检查文件是否已经从 PROCESSING 变为 ACTIVE,以及 MIME 类型是否与实际文件匹配。

文件上传成功后能一直复用吗?

不能把 Files API 文件当作永久资源。它适合在临时生命周期内复用;长期任务应保存原始文件并在资源过期后重新上传,必要时在业务层记录上传时间和失效时间。

文本提示应该放在文件前面还是后面?

核心是同一个请求中存在文本项和文件项,具体顺序按所用 SDK 的输入格式组织。单文件提示场景通常把文件置于文本前也可以,但不要用顺序掩盖状态、URI 或 MIME 类型错误。

小结

把 Gemini 文件输入和文本提示放在同一请求,实际要管理三件事:文本项说明任务,文件项携带 URI 与 MIME 类型,调用前确认文件状态。再把临时生命周期纳入重试和存储策略,就能避免“上传成功但请求不可用”以及“过期 URI 长期失效”这两类常见问题。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>