Python 调用 Gemini API:从零到流式输出
首页 / 文章 / 技术教程 / Python 调用 Gemini API:从零到流式输出
用官方 openai 包对接Itzyk API:改 base_url 与 Key 即可调用 Gemini,涵盖非流式、SSE 流式、多轮对话、错误重试与成本控制。
作者:Itzyk API · 发布:2026-09-30 · 更新:2026-11-09
一、前言 Python 是调用大模型最常见的语言之一:脚本、爬虫后处理、数据分析、FastAPI 服务,都能很快接上 AI。很多人第一次用 Gemini 时会卡住两件事:一是官方 SDK 和 OpenAI 写法不一样;二是国内直连不稳定、美元账单难对。 Itzyk API(https://api.itzyk.top)提供 OpenAI 兼容 的 Gemini 接口。对 Python 开发者来说,继续用官方 openai 包即可,只需改 base url 和 api key 。本文从环境准备、第一次非流式调用、SSE 流式、多轮对话、错误处理到成本控制,带你把 Gemini 稳稳接进 Python 项目。 推荐默认模型: gemini-3.6-flash (快、便宜,适合联调与日常对话)。 --- 二、环境准备 2.1 安装依赖 2.2 获取 API Key 1. 打开 https://api.itzyk.top/ 注册并登录 2. 「API 管理」→「创建 API Key」,复制 sk- 开头的密钥 3. 控制台充值少量余额(支付宝),保证第一次请求能扣费 安全提示: 不要把 Key 写进 Notebook 然后上传 GitHub;生产环境用密钥管理或容器 Secret。 --- 三、第一次非流式调用 成功时会打印回答,以及本次输入/输出 token。若报 401 ,检查 Key; 402 是余额不足; 403 多为模型未授权或 IP 白名单。 不确定可用模型时: 或用 curl: --- 四、流式输出:让终端「边想边说」 对话产品、CLI 助手、Notebook 演示更适合流式。Itzyk兼容 OpenAI SSE: stream=True 即可。 注意: 1. 不要把整段响应当 JSON 一次 loads 2. 部分 chunk 的 delta.content 可能为 None ,要判断 3. 对账仍以最终 usage 或控制台费用记录为准 FastAPI 里可以把生成器包成 StreamingResponse ,前端用 fetch 读流即可。 --- 五、多轮对话与参数建议 | 参数 | 建议 | 说明 | |------|------|------| | temperature | 0.2~0.7 | 抽取/客服偏低,创意偏高 | | max tokens | 按业务封顶 | 防止一次回答过长烧钱 | | model | 先 Flash | 复杂推理再换 Pro | 复杂推理、长文档可用 gemini-3.1-pro-preview ,单价更高,适合离线或低频路径。 --- 六、封装成可复用模块 业务代码里不要到处 OpenAI ... ,收进一个模块: 上线切模型只需改环境变量;超时、重试、日志脱敏也可以集中在这里加。 --- 七、错误处理与重试 | HTTP | 含义 | 建议 | |------|------|------| | 401 | Key 无效/过期 | 重建 Key | | 402 | 余额不足 | 充值 | | 403 | 权限/白名单 | 放开模型或 IP | | 429 | 限流 | 退避降并发 | | 502/503 | 上游异常 | 短时重试 | --- 八、成本控制小技巧 1. 日常默认 gemini-3.6-flash ,Pro 留给真正需要的路径 2. system prompt 写短,少塞无关历史 3. 设置合理 max tokens 4. 把 usage 打到日志,和客户侧账单对照 5. 开发机用独立 Key,避免调试打穿生产余额 公开价格页可先估算成本,再决定产品定价。 --- 九、小结 Python 调 Gemini 在Itzyk上的最短路径是:安装 openai → 配置 base url 与 Key → 非流式跑通 → 开流式 → 封装客户端。先用 Flash 联调,再按场景升级。 控制台:https://api.itzyk.top/ 。把本文示例跑通后,你就可以把它嵌进脚本、Notebook 或 Web 服务了。 --- 十、实战:做成命令行小工具 把调用封装成 CLI,团队成员不用读代码也能试用: 联调阶段用 CLI 验证模型权限与余额,比每次改 Web 服务更轻。把 usage 打到 stderr,不影响把 stdout 管道给下游脚本。 --- 十一、异步调用(asyncio) 高并发服务可用 AsyncOpenAI: 注意:并发上去后更容易撞 429,请配合信号量或队列限制同时飞行的请求数,例如 asyncio.Semaphore 5 。 --- 十二、与 Jupyter / 数据分析结合 数据分析师常在 Notebook 里清洗结果后再让模型写结论: 1. pandas 算出表或指标 2. 把「表格的 markdown 或 CSV 片段」塞进 user 3. 要求模型只基于给定数据解读,禁止编造数字 提示词里写清:「以下是唯一数据源;未出现的指标回答未知」。这样比让模型「凭印象」写行业报告可靠得多。注意控制贴表长度,超长先抽样或汇总。 --- 十三、安全与合规提醒 - Key 不进日志:对请求中间件做脱敏 - 用户输入做长度与敏感词策略(按你们行业合规) - 不要把内部未公开文档未经脱敏就批量送模型 - 生产与开发 Key 分离,离职即禁用 Itzyk侧已有鉴权与计费;业务侧仍要对自己的数据出境与留存负责。 --- 十四、常见问题 FAQ Q:和 google-generativeai 官方包比呢? 若你已深度绑定官方包且网络稳定,可继续官方路径。若希望与 OpenAI 生态统一、人民币账单、国内访问更省心,用Itzyk + openai 包通常更简单。 Q:流式中途断开怎么办? 捕获异常,向用户展示已生成部分,并允许「继续」;服务端不要假设流一定完整结束。 Q:如何做结构化输出? 在 system 中要求「只输出 JSON」,或在 prompt 给 schema 示例;拿到后 json.loads ,失败则短重试一次。需要严格 schema 时,业务层再校验字段。 Q:单元测试怎么写? 对 chat 做 mock,避免 CI 真实扣费;另备一条可选的集成测试(需密钥与网络)夜间跑。 --- 十五、落地检查清单 1. .env 已配置且未进仓库 2. curl /v1/models 成功 3. 非流式 chat 成功并打印 usage 4. 流式在终端逐字输出 5. 封装 get client / chat 6. 401/402/429 有明确处理 7. 默认模型为 Flash 全部勾完,就可以把模块并入正式服务。控制台:https://api.itzyk.top/ 。 --- 十六、团队协作时的推荐目录结构 一个小而清晰的目录,能避免「脚本满天飞、谁也不知道官方入口在哪」: 约定:业务代码禁止直接 OpenAI ... ;新人或外包只许调用 gemini client.chat 。这样换模型、加超时、加日志时只改一处。Code Review 时若发现散落的 SDK 初始化,直接打回。 文档里写明:开发用哪把 Key、如何申请权限、402 找谁充值。这些「人」的流程,往往比代码本身更能减少事故。 --- 十七、从原型到生产的迁移节奏 第一周:Notebook 或脚本跑通 Flash 非流式,确认中文效果可接受。 第二周:加上流式与基础封装,接到测试环境的一个真实接口。 第三周:补 usage 打点、错误码映射、开发/生产 Key 分离。 第四周:小流量灰度,看延迟与费用曲线,再决定是否全量。 不要第一天就上 Pro 和全量用户。费用与口碑都需要观察窗口。若效果不够,再针对「那 10% 难例」开 Pro,而不是全局升级。 --- 十八、结束语 Python 生态接 Gemini,在Itzyk上已经足够「无聊」——这是褒义:步骤少、坑少、和现有 OpenAI 代码同构。把无聊的部分标准化之后,你才能把精力放在提示词、评测与产品体验这些真正产生差异的地方。 现在就打开控制台创建开发 Key,把冒烟脚本跑绿,然后把 gemini client.py 推进你们的主仓库吧。 --- 十九、提示词与业务代码解耦 许多项目把超长中文提示词直接写在 Python 字符串里,改一个标点都要发版。更稳妥的做法是:提示词放 prompts/ .md 或配置中心,代码只负责读取、填充变量、调用 chat 。这样产品同学可以改文案,研发专注链路与配额。 变量填充时用明确占位符,例如 {{user question}} 、 {{knowledge snip}} ,并在填充前做长度检查,防止用户把整本小说粘进槽位。对提示词做简单单测:必填槽位是否都存在、渲染后是否仍含未替换的 {{ 。这些细节能减少「线上才发现 prompt 拼错」的尴尬。 另外,按场景拆分文件: customer service.md 、 title gen.md 、 doc summary.md ,比一个巨型 prompt 更好维护。灰度时可以让 10% 流量读 v2.md ,对比效果与 token 消耗,再全量切换。 最后提醒:提示词也是资产,内部仓库注意权限;不要把含客户隐私示例的 prompt 提交到公开开源仓库。与 Key 管理一样,提示词泄露同样可能带来业务与合规风险。把「谁能改生产提示词」写进权限表,和发版权限同等对待。 --- 下一步 把本文的非流式 / 流式两段示例收进你们的 client.py,再接上重试与超时。联调通过后到
本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。