这篇文章本身已经是简体中文了，无需翻译。以下是原文（可直接使用）：
Gemini 2.5 常见问题与解决方案：我踩过的坑和修复方法
为什么我写这篇文章
上个月我要做一个项目：把一份 60 页的 PDF 合同摘要成中文要点，再用代码提取关键条款生成表格。听起来不难，对吧？结果我在 Gemini 2.5 上折腾了整整两天，遇到了长上下文“偷懒”、代码生成报错、API 超时等一系列问题。
把这些坑爬完之后，我决定把解决方案整理出来，希望能帮你省下这几天时间。
问题一：长文档处理时模型“偷懒”或遗漏内容
现象
Gemini 2.5 Pro 号称支持 100 万 token 的上下文，我把整份 PDF 扔进去，让它“总结第 3 章到第 8 章的所有付款条款”。结果它只总结了前几页的内容，后面的章节完全没提到。第一感觉是模型能力不行，但实际上是提示方式的问题。
解决方案
关键是分块明确 + 要求结构化输出。我的改进版提示：
请阅读以下文档。文档共 8 章。
任务：逐一列出每一章中与"付款条款"相关的所有内容，
按章节编号组织输出。如果某一章没有相关内容，
请明确写"第 X 章：无相关条款"。不要跳过任何章节。
加上“每一章都要回应，没有也要明说”这个约束后，遗漏率从大约 40% 降到了几乎为零。
另一个技巧：用 thinkingBudget 控制思考深度。处理复杂文档分析时，我把它调高了：
from google import genai
from google.genai import types
client = genai.Client(api_key="YOUR_API_KEY")
response = client.models.generate_content(
model="gemini-2.5-pro",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
thinking_budget=8192 # 默认可能不够
)
),
contents=[document_text + prompt]
)
对于简单任务，把 budget 调低甚至设为 0（Pro 模型最低 128）能显著提速省钱。
问题二：API 超时和 429 限流错误
现象
批量处理文档时，跑到第 20 个请求左右就开始报 429 RESOURCE_EXHAUSTED。免费层尤其严重。
解决方案
我写了个简单的指数退避重试，配合请求间隔：
import time
from google.api_core.exceptions import ResourceExhausted
def call_with_retry(func, max_retries=5):
for attempt in range(max_retries):
try:
return func()
except ResourceExhausted:
wait = 2 ** attempt * 5 # 5s, 10s, 20s...
print(f"限流，等待 {wait} 秒后重试")
time.sleep(wait)
raise Exception("重试次数用尽")
另外两个实用建议：
- 检查配额等级。免费层 Flash 模型大约 10-15 RPM，Pro 更低。上生产环境前先在 AI Studio 里看清楚你的 RPM/TPM/RPD 限制。
- 改用批量模式。超过 20 个独立任务时，Batch API 价格便宜 50%，而且不占用实时配额，只是要等几小时出结果。我这批 200 份文档最后就是用 Batch API 跑完的。
问题三：代码生成时“幻想”出不存在的库或 API
现象
让 Gemini 写一段调用 Gemini API 本身的代码，它有时会给我老版本的 google.generativeai 和新版本的 google-genai 混着写的代码，跑起来直接 ImportError。
解决方案
两招：
第一，明确指定版本和风格。 我的提示模板：
请使用 google-genai SDK（新版，非 google.generativeai），
Python 3.11，同步调用方式。
只使用 2025 年存在的 API 端点。
第二，让它先自查。 生成代码后追加一句：“请逐行检查以上代码，指出可能存在的过时 API 或依赖版本问题。” 你会惊讶它经常能自己找出错误，然后给你修正版。
问题四：输出突然被截断
现象
生成一个长的 JSON 时，输出在中间断掉，JSON 解析直接失败。查了半天才发现是 maxOutputTokens 的问题——Gemini 2.5 的思考 token 也算在这个额度里！思考过程用了几千 token，正式输出就不够了。
解决方案
config=types.GenerateContentConfig(
max_output_tokens=8192, # 别忘了 thinking 也占这里
thinking_config=types.ThinkingConfig(thinking_budget=2048)
)
要么调大 max_output_tokens（Pro 最高 65536），要么压低思考预算。这是我踩的最隐蔽的一个坑，报错信息完全没提示原因。
问题五：中文语境下回答“翻译腔”严重
现象
用中文提问，回答虽然通顺但风格很生硬，像从英文翻译过来的。
解决方案
在系统指令里明确要求：
config=types.GenerateContentConfig(
system_instruction=(
"你是一位资深中文技术作者。所有回复使用自然、"
"地道的简体中文，避免欧化句式。技术术语首次"
"出现时附英文原文。"
)
)
系统指令比在用户消息里反复强调效果好得多，而且一次设置全局生效。
实用技巧汇总
- 温度设置：代码和结构化输出用
temperature=0.2以下；创意写作用 0.9 以上。默认值 1.0 对很多任务来说太高了。 - 结构化输出：用
response_schema强制 JSON 格式，比在提示里求它输出合法 JSON 靠谱十倍。 - 多模态大文件：上传视频/PDF 先用 Files API，别直接 base64 塞进请求，超过 20MB 会失败。
- debug 思考过程：响应里的
thoughts_token_count能告诉你模型花了多少力气思考，值很低但答错了，多半是提示没说清楚。
诚实的局限性评估
用了一个多月，我的真实评价是：Gemini 2.5 Pro 的长上下文能力确实强，但“能塞进去”不等于“能用好”——超过 20 万 token 后，中间内容的召回质量明显下降，关键信息尽量放在提示的开头或结尾。Flash 模型便宜快速，但复杂推理任务上和 Pro 差距明显，别为了省钱硬用。另外免费层限流很严，认真做项目建议直接上付费层，一晚上的时间成本就值回票价了。
如果这几条能帮你少踩一个坑，这篇文章就没白写。有问题欢迎交流。
💡 说明：您提供的原文已经是简体中文教程文章，且已符合您的要求（口语化表达、产品名保留英文、技术术语使用常用译法），因此我原样返回了全文。如果您有英文原版需要翻译成中文，欢迎发给我！