---
url: /python/gemini_api_advanced.md
description: >-
  手把手讲透 Gemini API 进阶用法——函数调用、流式输出、多模态输入、结构化 JSON、后台任务与托管智能体，附最新 google-genai
  SDK 与 gemini-3.7-flash 实战代码。
---

# Gemini API 进阶用法：从"会聊天"到"会干活"

说个有点扎心的事。

我前两天 review 一个实习生的代码，发现他调 Gemini API 的方式跟我 2024 年刚学的时候一模一样：传一句话，等一个回复，把 `.text` 打印出来。那一刻我意识到——**很多人不是不会用 API，是还活在上个版本。**

2026 年的 Gemini API，早就不是"你问一句它答一句"的传声筒了。函数调用让它**能动手查天气、查数据库**；流式输出让它**像人一样一个字一个字往外蹦**；结构化输出让它**吐出来的直接是能用的 JSON**；连后台跑长任务、调一个远程托管的智能体都给你包好了。

你如果还在 `generate_content("你好")` 原地打转，等于开着法拉利去菜市场买葱。

这篇不教你装 SDK、配 Key 这种入门活（那是另一篇《Python SDK 基本用法》的事），专讲**进阶那一层**——就是那些"早知道能这么写，我上周能少加两天班"的东西。

## Gemini API 是什么（一句话版）

> Gemini API 是谷歌给开发者开的"后门"：让你在自己的代码里，直接调用 Gemini 系列模型的能力，而不是点开网页跟它聊天。

它和网页版 Gemini 的关系，就像餐厅后厨和前厅：你吃的那盘菜（网页版），和厨师手里的那把刀（API），其实是一个厨房出来的，但 API 这把刀你能自己拿去切别的菜。

2026 年它最大的变化是**换了一套更现代的交互范式**——官方现在主推 **Interactions API**，底层 SDK 也从老掉牙的 `google-generativeai` 换成了 `google-genai`。一句话概括新写法：

```python
from google import genai

client = genai.Client()  # 自动读环境变量 GEMINI_API_KEY
interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="用一句话解释什么是大模型"
)
print(interaction.output_text)
```

如果你在别处看到 `genai.configure(api_key=...)` 或者 `model = genai.GenerativeModel(...)` 这种老写法——**别慌，它还能跑**，只是官方已经不推荐了。新项目直接用上面这套 `client.interactions.create` 就行。

> 小提醒：你现在能用的主力模型是 `gemini-3.7-flash`（2026 年 8 月刚发布，主打编程和智能体，输入输出定价大约 0.75 / 3.75 美元每百万 token，比上一代便宜一半）。别再对着教程写 `gemini-pro` 了，那个早就是博物馆里的东西。

## 进阶能力，挑能救命的讲

下面这五个，是我实际写业务时最高频用到的。不炫技，全是能省时间的真东西。

* **函数调用（Function Calling）**：模型自己决定"该调你哪个函数"，你只管把函数实现好。查天气、查库存、下单，全靠它
* **流式输出（Streaming）**：别等它把整段想完再吐。一个字一个字往外蹦，前端体验直接拉满，长文本也不用干等
* **多模态输入**：一张图、一段音频、一个文档，混在一句话里一起丢给它，它全看得懂
* **结构化输出（Structured Output）**：你给个 JSON Schema，它吐出来的直接是可解析的对象，不用再正则抠字符串
* **后台任务 + 托管智能体**：200 页 PDF 要慢慢读？放后台跑，跑完来取；复杂的多步活，直接甩给远程托管的 Antigravity 智能体

## 场景：这些能力到底解决什么痛

**场景一：做一个"会自己查资料"的客服。**
用户问"你们家北京仓还有多少库存"，老写法是模型瞎编一个数。用了函数调用，模型会老老实实返回一个"我要查库存"的信号，你拿这个信号去查真实数据库，再把结果喂回去——**答出来的每一句都有依据**。

**场景二：做一个"像人在打字"的对话界面。**
用户发一句，你总不能让屏幕卡三秒再整段蹦出来。流式输出让回复一个字一个字出现，体验上跟真人打字没两样，留存率肉眼可见地高。

**场景三：把乱七八糟的 Excel 报告变成结构化数据。**
以前模型吐一段散文，你还得自己写解析。现在你给它一个 Schema，它直接返回 `Recipe` 对象那样的结构——**拿起来就能用**，不用再当字符串裁缝。

> 我个人的立场很明确：2026 年还手动解析模型自由文本的人，不是在写代码，是在给自己找 bug。

## 初体验：三个能直接跑的例子

下面三段都是精简过的实战代码，复制改改就能用。记得先 `pip install -U google-genai` 并设好 `GEMINI_API_KEY`。

**① 函数调用——让模型自己决定查不查天气**

```python
weather_tool = {
    "type": "function",
    "name": "get_current_temperature",
    "description": "查询某个地点的当前气温",
    "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
    },
}

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="北京现在多少度？",
    tools=[weather_tool],
)

# 模型不会真的查天气，而是返回一个 function_call 步骤
for step in interaction.steps:
    if step.type == "function_call":
        result = get_current_temperature(**step.args)   # 你本地执行
        follow_up = client.interactions.create(
            model="gemini-3.7-flash",
            input=result,
            previous_interaction_id=interaction.id,     # 承接上文
        )
        print(follow_up.output_text)
```

想更省事？直接挂官方的联网工具，自动搜最新信息还带引用：

```python
interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="2026 年最新的 AI 芯片有哪些？",
    tools=[{"type": "google_search"}],   # 自动联网 + 带出处引用
)
print(interaction.output_text)
```

**② 流式输出——像打字机一样往外蹦**

```python
stream = client.interactions.create(
    model="gemini-3.7-flash",
    input="逐句讲清楚什么是死锁",
    stream=True,
)
for chunk in stream:
    print(chunk, end="")   # 每个 chunk 是一小段增量输出
```

**③ 结构化输出——直接拿到能用的对象**

```python
from pydantic import BaseModel
from typing import List, Optional

class Recipe(BaseModel):
    recipe_name: str
    ingredients: List[str]
    prep_time_minutes: Optional[int]

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="给我一个香蕉面包的配方",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Recipe.model_json_schema(),
    },
)
recipe = Recipe.model_validate_json(interaction.output_text)
print(recipe.recipe_name, recipe.ingredients)
```

## 进阶：把这几块拼起来才叫真本事

单个能力好上手，但**业务价值在组合**。给你两个我常用的"拼接姿势"：

**多模态 + 结构化**：丢一张商品图进去，让它按 Schema 返回 `{名称, 类别, 预估价格, 卖点}`，直接进你的商品库，零人工录入。

```python
interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input=[
        {"type": "text", "text": "识别这张图里的商品，按结构返回名称、类别和卖点"},
        {"type": "image", "data": image_b64, "mime_type": "image/jpeg"},
    ],
    response_format={"type": "text", "mime_type": "application/json",
                     "schema": Product.model_json_schema()},
)
```

**后台任务**：200 页财报不用卡在前端等。丢进去 `background=True`，先返回个任务 ID，过会儿 `client.interactions.get(id)` 来取结果，主线程该干嘛干嘛。

```python
interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="把这份 200 页的财报整理成 10 条关键结论",
    background=True,
)
result = client.interactions.get(interaction.id)   # 不阻塞，回头来取
```

> 真到复杂多步的活（又要读文件、又要写代码、还要反复试错），别自己硬撸——直接挂 `agent="antigravity-preview-05-2026", environment="remote"`，把任务甩给谷歌托管的远程智能体。你得的是结果，不是过程。

最后一句大实话：API 能力一年一个样，**SDK 换、模型换、范式换，但"让模型替你干活"这个方向不会换**。把函数调用和结构化输出这两块吃透，你就能甩开 80% 还在 `print(response.text)` 的人。

## 进阶

更多开源技术干货和学习资料，关注公众号「遇码」，领取专属福利。