本文详解在调用 gemini api（尤其是 gemini-1.5-pro-latest）时，为何直接以 application/pdf mime 类型内联上传 pdf 二进制数据会导致 500 错误，并提供符合官方规范、经实测可用的两种正确方案：文件托管上传（推荐）与纯文本提取上传。
本文详解在调用 gemini api（尤其是 gemini-1.5-pro-latest）时，为何直接以 application/pdf mime 类型内联上传 pdf 二进制数据会导致 500 错误，并提供符合官方规范、经实测可用的两种正确方案：文件托管上传（推荐）与纯文本提取上传。
Gemini 系列模型（包括当前主力版本 gemini-1.5-pro-latest）原生支持多模态输入，但其对 PDF 的处理有严格的前提条件：必须通过云端文件托管机制（files.create）上传，而非将 PDF 字节流作为 inline_data 直接嵌入 prompt。你遇到的 500 Internal Server Error，根本原因在于误用了不被支持的 MIME 类型和传输方式——Gemini 的 generate_content 接口 明确不接受 application/pdf 的 inline_data（官方文档仅列出图像类 MIME 类型如 "image/png" 等），强行传入会触发服务端解析失败，而非返回清晰的 4xx 客户端错误。
✅ 正确路径一：使用 files.create 托管上传（官方推荐，支持结构理解）
这是唯一能完整保留 PDF 逻辑结构（标题层级、表格、页眉页脚）并启用 Gemini 内置文档解析能力的方式：
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")
# 1. 上传 PDF 至 Gemini 文件服务（返回 file_id）
upload_response = genai.files.create(
file=open("report.pdf", "rb"),
mime_type="application/pdf"
)
file_id = upload_response.name # e.g., "files/abc123xyz"
# 2. 构建带文件引用的 prompt
model = genai.GenerativeModel("gemini-1.5-pro-latest")
response = model.generate_content([
{"fileData": {"fileUri": f"files/{file_id}", "mimeType": "application/pdf"}},
"请逐条提取该PDF中的核心结论、数据图表说明及作者建议，用中文分点输出。"
])
print(response.text)
⚠️ 注意事项：
- 必须使用 gemini-1.5-pro 或更高版本（gemini-1.5-pro-latest），低版本模型不支持 PDF 多模态输入；
- files.create 是异步操作，上传大文件需等待 state == "PROCESSING" 变为 "ACTIVE" 后再调用 generate_content；
- 文件大小上限为 200 MB（网页端）或 512 MB（API），超出需预处理切分。
✅ 正确路径二：提取纯文本后以 text/plain 传入（适用于简单文本 PDF）
若只需文本内容且 PDF 为可复制文字的电子版（非扫描件），可跳过文件托管，直接提取并拼入 prompt：
from pypdf import PdfReader
def extract_pdf_text(pdf_path: str) -> str:
reader = PdfReader(pdf_path)
text = ""
for page in reader.pages:
text += page.extract_text() + "\n"
return text.strip()
# 提取文本（UTF-8 编码）
pdf_text = extract_pdf_text("report.pdf")
# 作为纯字符串传入（非对象！）
model = genai.GenerativeModel("gemini-1.5-pro-latest")
response = model.generate_content(
f"请分析以下文本内容：\n\n{pdf_text}\n\n要求：总结3个关键发现，并指出数据来源页码。"
)
print(response.text)
? 关键要点：
- 绝不调用 json.dumps() 或 str() 封装 Python 对象——Gemini 输入必须是原始字符串；
- 清洗文本：移除页眉页脚、合并断裂段落、过滤控制字符（如 \u2028, BOM），避免触发 500；
- 控制 Token 量：gemini-1.5-pro 最高支持 100 万 Token，但建议预留 5% 给指令与推理，文本总长勿超 95 万 Token。
❌ 常见错误与规避
| 错误做法 | 后果 | 修正方案 |
|---|---|---|
| inline_data + mime_type="application/pdf" | 500 错误（MIME 不被支持） | 改用 files.create + fileUri 引用 |
| json.dumps({"fileData": ...}) 包裹文件结构 | 500（服务端 JSON 解析失败） | 直接构造 Python 字典，不序列化 |
| 上传扫描版 PDF 未 OCR | 返回空或乱码 | 先用 pytesseract 或 pdfplumber 预处理 |
| 超长文本未分块直接发送 | 截断或超时 | 使用 textwrap.fill() 分段 + 流式请求 |
综上，Gemini 对 PDF 的强大解析能力，依赖于正确的接入路径而非 raw bytes 注入。选择 files.create 托管上传，即可解锁其原生的多模态理解与结构感知；而纯文本路径则适合轻量、快速的场景。两者均绕开 500 错误陷阱，确保分析任务稳定、高效、可复现。
