Gemini API 怎样把文件输入和文本提示放在同一请求
如果你已经把 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。扩展名只是文件名的一部分,不能替代请求里的类型信息。

同一个请求里放入文本和文件
下面示例使用 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 写入长期业务表。需要长期保存的原始资料,应放在自己的对象存储中,在每次需要时重新上传,或按官方支持的云存储注册方式管理。

常见问题
为什么文件 URI 放进提示词后模型仍然不能读取?
先确认你传递的是接口要求的文件内容项,而不是把 URI 当普通字符串写进文本;再检查文件是否已经从 PROCESSING 变为 ACTIVE,以及 MIME 类型是否与实际文件匹配。
文件上传成功后能一直复用吗?
不能把 Files API 文件当作永久资源。它适合在临时生命周期内复用;长期任务应保存原始文件并在资源过期后重新上传,必要时在业务层记录上传时间和失效时间。
文本提示应该放在文件前面还是后面?
核心是同一个请求中存在文本项和文件项,具体顺序按所用 SDK 的输入格式组织。单文件提示场景通常把文件置于文本前也可以,但不要用顺序掩盖状态、URI 或 MIME 类型错误。
小结
把 Gemini 文件输入和文本提示放在同一请求,实际要管理三件事:文本项说明任务,文件项携带 URI 与 MIME 类型,调用前确认文件状态。再把临时生命周期纳入重试和存储策略,就能避免“上传成功但请求不可用”以及“过期 URI 长期失效”这两类常见问题。
Transformers tokenizer 怎样让 padding 与 truncation 对齐批量输入
- 上一篇
- Transformers tokenizer 怎样让 padding 与 truncation 对齐批量输入
- 下一篇
- LLM 评测集怎样按任务边界组织可回归样本
-
- 科技周边 · 人工智能 | 10分钟前 | 人工智能 · padding Transformers tokenizer attention_mask input_ids truncation
- Transformers tokenizer 怎样让 padding 与 truncation 对齐批量输入
- 416浏览 收藏
-
- 科技周边 · 人工智能 | 11分钟前 |
- Hugging Face Datasets DatasetDict 跨 train 与 validation 的 map 处理方案
- 267浏览 收藏
-
- 科技周边 · 人工智能 | 16分钟前 | 人工智能 · 结构化输出 · JSON Schema Responses API Structured Outputs strict refusal
- 结构化输出怎样约束模型返回 JSON Schema
- 328浏览 收藏
-
- 科技周边 · 人工智能 | 21分钟前 | 人工智能 · openai · 工具调用 Responses API function_call_output call_id
- Responses API 怎样处理工具调用后的继续响应
- 156浏览 收藏
-
- 科技周边 · 人工智能 | 21分钟前 | 人工智能 · openai · 多轮对话 Responses API conversation state OpenAI API previous_response_id
- Responses API 怎样用上一轮响应继续多轮对话
- 121浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 |
- GPT-Live双工语音会话接入后端
- 470浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 | 人工智能 · 文本生成 Transformers 重复片段 no_repeat_ngram_size GenerationConfig
- Transformers 怎样用 no_repeat_ngram_size 减少重复片段
- 493浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 | python · 人工智能 · OpenAI session Agents SDK SQLiteSession conversation_id
- OpenAI Agents API保存持久会话
- 414浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 |
- Transformers在vLLM中部署生成模型
- 122浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 |
- Transformers datasets流式读取训练数据
- 275浏览 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 485次学习
-
- PubMedQA
- 深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
- 1054次使用
-
- H2O EvalGPT
- H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
- 1054次使用
-
- LMArena
- LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
- 1219次使用
-
- HELM
- 深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
- 1161次使用
-
- MMBench
- MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
- 1004次使用
-
- Gemini 3 函数调用为什么要回传 thoughtSignature:Go 多轮工具链的顺序核对
- 2026-08-16 202浏览
-
- Gemini API 的 cachedContent 怎么复用长提示词:缓存创建与请求绑定
- 2026-08-27 257浏览
-
- Gemini File Search 多模态检索怎么留证:media_id 与 page_numbers 的引用边界
- 2026-09-03 377浏览
-
- Gemini API 结构化输出怎样限制 JSON 字段
- 2026-10-23 145浏览
-
- Gemini API 怎样为工具参数提供枚举约束
- 2026-11-03 322浏览

