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-skillsgemini-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字段——一个带类型的步骤数组像一条结构化时间线完整记录这一轮对话里发生的每一件事 。步骤分为两大类用户侧步骤步骤类型说明user_input用户输入文本、音频、多模态内含content数组模型/服务端步骤步骤类型说明model_output模型的最终生成结果content数组里可含文本、图像、音频等thought模型推理/思维链带必需的signature字段和可选summaryfunction_call/function_result工具调用请求与回传的工具结果google_search_call/google_search_resultGoogle 搜索工具步骤code_execution_call/code_execution_result代码执行工具步骤url_context_call/url_context_resultURL 上下文抓取步骤mcp_server_tool_call/mcp_server_tool_result远程 MCP 工具步骤file_search_call/file_search_result文件搜索工具步骤model_output与user_input的content数组支持四种内容类型text文本、image、audio、document、video后几者通过data/mime_type或uri携带数据。小技巧迁移旧代码时response.text对应的新写法就是interaction.steps[-1].content[0].text——取最后一步的第一个文本片段即可。流式事件实时输出的三步时间线设置streamTrue后服务端会按固定顺序推送增量事件整个流的结构非常整齐interaction.created → (step.start → step.delta 若干次 → step.stop) → interaction.completed六个流式事件类型一览事件作用interaction.created交互已创建包含元数据interaction.status_update交互级状态变更step.start新步骤开始带步骤type和初始元数据step.delta当前步骤的增量数据内含一个带类型的delta对象step.stop步骤结束包含indexinteraction.completed交互完成包含最终usagetoken 用量一个典型的 Python 处理模式摘自 SKILL.md 的 Streaming 章节for event in client.interactions.create( modelgemini-3.7-flash, input用简单的话解释量子纠缠。, streamTrue, ): if event.event_type step.delta and event.delta.type text: print(event.delta.text, end, flushTrue) elif event.event_type interaction.completed: print(event.interaction.usage.total_tokens)核心思路就两句话只关心step.delta来打字机式输出文本interaction.completed时读取总 token 数。Delta 类型五类增量数据逐个看每个step.delta事件里都带一个delta对象根据父步骤不同共有五种类型Delta 类型所属步骤内容textmodel_output增量文本 token最常见的打字机输出audiomodel_output音频片段base64imagemodel_output图像片段base64thought_summarythought思维过程摘要文本thought_signaturethought用于思维验证的不透明签名换句话说文本、音频、图像走model_output的 delta模型的思考走thought的 delta。判断event.delta.type即可分发处理。交互还有五种状态值需要留意completed完成、in_progress进行中、requires_action需用户操作如工具回调、failed失败、cancelled取消。后台任务如 Deep Research Agent就是靠轮询status来判断是否结束。响应助手属性一行代码取出结果除了逐层遍历 stepsSDK 还在Interaction上提供了便捷属性属性说明output_text末尾model_output步骤中最后一段连续文本output_image本次响应中模型生成的最后一张图base64 mime_typeoutput_audio本次响应中模型生成的最后一段音频base64 mime_type日常开发 90% 的场景读output_text就够了需要多模态结果时再取对应属性 。从旧 API 迁移新旧数据模型速查如果你还在用generateContentreferences/migration.md 提供了完整的对照与检查清单。核心差异一目了然维度旧 generateContentInteractions APISDK 方法client.models.generate_content()client.interactions.create()取文本response.textinteraction.steps[-1].content[0].text多轮对话手动维护历史数组previous_interaction_id流式generate_content_stream()streamTruestep.delta事件函数调用candidates[0].content.parts里翻找独立的function_call步骤REST 端点POST /v1beta/models/{model}:generateContentPOST /v1beta/interactions⚠️ 两个关键提醒SDK 版本google-genai/google/genai需 ≥ 2.0.0它们自动使用新的 steps 数据模型旧的google-generativeai、google/generative-ai包已弃用。模型升级是即插即用的在 Interactions API 内部换模型只需改字符串如把已弃用的gemini-2.0-flash换成gemini-3.7-flash。项目文件导航 文件用途README.md项目总览、技能清单与安装方式plugin.json插件元信息名称、版本、关键词skills/gemini-api-dev/SKILL.mdGemini API 应用开发最佳实践skills/gemini-interactions-api/SKILL.mdInteractions API 完整技能本文数据模型的出处skills/gemini-interactions-api/references/migration.md迁移对照表与检查清单skills/gemini-live-api-dev/SKILL.md实时双向流式Live API技能skills/gemini-omni-flash-api/SKILL.md视频生成/编辑专项技能总结三张表记住整个数据模型Stepsuser_input负责输入model_output负责输出中间穿插thought与各类工具调用/结果步骤构成完整时间线流式事件created → start → delta* → stop → completed的固定节奏六类事件各司其职Deltatext/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考