quickstart.py

from google import genai client = genai.Client(api_key="YOUR_API_KEY") resp = client.models.generate_content( model="gemini-2.0-flash“, contents=“用 3 句话解释什么是 RAG。”, ) print(resp.text) `` 运行后终端将输出模型生成的三句话。结果确认无误后，可进阶尝试流式输出：将 generate_content 替换为 generate_content_stream 并逐块打印，可显著降低长回答的首 token 延迟（首字返回时间）。 ### 核心能力详解：4 大支柱 支柱一：多模态统一理解。 2.0 Flash 支持文本与图片交错输入、视频帧序列、音频波形作为输入。开发者可将手机拍摄的照片、会议录音、产品宣传视频直接作为提示词的一部分传入，模型统一编码后完成描述、问答、翻译、转写等任务。官方文档强调，多模态文件通过 types.Part.from_uri 或 from_bytes 构造，并须正确声明 MIME 类型，否则请求会报错。 支柱二：低延迟文本与代码生成。 面向对话、摘要、翻译、代码补全等高频任务，响应速度是 Pro 系列的数倍，价格远低于同档次竞品。它同时支持 JSON 模式（response_mime_type=”application/json“）与 response_schema 强制结构化输出，保证下游解析稳定，适合批量数据处理管道。 支柱三：原生工具调用（Function Calling）。 模型通过 types.Tool 声明函数列表，在生成过程中自动输出函数名与参数，由开发者执行后把结果回传模型继续生成。与旧版相比，2.0 Flash 的改进在于多轮工具调用时上下文衔接更稳、参数格式错误率更低，官方示例覆盖了天气查询、航班预订等多步 Agent 场景。 支柱四：百万级上下文窗口。 上下文上限为 1,048,576 token，可一次性放入 100 页以上文档或数小时音视频转写文本。配合上下文缓存（Context Caching），对重复前缀（如系统提示词、固定知识库）的计费成本可降低最高约 75%，这是长文档应用控制成本的关键手段。需要注意：上下文越长，每次请求的延迟与费用越高，并非“放得下就划算”。 ### 生产部署与监控：从上线到运维 部署路径一：Google AI Studio → Gemini API。 适合原型验证与中小流量生产。AI Studio 提供免费额度与用量面板，Gemini API 端点为 generativelanguage.googleapis.com`，按 token 计费，适合以 API Key 直连为架构的轻量应用。生产环境应避免前端直接暴露密钥，建议通过 BFF 层（后端中转服务）代理请求。 部署路径二：Vertex AI。 适合对数据治理、审计日志、VPC 隔离有要求的企业场景。Vertex AI 提供统一的模型网关、IAM 权限体系与 Cloud Monitoring 集成，支持从 AI Studio 导出的提示词一键迁移，同时可搭配 Vertex AI Agent Builder 搭建完整的 Agent 应用。两者的模型权重一致，差异主要在计费模式与管理能力。 可观测性。 AI Studio 后台提供请求量、错误率、token 消耗的汇总图表；Vertex AI 侧可对接 Cloud Logging 与 Cloud Monitoring，按模型版本、区域、响应码维度设置告警。生产调用务必实现指数退避重试（首次 1 秒，倍增到 32 秒上限）以应对 429 限流；对内容安全策略触发返回的 400/403 错误，应单独记录并检查提示词合规性。 <p class=”para-label“>避坑清单：</p> <ul class=”dash-list"><li>把 100 万上下文当成无限容量，不做任何长度预估就整体塞入文档，导致延迟数十秒、单次费用飙升——上线前应评估实际输入长度，并配合上下文缓存或摘要压缩。</li><li>混用新旧两代 SDK：旧版 google-generativeai 的类名与方法（如 generate_text）与新 google-genai 完全不同，网上大量旧教程的代码直接复制会报错，务必确认 pip 包名与官方文档版本一致。</li><li>把 API Key 硬编码在源码或前端请求中，一旦上传 GitHub 被他人盗用，轻则配额耗尽，重则产生高额账单——一律用环境变量或密钥管理服务注入。</li><li>忽略免费层配额与生产差异：AI Studio 免费层仅用于原型验证，有每分钟请求数限制，直接上生产会频繁触发 429，应提前申请付费配额。</li></ul> ## 同类工具对比 | 维度 | Gemini 2.0 Flash | GPT-4o mini | Claude 3.5 Haiku | DeepSeek-V3 | | --- | --- | --- | --- | --- | | 定位 | 低延迟多模态轻量模型 | OpenAI 小型多模态模型 | 强调可靠性的快速轻量模型 | 开源通用大参数模型 | | 编排范式 | 原生工具调用 + 可与 Vertex AI Agent 框架衔接 | Function Calling，依赖外部编排框架 | 工具调用 + 原生 MCP（Model Context Protocol）支持 | Function Calling API，生态依赖社区框架 | | 类型约束 | JSON 模式 + response_schema 强制结构 | JSON 模式 + 结构化输出 | 结构化输出（Tool Use 返回值校验严格） | JSON 输出，需自行校验 | | 学习曲线 | 低：AI Studio 无代码入口，文档齐全 | 低：OpenAI 生态积累最大 | 中：官方强调长指令与角色设定 | 低：兼容 OpenAI 格式，迁移成本低 | | 生态集成 | AI Studio、Vertex AI、LangChain、众多 Google 系产品 | Azure OpenAI、Copilot、LangChain、LlamaIndex | Claude Code、AWS Bedrock、MCP | Ollama、vLLM、国内云厂商、Hugging Face | | 生产部署 | Vertex AI 企业级治理，也可直连 API | Azure OpenAI 托管，或 OpenAI 直连 | Anthropic API / AWS Bedrock 托管 | 自托管或第三方 API 供应商 | | License | 闭源 API；9B 蒸馏版权重开放 | 闭源 | 闭源 | MIT 开源 | | 适合谁 | 谷歌云生态用户、多语言多模态应用 | 需要 Azure/微软生态集成的团队 | 对指令遵循与安全审查有高要求的 Agent 团队 | 需要本地部署、成本敏感的开源团队 |