TRAE-AI编程
装哪个 Gemini SDK
google-genai 是现行 Python SDK（JS 为 @google/genai）；google-generativeai 等旧库已弃用、不再维护，也拿不到新特性。（核验 2026-11-05，F1、F2、F63）
一、装哪个 Gemini SDK：问题不是哪个能跑，而是装错了会静默降级
照着一篇新文档写 client.interactions.create(...)，运行报 AttributeError: 'GenerativeModel' object has no attribute 'interactions'。你以为是文档写错了，其实是环境里装的是另一个包。
更麻烦的是另一种情况：两个包都装着，代码照样跑得动，只是拿到的对象少了一半能力——没有服务端会话，没有可观测步骤，也没有新模型。它不报错，所以你不会去查。
官方把这件事写得很直接。规范包是 google-genai（Python）与 @google/genai（JS）（F1）；google-generativeai 与 @google/generative-ai 属于被明令不要再用的旧包（F2）。旧库的现状是三重：deprecated as of November 30th, 2025、Not actively maintained、不提供 Live API 与 Veo 这类新能力（F63）。
也就是说，选错包不是「少个功能」，是从起点就掉出主线：后面几章讲的会话、签名、后台执行，在旧包里根本不存在。
二、Gemini SDK 依赖审计：最小可运行示例
装之前先看清环境里有什么。下面这段脚本读一份包清单（示意，实际用 pip freeze 的输出），判断是否混装了新旧包。
## EXPECT: 废弃包 1 个：google-generativeai | 规范包 1 个：google-genai | 结论：先卸载废弃包再装规范包
INSTALLED = ["google-generativeai", "google-genai", "requests"]
DEPRECATED = {"google-generativeai", "@google/generative-ai"}
CANONICAL = {"google-genai", "@google/genai"}
def audit(pkgs):
bad = [p for p in pkgs if p in DEPRECATED]
good = [p for p in pkgs if p in CANONICAL]
if bad and good:
verdict = "先卸载废弃包再装规范包"
elif not good:
verdict = "补装规范包"
else:
verdict = "可以开工"
return bad, good, verdict
bad, good, verdict = audit(INSTALLED)
out = f"废弃包 {len(bad)} 个：{'、'.join(bad)} | 规范包 {len(good)} 个：{'、'.join(good)} | 结论：{verdict}"
assert bad == ["google-generativeai"]
assert verdict == "先卸载废弃包再装规范包"
print(out)注意这段代码里没有「安装」动作——审计和使用是两件事。先看清楚，再动手卸，顺序反了容易把正在跑的脚本弄挂。
三、解释与边界：三条容易踩的线
第一条，pip 名不等于 import 名。 pip install google-genai 装完之后，代码里写的是 from google import genai；旧包 google-generativeai 对应的是 import google.generativeai。两个包共用顶层 google 命名空间，所以它们在同一个环境里并存时，import 语句不会告诉你「你装错了」，只会让你拿到不同的对象。
第二条，别用 import 顺序来「解决」冲突。 有人会在文件顶部调整 import 的先后，试图让某一行生效。这在单文件里偶尔看起来有效，进到框架、插件、异步任务里就会随机失效，而且失效方式是静默的。正解只有一个：把废弃包卸掉。
第三条，依赖要锁，但别锁死到具体小版本。 下面这份清单故意不写版本号：
## requirements.txt（示意：写在你的项目里，版本由 pip freeze 产出）
google-genai
python-dotenv
理由是版本号天天变，写进正文就等于写进一个必然过期的数字。正确做法是装完后跑 pip freeze > requirements.lock 把实际版本固定下来，让锁文件承担「可复现」，而不是让文档承担。
边界也要说清。 本教程只讲 Python 与 JS 两条主线，Java、Go、Dart 的包名各不相同（F63 那张表里逐个列了），但它们的调用思路一致，不在本教程展开。另外，旧库「不再维护」不等于「已删除」——它还能装、还能跑，所以它才危险：一个能跑的过时环境，比一个装不上的环境更容易误导人。
四、预期输出与异常分支
真跑输出：
废弃包 1 个：google-generativeai | 规范包 1 个：google-genai | 结论：先卸载废弃包再装规范包
四种分支对应四个动作。只装旧包：把 INSTALLED 改成 ["google-generativeai"]，结论变成「补装规范包」，此时旧代码还能跑，但新能力全无。两个都装：就是当前输出，先卸废弃包，再确认 pip list | grep generative 已经没有旧包。两个都没有：结论是「补装规范包」，注意 pip install google-genai 之后要重启解释器，否则当前进程里没有新装的模块。装对了但写法不对：写成 from google import generativeai 会直接 ImportError，这是好事——显式报错比静默降级好查得多。
五、判据卡：看到什么就该停下来
| 该这么做 | 不该这么做 |
|---|---|
依赖里只留 google-genai／@google/genai |
两个包都留着「以防万一」 |
见到 google.generativeai 就停手，先查依赖 |
靠调 import 顺序让代码跑起来 |
用 pip freeze 生成锁文件固定版本 |
在正文或博客里抄死某个小版本号 |
| 卸载后重启解释器再验证 | 卸完不重启，以为没生效 |
六、来源与核验
https://aistudio.google.com/docs/libraries.md（核验 2026-11-05，F1、F2、F63）https://aistudio.google.com/llms.txt（核验 2026-11-05，F1、F2）https://aistudio.google.com/docs/get-started.md（核验 2026-11-05，F9）
旧库的弃用日期与维护状态以 2026-11-05 抓取的官方页为准；它属于「限流／版本／API 结构」那一档，复核周期三个月，见 1.3。
七、动手试
- 在你自己的项目里跑
pip list | grep -i generative，把结果填进INSTALLED，重跑示例。验收标准：输出里的「结论」一行能与你的实际操作对上，对不上说明清单漏了包名。 - 把
DEPRECATED里的@google/generative-ai换成@google/generativeai（少一个连字符），重跑。预期输出不变，因为这份清单里没有 JS 包；验收标准是你能说出「为什么这条检查对 JS 项目无效、该怎么补」。 - 打开官方 libraries 页的 legacy 表，找出你所用语言对应的「推荐库」一列，写下包名。验收标准：包名必须与本节判据卡里的一致，不一致就以官方页为准并回来改这份清单。
更多建议：