[BUG] Getting-started docs reference retired Gemini model ids that return 404

问题场景

用户在阅读 CrewAI 官方文档（docs/edge/en/ 目录）时，按照教程（如 first-crew、first-flow 等入门指南）复制 Gemini 模型 ID 调用 API，首次请求即收到 404 错误。问题影响 6 个文档页面，其中包括面向新用户的入门教程路径。报错发生在 Gemini API 层，与 CrewAI 运行时无关。

报错原文

[BUG] Getting-started docs reference retired Gemini model ids that return 404

gemini-2.0-flash               HTTP 404: "This model models/gemini-2.0-flash is no longer available.
                                          Please update your code to use a newer model ..."
gemini-2.0-flash-001           HTTP 404: "This model models/gemini-2.0-flash-001 is no longer available.
                                          Please update your code to use a newer model ..."
gemini-2.5-flash-preview-05-20 HTTP 404: "models/gemini-2.5-flash-preview-05-20 is not found for API
                                          version v1beta, or is not supported for generateContent."

原因分析

可能原因：Gemini API 官方对部分模型 ID 执行了版本退役，导致文档中引用的模型 ID 不再被 generateContent 接口服务。Issue 中确认了三个已失效的模型：gemini-2.0-flash、gemini-2.0-flash-001、gemini-2.5-flash-preview-05-20。值得注意的是，ListModels 接口仍会返回 gemini-2.5-flash，但 generateContent 会拒绝它并提示“no longer available to new users”，因此仅依靠模型列表 API 判断可用性并不可靠。

环境排查

• 确认你使用的 Gemini 模型 ID 是否属于上述三个已退役 ID。
• 用同一 API Key 直接调用 Gemini API（不经过 CrewAI），排除运行时干扰。
• 验证 API Key 配额和请求格式是否正常——Issue 中 gemini-3.7-flash 在同一 Key 和请求格式下返回 200，可排除 Key/配额/格式问题。
• 如果使用 -latest 别名，注意确认该别名是否带版本号前缀（如 gemini-2.0-flash-latest 已失效，gemini-flash-latest 当前有效）。

解决步骤

1. 检查你的代码或教程文档中使用的 Gemini 模型 ID，确认是否为 gemini-2.0-flash、gemini-2.0-flash-001 或 gemini-2.5-flash-preview-05-20。
2. 对于“快速跑通”场景（first-crew、first-flow、memory、llm-connections、litellm-removal-guide），将模型 ID 替换为 gemini-flash-latest。实测该别名当前解析到 gemini-3.7-flash，返回 HTTP 200，且具有自动跟随新版本的能力。
3. 对于 llm-selection-guide 中展示成本/能力对比的示例（第 150、415 行），建议使用固定版本 gemini-3.7-flash——浮动别名可能静默改变示例演示的模型层级，使教学内容失真。
4. 替换后务必保留各文档中的 provider 前缀（如 gemini/、openai/），不要随意去掉。
5. 验证修改后的 MDX 代码片段和文档检查能否通过仓库的 CI 验证。

验证方法

使用修改后的模型 ID 直接调用 Gemini API，确认返回 HTTP 200 而非 404。可参考 Issue 中的 curl 命令模板：

export GEMINI_API_KEY=...
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gEMINI_MODEL_ID:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"parts":[{"text":"hi"}]}],"generationConfig":{"maxOutputTokens":8}}'

如果返回 200 且包含正常响应内容，说明模型 ID 可用。同时建议检查你用的 -latest 别名是否带版本号前缀——只有不带版本号的 gemini-flash-latest 这类别名才具备长期有效性。

参考来源

crewAIInc/crewAI #7002

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。