Gemini 3.8 Flash API 教程：思考级别、PDF 抽取与 Python 中的函数调用

什么是 Gemini 3.8 Flash？

Gemini 3.8 Flash 是 Google 的主力模型，自 2026 年 9 月 2 日起全面开放，对应模型 ID 为 gemini-3.8-flash。它在 3.7 Flash 发布 3 周后上线，定位于长时程编码、Agent 工作流，以及金融、法律等专门领域的多步推理。

与 3.7 相比，API 调用相关的规格未变：

• 100 万 token 上下文窗口
• 最多 64k 输出 token
• 多模态输入（文本、图片、视频、音频、PDF），输出为文本
• 同样的试运行价格：截至 2026 年 12 月 31 日每百万输入 token $0.75，每百万输出 token $3.75（自 2027 年 1 月 1 日起分别升至 $1.50 和 $7.50）

变化的是行为而非表面。Google 表示 3.8 在复杂任务上更“用功”，会执行额外的推理步骤并迭代调用工具，这在更高努力级别下可能增加 token 使用。3.7 Flash 仍完全支持，适用于效率优先的工作负载。

基准测试与详细定价，请参阅我们的 Gemini 3.8 Flash 指南，或阅读What is Google Gemini? 平台综述。

Gemini 3.8 Flash 与 3.8 Flash Cyber 对比

此次发布包含 2 个变体，其中只有 1 个有可直接输入的模型 ID。

• Gemini 3.8 Flash 是通用模型，今日即可在 Google AI Studio 和 Gemini API 中使用。
• Gemini 3.8 Flash Cyber 是面向网络安全的变体，针对漏洞发现和自动修复进行调优。

Cyber 变体不对公共 API 开放：访问需通过 Google 的 Fairwind Program，仅限已批准的政府机构、关键基础设施运营方和软件维护者。

若您在跟随本教程，您的模型 ID 是 gemini-3.8-flash。下文均不需要、也不使用 Cyber 变体。

Interactions API vs. generateContent

调用 Gemini 3.8 Flash 时，请在 google-genai SDK 中使用 client.interactions.create()。Google 已在 2026 年 6 月将 Interactions API 设为 GA，并推荐在所有新项目中使用。虽然 generateContent 仍可用，但现已属遗留。诸如服务端历史、后台执行、可观测的执行步骤等新功能会优先登陆 Interactions。

实践中最大的变化是状态管理。多轮调用现在使用服务端的 previous_interaction_id：您传入上一轮交互的 ID，服务端负责恢复状态。您不再需要在客户端手动追加或重发完整的对话历史。也避免预填模型轮次；那是遗留的 generateContent 用法，会在 Gemini 3.x 上出错。

有个点几乎人人会踩坑，且在 PDF 小节还会出现：previous_interaction_id 只恢复会话历史，不恢复其它内容。tools、system_instruction、generation_config 和 response_format 都是“交互作用域”的，因此任何需要它们的轮次都必须再次传入。

thinking_level 取代采样旋钮

在旧版 Gemini 模型中，开发者使用 temperature、top_p、top_k 控制输出随机性。Gemini 3.x 移除了这些采样旋钮，改由 thinking_level 作为唯一控制。

它接受 3 个值：

• low：最少的推理 token，最快最省。适合抽取、分类，以及任何您会自行核查的内容。

• medium：默认值，Google 推荐用于代码和 Agent 工作。

• high：最大的推理预算，适合困难的多步逻辑和重工具任务。

不要发送 minimal。自 Gemini Flash 3.7 起即无效，会返回 400 校验错误。

另一个从 3.7 延续的规则：frequency_penalty、presence_penalty 和 candidate_count 现在会抛出活跃 API 错误，因此也要从遗留配置中移除。

如何设置 Gemini 3.8 Flash API？

环境设置约需 2 分钟。您需要从 Google AI Studio 获取 API 密钥，并安装更新后的 google-genai Python 库。

从 Google AI Studio 获取 API 密钥

在浏览器访问 Google AI Studio，使用您的 Google 账号登录。点击Create API Key，选择或创建一个 Google Cloud 项目，并复制您的密钥字符串。

打开终端，将密钥保存为环境变量：export GEMINI_API_KEY=<your-key>。

切勿将密钥作为 URL 中的 ?key= 查询参数传递；查询字符串会出现在服务器日志、浏览器历史与代理缓存中。若您想在写代码前先在 playground 中体验该模型，Google AI Studio 教程涵盖 Chat、Build 与 Stream 模式；本文聚焦 API。

在生产系统中，认证方式会不同：Vertex AI（现为Gemini Enterprise Agent Platform 的一部分）提供 OAuth、IAM 角色与区域端点，替代裸 API 密钥。本文全部使用 AI Studio 密钥，因为这是学习最快路径，但在接触真实用户数据前，请规划 Vertex 迁移。

安装 google-genai 并创建客户端

许多教程仍建议安装 google-generativeai。那是旧版 SDK，且不包含 Interactions API。请安装 google-genai（2.3.0 或更高版本）：

pip install -U google-genai

安装后，验证 Python 能加载该库并无错误地初始化客户端：

from google import genai # reads GEMINI_API_KEY from the environment
client = genai.Client() 
print("Client initialized successfully.")

发起您的首个 Interactions API 调用

对 Interactions API 的每个请求都会创建一个 Interaction 资源，记录完整的轮次：您的输入、模型的思考、任何工具调用以及最终输出。SDK 通过 output_text 便捷属性暴露最终文本，因此很少需要手动遍历步骤。

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        "Write a pandas one-liner that adds a 7-day rolling average "
        "revenue column per store_id to a DataFrame with columns "
        "date, store_id, revenue. Reply with only the code, no explanation."
    ),
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
    f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
    f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)

在我的机器上，模型返回了一个链式的 pandas 单行代码，并打印了如下用量：

这些数字隐藏了与 3.7 的首个真实差异。我用更长的提示词且不限制输出再次运行同一任务，3.8 花费了 1,436 个思考 token，而输出 token 为 870；加上限制后，思考为 1,515，对比输出 42。推理预算几乎不变，这与 3.7 相反——相同两条提示词会让思考从 838 摇到 1,530。

换句话说，3.8 根据任务本身决定“思考强度”，而非取决于您如何措辞任务，这与 Google 所称的“模型更有意识地推理与验证”一致。思考按输出费率计费，因此在受限调用中，约 97% 的计费 token 是我看不到的推理。这也是下一节存在的原因。

流式返回响应

对于聊天界面或任何有人观看的场景，等待数秒直至完整响应会显得慢。向 client.interactions.create() 传入 stream=True，并在分片到达时打印：

	from google import genai

	client = genai.Client()

	stream = client.interactions.create(
	   model="gemini-3.8-flash",
	   input="Explain the difference between a JOIN and a correlated subquery in SQL.",
	   generation_config={"thinking_level": "low"},
	   stream=True,
	)

	for event in stream:
	   if event.event_type == "step.delta" and event.delta.type == "text":
	       print(event.delta.text, end="", flush=True)
	print() 

当我运行时，模型在 thinking_level: "low" 下返回了一段结构良好的长答案：概念对比、总结表，以及 2 个 SQL 示例（均为查找每位客户的最近订单，一个用派生表 JOIN，一个在 SELECT 列表中用相关子查询）。首批文字几乎立即出现，这正是重点。

最后的 print() 是有用的。没有它，最后一个分片会停在行中间，zsh 会在提示符前显示一个多余的 %，因为流式输出恰好停在模型文本停止处。另外，若要记录每次请求的 token 计数，增量事件通常不携带总计，需从最终完成事件读取，而不是对分片求和。

thinking_level 如何影响成本与质量？

thinking_level 决定 Gemini 3.8 Flash 在写答案前会进行多少推理。推理 token 按每百万 $3.75 的输出费率计费，因此您选择的级别会直接影响成本与时延。Google 还表示 3.8 有意在复杂任务上投入更多推理步骤，在更高努力级别可能比 3.7 消耗更多 token。

以同一提示分别运行 low、medium、high

测试内容是支付重试函数中的竞态条件，用同一提示在 3 个级别下运行。并发类漏洞容易因粗读而漏判，因此若各级别结果有差异，这里最能体现。若您只运行本文的一段代码，就选这段，因为数据胜过任何文字辩解。

import time

from google import genai

client = genai.Client()

BUGGY_CODE = '''
import threading

payment_attempts = {}

def retry_payment(order_id, charge_fn, max_retries=3):
    """Retry a failed payment up to max_retries times."""
    if order_id not in payment_attempts:
        payment_attempts[order_id] = 0

    while payment_attempts[order_id] < max_retries:
        success = charge_fn(order_id)
        if success:
            del payment_attempts[order_id]
            return True
        payment_attempts[order_id] += 1
    return False
'''

PROMPT = (
    "Two worker threads can call retry_payment() with the same order_id "
    "at the same time. Identify the concurrency bug that can double-charge "
    "a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)

for level in ["low", "medium", "high"]:
    start = time.perf_counter()
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=PROMPT,
        generation_config={"thinking_level": level},
    )
    elapsed = time.perf_counter() - start
    usage = interaction.usage
    print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
    print(interaction.output_text)
    print(
        f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
        f"thinking={usage.total_thought_tokens}"
    )

作为背景，漏洞在于对 payment_attempts[order_id] 的“检查后执行”非原子操作。在并发下，两个线程都可能通过 while 条件，并在任一方自增计数器之前都调用了 charge_fn()。修复方法是将“读取-检查-扣款-自增”的流程用“按订单加锁”的方式包裹，或在网关使用幂等键。

结果对比

以下为我的运行结果：

三个级别都找到了双重扣款问题，且都采用了“按订单加锁”，从而不同订单可并行处理。与 3.7 对比时，这点尤为亮眼：在 3.7 上，low 会用一个全局锁包住一切并在网络调用期间持有，而“按订单加锁”只在 medium 出现。在 3.8 上，low 以 0 思考 token、耗时 7.8 秒、不到 1/3 美分的成本就写出了更好的设计。

那么不同级别现在“买”到的是什么？审计深度。此代码有 4 种不同失败模式（双重扣款、并发删除导致的 KeyError、成功路径删除状态后再次扣款、计数器自增的非原子性），仅 high 全部点名；low 漏掉了“再次扣款”，medium 漏掉了“计数器”。

high 也是唯一一个明确说明其修复方案失败路径语义的级别：一旦重试耗尽，后续调用将返回 False，而不是再次扣款。

“思考”一列正是 Google“3.8 更用功”主张在终端中的体现。对同一提示，在 3.7 上，medium 的思考 token 从 2,343 增至 3,158，high 从 2,217 增至 4,512，约翻倍，而这些额外 token 带来的是更完整的分析，而非不同结论。本次运行中时延依次上升（7.8 s、16.6 s、25.5 s），但这些模型的单次计时波动较大，因此请优先比较 token 计数而非秒数。

选择默认级别及何时升级

以下是我对推理级别的经验法则：

• 在 3.8 上，low 的作用比 Google 推荐的默认 medium 更大：它在 0 思考 token 的情况下给出了正确、设计良好的修复。因此，凡是上线前会有人阅读的内容（分诊、草稿、摘要、将由您评审的代码），请从它开始。

• 当输出将不经人工阅读直接上线时，保留使用 medium，因为额外的思考带来了更完整的失败模式分析，而无人值守的流水线恰恰最容易被“未列出的失败模式”击中。

• 将 high 保留给失败路径本身就是产品的输出，比如支付流程、迁移，或任何会被审阅者逐行审计的内容。在我的运行中，它是唯一抓到 4 个漏洞并文档化“重试耗尽后”行为的级别。

在 high 相当于 low 成本的 6.6 倍的情况下，这笔账在截至 2026 年 12 月 31 日每百万输出 token $3.75 与之后 $7.50 的价位下，读起来会非常不同，因此请按请求逐步升级，而非全局切换。

有个可选退路值得了解：Google 表示 3.7 Flash 仍对效率优先的工作负载提供完整支持。若 3.8 的额外谨慎超出您任务所需的成本，保留在 gemini-3.7-flash 上是受支持的选择，而非权宜之计。

如何从 PDF 提取结构化数据？

Gemini 3.8 Flash 可直接读取 PDF 作为输入，因此您可以发送发票或报告并就此提问。我使用了一页的供应商发票，其中包含发票号、日期、4 条明细以及总计。

将 PDF 附加到提示中

让我们使用 Files API 上传本地的发票 PDF。Files API 会在 Google 基础设施上处理文件存储与缓存：

	from google import genai
	client = genai.Client()
	print("Uploading invoice...")
	doc = client.files.upload(file="invoice_aug_2026.pdf")
	print(f"File uploaded: {doc.uri}\n")

	interaction = client.interactions.create(
	   model="gemini-3.8-flash",
	   input=[
	       {
	           "type": "text",
	           "text": "Extract the invoice number, total amount due, and due date.",
	       },
	       {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
	   ],
	)
	print(interaction.output_text)

我的发票输出如下：

三个值均正确。上传只需一次，文件在后续请求中可重用——这在您就同一文档提出多个问题时尤为重要。答案以 Markdown 列表返回，便于阅读，但不便于直接进入流水线。

使用响应模式强制输出 JSON

若要获取 JSON 而非散文，请在 response_format 中传入模式。在 Interactions API 上，这是顶层参数；您在旧教程中看到的 generationConfig 内的 responseMimeType 属于遗留的 generateContent 端点。

import json

from google import genai
from pydantic import BaseModel

client = genai.Client()


class Invoice(BaseModel):
    invoice_number: str
    total_due_usd: float
    due_date: str  # ISO 8601


doc = client.files.upload(file="invoice_aug_2026.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "text",
            "text": "Extract the invoice number, total amount due in USD, and due date.",
        },
        {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Invoice.model_json_schema(),
    },
)

invoice = json.loads(interaction.output_text)
print(invoice)

我收到的输出如下：

您的 Pydantic 类定义了所需字段与数据类型，而 model_json_schema() 生成 Gemini API 需要的 JSON 模式。处理完成后，json.loads() 将模型输出转换为标准的 Python 字典。从这一步开始，结构化数据即可转换为 DataFrame 行、写入数据库，或追加到 Google 表格。

使用 previous_interaction_id 追问

若要就同一文档提出第二个问题，请将第一次交互的 id 作为 previous_interaction_id 传入。服务器已拥有 PDF 与第一次对话，因此无需再次发送：

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input="List each line item on the invoice with its amount.",
)

print(follow_up.output_text)

它按顺序返回了全部 4 条明细（包括重复的 compute 行），并未评论重复项。对于所提问题，这是正确行为；若您希望它标注异常，请明确提出该要求。

就此例而言，3.7 的表现一致，因此 3.8 的额外勤勉体现在其自身推理上，而非主动进行您未请求的审计。

关于此调用，有两点需知：

• response_format 并未沿用，因为它是交互作用域，因此本轮返回为散文。

• 交互默认会被存储（store=True）：付费层为 55 天，免费层为 1 天；store=False 会使调用无状态，但随后您无法基于它串联 previous_interaction_id。

如何为 Gemini 3.8 Flash 添加函数调用？

在 Gemini 3.8 Flash 上，函数调用是一个回路：模型请求工具，您的代码执行它，您把结果传回，模型写出最终答案。本节将手动搭建该回路。

若您希望由 Google 为您运行这一回路并托管多工具 Agent，请继续阅读我们的 Gemini API 中的“托管 Agent” 教程。若从长期看您将走向 Agent，我们的 Building AI Agents with Google ADK 课程会基于相同基元构建一个完整的客服助理。

定义工具并执行交互回路

这里的工具是 lookup_exchange_rate(currency, date)，由一个小型内存字典支撑，因此示例无需外部 API 即可运行。其声明是一个 JSON 模式。模型从不直接运行函数；它返回一个 function_call 步骤，要求您的代码进行如下操作：

import json

from google import genai

client = genai.Client()

# Local "data source" standing in for a real FX API
RATES = {
    ("USD", "2026-08-03"): 87.42,
    ("USD", "2026-08-10"): 87.15,
    ("EUR", "2026-08-03"): 95.08,
}


def lookup_exchange_rate(currency: str, date: str) -> dict:
    rate = RATES.get((currency.upper(), date))
    if rate is None:
        return {"error": f"No rate for {currency} on {date}"}
    return {"currency": currency.upper(), "date": date, "inr_rate": rate}


rate_tool = {
    "type": "function",
    "name": "lookup_exchange_rate",
    "description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
    "parameters": {
        "type": "object",
        "properties": {
            "currency": {"type": "string", "description": "ISO code, e.g. USD"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["currency", "date"],
    },
}

# Turn 1: the model decides to call the tool
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What was the USD to INR exchange rate on 2026-08-03?",
    tools=[rate_tool],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")

# Your code executes the function locally
result = lookup_exchange_rate(**fc_step.arguments)

# Turn 2: send the result back; tools must be re-specified (interaction-scoped)
final = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[rate_tool],
)

print(final.output_text)

输出如下：

这里发生了三件事：

1. 第 1 轮返回了一个 function_call 步骤，包含名称、结构化参数和一个 id。

2. 您的 Python 代码执行了查询。

3. 第 2 轮发送了引用该调用的 function_result 块。

第 2 轮再次传入 tools 的原因与在 PDF 小节需重传 response_format 相同：previous_interaction_id 携带的是历史而非配置。

Gemini 3.x 上的函数调用常见错误

若工具回路出错，几乎总是两个问题之一。

其一，每个结果必须能映射回其调用。在 Interactions API 上，这体现在 function_result 块的 call_id 和 name；在遗留的 generateContent API 上，FunctionResponse 必须与前一条 FunctionCall 的 id 和 name 匹配。在 Gemini 3.x 上，两者都不是可选项。

其二，Malformed_Function_Call 错误通常出现在模型在工具调用前输出了评论。Google 的 3.8 开发者指南建议清理工具调用前的前置文本，用 \n\n 格式化内联指令，并将工作笔记包装进专用的函数调用而非裸文本。请收紧系统提示，不要盲目重试。

切换到 Gemini 3.8 Flash 会破坏什么？

这取决于您的起点。

• 从 Gemini 3.7 Flash：不会。将模型字符串改为 gemini-3.8-flash，本文所有代码片段均可不作修改直接运行，因为 API 表面相同。

• 从 Gemini 3.6 Flash 或更早：模型配置需要与以往相同的 15 分钟审计。

迁移清单（自 3.6 Flash 或更早版本）

按顺序完成以下步骤。第 1 至 3 项会立即导致 400；第 4 与 5 项会造成无声的质量问题。

1. 将模型 ID 改为 gemini-3.8-flash。

2. 删除废弃的采样参数：temperature、top_p、top_k 在 Gemini 3.x 中会被忽略或拒绝，而 frequency_penalty、presence_penalty、candidate_count 会抛出活跃 API 错误。从遗留配置中移除这 6 个参数。

3. 用 thinking_level 替换 thinking_budget：仅使用 low、medium 或 high。旧的 minimal 值会返回校验错误。同一请求中同时发送 thinking_budget 与 thinking_level 将返回 400。

4. 移除预填的模型轮次：从您构造的任何会话中剔除这些内容，并确保最后一个用户轮次包含非空文本。历史负载不能以模型轮次结尾。

5. 标准化多轮流程：依赖 previous_interaction_id 而非客户端回放历史。您必须在每个需要的轮次上重新指定工具、system_instruction 和 generation_config。

Google 在 Gemini API 模型文档中发布权威版本，包括若您的编码 Agent 支持“技能”时的自动化路径。即便如此，也请亲自通读一次；自动迁移不会告诉您当初为何设置 temperature=0.2。

您在生产中会遇到的错误

以下 4 个状态码值得专门处理，并说明它们在本 API 上的实际含义：

还有两点：

• 当 thinking_level: "high" 与较长的工具回路结合时，请设置明确的客户端超时，因为“请求挂起”比“失败”更糟，而 3.8 的额外勤勉意味着长时推理的概率更高而非更低。

• 并在每次请求中记录 interaction.id；这是您后续检索、调试或删除已存交互的句柄。

结语

本文的一切都源于三大转变。Interactions API 改变了调用方式；thinking_level 取代了您过去用来调优的所有采样旋钮；而通过 previous_interaction_id 的服务端状态，让 PDF 追问与工具回路都成为“一行式”的轮次，而非历史回放操练。Gemini 3.8 Flash 并未改变这些表面；它改变的是模型在内部“用功”的程度，这也是为何本文的度量在 3.8 上重新测得，而非沿用 3.7 的结果。

在采纳我的级别建议前，请将对比脚本对准您自己的积压任务；在支付重试竞态中胜出的级别，未必在您的 SQL 生成工作负载中同样取胜。

当单次 API 调用不再满足、而您希望构建生产级 AI 系统时，我们的 面向开发者的副 AI 工程师学习路径覆盖完整路线，面向数据科学家的副 AI 工程师学习路径则从数据侧切入，提供相同覆盖。