Gemini Python SDK 默认请求超时时间过短，导致频繁触发 DeadlineExceeded (504) 错误；而直接使用 curl 却能快速响应，根本原因在于 SDK 的 gRPC 客户端默认 timeout 设置不合理（通常仅约 60 秒且可能受底层重试逻辑影响），需显式延长超时阈值。
gemini python sdk 默认请求超时时间过短，导致频繁触发 `deadlineexceeded (504)` 错误；而直接使用 curl 却能快速响应，根本原因在于 sdk 的 grpc 客户端默认 timeout 设置不合理（通常仅约 60 秒且可能受底层重试逻辑影响），需显式延长超时阈值。
在使用 Google Generative AI Python SDK（即 google-generativeai）调用 Gemini 模型时，许多开发者会遇到看似“网络通畅但 SDK 持续失败”的现象：curl 命令可在 5–6 秒内稳定返回结果，而相同请求通过 model.generate_content() 却反复抛出 google.api_core.exceptions.DeadlineExceeded: 504 Deadline Exceeded 异常。这并非 API 密钥、区域或模型权限问题，而是 SDK 客户端的默认超时策略与实际服务延迟不匹配所致。
✅ 正确解决方案：显式设置 request_options["timeout"]
SDK 的 generate_content() 方法支持通过 request_options 参数传入底层 gRPC 调用的配置，其中 timeout（单位：秒）是关键修复项。推荐设置为 90–120 秒，以覆盖网络波动、服务排队及长响应生成场景：
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel("gemini-pro")
# ✅ 推荐写法：显式指定足够长的超时时间（单位：秒）
response = model.generate_content(
"What is the meaning of life?",
request_options={"timeout": 120} # 关键！避免默认过短 timeout 触发 504
)
print(response.text)
? 注意：timeout 值必须为浮点数或整数（单位：秒），不可传入毫秒值（如 1000 是 1000 秒，非 1 秒）。上文答案中 "timeout": 1000 虽能工作，但过度冗余；实践中 90–120 秒已充分兼顾稳定性与响应性。
⚠️ 其他常见误区与补充建议
- 不要混淆 retry 与 timeout：request_options 中的 timeout 控制单次请求生命周期，而 retry（如 retry=retry.Retry(deadline=...)）控制重试总耗时。二者需协同配置，但 timeout 是首要修复项。
- 避免在高延迟环境省略 timeout：即使本地网络良好，Google 的全球边缘节点调度、模型负载波动也可能导致个别请求延迟升高。显式设值是生产级最佳实践。
- 升级 SDK 版本：确保使用 google-generativeai >= 0.8.0（当前最新稳定版），旧版本可能存在默认 timeout 计算缺陷。
-
调试技巧：启用日志观察真实耗时：
import logging logging.basicConfig(level=logging.DEBUG) # 查看 gRPC 请求/响应时间戳
✅ 总结
DeadlineExceeded 在 Gemini Python SDK 中本质是客户端超时异常，而非服务端故障。其根源在于 SDK 对 gRPC 调用设置了偏保守的默认 timeout（内部可能叠加多次重试），而实际 Gemini 服务端响应受内容复杂度、模型负载等影响存在合理波动。唯一可靠解法是主动通过 request_options={"timeout": N} 显式延长单次请求时限——这既简单有效，又符合 Google Cloud 官方推荐模式（参见 google-api-core timeout 文档）。完成配置后，你的 Python 脚本将与 curl 一样稳定、高效。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
