先把话放前面这个系列写到第四篇前面的内容如果都跟下来了现在应该已经能在本地跑通 Python 环境也试过用基础请求去碰 Gemini 的接口。但真正干活的时候你会发现光会发请求不够还得知道怎么设计 prompt、怎么控制输出、怎么处理异常、怎么把模型能力嵌进自己的业务流程里。这篇就专门讲这些实打实的细节所有代码都基于 Python 3.8 和官方google-generativeai库场景全部围绕文本生成、代码辅助、结构化输出和批量处理看完可以直接往自己的项目里套。这篇内容适合三类人第一类是刚把 Gemini API 调通、但只会跑官方示例的初学者第二类是已经封装过接口、想优化交互细节的开发者第三类是打算用 Gemini 做内容处理、数据处理但还没找到合适方案的产品或运营。如果只是抱着“玩玩”的心态前几篇够了要想用在正经项目里这篇的坑你大概率都会踩到。1. 项目整体设计与思路拆解1.1 为什么用 Python 而不是直接调 HTTP 接口Gemini 官方提供 REST API理论上用 Postman 或者 curl 就能测通但一旦进入业务逻辑HTTP 裸调很快就会让你崩溃。原因很简单要自己处理鉴权、构造请求体、解析流式响应、重试机制、长文本截断这些工作量全部堆起来比你写核心业务代码还费劲。Python 的优势在于google-generativeai这个 SDK 把这些底层逻辑全包了。你传一个 API key、指定模型名然后model.generate_content()一行调用返回的是一个完整的GenerateContentResponse对象。这个对象里不仅有文本还有候选结果、Token 统计、安全评分这些信息省去了一大堆 json 解析和状态码判断。我一开始也是用 requests 手撸结果遇到一个问题Gemini 返回的 JSON 结构里字段嵌套很深不同模型返回的字段还不完全一样写解析代码就花了半天后来换了 SDK半小时就完成了同样的功能。所以如果你要正经做项目直接用 SDK不是因为它“官方”而是因为它把版本间的字段差异做了兼容你不需要跟着 API 文档逐字逐句对齐。1.2 Gemini 与 Bard 的关系以及能力边界Bard 是 Google 之前的对话产品Gemini 是背后的模型系列。现在对外提供 API 的是 Gemini所以标题里写“Bard 编程指南”更多是沿用了大家熟悉的称呼。实际开发中我们面对的核心对象是gemini-pro、gemini-pro-vision这些模型端点。这系列做下来我总结 Gemini API 的能力边界大致有三块文本生成与对话、代码生成与解释、多模态理解Vision 模型。第四篇重点讲前两块因为这两块是日常开发用得最频繁的。需要提醒的是Gemini 不像某些国产大模型那样有“完全离线可用”的版本所有请求都必须发到 Google 的服务器。这意味着你必须有稳定的网络环境并且要注意请求体大小和频率限制。免费层的限制一般是每分钟请求数RPM和每天 Token 数具体数值会变以官方控制台为准。1.3 典型应用场景与整体流程设计拿我最近做的一个小项目举例本地有一批产品描述文本需要自动生成 SEO 标题和摘要。传统做法是写一堆正则和模板效果生硬。用 Gemini 的做法是读取本地文本文件构造一个通用 prompt包含待处理文本和输出格式要求循环调用generate_content把结果解析成字典写入 CSV这个过程里最关键的其实是第 2 步 prompt 的设计和第 3 步的异常处理。模型能力再强prompt 写不清楚输出也会乱API 再稳定也架不住网络抖动和配额超限。所以我把这套流程拆成三个独立模块gemini_client.py负责初始化客户端统一管理 API key 和模型参数prompt_builder.py负责把输入文本和指令拼成标准 promptbatch_processor.py负责循环调用、异常跳过、结果落盘模块分离的好处是以后想换模型、换场景只需要改 prompt 或客户端配置不用动主流程代码。下面四节的内容都围绕这套架构展开。2. 核心细节解析与实操要点2.1 环境准备与依赖安装先说环境。Python 版本建议 3.8 以上实测 3.10 和 3.11 都没问题。安装依赖pip install google-generativeai如果你之前装过老版本最好升级一下pip install -U google-generativeai这个包依赖grpcio、protobuf、google-auth等一堆东西首次安装可能要等一会儿属于正常现象。装完后验证一下python -c import google.generativeai as genai; print(genai.__version__)能输出版本号就说明基础环境没问题。如果卡在 import 阶段常见原因是grpcio版本冲突解决办法是卸载重装pip uninstall grpcio google-generativeai pip install google-generativeai --no-cache-dir另外提醒一句不要直接在代码里硬编码 API key。虽然写着方便但一旦代码泄漏到 GitHub 或者别人电脑上key 就可能被滥用。我自己的做法是放到环境变量里export GEMINI_API_KEY你的key然后在代码里import os import google.generativeai as genai genai.configure(api_keyos.environ[GEMINI_API_KEY])这样既安全又方便在不同环境切换。2.2 模型选择与参数配置Gemini API 目前的模型命名常见有gemini-pro和gemini-pro-vision。前者适合纯文本输入输出后者支持图像文本输入。代码生成、文本摘要、问答对话这些场景直接用gemini-pro就够了。初始化模型时可以配置一些生成参数model genai.GenerativeModel( model_namegemini-pro, generation_config{ temperature: 0.7, max_output_tokens: 2048, top_p: 0.95, top_k: 40, } )这些参数的含义temperature控制随机性。0 表示几乎总是选概率最高的 token适合分类、抽取这类确定任务0.7~0.9 适合创意写作输出更多样。做代码生成建议 0.2 到 0.4否则同样的 prompt 会得到风格不一致的代码。max_output_tokens限制输出长度。Gemini 的输出 Token 上限与输入 Token 数有关系太长会截断。中文场景下1 个汉字大约等于 1~2 个 token按经验留一半余量。top_p核采样阈值控制候选 token 的累积概率范围。值越小生成越保守。top_k每一步从概率最高的 k 个 token 里选。一般不用调太细保持默认即可。我实际用下来大部分任务只需要调 temperature 和 max_output_tokens其他参数用默认值完全够。别过度调参模型能力本身远比参数的微小差异重要。2.3 Prompt 设计的核心原则Gemini 这类大模型对 prompt 的敏感度极高。同一个任务prompt 写法不同结果质量可能差一个档次。我踩过不少坑之后总结出三条原则第一明确指令。不要说“帮我看看这段文字”要说“从这段文字中提取商品名称、价格和促销信息以 JSON 格式输出”。第二给出格式约束。如果你预期输出 JSON就在 prompt 里写明 JSON 的字段结构和示例。否则模型可能给你一段冗长的叙述。第三少用否定句多用肯定句。比如“不要输出无关内容”不如“只输出符合指定 JSON 结构的内容”效果好。举一个对比明显的例子。弱 prompt分析以下文本并给出建议。 文本...强 prompt你是一位资深电商运营专家。请分析以下商品描述输出包含title、keywords、summary三个字段的 JSON其中 title 不超过 20 字keywords 是 5 个关键词组成的数组summary 不超过 50 字。 文本...后者不仅约束了角色还约束了输出结构模型就知道该怎么回答了。大约 80% 的“生成结果乱”的问题本质上都是 prompt 没说清楚。2.4 多轮对话的会话管理Gemini API 支持多轮对话官方有个ChatSession对象chat model.start_chat(history[]) response chat.send_message(你好) print(response.text)这个对象会自动记录上下文但要注意它把整个历史都放在请求里所以对话轮次越多请求 Token 越大费用和延迟都会涨。我测试过超过 10 轮之后响应速度明显变慢。如果你的场景只是单轮单次调用直接用generate_content就够了别开ChatSession白白增加请求体。如果确实需要多轮但又不希望上下文无限膨胀可以手动裁剪历史。比如只保存最近 4 轮对话的内容拼接成一个人为的 prompt 再调用generate_content。这样既保留一定上下文又控制 Token 消耗。3. 实操过程与核心环节实现3.1 最小可用的文本生成脚本先给一个最基础的脚本跑通后我们再逐步扩展。import os import google.generativeai as genai genai.configure(api_keyos.environ[GEMINI_API_KEY]) model genai.GenerativeModel( model_namegemini-pro, generation_config{ temperature: 0.3, max_output_tokens: 1024, } ) prompt 请用一句话解释什么是Python闭包并给出一个简单代码示例。 response model.generate_content(prompt) print(response.text)运行之前确认环境变量GEMINI_API_KEY已设置。如果之前没设置最直接的方式是export GEMINI_API_KEY你的key python your_script.py这段代码跑通后你就拥有了最基本的“文生文”能力。接下来把它封装成一个函数方便复用def ask_gemini(prompt, temperature0.3, max_tokens1024): model genai.GenerativeModel( model_namegemini-pro, generation_config{ temperature: temperature, max_output_tokens: max_tokens, } ) response model.generate_content(prompt) return response.text这个封装看起来很普通但实际开发中你一定会遇到一个问题多次调用GenerativeModel会不会有性能损耗实测结果是可以忽略不计因为底层连接池是复用的。不过更优雅的做法是全局只初始化一次模型实例其他函数调用它。3.2 流式输出与实时打印大模型生成长文本时如果等它全部生成完再返回对于几百字的输出可能还好但对于几千字的文章等待时间会显得很长。Gemini SDK 支持流式生成即边生成边返回。response model.generate_content(prompt, streamTrue) for chunk in response: print(chunk.text, end)流式和批量在 API 层面不是同一个请求模式流式响应对应的是流式传输Token 总数一样但首字节延迟明显更低。如果你做的是对话机器人或实时写作工具强烈建议用流式。注意流式模式下response.text并不是一开始就有。你需要遍历 chunks把它们拼接起来。拼接的方式full_text for chunk in response: full_text chunk.text另外流式输出在异常处理上有个特殊点如果你在遍历过程中网络断了chunk.text可能会抛异常。所以要把整个遍历过程包在 try 里而不是只包在生成请求时。3.3 结构化输出让模型返回 JSON 并用 Python 解析实际工程中我们很少只让模型返回纯文本更多的是让它返回结构化的数据。比如批量提取网页中的商品信息、抽取新闻的关键要素。这时候我们要让模型输出 JSON再用json.loads解析。准备这样一个 promptprompt 请从以下文本中提取信息并以 JSON 格式返回包含三个字段 - title: 商品标题 - price: 价格数值不含货币符号 - tags: 标签列表 文本这台智能扫地机器人支持激光导航售价1299元适合100平米以上户型。 JSON 输出 调用模型获取结果后直接解析import json raw model.generate_content(prompt).text # 模型有时会输出 Markdown 代码块标记需要清理 raw raw.strip() if raw.startswith(): raw raw.strip() if raw.startswith(json): raw raw[4:].strip() data json.loads(raw) print(data[title], data[price], data[tags])这里有一个常见的坑Gemini 有时会依照它训练时的习惯在 JSON 外面包裹 json 代码块。如果你不清理json.loads直接报错。所以写了一个简单的清理逻辑。更稳妥的方式是在 prompt 里强调“不要输出任何代码块标记直接输出 JSON”但依然不能 100% 保证。所以解析时做两层保护先清理 Markdown 标记如果解析失败再尝试提取 JSON 片段。我封装过一个健壮的解析函数def extract_json(text): text text.strip() if text.startswith(): text re.sub(r^(?:json)?\s*|\s*$, , text, flagsre.IGNORECASE) try: return json.loads(text) except json.JSONDecodeError: start text.find({) end text.rfind(}) if start ! -1 and end ! -1: return json.loads(text[start:end1]) raise这里的re.sub可能写得稍微有点糙但你实际运行时会发现绝大多数模型输出都能被这个函数成功解析。3.4 批量处理与限速控制批量处理是另一个高频应用场景。比如我有 200 条新闻标题需要生成摘要循环调用 200 次 Gemini API。第一次写这种代码你可能会直接写for item in items: result ask_gemini(item) save(result)大错特错。如果不做任何限速短时间内发出大量请求要么触发配额限制429要么被风控封掉 key。解决方法是加延时或用并发池控制速率。最简单稳妥的限速方式import time for item in items: prompt build_prompt(item) try: result ask_gemini(prompt) save(item, result) except Exception as e: log_error(item, e) time.sleep(2) # 每请求间隔 2 秒这个时间间隔不是固定的。如果你调的是免费层通常每分钟请求数在 60 左右那么间隔 1 秒就够了。但如果你不确定当前配额建议先用一条请求测试连续跑 10 条看是否报错再动态调整 sleep 时长。我自己的做法是写一个简单的自适应限速器记录上次请求时间如果在min_interval内就 sleep 补足。如果遇到 429 错误就把min_interval增加 5 秒并把当前请求重试一次。这样既不会太慢也不会被限制。批量处理时还要考虑断点续跑。程序跑一半崩了全部重新来很亏。我一般会给每一条记录添加一个“已处理”标记或者将结果逐条写入文件这样下次运行就能跳过已经处理过的条目。4. 常见问题与排查技巧实录4.1 API Key 相关问题的排查顺序API key not valid或者ApiException: [401]这类报错出现次数最多。排查顺序如下确认 key 是否复制完整注意不要带引号或空格。确认环境变量是否在当前 Shell 会话中生效。用echo $GEMINI_API_KEY查看。确认项目里没写死其他 key。如果你在代码里调用genai.configure(api_key...)会覆盖环境变量。确认 key 是否过期。Google AI Studio 的 key 可以随时创建也可以删除如果你之前在测试时删过 key再运行就会出现 401。还有一点容易被忽略genai.configure必须在所有模型调用之前执行。如果你在 import 别的模块时调用了模型而那个模块里没有执行 configure就会报“未配置 API key”的错。4.2 429 配额超限的应对方案当请求频率或 Token 数超过限制时你会看到google.api_core.exceptions.ResourceExhausted: 429 ... limit这种错误分两种情况RPM 超限和 TPM每分钟 Token 数超限。前者好解决降低请求频率后者麻烦一点需要减少每个请求的 Token 数比如缩短 prompt 长度、减少历史对话条数。我的经验是遇到 429 不要立即重试先 sleep 30 秒以上因为配额窗口是按分钟滑动的立刻重试大概率继续 429。你可以在代码里捕获这个异常设置一个指数退避import time for attempt in range(5): try: response model.generate_content(prompt) break except ResourceExhausted: wait_time 30 * (2 ** attempt) print(f配额超限等待 {wait_time} 秒) time.sleep(wait_time) else: print(重试次数用完)还有一个更简单的规避思路把大的批量任务拆成多次小程序运行每次处理 20 条中间间隔几分钟。手动控制比写复杂退避算法更可靠。4.3 输出内容被安全过滤的问题Gemini 内置了安全设置对于某些用户输入或输出内容可能会触发内容过滤导致response.text返回空字符串或者prompt_feedback里出现block_reason。我做代码生成时遇到过prompt 里只要出现“攻击”、“破解”等词即使是讨论安全防御的正当内容也可能被过滤掉。解决方式有几种改写 prompt把敏感词替换成中性表达。在生成配置里调整安全辅助方向阈值。官方支持safety_settings参数你可以设置model genai.GenerativeModel( model_namegemini-pro, safety_settings{ HARM_CATEGORY_HARASSMENT: BLOCK_NONE, HARM_CATEGORY_HATE_SPEECH: BLOCK_NONE, HARM_CATEGORY_SEXUALLY_EXPLICIT: BLOCK_NONE, HARM_CATEGORY_DANGEROUS_CONTENT: BLOCK_NONE, } )但注意BLOCK_NONE在部分类型内容上可能不被允许而且如果 context 本身违规无论设置如何都会被过滤。这里要说明调整安全设置只能解决误拦截问题不代表可以规避限制。最实际的建议在设计业务时尽量避免触发高风险分类。比如你是做医疗问答的就不要让模型扮演“医生诊断”而是改成“提供健康信息参考”这样既符合合规要求也不容易被过滤。4.4 返回结果截断问题当输出达到max_output_tokens上限或模型认为已经“说完”时可能会返回finish_reasonSTOP正常结束。但如果你看到finish_reasonMAX_TOKENS说明输出被截断了。常见的处理方式增大max_output_tokens但要注意输入输出不能超过模型上下文限制。把任务拆成多轮让模型分步生成。比如长文章按章节生成。检测到截断后把已生成的内容作为上下文让模型继续补全。检测截断的方式response model.generate_content(prompt) if response.candidates[0].finish_reason.name MAX_TOKENS: print(输出被截断需要处理)这个检测在批量处理长文时非常有用。我做文章摘要时如果摘要过长被截断我会把“请继续”接在后面让模型把未说完的内容说完。4.5 网络超时的处理SDK 默认请求超时时间有时候不够长。当你的 prompt 很长或模型负载高时可能在几十秒内没有响应。这时你会看到截止时间已到deadline exceeded之类的错误。处理办法是在generate_content里设置request_optionsresponse model.generate_content( prompt, request_options{timeout: 120} )这个参数在较新的 SDK 版本里可用老版本可能不识别。如果不行可以升级google-generativeai到最新版。另外流式模式下如果响应中途断流超过一段时间SDK 也可能超时。这时候可以做前台静默重试但要注意流式响应一旦中途断掉[之前已经生成的部分]是不完整的重试时最好把长 prompt 精简后再请求一次避免重复消耗 Token。5. 进阶应用把 Gemini 嵌进真实业务流程5.1 用 Gemini 辅助生成 Python 代码模板回到标题里的“Bard 编程指南”编程辅助本身就是 Gemini 的强项。我不建议直接让模型写整个项目的代码但非常适合让它生成函数模板、正则表达式、样板代码。比如我想写一个读取 CSV 并过滤某列数据的功能可以直接问prompt 请在 Python 中实现一个函数读取名为 data.csv 的文件过滤掉 age 列小于 18 的行并返回过滤后的 DataFrame。使用 pandas并处理文件不存在的情况。 response model.generate_content(prompt) print(response.text)模型生成的代码大概率能直接用但你要检查两件事错误处理的逻辑是否完备以及是否用到了你项目里已经存在的依赖。生成代码当草稿自己改一改效率提升是肉眼可见的。还有一种玩法让模型解释你项目中已有的一段复杂代码。粘贴给它询问“这段代码有哪些潜在 bug 或者优化空间”会有不错的反馈。毕竟模型看到过大量相似的模式找常规问题比人工review更快。5.2 批量文档分类与信息抽取信息抽取是 Gemini 在业务上最稳的落地场景。我做过一个例子从一堆招聘启事中提取“岗位名称、薪资、学历要求、经验要求”四个字段。prompt 这样写你负责从招聘信息中提取结构化数据。只输出 JSON不要输出解释。 要求字段 - position: 岗位名称 - salary_min: 最低薪资整型单位K/月 - salary_max: 最高薪资整型 - degree: 最低学历要求 - experience: 经验要求 招聘信息 ...关键在于我把薪资范围拆成了两个数值字段方便后续统计而不是保留“15K-25K”这种字符串。这一步表面上是小事但直接影响后面的数据分析效率。模型在单一 JSON 里输出两个字段完全没问题所以尽量在设计 prompt 时就把数据结构想好。批量跑 1000 条数据时观察过成功解析率在 98% 左右剩下的 2% 多是因为原文本身缺失关键信息或者模型返回了空字段。这时候不要反复重试而是把失败的数据单独标记回头人工检查。盲目重试既费 Token 又容易触发限流。5.3 结合本地 Python 生态做自动化流水线Gemini 响应结果需要和现有 Python 生态衔接比如数据清洗、数据库写入、定时任务。一个完整的自动化流程可以是用schedule或系统 crontab 定时触发脚本脚本从数据库读取待处理记录构造 prompt调用 Gemini 生成摘要或分类解析 JSON 结果写回数据库更新状态字段记录运行日志失败任务重试或告警这里面有一个心得不要把 Gemini 的调用逻辑和业务逻辑写在同一个函数里。保持ask_gemini()只负责“入参 prompt - 出参 text”业务层再去解析这样后期换模型或调整 prompt 时不需要翻一堆数据库代码。我在实际项目里把 Gemini 封装成了一个独立的微服务通过 HTTP 接口给其他模块调用。这样不仅团队内部可以共用一个 API key 和配额还可以在服务层做缓存、负载均衡、日志监控。单个业务脚本调用同一份 API key 遇到限流是整个系统的瓶颈但集中到一个服务后可以用队列和重试机制消化波动。5.4 一个完整的 CSV 摘要生成器这里给出一个可以直接抄作业的完整脚本综合了前面所有要点环境变量、模型封装、JSON 解析、批量处理、断点续跑、错误重试。import os import csv import json import time import re import google.generativeai as genai genai.configure(api_keyos.environ[GEMINI_API_KEY]) model genai.GenerativeModel( model_namegemini-pro, generation_config{ temperature: 0.2, max_output_tokens: 256, } ) def build_prompt(text): return f 请根据以下新闻内容生成摘要输出 JSON字段为 - summary: 不超过 50 字的中文摘要 - keywords: 最多 3 个关键词 新闻内容 {text} def extract_json(text): text text.strip() if text.startswith(): text re.sub(r^(?:json)?\s*|\s*$, , text, flagsre.IGNORECASE) try: return json.loads(text) except json.JSONDecodeError: start text.find({) end text.rfind(}) if start ! -1 and end ! -1: return json.loads(text[start:end1]) raise def ask_gemini(prompt, retries3): for attempt in range(retries): try: raw model.generate_content(prompt).text return extract_json(raw) except Exception as e: if attempt retries - 1: raise time.sleep(5 * (attempt 1)) def process_csv(input_path, output_path, resumeTrue): processed set() if resume and os.path.exists(output_path): with open(output_path, r, encodingutf-8) as f: reader csv.DictReader(f) for row in reader: processed.add(row[id]) with open(input_path, r, encodingutf-8) as fin, open(output_path, a, encodingutf-8, newline) as fout: reader csv.DictReader(fin) fieldnames [id, text, summary, keywords, status] writer csv.DictWriter(fout, fieldnamesfieldnames) if os.path.getsize(output_path) 0: writer.writeheader() for row in reader: uid row[id] if uid in processed: continue try: result ask_gemini(build_prompt(row[text])) writer.writerow({ id: uid, text: row[text], summary: result.get(summary, ), keywords: ;.join(result.get(keywords, [])), status: ok }) except Exception as e: writer.writerow({ id: uid, text: row[text], summary: , keywords: , status: ferror: {e} }) fout.flush() time.sleep(1.5) if __name__ __main__: process_csv(input.csv, output.csv)这个脚本有几个设计亮点每条结果立刻写入文件并 flush防止中途崩溃丢数据。用processed集合跳过已处理过的 id配合 resume 参数实现断点续跑。输出状态字段把失败原因记录下来方便人工review。请求间隔固定在 1.5 秒平衡速度和配额。你可以按自己的 CSV 字段名调整reader的列名。如果要跑大数据量记得先用 10 条数据试一遍观察是否有 429 或解析报错再放开跑全量。6. 个人体会与几个实用的补充技巧写这篇的时候我重新审视了自己从零接触 Gemini API 到做进生产流程的整个过程。最深的体会是大模型的 API 调用看似简单真正麻烦的从来不是“怎么调通”而是“怎么稳定地在业务里用起来”。Prompt 设计、异常处理、批量限速、输出解析这四个环节每一个都有大量细节任何一个处理不好线上都会出问题。再分享几个之前没提到的小技巧都是实操中验证过的。第一输出结果一定要记录原始日志。不要把response.text直接覆盖掉原始输入。很多时候模型返回的结果看起来合理但其实是幻觉没有原始日志就没有复盘依据。每条请求都记录 prompt 和 output 的摘要哪怕写到本地文件都行。第二小心重复调用导致的无意义消耗。代码里如果有一个函数在循环里调了多次 Gemini很可能是逻辑设计缺陷。把能本地计算的内容先算了不要全部丢给模型。比如文本清洗、正则匹配这些是确定性任务用普通代码又快又便宜。第三temperature0并不绝对意味着每次输出一致。它只是让随机性降到最低但某些模型后端也可能因并行优化产生微小差异。如果你的业务要求严格幂等比如“提取字段”可以在 prompt 里加一句“基于输入文本逐字提取不要推测”比单纯依赖参数更进一步。第四long context 任务要注意“注意力流失”。如果你的输入文本有几千字把关键信息放在 prompt 的开头和结尾比放在中间效果更好。这是很多大模型的通病Gemini 也有这个倾向。如果实在绕不开可以把文本拆成几段分段提取后合并再交给模型生成最终结果。这个系列到这一篇核心的 Python 编程技巧基本覆盖完了。后面如果再写我大概率会聊一些偏工程的话题比如模型结果的评估方法、成本控制或者更复杂的检索增强生成。但眼下如果你能把自己手头的任务用上面这套流程跑通一遍就已经领先大多数只停留在“能跑通示例”的人了。去动手吧。
先把话放前面这个系列写到第四篇前面的内容如果都跟下来了现在应该已经能在本地跑通 Python 环境也试过用基础请求去碰 Gemini 的接口。但真正干活的时候你会发现光会发请求不够还得知道怎么设计 prompt、怎么控制输出、怎么处理异常、怎么把模型能力嵌进自己的业务流程里。这篇就专门讲这些实打实的细节所有代码都基于 Python 3.8 和官方google-generativeai库场景全部围绕文本生成、代码辅助、结构化输出和批量处理看完可以直接往自己的项目里套。这篇内容适合三类人第一类是刚把 Gemini API 调通、但只会跑官方示例的初学者第二类是已经封装过接口、想优化交互细节的开发者第三类是打算用 Gemini 做内容处理、数据处理但还没找到合适方案的产品或运营。如果只是抱着“玩玩”的心态前几篇够了要想用在正经项目里这篇的坑你大概率都会踩到。1. 项目整体设计与思路拆解1.1 为什么用 Python 而不是直接调 HTTP 接口Gemini 官方提供 REST API理论上用 Postman 或者 curl 就能测通但一旦进入业务逻辑HTTP 裸调很快就会让你崩溃。原因很简单要自己处理鉴权、构造请求体、解析流式响应、重试机制、长文本截断这些工作量全部堆起来比你写核心业务代码还费劲。Python 的优势在于google-generativeai这个 SDK 把这些底层逻辑全包了。你传一个 API key、指定模型名然后model.generate_content()一行调用返回的是一个完整的GenerateContentResponse对象。这个对象里不仅有文本还有候选结果、Token 统计、安全评分这些信息省去了一大堆 json 解析和状态码判断。我一开始也是用 requests 手撸结果遇到一个问题Gemini 返回的 JSON 结构里字段嵌套很深不同模型返回的字段还不完全一样写解析代码就花了半天后来换了 SDK半小时就完成了同样的功能。所以如果你要正经做项目直接用 SDK不是因为它“官方”而是因为它把版本间的字段差异做了兼容你不需要跟着 API 文档逐字逐句对齐。1.2 Gemini 与 Bard 的关系以及能力边界Bard 是 Google 之前的对话产品Gemini 是背后的模型系列。现在对外提供 API 的是 Gemini所以标题里写“Bard 编程指南”更多是沿用了大家熟悉的称呼。实际开发中我们面对的核心对象是gemini-pro、gemini-pro-vision这些模型端点。这系列做下来我总结 Gemini API 的能力边界大致有三块文本生成与对话、代码生成与解释、多模态理解Vision 模型。第四篇重点讲前两块因为这两块是日常开发用得最频繁的。需要提醒的是Gemini 不像某些国产大模型那样有“完全离线可用”的版本所有请求都必须发到 Google 的服务器。这意味着你必须有稳定的网络环境并且要注意请求体大小和频率限制。免费层的限制一般是每分钟请求数RPM和每天 Token 数具体数值会变以官方控制台为准。1.3 典型应用场景与整体流程设计拿我最近做的一个小项目举例本地有一批产品描述文本需要自动生成 SEO 标题和摘要。传统做法是写一堆正则和模板效果生硬。用 Gemini 的做法是读取本地文本文件构造一个通用 prompt包含待处理文本和输出格式要求循环调用generate_content把结果解析成字典写入 CSV这个过程里最关键的其实是第 2 步 prompt 的设计和第 3 步的异常处理。模型能力再强prompt 写不清楚输出也会乱API 再稳定也架不住网络抖动和配额超限。所以我把这套流程拆成三个独立模块gemini_client.py负责初始化客户端统一管理 API key 和模型参数prompt_builder.py负责把输入文本和指令拼成标准 promptbatch_processor.py负责循环调用、异常跳过、结果落盘模块分离的好处是以后想换模型、换场景只需要改 prompt 或客户端配置不用动主流程代码。下面四节的内容都围绕这套架构展开。2. 核心细节解析与实操要点2.1 环境准备与依赖安装先说环境。Python 版本建议 3.8 以上实测 3.10 和 3.11 都没问题。安装依赖pip install google-generativeai如果你之前装过老版本最好升级一下pip install -U google-generativeai这个包依赖grpcio、protobuf、google-auth等一堆东西首次安装可能要等一会儿属于正常现象。装完后验证一下python -c import google.generativeai as genai; print(genai.__version__)能输出版本号就说明基础环境没问题。如果卡在 import 阶段常见原因是grpcio版本冲突解决办法是卸载重装pip uninstall grpcio google-generativeai pip install google-generativeai --no-cache-dir另外提醒一句不要直接在代码里硬编码 API key。虽然写着方便但一旦代码泄漏到 GitHub 或者别人电脑上key 就可能被滥用。我自己的做法是放到环境变量里export GEMINI_API_KEY你的key然后在代码里import os import google.generativeai as genai genai.configure(api_keyos.environ[GEMINI_API_KEY])这样既安全又方便在不同环境切换。2.2 模型选择与参数配置Gemini API 目前的模型命名常见有gemini-pro和gemini-pro-vision。前者适合纯文本输入输出后者支持图像文本输入。代码生成、文本摘要、问答对话这些场景直接用gemini-pro就够了。初始化模型时可以配置一些生成参数model genai.GenerativeModel( model_namegemini-pro, generation_config{ temperature: 0.7, max_output_tokens: 2048, top_p: 0.95, top_k: 40, } )这些参数的含义temperature控制随机性。0 表示几乎总是选概率最高的 token适合分类、抽取这类确定任务0.7~0.9 适合创意写作输出更多样。做代码生成建议 0.2 到 0.4否则同样的 prompt 会得到风格不一致的代码。max_output_tokens限制输出长度。Gemini 的输出 Token 上限与输入 Token 数有关系太长会截断。中文场景下1 个汉字大约等于 1~2 个 token按经验留一半余量。top_p核采样阈值控制候选 token 的累积概率范围。值越小生成越保守。top_k每一步从概率最高的 k 个 token 里选。一般不用调太细保持默认即可。我实际用下来大部分任务只需要调 temperature 和 max_output_tokens其他参数用默认值完全够。别过度调参模型能力本身远比参数的微小差异重要。2.3 Prompt 设计的核心原则Gemini 这类大模型对 prompt 的敏感度极高。同一个任务prompt 写法不同结果质量可能差一个档次。我踩过不少坑之后总结出三条原则第一明确指令。不要说“帮我看看这段文字”要说“从这段文字中提取商品名称、价格和促销信息以 JSON 格式输出”。第二给出格式约束。如果你预期输出 JSON就在 prompt 里写明 JSON 的字段结构和示例。否则模型可能给你一段冗长的叙述。第三少用否定句多用肯定句。比如“不要输出无关内容”不如“只输出符合指定 JSON 结构的内容”效果好。举一个对比明显的例子。弱 prompt分析以下文本并给出建议。 文本...强 prompt你是一位资深电商运营专家。请分析以下商品描述输出包含title、keywords、summary三个字段的 JSON其中 title 不超过 20 字keywords 是 5 个关键词组成的数组summary 不超过 50 字。 文本...后者不仅约束了角色还约束了输出结构模型就知道该怎么回答了。大约 80% 的“生成结果乱”的问题本质上都是 prompt 没说清楚。2.4 多轮对话的会话管理Gemini API 支持多轮对话官方有个ChatSession对象chat model.start_chat(history[]) response chat.send_message(你好) print(response.text)这个对象会自动记录上下文但要注意它把整个历史都放在请求里所以对话轮次越多请求 Token 越大费用和延迟都会涨。我测试过超过 10 轮之后响应速度明显变慢。如果你的场景只是单轮单次调用直接用generate_content就够了别开ChatSession白白增加请求体。如果确实需要多轮但又不希望上下文无限膨胀可以手动裁剪历史。比如只保存最近 4 轮对话的内容拼接成一个人为的 prompt 再调用generate_content。这样既保留一定上下文又控制 Token 消耗。3. 实操过程与核心环节实现3.1 最小可用的文本生成脚本先给一个最基础的脚本跑通后我们再逐步扩展。import os import google.generativeai as genai genai.configure(api_keyos.environ[GEMINI_API_KEY]) model genai.GenerativeModel( model_namegemini-pro, generation_config{ temperature: 0.3, max_output_tokens: 1024, } ) prompt 请用一句话解释什么是Python闭包并给出一个简单代码示例。 response model.generate_content(prompt) print(response.text)运行之前确认环境变量GEMINI_API_KEY已设置。如果之前没设置最直接的方式是export GEMINI_API_KEY你的key python your_script.py这段代码跑通后你就拥有了最基本的“文生文”能力。接下来把它封装成一个函数方便复用def ask_gemini(prompt, temperature0.3, max_tokens1024): model genai.GenerativeModel( model_namegemini-pro, generation_config{ temperature: temperature, max_output_tokens: max_tokens, } ) response model.generate_content(prompt) return response.text这个封装看起来很普通但实际开发中你一定会遇到一个问题多次调用GenerativeModel会不会有性能损耗实测结果是可以忽略不计因为底层连接池是复用的。不过更优雅的做法是全局只初始化一次模型实例其他函数调用它。3.2 流式输出与实时打印大模型生成长文本时如果等它全部生成完再返回对于几百字的输出可能还好但对于几千字的文章等待时间会显得很长。Gemini SDK 支持流式生成即边生成边返回。response model.generate_content(prompt, streamTrue) for chunk in response: print(chunk.text, end)流式和批量在 API 层面不是同一个请求模式流式响应对应的是流式传输Token 总数一样但首字节延迟明显更低。如果你做的是对话机器人或实时写作工具强烈建议用流式。注意流式模式下response.text并不是一开始就有。你需要遍历 chunks把它们拼接起来。拼接的方式full_text for chunk in response: full_text chunk.text另外流式输出在异常处理上有个特殊点如果你在遍历过程中网络断了chunk.text可能会抛异常。所以要把整个遍历过程包在 try 里而不是只包在生成请求时。3.3 结构化输出让模型返回 JSON 并用 Python 解析实际工程中我们很少只让模型返回纯文本更多的是让它返回结构化的数据。比如批量提取网页中的商品信息、抽取新闻的关键要素。这时候我们要让模型输出 JSON再用json.loads解析。准备这样一个 promptprompt 请从以下文本中提取信息并以 JSON 格式返回包含三个字段 - title: 商品标题 - price: 价格数值不含货币符号 - tags: 标签列表 文本这台智能扫地机器人支持激光导航售价1299元适合100平米以上户型。 JSON 输出 调用模型获取结果后直接解析import json raw model.generate_content(prompt).text # 模型有时会输出 Markdown 代码块标记需要清理 raw raw.strip() if raw.startswith(): raw raw.strip() if raw.startswith(json): raw raw[4:].strip() data json.loads(raw) print(data[title], data[price], data[tags])这里有一个常见的坑Gemini 有时会依照它训练时的习惯在 JSON 外面包裹 json 代码块。如果你不清理json.loads直接报错。所以写了一个简单的清理逻辑。更稳妥的方式是在 prompt 里强调“不要输出任何代码块标记直接输出 JSON”但依然不能 100% 保证。所以解析时做两层保护先清理 Markdown 标记如果解析失败再尝试提取 JSON 片段。我封装过一个健壮的解析函数def extract_json(text): text text.strip() if text.startswith(): text re.sub(r^(?:json)?\s*|\s*$, , text, flagsre.IGNORECASE) try: return json.loads(text) except json.JSONDecodeError: start text.find({) end text.rfind(}) if start ! -1 and end ! -1: return json.loads(text[start:end1]) raise这里的re.sub可能写得稍微有点糙但你实际运行时会发现绝大多数模型输出都能被这个函数成功解析。3.4 批量处理与限速控制批量处理是另一个高频应用场景。比如我有 200 条新闻标题需要生成摘要循环调用 200 次 Gemini API。第一次写这种代码你可能会直接写for item in items: result ask_gemini(item) save(result)大错特错。如果不做任何限速短时间内发出大量请求要么触发配额限制429要么被风控封掉 key。解决方法是加延时或用并发池控制速率。最简单稳妥的限速方式import time for item in items: prompt build_prompt(item) try: result ask_gemini(prompt) save(item, result) except Exception as e: log_error(item, e) time.sleep(2) # 每请求间隔 2 秒这个时间间隔不是固定的。如果你调的是免费层通常每分钟请求数在 60 左右那么间隔 1 秒就够了。但如果你不确定当前配额建议先用一条请求测试连续跑 10 条看是否报错再动态调整 sleep 时长。我自己的做法是写一个简单的自适应限速器记录上次请求时间如果在min_interval内就 sleep 补足。如果遇到 429 错误就把min_interval增加 5 秒并把当前请求重试一次。这样既不会太慢也不会被限制。批量处理时还要考虑断点续跑。程序跑一半崩了全部重新来很亏。我一般会给每一条记录添加一个“已处理”标记或者将结果逐条写入文件这样下次运行就能跳过已经处理过的条目。4. 常见问题与排查技巧实录4.1 API Key 相关问题的排查顺序API key not valid或者ApiException: [401]这类报错出现次数最多。排查顺序如下确认 key 是否复制完整注意不要带引号或空格。确认环境变量是否在当前 Shell 会话中生效。用echo $GEMINI_API_KEY查看。确认项目里没写死其他 key。如果你在代码里调用genai.configure(api_key...)会覆盖环境变量。确认 key 是否过期。Google AI Studio 的 key 可以随时创建也可以删除如果你之前在测试时删过 key再运行就会出现 401。还有一点容易被忽略genai.configure必须在所有模型调用之前执行。如果你在 import 别的模块时调用了模型而那个模块里没有执行 configure就会报“未配置 API key”的错。4.2 429 配额超限的应对方案当请求频率或 Token 数超过限制时你会看到google.api_core.exceptions.ResourceExhausted: 429 ... limit这种错误分两种情况RPM 超限和 TPM每分钟 Token 数超限。前者好解决降低请求频率后者麻烦一点需要减少每个请求的 Token 数比如缩短 prompt 长度、减少历史对话条数。我的经验是遇到 429 不要立即重试先 sleep 30 秒以上因为配额窗口是按分钟滑动的立刻重试大概率继续 429。你可以在代码里捕获这个异常设置一个指数退避import time for attempt in range(5): try: response model.generate_content(prompt) break except ResourceExhausted: wait_time 30 * (2 ** attempt) print(f配额超限等待 {wait_time} 秒) time.sleep(wait_time) else: print(重试次数用完)还有一个更简单的规避思路把大的批量任务拆成多次小程序运行每次处理 20 条中间间隔几分钟。手动控制比写复杂退避算法更可靠。4.3 输出内容被安全过滤的问题Gemini 内置了安全设置对于某些用户输入或输出内容可能会触发内容过滤导致response.text返回空字符串或者prompt_feedback里出现block_reason。我做代码生成时遇到过prompt 里只要出现“攻击”、“破解”等词即使是讨论安全防御的正当内容也可能被过滤掉。解决方式有几种改写 prompt把敏感词替换成中性表达。在生成配置里调整安全辅助方向阈值。官方支持safety_settings参数你可以设置model genai.GenerativeModel( model_namegemini-pro, safety_settings{ HARM_CATEGORY_HARASSMENT: BLOCK_NONE, HARM_CATEGORY_HATE_SPEECH: BLOCK_NONE, HARM_CATEGORY_SEXUALLY_EXPLICIT: BLOCK_NONE, HARM_CATEGORY_DANGEROUS_CONTENT: BLOCK_NONE, } )但注意BLOCK_NONE在部分类型内容上可能不被允许而且如果 context 本身违规无论设置如何都会被过滤。这里要说明调整安全设置只能解决误拦截问题不代表可以规避限制。最实际的建议在设计业务时尽量避免触发高风险分类。比如你是做医疗问答的就不要让模型扮演“医生诊断”而是改成“提供健康信息参考”这样既符合合规要求也不容易被过滤。4.4 返回结果截断问题当输出达到max_output_tokens上限或模型认为已经“说完”时可能会返回finish_reasonSTOP正常结束。但如果你看到finish_reasonMAX_TOKENS说明输出被截断了。常见的处理方式增大max_output_tokens但要注意输入输出不能超过模型上下文限制。把任务拆成多轮让模型分步生成。比如长文章按章节生成。检测到截断后把已生成的内容作为上下文让模型继续补全。检测截断的方式response model.generate_content(prompt) if response.candidates[0].finish_reason.name MAX_TOKENS: print(输出被截断需要处理)这个检测在批量处理长文时非常有用。我做文章摘要时如果摘要过长被截断我会把“请继续”接在后面让模型把未说完的内容说完。4.5 网络超时的处理SDK 默认请求超时时间有时候不够长。当你的 prompt 很长或模型负载高时可能在几十秒内没有响应。这时你会看到截止时间已到deadline exceeded之类的错误。处理办法是在generate_content里设置request_optionsresponse model.generate_content( prompt, request_options{timeout: 120} )这个参数在较新的 SDK 版本里可用老版本可能不识别。如果不行可以升级google-generativeai到最新版。另外流式模式下如果响应中途断流超过一段时间SDK 也可能超时。这时候可以做前台静默重试但要注意流式响应一旦中途断掉[之前已经生成的部分]是不完整的重试时最好把长 prompt 精简后再请求一次避免重复消耗 Token。5. 进阶应用把 Gemini 嵌进真实业务流程5.1 用 Gemini 辅助生成 Python 代码模板回到标题里的“Bard 编程指南”编程辅助本身就是 Gemini 的强项。我不建议直接让模型写整个项目的代码但非常适合让它生成函数模板、正则表达式、样板代码。比如我想写一个读取 CSV 并过滤某列数据的功能可以直接问prompt 请在 Python 中实现一个函数读取名为 data.csv 的文件过滤掉 age 列小于 18 的行并返回过滤后的 DataFrame。使用 pandas并处理文件不存在的情况。 response model.generate_content(prompt) print(response.text)模型生成的代码大概率能直接用但你要检查两件事错误处理的逻辑是否完备以及是否用到了你项目里已经存在的依赖。生成代码当草稿自己改一改效率提升是肉眼可见的。还有一种玩法让模型解释你项目中已有的一段复杂代码。粘贴给它询问“这段代码有哪些潜在 bug 或者优化空间”会有不错的反馈。毕竟模型看到过大量相似的模式找常规问题比人工review更快。5.2 批量文档分类与信息抽取信息抽取是 Gemini 在业务上最稳的落地场景。我做过一个例子从一堆招聘启事中提取“岗位名称、薪资、学历要求、经验要求”四个字段。prompt 这样写你负责从招聘信息中提取结构化数据。只输出 JSON不要输出解释。 要求字段 - position: 岗位名称 - salary_min: 最低薪资整型单位K/月 - salary_max: 最高薪资整型 - degree: 最低学历要求 - experience: 经验要求 招聘信息 ...关键在于我把薪资范围拆成了两个数值字段方便后续统计而不是保留“15K-25K”这种字符串。这一步表面上是小事但直接影响后面的数据分析效率。模型在单一 JSON 里输出两个字段完全没问题所以尽量在设计 prompt 时就把数据结构想好。批量跑 1000 条数据时观察过成功解析率在 98% 左右剩下的 2% 多是因为原文本身缺失关键信息或者模型返回了空字段。这时候不要反复重试而是把失败的数据单独标记回头人工检查。盲目重试既费 Token 又容易触发限流。5.3 结合本地 Python 生态做自动化流水线Gemini 响应结果需要和现有 Python 生态衔接比如数据清洗、数据库写入、定时任务。一个完整的自动化流程可以是用schedule或系统 crontab 定时触发脚本脚本从数据库读取待处理记录构造 prompt调用 Gemini 生成摘要或分类解析 JSON 结果写回数据库更新状态字段记录运行日志失败任务重试或告警这里面有一个心得不要把 Gemini 的调用逻辑和业务逻辑写在同一个函数里。保持ask_gemini()只负责“入参 prompt - 出参 text”业务层再去解析这样后期换模型或调整 prompt 时不需要翻一堆数据库代码。我在实际项目里把 Gemini 封装成了一个独立的微服务通过 HTTP 接口给其他模块调用。这样不仅团队内部可以共用一个 API key 和配额还可以在服务层做缓存、负载均衡、日志监控。单个业务脚本调用同一份 API key 遇到限流是整个系统的瓶颈但集中到一个服务后可以用队列和重试机制消化波动。5.4 一个完整的 CSV 摘要生成器这里给出一个可以直接抄作业的完整脚本综合了前面所有要点环境变量、模型封装、JSON 解析、批量处理、断点续跑、错误重试。import os import csv import json import time import re import google.generativeai as genai genai.configure(api_keyos.environ[GEMINI_API_KEY]) model genai.GenerativeModel( model_namegemini-pro, generation_config{ temperature: 0.2, max_output_tokens: 256, } ) def build_prompt(text): return f 请根据以下新闻内容生成摘要输出 JSON字段为 - summary: 不超过 50 字的中文摘要 - keywords: 最多 3 个关键词 新闻内容 {text} def extract_json(text): text text.strip() if text.startswith(): text re.sub(r^(?:json)?\s*|\s*$, , text, flagsre.IGNORECASE) try: return json.loads(text) except json.JSONDecodeError: start text.find({) end text.rfind(}) if start ! -1 and end ! -1: return json.loads(text[start:end1]) raise def ask_gemini(prompt, retries3): for attempt in range(retries): try: raw model.generate_content(prompt).text return extract_json(raw) except Exception as e: if attempt retries - 1: raise time.sleep(5 * (attempt 1)) def process_csv(input_path, output_path, resumeTrue): processed set() if resume and os.path.exists(output_path): with open(output_path, r, encodingutf-8) as f: reader csv.DictReader(f) for row in reader: processed.add(row[id]) with open(input_path, r, encodingutf-8) as fin, open(output_path, a, encodingutf-8, newline) as fout: reader csv.DictReader(fin) fieldnames [id, text, summary, keywords, status] writer csv.DictWriter(fout, fieldnamesfieldnames) if os.path.getsize(output_path) 0: writer.writeheader() for row in reader: uid row[id] if uid in processed: continue try: result ask_gemini(build_prompt(row[text])) writer.writerow({ id: uid, text: row[text], summary: result.get(summary, ), keywords: ;.join(result.get(keywords, [])), status: ok }) except Exception as e: writer.writerow({ id: uid, text: row[text], summary: , keywords: , status: ferror: {e} }) fout.flush() time.sleep(1.5) if __name__ __main__: process_csv(input.csv, output.csv)这个脚本有几个设计亮点每条结果立刻写入文件并 flush防止中途崩溃丢数据。用processed集合跳过已处理过的 id配合 resume 参数实现断点续跑。输出状态字段把失败原因记录下来方便人工review。请求间隔固定在 1.5 秒平衡速度和配额。你可以按自己的 CSV 字段名调整reader的列名。如果要跑大数据量记得先用 10 条数据试一遍观察是否有 429 或解析报错再放开跑全量。6. 个人体会与几个实用的补充技巧写这篇的时候我重新审视了自己从零接触 Gemini API 到做进生产流程的整个过程。最深的体会是大模型的 API 调用看似简单真正麻烦的从来不是“怎么调通”而是“怎么稳定地在业务里用起来”。Prompt 设计、异常处理、批量限速、输出解析这四个环节每一个都有大量细节任何一个处理不好线上都会出问题。再分享几个之前没提到的小技巧都是实操中验证过的。第一输出结果一定要记录原始日志。不要把response.text直接覆盖掉原始输入。很多时候模型返回的结果看起来合理但其实是幻觉没有原始日志就没有复盘依据。每条请求都记录 prompt 和 output 的摘要哪怕写到本地文件都行。第二小心重复调用导致的无意义消耗。代码里如果有一个函数在循环里调了多次 Gemini很可能是逻辑设计缺陷。把能本地计算的内容先算了不要全部丢给模型。比如文本清洗、正则匹配这些是确定性任务用普通代码又快又便宜。第三temperature0并不绝对意味着每次输出一致。它只是让随机性降到最低但某些模型后端也可能因并行优化产生微小差异。如果你的业务要求严格幂等比如“提取字段”可以在 prompt 里加一句“基于输入文本逐字提取不要推测”比单纯依赖参数更进一步。第四long context 任务要注意“注意力流失”。如果你的输入文本有几千字把关键信息放在 prompt 的开头和结尾比放在中间效果更好。这是很多大模型的通病Gemini 也有这个倾向。如果实在绕不开可以把文本拆成几段分段提取后合并再交给模型生成最终结果。这个系列到这一篇核心的 Python 编程技巧基本覆盖完了。后面如果再写我大概率会聊一些偏工程的话题比如模型结果的评估方法、成本控制或者更复杂的检索增强生成。但眼下如果你能把自己手头的任务用上面这套流程跑通一遍就已经领先大多数只停留在“能跑通示例”的人了。去动手吧。
