跳转到主要内容
本页扩展 原生 Gemini 入门,同一个 Python 文件提供纯文本 SSE 和函数工具闭环。两种模式都读取真实 SSE 数据流,完整校验后才打印最终可见答案;不会逐片向终端展示未完成文本。先向管理员确认模型和渠道支持原生流式及函数工具。

准备与运行

使用 Python 3.10+,仅依赖标准库,无需安装供应商 SDK。预先设置网关令牌 API_KEY,然后设置不含 /v1 或 /v1beta 的根地址;允许部署路径前缀。
从文档目录运行;单独保存时,去掉命令中的 examples/。第一条只请求一句问候;第二条提供 multiply,让模型计算 7 × 8,再将结果回传给模型生成最终回答。
API_NATIVE_MODE 默认 text;tools 模式也允许模型直接回答。测试固定了模拟回答,真实模型措辞和是否调用工具均不保证。

事件与闭环

functionCall.id 存在时必须原样回传,重复或空 ID 会失败;没有 ID 时按调用顺序与名称关联,不杜撰 ID。即使同一函数调用多次,也逐一返回对应结果。 保留每个 part 上的 thoughtSignature,包括空文本和仅有签名的 part;不把多个签名合并,不把 model 内容压成一段文本。thought: true 仅影响终端展示,不会从回放历史删除。签名是否由目标渠道正确转发仍需联调。 本例使用默认的完整 functionCall.args 模式,没有启用细粒度参数流式扩展。遇到 partialArgs 或 willContinue: true 会退出,不能像 Claude 那样拼接任意 JSON 字符串。多个完整调用可以分布在多个 SSE 帧中;所有候选结束后才执行。模型 ID 沿用入门示例的裸 ID 字符限制。

完整 Python 示例

失败与资源边界

SSE 读取器处理增量 UTF-8、LF / CRLF / CR、注释及多行 data,忽略 id / retry,不会因服务端建议重连就自动重放请求。每次 socket 操作超时 60 秒;这不是整段工作流的总耗时上限。每轮最多 512 个数据事件、4096 行、1,048,576 个解码字符,每行最多 65,536 个字符;这些都是示例边界,不是网关限制。 工具只允许本地纯计算 multiply,参数必须恰好是有限数值 a、b,拒绝布尔值、额外字段和非有限结果。最多 3 次模型请求,每轮最多 4 次工具调用;达到第三轮还要求工具时直接退出。工具结果全部准备好后才发送下一轮。对带副作用的工具,仍需另行实现授权、幂等执行与恢复,不能用这个乘法示例替代事务设计。 HTTP 失败、重定向、错误内容类型、非法 JSON、截断 SSE、异常断连、业务未完成和不支持的协议扩展均返回非零退出状态。不会打印密钥、上游错误体、思考文本或不完整答案;遇到未知事件/内容块采取失败退出策略,需要显式扩展解析器才能支持它们。 Gemini 另限制每轮 256 个 parts、工具参数序列化后 16,384 个字符。细粒度参数分片、多个候选、媒体块、Live API 和异步工具调度不在示例支持范围。

验证

运行 npm run check:examples,测试会启动本机 HTTP fixture 并执行这份脚本,检查纯文本与工具模式、完整历史和签名、结果关联、UTF-8 分块、错误与断流、无重试及第二轮失败短路。没有真实模型请求;真实渠道是否返回正确事件和保留签名,仍需部署端验证。 Gemini 原生 API · 签名保留 Read in English