Interactions API数据模型详解：彻底读懂gemini-skills的Steps、流式事件与Delta类型

Interactions API数据模型详解：彻底读懂gemini-skills的Steps、流式事件与Delta类型

【免费下载链接】gemini-skillsSkills for the Gemini API, SDK and model/agent interactions项目地址: https://gitcode.com/gh_mirrors/ge/gemini-skills

gemini-skills是 Google 开源的 Gemini API 技能库，其中 gemini-interactions-api 技能 覆盖了 Interactions API 的全部核心能力。而想真正用好它，绕不开三组概念：Steps（步骤时间线）、流式事件（Streaming Events）和Delta 类型。这篇文章用最通俗的方式带你彻底读懂这套数据模型，新手也能一次看懂 🧭。

为什么需要理解 Interactions API 数据模型

大模型的训练知识有截止日期，而 API 迭代飞快。gemini-skills 正是为此而生：用轻量级的"技能"文档给 AI 助手补充最新上下文。项目 README.md 中的官方评估显示，加载技能后，Agent 按最佳实践生成正确 API 代码的能力达到87%（Gemini 3 Flash）到 96%（Gemini 3.1 Pro）。

Interactions API 是官方推荐的调用方式，一次请求对应一个Interaction对象。读懂它的数据模型，你就读懂了：

• 模型这一轮做了什么（Steps 时间线）
• 数据如何实时推送（流式事件）
• 每个增量片段是什么类型（Delta）

数据模型骨架：一切都在 Steps 里

Interactions API 的响应对象Interaction中最关键的是steps字段——一个带类型的步骤数组，像一条结构化时间线，完整记录这一轮对话里发生的每一件事 💡。

步骤分为两大类：

用户侧步骤

模型/服务端步骤

model_output与user_input的content数组支持四种内容类型：text（文本）、image、audio、document、video（后几者通过data/mime_type或uri携带数据）。

小技巧：迁移旧代码时，response.text对应的新写法就是interaction.steps[-1].content[0].text——取最后一步的第一个文本片段即可。

流式事件：实时输出的三步时间线

设置stream=True后，服务端会按固定顺序推送增量事件，整个流的结构非常整齐：

interaction.created → (step.start → step.delta 若干次 → step.stop)+ → interaction.completed

六个流式事件类型一览：

一个典型的 Python 处理模式（摘自 SKILL.md 的 Streaming 章节）：

for event in client.interactions.create( model="gemini-3.7-flash", input="用简单的话解释量子纠缠。", stream=True, ): if event.event_type == "step.delta" and event.delta.type == "text": print(event.delta.text, end="", flush=True) elif event.event_type == "interaction.completed": print(event.interaction.usage.total_tokens)

核心思路就两句话：只关心step.delta来"打字机式"输出文本，interaction.completed时读取总 token 数。

Delta 类型：五类增量数据逐个看

每个step.delta事件里都带一个delta对象，根据父步骤不同，共有五种类型：

换句话说：文本、音频、图像走model_output的 delta；模型的"思考"走thought的 delta。判断event.delta.type即可分发处理。

交互还有五种状态值需要留意：completed（完成）、in_progress（进行中）、requires_action（需用户操作，如工具回调）、failed（失败）、cancelled（取消）。后台任务（如 Deep Research Agent）就是靠轮询status来判断是否结束。

响应助手属性：一行代码取出结果

除了逐层遍历 steps，SDK 还在Interaction上提供了便捷属性：

日常开发 90% 的场景读output_text就够了，需要多模态结果时再取对应属性 🎯。

从旧 API 迁移：新旧数据模型速查

如果你还在用generateContent，references/migration.md 提供了完整的对照与检查清单。核心差异一目了然：

⚠️ 两个关键提醒：

1. SDK 版本：google-genai/@google/genai需 ≥ 2.0.0，它们自动使用新的 steps 数据模型；旧的google-generativeai、@google/generative-ai包已弃用。
2. 模型升级是"即插即用"的：在 Interactions API 内部换模型只需改字符串，如把已弃用的gemini-2.0-flash换成gemini-3.7-flash。

项目文件导航 📚

总结：三张表记住整个数据模型

• Steps：user_input负责输入，model_output负责输出，中间穿插thought与各类工具调用/结果步骤，构成完整时间线；
• 流式事件：created → start → delta* → stop → completed的固定节奏，六类事件各司其职；
• Delta：text/audio/image是生成内容的增量，thought_summary/thought_signature是思维过程的增量。

掌握这三组概念后，无论是一次性调用、流式渲染还是工具回调，你都能准确定位数据来自哪个步骤、处于什么状态。建议把 SKILL.md 的 Data Model 章节 收藏起来，作为日后开发的手边速查表 ✅

【免费下载链接】gemini-skillsSkills for the Gemini API, SDK and model/agent interactions项目地址: https://gitcode.com/gh_mirrors/ge/gemini-skills