Gemini 原生协议：contents、parts 与兼容迁移
解释 Gemini 原生消息的 contents 与 parts 结构、响应读取和消息角色差异，提供迁移到德他纯文本入口的判断方法。
作者：德他数据技术团队 · 更新于 2026-09-24
核心解答
Gemini 原生请求围绕 contents 与 parts 组织消息，响应从 candidates 中读取内容；它不是 Chat Completions 的 messages/choices 格式。德他当前未开放 Gemini 原生协议，只能对获核准纯文本方案使用兼容入口。
阅读范围与当前状态
本篇为完整的协议说明或接入准备指南，不代表所述原生、视频或扩展能力已在德他开放。真实调用以接口开放范围和具体模型的核准状态为准。
原生消息结构
Gemini 原生生成接口以内容列表和内容片段组织输入。仅展示文本结构的示意如下，不是德他可执行请求：
{"contents":[{"role":"user","parts":[{"text":"请用三句话解释缓存。"}]}]}
原生对话通常使用 user/model 表示轮次，响应内容来自 candidates 的内容片段。不能把数组字段换一个名字就认为所有原生语义已经转换。
迁移对照
| 原生概念 | 德他纯文本兼容处理 |
| --- | --- |
| contents 中的文本轮次 | 整理为 messages |
| user/model 角色 | 按 user/assistant 组织文本 |
| parts 中的文本 | 合并或明确拆分为字符串内容 |
| 图像等非文本片段 | 当前不支持迁移到文本入口 |
| candidates 结果 | 兼容入口读取 choices |
实际模型必须支持所选消息与任务，不能仅凭品牌推断。
适配步骤
先列出应用依赖的能力：是否要求图片、工具、结构化扩展或流式。只要核心需求依赖当前未开放能力，就应判定该应用暂不兼容。仅纯文本需求可以在具体模型方案已核准后，使用德他最小文本示例验证。
安全与费用
原厂 SDK 可能自动携带专有路径与参数，应检查实际请求而非只看 Base URL 输入框。不要记录密钥、用户私密提示或带授权的素材地址；失败与超时按请求编号核验费用。
常见问题
可以把 model 角色原样传给德他吗？
不可以，德他支持的消息角色以文本参数文档为准。
多个 parts 是否都能直接拼接？
仅纯文本且业务允许时才考虑；媒体片段和结构化语义不能当普通字符串丢弃。
关联文档：德他数据教程。本文按德他实际功能独立编写。