# Gemini 3 Pro API 集成将 Google 的 Gemini 3 Pro API/SDK 集成到您的应用程序中的综合指南。涵盖设置、身份验证、文本生成、动态思维的高级推理、聊天应用程序、流响应和生产部署模式。 ## 概述 **Gemini 3 Pro**（“gemini-3-pro-preview”）是 Google 最智能的模型，专为需要高级推理和广泛世界知识的复杂任务而设计。此技能提供使用 Python 或 Node.js SDK 进行 API 集成的完整工作流程。 ### 关键功能 * **海量上下文：** 1M 代币输入，64k 代币输出 * **动态思维：** 高/低模式的自适应推理 * **流式传输：** 实时令牌传递 * **聊天：** 具有历史记录的多轮对话 * **生产就绪：** 错误处理、重试逻辑、成本优化 ### 何时使用此技能 * 设置 Gemini 3 Pro API 访问 * 构建文本生成应用程序 * 用推理实现聊天应用 * 配置高级思维模式 * 部署生产 Gemini 应用程序 * 优化API使用和成本 ** ** ## 快速入门 ### 先决条件 * **API Key：** 从 [Google AI Studio]() 获取 * **Python 3.9+** 或 **Node.js 18+** ### Python 快速入门 # 安装SDK pip 安装 google-genai # 基本用法将 google.generativeai 导入为 genai genai.configure(api_key="YOUR_API_KEY") 模型 = genai.GenerativeModel("gemini-3-pro-preview") response = model.generate_content("解释量子计算") 打印（响应.文本） ### Node.js 快速入门 // 安装SDK npm install @google/generative-ai // 基本用法从“@google/generative-ai”导入 { GoogleGenerativeAI }； const genAI = new GoogleGenerativeAI("YOUR_API_KEY"); const model = genAI.getGenerativeModel({ model: "gemini-3-pro-preview" }); const result = wait model.generateContent("解释量子计算"); console.log(结果.response.text()); ** ** ## 核心工作流程 ### 工作流程 1：快速启动设置 **目标：** 在 5 分钟内从零调用到第一次成功的 API 调用。 **步骤：** 1. **获取API密钥** * 访问[Google AI Studio]() * 创建或选择项目 * 生成API密钥 * 安全地复制密钥 2. **安装SDK** # Python pip 安装 google-genai # 节点.js npm install @google/generative-ai 3. **配置身份验证** # Python - 使用环境变量（推荐）导入操作系统将 google.generativeai 导入为 genai genai.configure(api_key=os.getenv("GEMINI_API_KEY")) // Node.js - 使用环境变量（推荐） const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY); 4. **进行第一次 API 调用** # Python 模型 = genai.GenerativeModel("gemini-3-pro-preview") response = model.generate_content("写一首关于编码的俳句") 打印（响应.文本） 5. **验证成功** * 检查收到的回复 * 验证文本输出 * 注意令牌的使用 * 确认API密钥有效 **预期结果：** 在 5 分钟内即可完成 API 集成。 ** ** ### 工作流程 2：聊天应用程序开发 **目标：** 构建一个具有对话历史记录和流媒体功能的生产就绪聊天应用程序。 **步骤：** 1. **初始化聊天模型** # Python 模型 = genai.GenerativeModel( “gemini-3-pro-预览”，一代配置={ "thinking_level": "high", # 动态推理 "温度": 1.0, # 保持在 1.0 以获得最佳结果 “最大输出令牌”：8192 } ） 2. **开始聊天会话** 聊天 = model.start_chat(历史记录=[]) 3. **通过流媒体发送消息** 响应 = chat.send_message( “解释神经网络如何学习”，流=真） # 实时流式传输令牌对于响应块：打印（chunk.text，结束=“”，flush=True） 4. **管理对话历史记录** # 历史记录自动维护 # 随时访问 print(f"对话轮数: {len(chat.history)}") # 继续对话 response = chat.send_message("你能举个例子吗？") 5. **处理思想签名** * SDK 在标准聊天流程中自动处理 * 基本使用无需人工干预 * 高级案例参见 `references/thought-signatures.md` 6. **实施错误处理** 导入时间 from google.api_core import 重试，异常 @retry.Retry(谓词=retry.if_exception_type( 异常。资源耗尽，异常.ServiceUnavailable ）） def send_with_retry(聊天，消息)：返回 chat.send_message(消息) 尝试：响应 = send_with_retry(聊天, user_input) 除了异常。GoogleAPIError 为 e： print(f"API 错误：{e}") **预期结果：** 具有流媒体、历史记录和错误处理功能的生产就绪聊天应用程序。 ** ** ### 工作流程 3：生产部署 **目标：** 部署 Gemini 3 Pro 与监控、成本控制和可靠性集成。 **步骤：** 1. **设置身份验证（生产）** # 使用环境变量（不要硬编码密钥）导入操作系统从 pathlib 导入路径 # 选项1：环境变量 api_key = os.getenv("GEMINI_API_KEY") # 选项 2：Secrets manager（推荐用于生产） # 使用 Google Secret Manager、AWS Secrets Manager 等。 2. **配置生产设置** 模型 = genai.GenerativeModel( “gemini-3-pro-预览”，一代配置={ "thinking_level": "high", # 或 "low" 用于简单任务 "温度": 1.0, # 关键: 保持在 1.0 “最大输出令牌”：4096， “顶部p”：0.95， “top_k”：40 }, 安全设置={ # 根据需要配置内容过滤 } ） 3. **实施全面的错误处理** from google.api_core 导入异常，重试导入日志记录日志记录.basicConfig（级别=日志记录.INFO）记录器=logging.getLogger(__name__) defgenerate_with_fallback（提示，max_retries=3）： @重试.重试( 谓词=重试.if_exception_type( 异常。资源耗尽，异常。服务不可用，异常.DeadlineExceeded ), 初始=1.0，最大值=10.0，乘数=2.0，截止日期=60.0 ） def _generate(): 返回 model.generate_content(提示) 尝试：返回_generate() 除了异常。InvalidArgument 为 e： logger.error(f"无效参数：{e}") 提高除了例外情况。PermissionDenied 为 e： logger.error(f"权限被拒绝：{e}") 提高除了异常 e： logger.error(f"意外错误：{e}") # 回退到更简单的模型或缓存的响应返回无 4. **监控使用情况和成本** def log_usage(响应): 用法 = 响应.usage_metadata logger.info(f"令牌 - 输入：{usage.prompt_token_count}，" f“输出：{usage.candidates_token_count}，” f“总计：{usage.total_token_count}”） # 估计成本（提示≤200k 代币） input_cost = (usage.prompt_token_count / 1_000_000) * 2.00 输出成本 = (usage.candidates_token_count / 1_000_000) * 12.00 总成本 = 输入成本 + 输出成本 logger.info(f"预计成本：${total_cost:.6f}") 响应= model.generate_content（提示） log_usage（响应） 5. **实施速率限制** 导入时间从集合导入双端队列类速率限制器： def __init__(self, 每分钟最大请求数=60): self.max_rpm = 每分钟最大请求数 self.requests = 双端队列() def wait_if_needed(自身): 现在 = 时间.time() # 删除超过 1 分钟的请求而 self.requests 和 self.requests[0] < 现在 - 60： self.requests.popleft() # 检查是否达到极限如果 len(self.requests) >= self.max_rpm: sleep_time = 60 - （现在 - self.requests[0]）如果睡眠时间 > 0：时间.睡眠（睡眠时间） self.requests.append（现在）限制器 = RateLimiter(每分钟最大请求数=60) defgenerate_with_rate_limit（提示）： limiter.wait_if_needed() 返回 model.generate_content(提示) 6. **设置日志记录和监控** 导入日志记录从日期时间导入日期时间 # 配置日志记录日志记录.basicConfig( 级别=日志记录.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', 处理程序=[ logging.FileHandler('gemini_api.log'), 日志记录.StreamHandler() ] ）记录器=logging.getLogger(__name__) def Monitored_generate（提示）：开始时间 = 日期时间.now() 尝试：响应= model.generate_content（提示）持续时间 = (datetime.now() - start_time).total_seconds() logger.info(f"成功 - 持续时间: {duration}s, " f“令牌：{response.usage_metadata.total_token_count}”）返回响应除了异常 e：持续时间 = (datetime.now() - start_time).total_seconds() logger.error(f"失败 - 持续时间: {duration}s, 错误: {e}") 提高 **预期结果：** 具有监控、成本控制、错误处理和速率限制的生产就绪部署。 ** ** ## 思维水平 ### 动态思维系统 Gemini 3 Pro引入了“thinking_level”来控制推理深度： **`思考级别：“高”`（默认）** * 最大推理深度 * 复杂任务的最佳质量 * 第一个令牌响应较慢 * 成本较高 * **用于：** 复杂推理、编码、分析、研究 **`思维水平：“低”`** * 最小的推理开销 * 更快的响应 * 成本更低 * 更简单的输出 * **用于：** 简单问题、事实答案、快速查询 ### 配置 # Python 模型 = genai.GenerativeModel( “gemini-3-pro-预览”，一代配置={ "thinking_level": "high" # 或 "low" } ） // 节点.js const 模型 = genAI.getGenerativeModel({ 型号：“gemini-3-pro-preview”，生成配置：{ Thinking_level：“高”//或“低” } }); ### 重要说明 ⚠️ **温度必须保持在 1.0** \- 改变温度可能会导致复杂推理任务的循环或性能下降。 ⚠️ **无法将** `thinking_level` 与旧版 `thinking_budget` 参数结合起来。有关详细指南，请参阅“references/thinking-levels.md”。 ** ** ## 流式响应 ### Python 流响应 = model.generate_content( “写一篇关于人工智能的长篇文章”，流=真）对于响应块：打印（chunk.text，结束=“”，flush=True） ### Node.js 流式传输 const result = wait model.generateContentStream("写一篇关于人工智能的长文章"); for wait (const chunk of result.stream) { process.stdout.write(chunk.text()); } ### 好处 * 更低的感知延迟 * 实时用户反馈 * 更好的用户体验以实现长响应 * 可以在令牌到达时对其进行处理有关高级模式，请参阅“references/streaming.md”。 ** ** ## 成本优化 ### 定价（Gemini 3 Pro）上下文大小 |输入 |输出 ---|---|--- ≤ 200k 代币 | 2/100 万美元 | $12/100 万美元 > 200k 代币 | 4/100 万美元 | 18 美元/100 万美元 ### 优化策略 1. **将提示保持在 200k 代币以下**（便宜 50%） 2. **使用`thinking_level: "low"`来完成简单的任务**（更快，成本更低） 3. **为可重用上下文实现上下文缓存**（参见`gemini-3-advanced`技能） 4. **监控代币使用情况**并设置预算 5. **使用 Gemini 1.5 Flash** 执行简单任务（便宜 20 倍）请参阅“references/best-practices.md”以了解全面的成本优化。 ** ** ## 型号选择 ### Gemini 3 Pro 与其他型号对比型号|背景 |输出|输入价格|最适合 ---|---|---|---|--- **gemini-3-pro-预览版** | 1M | 64k | $2-4/100 万美元 |复杂推理、编码双子座-1.5-pro | 1M | 8k | $7-14/100 万美元 |一般用途，多式联运 Gemini-1.5-flash | 双子座-1.5-flash | 1M | 8k | $0.35-0.70/100 万美元 |任务简单，成本敏感 ### 何时使用 Gemini 3 Pro ✅ 复杂的推理任务 ✅ 高级编码问题 ✅ 长上下文分析（最多 1M 个标记） ✅ 大输出要求（最多 64k 个标记） ✅ 需要动态思维的任务 ### 何时使用替代方案 * **Gemini 1.5 Flash：** 简单的任务，成本敏感的应用 * **Gemini 1.5 Pro：** 多模式任务，一般用途 * **Gemini 2.5 型号：** 实验特性、特定功能 ** ** ## 错误处理 ### 常见错误错误 |原因 |解决方案 ---|---|--- `资源耗尽` |超出速率限制 |实施带退避的重试 `无效参数` |无效参数 |验证输入，检查文档 `权限被拒绝` |无效的 API 密钥 |检查身份验证 `超过截止日期` |请求超时|减少上下文，重试 ### 生产错误处理 from google.api_core 导入异常，重试 @重试.重试( 谓词=重试.if_exception_type( 异常。资源耗尽，异常.ServiceUnavailable ), 初始=1.0，最大值=60.0，乘数=2.0 ） def safe_generate(提示): 尝试：返回 model.generate_content(提示) 除了异常。InvalidArgument 为 e： logger.error(f"无效参数：{e}") 提高除了例外情况。PermissionDenied 为 e： logger.error(f“权限被拒绝 - 检查 API 密钥：{e}”) 提高除了异常 e： logger.error(f"意外错误：{e}") 提高有关全面的模式，请参阅“references/error-handling.md”。 * * * ＃＃参考 **设置和配置** * [安装指南]() \- 安装、认证、配置 * [最佳实践]() \- 优化、成本控制、技巧 **特点** * [文本生成]() \- 详细的文本生成模式 * [聊天模式]() \- 聊天对话管理 * [思维水平]() \- 动态思维系统指南 * [Streaming]() \- 流响应模式 **生产** * [错误处理]() \- 错误处理和重试策略 **官方资源** * [Gemini 3 文档]() * [Python SDK 文档]() * [Node.js SDK 文档]() * [API 参考]() * [定价]() ** ** ## 后续步骤 ### 基本设置后 1. **探索聊天应用程序** \- 构建对话界面 2. **添加多模式功能** \- 使用 `gemini-3-multimodal` 技能 3. **添加图像生成** \- 使用 `gemini-3-image- Generation` 技能 4. **添加高级功能** \- 使用 `gemini-3-advanced` 技能（缓存、工具、批处理） ### 常见集成模式 * **简单聊天机器人：** 仅此技能 * **多模态助手：** 该技能+`gemini-3-multimodal` * **创意机器人：** 该技能 + `gemini-3-image- Generation` * **制作应用程序：** 所有 4 个 Gemini 3 技能 ** ** ## 故障排除 ### 问题：API 密钥不起作用 **解决方案：** 验证 Google AI Studio 中的 API 密钥，检查环境变量 ### 问题：速率限制错误 **解决方案：** 实施速率限制，升级到付费级别，降低请求频率 ### 问题：响应缓慢 **解决方案：** 对于简单任务使用 `thinking_level: "low"`，启用流式传输，减少上下文大小 ### 问题：成本高 **解决方案：** 将提示保持在 200k 代币以下，使用适当的思维水平，考虑 Gemini 1.5 Flash 来完成简单的任务 ### 问题：温度警告 **解决方案：** 将温度保持在 1.0（默认） - 对于复杂的推理任务不要修改 ** ** ## 总结此技能提供将 Gemini 3 Pro API 集成到您的应用程序中所需的一切： ✅ 快速设置（< 5 分钟） ✅ 生产就绪的聊天应用程序 ✅ 动态思维配置 ✅ 流式响应 ✅ 错误处理和重试逻辑 ✅ 成本优化策略 ✅ 监控和记录模式有关多模态、图像生成和高级功能，请参阅配套技能。 **准备好构建了吗？** 从上面的 **工作流程 1：快速启动设置**开始！

双子座 3 Pro 火

包含技能