Gemini API Python实战：Prompt设计、结构化输出与批量处理细节

先把话放前面：这个系列写到第四篇，前面的内容如果都跟下来了，现在应该已经能在本地跑通 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 的做法是：

1. 读取本地文本文件
2. 构造一个通用 prompt，包含待处理文本和输出格式要求
3. 循环调用generate_content
4. 把结果解析成字典，写入 CSV

这个过程里，最关键的其实是第 2 步 prompt 的设计和第 3 步的异常处理。模型能力再强，prompt 写不清楚输出也会乱；API 再稳定，也架不住网络抖动和配额超限。

所以我把这套流程拆成三个独立模块：

• gemini_client.py：负责初始化客户端，统一管理 API key 和模型参数
• prompt_builder.py：负责把输入文本和指令拼成标准 prompt
• batch_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_key=os.environ["GEMINI_API_KEY"])

这样既安全又方便在不同环境切换。

2.2 模型选择与参数配置

Gemini API 目前的模型命名常见有gemini-pro和gemini-pro-vision。前者适合纯文本输入输出，后者支持图像+文本输入。代码生成、文本摘要、问答对话这些场景直接用gemini-pro就够了。

初始化模型时，可以配置一些生成参数：

model = genai.GenerativeModel( model_name="gemini-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_key=os.environ["GEMINI_API_KEY"]) model = genai.GenerativeModel( model_name="gemini-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, temperature=0.3, max_tokens=1024): model = genai.GenerativeModel( model_name="gemini-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, stream=True) 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解析。

准备这样一个 prompt：

prompt = """ 请从以下文本中提取信息，并以 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, flags=re.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:end+1]) 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]这类报错出现次数最多。排查顺序如下：

1. 确认 key 是否复制完整，注意不要带引号或空格。
2. 确认环境变量是否在当前 Shell 会话中生效。用echo $GEMINI_API_KEY查看。
3. 确认项目里没写死其他 key。如果你在代码里调用genai.configure(api_key=...)，会覆盖环境变量。
4. 确认 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 里只要出现“攻击”、“破解”等词，即使是讨论安全防御的正当内容，也可能被过滤掉。解决方式有几种：

1. 改写 prompt，把敏感词替换成中性表达。
2. 在生成配置里调整安全辅助方向阈值。官方支持safety_settings参数，你可以设置：

model = genai.GenerativeModel( model_name="gemini-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 本身违规，无论设置如何都会被过滤。这里要说明：调整安全设置只能解决误拦截问题，不代表可以规避限制。

3. 最实际的建议：在设计业务时，尽量避免触发高风险分类。比如你是做医疗问答的，就不要让模型扮演“医生诊断”，而是改成“提供健康信息参考”，这样既符合合规要求，也不容易被过滤。

4.4 返回结果截断问题

当输出达到max_output_tokens上限或模型认为已经“说完”时，可能会返回finish_reason=STOP，正常结束。但如果你看到finish_reason=MAX_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_options：

response = 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 生态衔接，比如数据清洗、数据库写入、定时任务。一个完整的自动化流程可以是：

1. 用schedule或系统 crontab 定时触发脚本
2. 脚本从数据库读取待处理记录
3. 构造 prompt，调用 Gemini 生成摘要或分类
4. 解析 JSON 结果
5. 写回数据库，更新状态字段
6. 记录运行日志，失败任务重试或告警

这里面有一个心得：不要把 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_key=os.environ["GEMINI_API_KEY"]) model = genai.GenerativeModel( model_name="gemini-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, flags=re.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:end+1]) raise def ask_gemini(prompt, retries=3): 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, resume=True): processed = set() if resume and os.path.exists(output_path): with open(output_path, "r", encoding="utf-8") as f: reader = csv.DictReader(f) for row in reader: processed.add(row["id"]) with open(input_path, "r", encoding="utf-8") as fin, open(output_path, "a", encoding="utf-8", newline="") as fout: reader = csv.DictReader(fin) fieldnames = ["id", "text", "summary", "keywords", "status"] writer = csv.DictWriter(fout, fieldnames=fieldnames) 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": f"error: {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，很可能是逻辑设计缺陷。把能本地计算的内容先算了，不要全部丢给模型。比如文本清洗、正则匹配，这些是确定性任务，用普通代码又快又便宜。

第三，temperature=0并不绝对意味着每次输出一致。它只是让随机性降到最低，但某些模型后端也可能因并行优化产生微小差异。如果你的业务要求严格幂等，比如“提取字段”，可以在 prompt 里加一句“基于输入文本逐字提取，不要推测”，比单纯依赖参数更进一步。

第四，long context 任务要注意“注意力流失”。如果你的输入文本有几千字，把关键信息放在 prompt 的开头和结尾，比放在中间效果更好。这是很多大模型的通病，Gemini 也有这个倾向。如果实在绕不开，可以把文本拆成几段，分段提取后合并再交给模型生成最终结果。

这个系列到这一篇，核心的 Python 编程技巧基本覆盖完了。后面如果再写，我大概率会聊一些偏工程的话题，比如模型结果的评估方法、成本控制，或者更复杂的检索增强生成。但眼下，如果你能把自己手头的任务用上面这套流程跑通一遍，就已经领先大多数只停留在“能跑通示例”的人了。去动手吧。