Gemini 中文指南
获取 API 密钥 ↗

迁移到 Interactions API

↓ 下载 MarkdownInteractions API

本指南可帮助您从 generateContent API 至 Interactions API。

Interactions API 是使用 Gemini 进行构建的标准接口。它针对智能体工作流程、服务器端状态管理和复杂的多模式、多轮对话进行了优化,同时仍然完全支持简单的无状态单轮请求。同时 generateContent 仍得到充分支持,我们推荐 Interactions API 用于所有新开发。

为什么要迁移? #

Interactions API 提供了一种更结构化、更强大的方式来使用 Gemini 进行构建:

  • 服务器端历史管理:简化的多匝流程 previous_interaction_id。服务器默认启用状态(store=true),但您可以通过设置选择无状态行为 store=false.
  • 可观察的执行步骤:键入步骤可以轻松调试复杂的流程并为中间事件(如想法或搜索小部件)呈现 UI。
  • 专为智能体工作流程而构建:通过类型化执行步骤对多步骤工具使用、编排和复杂推理流程提供本机支持。
  • 长时间运行和后台任务:支持使用 Deep Think 和 Deep Research 等将时间密集型操作卸载到后台进程 background=true.

基本输入/输出 #

本节介绍如何迁移简单的文本生成请求。

之前(生成内容) #

该 generateContent API是无状态的,直接返回响应。响应结构将输出包装在一个列表中 candidates,每个包含 content 与一个列表 parts 来解析。

python
from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-4-hydrogen", contents="Tell me a joke."
)
print(response.text)

Interactions API 返回一个存储的交互资源 steps 时间线。虽然您可以检查 steps 手动数组来查找中间事件,Google GenAI SDK 直接在返回的值上提供方便的属性 Interaction 对象访问最终输出。

最常见的便利属性是 .output_text (字符串),自动提取并连接连续的 TextContent 模型响应末尾的块。虽然这非常适合简单的响应,但它不包括由非文本内容(例如想法、图像、音频或工具调用)分隔的早期文本块。对于复杂或交错的多模态响应,您必须手动迭代 steps 相反。

python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen", input="Tell me a joke."
)

print(interaction.output_text)

多轮对话 #

Interactions API 默认存储交互,从而实现多轮对话的服务器端状态管理。

之前(生成内容) #

在 generateContent,您必须使用手动管理对话历史记录 contents 数组或客户端聊天助手。

使用聊天助手(推荐)

python
from google import genai

client = genai.Client()

chat = client.chats.create(model="gemini-4-hydrogen")
response1 = chat.send_message("Hi, my name is Phil.")
print(response1.text)

response2 = chat.send_message("What is my name?")
print(response2.text)

手动管理历史记录

python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[
        types.Content(
            role="user", parts=[types.Part.from_text("Hi, my name is Phil.")]
        ),
        types.Content(
            role="model",
            parts=[types.Part.from_text("Hi Phil, how can I help you?")],
        ),
        types.Content(
            role="user", parts=[types.Part.from_text("What is my name?")]
        ),
    ],
)
print(response.text)

之后(Interactions API) #

Interactions API 管理服务器上的状态。您通过引用继续对话 previous_interaction_id.

python
from google import genai

client = genai.Client()

interaction1 = client.interactions.create(
    model="gemini-4-hydrogen", input="Hi, my name is Phil."
)
print("Response 1:", interaction1.output_text)

interaction2 = client.interactions.create(
    model="gemini-4-hydrogen",
    previous_interaction_id=interaction1.id,
    input="What is my name?",
)
print("Response 2:", interaction2.output_text)

多模态输入 #

两个 API 都支持多模态输入(文本、图像、视频等)。

之前(生成内容) #

在 generateContent,你传递一个列表 parts 内 contents 数组。响应返回输出 parts 第一候选人的。

python
from google import genai
from google.genai import types

client = genai.Client()

with open("sample.jpg", "rb") as f:
    image_bytes = f.read()

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[
        types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
        "Describe this image.",
    ],
)
print(response.text)

之后(Interactions API) #

在 Interactions API 中,您将一个数组传递给 input 场。您可以通过查找来检索输出内容 model_output 时间线中的一步。

python
from google import genai

client = genai.Client()

with open("sample.jpg", "rb") as f:
    image_bytes = f.read()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {
            "type": "image",
            "mime_type": "image/jpeg",
            "data": image_bytes,
        },
        {"type": "text", "text": "Describe this image."},
    ],
)
print(interaction.output_text)

结构化输出 #

要使模型返回与特定架构匹配的 JSON,请配置响应格式。

之前(生成内容) #

在 generateContent,您可以使用以下命令配置输出格式 response_mime_type 和 response_schema 嵌套在里面的字段 config (或 generationConfig) 对象。

python
from google import genai
from google.genai import types
from pydantic import BaseModel

client = genai.Client()

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

response = client.models.generate_content(
    model="gemini-2.5-flash-lite",
    contents="Give me a recipe for chocolate chip cookies.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=Recipe,
    ),
)
print(response.text)

之后(Interactions API) #

在 Interactions API 中,输出格式控件移至顶层 response_format 场。当您请求多种输出类型时,传递单个格式对象或一组格式对象。

python
from google import genai
from pydantic import BaseModel

client = genai.Client()

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Give me a recipe for chocolate chip cookies.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Recipe.model_json_schema(),
    },
)

print(interaction.output_text)

多模态生成 #

当以文本以外的方式(例如图像或音频)生成内容时,主要区别在于响应如何构建生成的媒体。

之前(生成内容) #

在 generateContent,响应直接返回生成的媒体 parts 候选人的,通常作为base64数据 inlineData.

json
# Response structure concept
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is your generated image:"
          },
          {
            "inlineData": {
              "mimeType": "image/jpeg",
              "data": "...base64..."
            }
          }
        ]
      }
    }
  ]
}

之后(Interactions API) #

在 Interactions API 中,生成的媒体在 content 的数组 model_output 时间线中的一步,保持交互的时间顺序。

json
# Response structure concept
{
  "id": "int_123",
  "steps": [
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Here is your generated image:"
        },
        {
          "type": "image",
          "mime_type": "image/jpeg",
          "data": "...base64..." // Or a reference URL in future
        }
      ]
    }
  ]
}

这使响应解析与输入和文本输出的处理方式保持一致——一切都是时间线中的一个步骤。

服务器端工具 #

Gemini 支持 Google 搜索事实依据等内置服务器端工具。主要区别在于响应如何表示工具执行。

之前(生成内容) #

在 generateContent,服务器端工具很大程度上是不透明的。您启用该工具并通过单独的命令获得最终答案 groundingMetadata 对象。至关重要的是,引用不是内联的; groundingSupports 使用字符索引将文本段映射回网络源 groundingChunks.

python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents="Who won Euro 2024?",
    config=types.GenerateContentConfig(
        tools=[{"google_search": {}}]
    ),
)

metadata = response.candidates[0].grounding_metadata
if metadata.search_entry_point:
    print(f"Search Entry Point: {metadata.search_entry_point.rendered_content}")

for support in metadata.grounding_supports:
    print(f"Citation: {support.segment.text}")

之后(Interactions API) #

在 Interactions API 中,服务器端工具提供完整的时间线透明度。 API 将调用和结果记录为不同的执行 steps (google_search_call 和 google_search_result),准确揭示模型检索的数据。

此外,API 返回引用 内联。代替从单独的元数据对象映射索引, model_output 步骤包含其自己的 annotations 数组直接链接到源。

python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Who won Euro 2024?",
    tools=[{"type": "google_search"}],
)

for step in interaction.steps:
    if step.type == "google_search_result":
        print(f"Search Suggestions: {step.search_suggestions}")
    elif step.type == "model_output":
        print(f"Answer: {step.content[0].text}")
        if step.content[0].annotations:
            for anno in step.content[0].annotations:
                print(f"Citation: {anno.title} ({anno.uri})")

函数调用 #

函数调用和结果的结构也已更改以适应步骤架构。

之前(生成内容) #

在 generateContent,响应返回候选中的函数调用。

python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents="What's the weather in Boston?",
    config=types.GenerateContentConfig(tools=[weather_tool]),
)

function_call = response.candidates[0].content.parts[0].function_call
print(f"Requested tool: {function_call.name}")

result = "52°F and rain"

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[
        types.Content(
            role="user",
            parts=[
                types.Part.from_text(text="What's the weather in Boston?")
            ],
        ),
        response.candidates[0].content,
        types.Content(
            role="user",
            parts=[
                types.Part.from_function_response(
                    name=function_call.name,
                    response={"result": result},
                )
            ],
        ),
    ],
    config=types.GenerateContentConfig(tools=[weather_tool]),
)
print(response.text)

之后(Interactions API) #

工具调用和结果现在是时间线中不同的步骤。

python
from google import genai

client = genai.Client()

weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Gets weather",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
    },
}

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="What's the weather in Boston?",
    tools=[weather_tool],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Executing {step.name} for {step.arguments}")

        result = "52°F and rain"

        interaction = client.interactions.create(
            model="gemini-4-hydrogen",
            previous_interaction_id=interaction.id,
            input=[
                {
                    "type": "function_result",
                    "call_id": step.id,
                    "name": step.name,
                    "result": [{"type": "text", "text": result}],
                }
            ],
        )
        print(next_interaction.output_text)

流式输出 #

流式传输的一个关键区别是 Interactions API 使用相同的端点 "stream": true 在请求正文中,而 generateContent API 需要调用专用端点(:streamGenerateContent).

此外,流事件现在使用专门的类型来监视交互生命周期并跟踪时间轴上的执行步骤。

之前(生成内容流) #

与 generateContent,您消耗响应块流。

python
response = client.models.generate_content_stream(
    model="gemini-4-hydrogen", contents="Tell me a story"
)
for chunk in response:
    print(chunk.text, end="")

之后(Interactions API) #

在 Interactions API 中,流式传输使用服务器发送事件 (SSE) 和专用增量类型来表示发生时的执行步骤。

python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Tell me a story",
    stream=True,
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
    elif event.event_type == "interaction.completed":
        print(f"\n\n--- Stream Finished ---")

流媒体工具和函数调用 #

工具在流中的行为方式已经从 generateContent 提供更精细的控制和可见性。

之前(生成内容) #

与 generateContent,流函数调用在单个块中完成。您无法看到实时生成的参数,因此处理程序只是检查完整的参数 functionCall 对象。

python
from google import genai
from google.genai import types

client = genai.Client()

stream = client.models.generate_content_stream(
    model="gemini-4-hydrogen",
    contents="What's the weather in Boston?",
    config=types.GenerateContentConfig(tools=[weather_tool]),
)

for chunk in stream:
    if chunk.candidates[0].content.parts[0].function_call:
        fc = chunk.candidates[0].content.parts[0].function_call
        print(f"Call: {fc.name}({fc.args})")
    elif chunk.text:
        print(chunk.text, end="")

之后(Interactions API) #

Interactions API 逐个字符地流函数调用参数: arguments_delta 事件。整个工具生命周期——思考、调用、结果和输出——表现为一系列不同的步骤。

python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-4-hydrogen",
    input="What's the weather in Boston?",
    tools=[get_weather_tool],
    stream=True,
)

for event in stream:
    if event.event_type == "step.start":
        if event.step.type == "function_call":
            print(f"Calling: {event.step.name}")
    elif event.event_type == "step.delta":
        if event.delta.type == "arguments_delta":
            print(f" args: {event.delta.arguments}")
        elif event.delta.type == "text":
            print(event.delta.text, end="")
    elif event.event_type == "interaction.completed":
        print("\n--- Done ---")

搜索标题、API 名称或正文内容