Gemini API从google-generativeai迁移到新版google-genai SDK的完整指南：汇总

必须在2025年11月30日前将Google Generative AI SDK从legacy版（<0.8.0）迁移到新版google-genai（≥1.0.0），否则无法使用gemini-1.5/2.0模型、流式响应及多模态功能。

你现在正在维护一个用 Python 调用 Gemini API 的项目，但发现代码里还写着 import google.generativeai as genai，而 Google 最新文档首页已标红提示“Legacy SDK”，且旧库将在 2025 年 11 月 30 日彻底停止维护——这意味着你必须在截止日前完成迁移，否则新模型（如 gemini-1.5-flash、gemini-2.0）无法接入，流式响应、多模态 PDF 解析等关键能力将直接失效。

确认当前 SDK 版本与弃用状态

运行 pip show google-generativeai 查看已安装版本。若输出中 【Version 字段低于 0.8.0】 或显示 WARNING: This package is deprecated，说明你正使用已被标记为 Legacy 的旧 SDK。

打开终端执行 pip list | grep generative，如果同时存在 google-generativeai 和 google-genai，必须先卸载旧版，否则导入时可能因命名空间冲突导致 AttributeError: module 'google.generativeai' has no attribute 'GenerativeModel'。

执行 pip uninstall google-generativeai -y 彻底清除旧包。

安装并初始化新版 google-genai SDK

方法一：标准安装

运行 pip install google-genai。注意不要拼错成 google-generativeai 或 genai（后者是无效包名）。

方法二：指定版本安装（推荐）

执行 pip install "google-genai>=1.0.0"，确保获取支持 Gemini 2.0 模型的最新稳定版。当前（2026年6月）最新版为 1.0.4，已内置对 gemini-2.0-flash-exp 的完整适配。

初始化方式已变更：旧版用 genai.configure(api_key="xxx")，新版必须显式创建客户端实例 → from google.genai import GenerativeModel; model = GenerativeModel("gemini-1.5-pro")。这一步不写 client 参数，默认走 GOOGLE_API_KEY 环境变量或默认凭据链；若需指定服务账号，必须传入 credentials 参数。

重写核心调用逻辑

第一步：替换模型加载方式

旧代码：model = genai.GenerativeModel("gemini-pro")

新代码：model = GenerativeModel("gemini-1.5-pro")。注意模型 ID 必须升级，gemini-pro 已不可用，调用会返回 404；gemini-1.0-pro 仍可工作但无长上下文支持。

第二步：重构请求内容结构

旧版允许单字符串输入：response = model.generate_content("你好")；新版强制要求 contents 为列表，且每项必须含 role 和 parts → response = model.generate_content([{"role": "user", "parts": [{"text": "你好"}]}])。若传入纯字符串，SDK 会静默转为 [{"role": "user", "parts": [{"text": "..."}]}]，但该自动转换在 v1.0.3+ 中已被移除，直接报 TypeError。

第三步：启用流式响应

旧版无原生流式支持；新版只需加 stream=True 参数 → response = model.generate_content(contents, stream=True)。返回对象变为 GenerateContentResponse 迭代器，需用 for chunk in response: 逐块读取。若仍用 .text 属性访问，会触发 ValueError: Response is streaming。

处理多模态与安全字段变更

上传图片/PDF/音频时，旧版用 genai.upload_file() 返回文件 URI 再塞进 parts；新版统一为 Part.from_uri() 或 Part.from_data() → {"role": "user", "parts": [Part.from_uri("gs://bucket/file.pdf", mime_type="application/pdf")]}。注意 【GCS URI 必须启用 publicRead 权限，否则返回 403】。

删除已弃用参数：旧版支持的 topP、topK 字段在新版 v1 接口中被移除，保留会导致 400 错误；temperature 取值范围收紧为 [0.0, 2.0]，传 2.5 会直接拒绝。