第 3 课

传入官方示例 PDF,做多轮会话并认识隐式缓存

把官方示例 PDF 交给模型做摘要,继续多轮会话,并认识隐式缓存

图文21 分钟Gemini 官方文档 ↗

课程目录第 3 / 3 课

学习位置仅保存在当前浏览器,有效期 180 天。

01 / 图文教材

图文教材

本课对照官方文档「文档理解」「Getting started」「Interactions API 概览」「上下文缓存」编写。PDF 示例地址和多轮会话代码来自官方文档;成功摘要和缓存命中数字采用官方说明,本环境未用真实密钥跑出成功回复。2026-11-20 核对。

本课目标

  • 按官方文档把一份公开 PDF 交给 gemini-4-neon 做摘要
  • 用 previous_interaction_id 继续同一段会话
  • 认识 Neon 只支持隐式缓存,以及缓存命中后的刊例价
  • 知道默认会存储 Interaction,以及何时改用 store=false

前置条件

  • 已完成第 1 课和第 2 课,当前终端里仍有有效的 GEMINI_API_KEY
  • 已安装 google-genai
  • 本机还能安装 httpx,用于按官方示例下载远程 PDF
  • 能访问官方示例使用的 arXiv 地址

第 1 步:先确认官方示例文档能打开

官方「文档理解」在「Large PDFs from URLs」一节使用下面这份公开 PDF,作为大文档示例:

https://arxiv.org/pdf/2312.11805

这是 arXiv 上的 Gemini 技术报告(编号 2312.11805)。先在浏览器或终端确认能下载,再发给模型。不要改用未经核对的其他地址来顶替这一步。

curl -L -o gemini-paper.pdf "https://arxiv.org/pdf/2312.11805"
ls -lh gemini-paper.pdf

你应看到一个体积不是空文件的 PDF。具体字节数会随 arXiv 当时提供的文件变化,本课不把它写成必须一致的校验和。

官方「文档理解」页首屏

2026-11-20 实拍。

https://aistudio.google.com/docs/document-processing

第 2 步:按官方示例上传 PDF 并请求摘要

官方这一节的 Python 示例通过 File API 上传远程 PDF,再把文件 URI 传给 Interactions API。示例原文使用 gemini-4-hydrogen。本课按「迁移到 Neon」的说明,只把 model 改成 gemini-4-neon,其余流程保持官方原样。

官方示例依赖 httpx。若尚未安装:

pip install httpx

新建 summarize_pdf.py:

from google import genai
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://arxiv.org/pdf/2312.11805"

doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

sample_doc = client.files.upload(
    file=doc_io,
    config=dict(mime_type="application/pdf")
)

prompt = "Summarize this document"

interaction = client.interactions.create(
    model="gemini-4-neon",
    input=[
        {
            "type": "document",
            "uri": sample_doc.uri,
            "mime_type": sample_doc.mime_type,
        },
        {"type": "text", "text": prompt},
    ],
)
print(interaction.id)
print(interaction.output_text)
python summarize_pdf.py

这是一次计费调用。官方定价页还写明:DOCUMENT 模态(例如 PDF)的 tokens 按图片 tokens 费率计费,并出现在响应 promptTokensDetails 的 DOCUMENT 项里。PDF 本身加上默认 high 思考档,费用会明显高于第 1 课的短文本请求。若只想先确认上传是否成功,可以把 thinking_level 临时设为 low,但那是你自己的调整,不是官方这一节的默认写法。

官方这一页没有给出该 PDF 的固定摘要文本,本课也不编造。成功时,你应得到一个 interaction.id,以及一段针对该文档的摘要;失败时先检查 Key、付费层、网络能否下载该 PDF,以及 httpx 是否已安装。

采用官方文档示例,本环境未用真实密钥跑出成功回复。

第 3 步:用 previous_interaction_id 继续提问

官方「Getting started」把带服务端状态的多轮会话写为推荐做法:第一次请求完成后,把返回的 id 作为下一次请求的 previous_interaction_id,不必把全部历史再发一遍。

下面在第 2 步的摘要之后,追加一轮追问。官方多轮示例原文使用 gemini-4-hydrogen 和另一组提示;这里保持同样的参数结构,只把模型改成 gemini-4-neon,并接上你刚得到的文档摘要会话:

from google import genai

client = genai.Client()

# 把上一轮打印出的 interaction.id 填在这里
previous_id = "v1_REPLACE_WITH_YOUR_INTERACTION_ID"

followup = client.interactions.create(
    model="gemini-4-neon",
    input="List the paper's main contributions in 5 bullet points.",
    previous_interaction_id=previous_id,
)

print(followup.output_text)

官方强调:previous_interaction_id 只保留对话历史(输入和输出)。tools、system_instruction 和 generation_config(包括 thinking_level)只对当前这一次请求生效。如果你在上一轮设过思考档,这一轮还要再写一遍,否则会回到型号默认值。对 Neon 来说,默认值是 high。

官方「Getting started」用“I have 2 dogs in my house.”和“How many paws are in my house?”演示同一机制。本课把这个机制接到文档摘要之后,方便你核对模型是否还记得上一轮的 PDF。官方没有给出这两段追问的固定样例回复,本课也不编造。

官方「Interactions API」页首屏

2026-11-20 实拍。

https://aistudio.google.com/docs/interactions-overview

第 4 步:认识隐式缓存,不要再调用显式缓存

官方「上下文缓存」写明:Interactions API 以及所有 Gemini 4 型号都只支持隐式缓存,不支持显式缓存(cachedContents 和 caches.create)。若请求里还带着 cached_content 字段,应删掉。隐式缓存默认开启,只要请求命中缓存,官方就会把节省下来的费用返还,你不必再单独打开开关。

对 Gemini 4 Neon,隐式缓存的最小输入长度是 4,096 tokens。官方定价页写明:缓存输入打 5% 的价格,也就是每 100 万 tokens $0.15。要提高命中机会,官方建议:

  • 把较大、且多次重复使用的内容放在提示的开头
  • 在较短时间内发送前缀相似的请求
  • 多轮会话优先用 previous_interaction_id,让服务端更容易复用历史前缀

另外还有一条针对 Gemini 4 多轮和智能体循环的规则:只有当新请求至少新增 2,050 tokens 时,模型才会把上一轮完整请求缓存下来。模型输出、思考和函数结果都计入这个增量。增量更小时,Gemini 会按标准输入价重新处理上一轮最后 2,050 tokens。官方称大多数智能体回合会超过这个阈值。

缓存命中的 token 数写在响应的 usage.total_cached_tokens 里(Python 与 JavaScript 字段名相同)。本环境没有用真实密钥跑出缓存命中,因此不编造该字段的数字。你用自己的付费额度、并在提示达到 4,096 tokens 之后,应在第二次及以后的相似请求里核对该字段。

官方「上下文缓存」页首屏

2026-11-20 实拍。页中表格列出 Gemini 4 Neon 的最小缓存长度是 4,096 tokens。

https://aistudio.google.com/docs/caching

第 5 步:了解默认存储,以及何时关闭

默认情况下,Interactions API 会存储请求(store=true),以便使用 previous_interaction_id、后台执行和日志查看。官方写明:付费层会把 Interaction 保留 55 天,免费层保留 1 天。Neon 只在付费层提供,因此走的是 55 天这一档。付费项目还可以在 AI Studio 里把保留期配置为 7、14、28 或 55 天。

如果你不希望保存某一次请求,可以在创建时加上 store=false。官方同时提醒:store=false 与后台执行不兼容,也不能再把这次结果当作后续回合的 previous_interaction_id。需要删除已存储的 Interaction 时,可按官方文档使用 delete 方法,或在 AI Studio 的 Logs 页管理。

日常跟做文档摘要和多轮追问,保持默认的 store=true 即可。

常见坑

  • 把显式缓存的旧字段继续传给 Neon。Gemini 4 和 Interactions API 都不支持显式缓存。
  • 忘记在每一轮重新传入 generation_config。思考档不会随着 previous_interaction_id 自动继承。
  • 用只有几百 tokens 的短提示去「验证」隐式缓存。Neon 的最小缓存长度是 4,096 tokens,短请求不会命中。
  • 把 store=false 和 background=true 或后续多轮会话写在一起。官方写明这两者不兼容。
  • 在网络无法访问 arXiv 时,改用一份来源不明的本地 PDF,却仍把结果当成官方示例对照。请先解决下载问题,或明确写明你改用了哪一份自己的文件。

小结

这一课你已经按官方文档把公开 PDF 交给 Neon,会用 previous_interaction_id 继续提问,并知道隐式缓存的最小长度、刊例价和字段名。把三课合在一起,就完成了从第一个请求、思考档到多模态文档与缓存的入门路径。更复杂的函数调用、Google Search 接地和托管智能体,请继续对照官方对应指南跟做,不要把未核对的二手步骤写进生产代码。

本课资料

适用环境

  • 网页
  • iOS
  • Android
  • API

官方文档

Gemini ↗