name: gemini-document-processing description: 实现Google Gemini API文档处理的指南 - 使用原生视觉分析PDF，提取文本、图像、图表、图表和表格。在处理文档、提取结构化数据、总结PDF、回答文档内容问题或转换文档为结构化格式时使用。（项目）

Gemini 文档处理

使用 Google Gemini 的原生视觉功能处理和分析 PDF 文档。提取结构化信息、总结内容、回答问题，并理解包含文本、图像、图表、图表和表格的复杂文档。

核心功能

PDF 视觉处理：原生理解最多 1,000 页的 PDF（每页 258 个令牌）
多模态分析：处理文本、图像、图表、图表和表格
结构化提取：输出为 JSON，支持模式验证
文档 Q&A：基于文档内容回答问题
总结：生成保留上下文的摘要
格式转换：转录为 HTML，同时保留布局

何时使用此技能

当您需要时使用此技能：

从 PDF 文档提取结构化数据（发票、简历、表格）
总结长文档或报告
回答关于 PDF 内容的问题
分析包含复杂布局、图表或图表的文档
将 PDF 转换为结构化格式（JSON, HTML）
批量处理多个文档
构建文档处理管道

快速设置

1. API 密钥配置

技能按此优先级顺序检查 GEMINI_API_KEY：

进程环境变量
技能目录中的 .env 文件（.claude/skills/gemini-document-processing/.env）
项目根目录中的 .env 文件

获取您的 API 密钥： https://aistudio.google.com/apikey

选项 A：环境变量（推荐）

export GEMINI_API_KEY="your-api-key-here"

选项 B：技能目录

cd .claude/skills/gemini-document-processing
echo "GEMINI_API_KEY=your-api-key-here" > .env

选项 C：项目根目录

echo "GEMINI_API_KEY=your-api-key-here" > .env

2. 安装依赖

pip install google-genai python-dotenv

常见用例

1. 从 PDF 提取结构化数据

# 使用提供的脚本
python .claude/skills/gemini-document-processing/scripts/process-document.py \
  --file invoice.pdf \
  --prompt "以 JSON 格式提取发票详情" \
  --format json

2. 总结长文档

# 处理并总结
python .claude/skills/gemini-document-processing/scripts/process-document.py \
  --file report.pdf \
  --prompt "提供一个简洁的执行摘要"

3. 回答文档相关问题

# 基于文档内容的 Q&A
python .claude/skills/gemini-document-processing/scripts/process-document.py \
  --file contract.pdf \
  --prompt "关键条款和条件是什么？"

4. 使用 Python SDK 处理

from google import genai

client = genai.Client()

# 读取 PDF
with open('document.pdf', 'rb') as f:
    pdf_data = f.read()

# 处理文档
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[
        '从此文档中提取关键信息',
        genai.types.Part.from_bytes(
            data=pdf_data,
            mime_type='application/pdf'
        )
    ]
)

print(response.text)

5. 带 JSON 模式的结构化输出

from google import genai
from pydantic import BaseModel

class InvoiceData(BaseModel):
    invoice_number: str
    date: str
    total: float
    vendor: str

client = genai.Client()

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[
        '提取发票详情',
        genai.types.Part.from_bytes(
            data=open('invoice.pdf', 'rb').read(),
            mime_type='application/pdf'
        )
    ],
    config=genai.types.GenerateContentConfig(
        response_mime_type='application/json',
        response_schema=InvoiceData
    )
)

invoice_data = InvoiceData.model_validate_json(response.text)

关键约束

格式：只有 PDF 获得视觉处理（TXT、HTML、Markdown 仅为文本）
大小：< 20MB 使用内联编码，> 20MB 使用文件 API
页数：每文档最多 1,000 页
存储：文件 API 仅存储 48 小时
成本：每页 258 个令牌（固定，无论内容密度）

性能提示

使用内联编码 对于 < 20MB 的 PDF（更简单，单次请求）
使用文件 API 对于大文件或重复查询（启用上下文缓存）
将提示放在 PDF 后 对于单页文档
使用上下文缓存 当多次查询同一 PDF 时
并行处理 对于多个独立文档
使用 gemini-2.5-flash 以获得最佳性价比

决策指南

PDF < 20MB？
├─ 是 → 使用内联 base64 编码
└─ 否 → 使用文件 API

需要结构化 JSON 输出？
├─ 是 → 用 Pydantic 定义 response_schema
└─ 否 → 获取文本响应

同一 PDF 多个查询？
├─ 是 → 使用文件 API + 上下文缓存
└─ 否 → 内联编码足够

脚本参考

技能包括一个随时可用的处理脚本：

# 基本用法
python scripts/process-document.py --file document.pdf --prompt "您的提示"

# 带 JSON 输出
python scripts/process-document.py --file document.pdf --prompt "提取数据" --format json

# 使用文件 API（对于大文件）
python scripts/process-document.py --file large-document.pdf --prompt "总结" --use-file-api

# 多个提示
python scripts/process-document.py --file document.pdf --prompt "问题 1" --prompt "问题 2"

参考文献

有关全面文档，请参阅：

references/gemini-document-processing-report.md - 完整 API 参考
references/quick-reference.md - 快速查找指南
references/code-examples.md - 额外代码模式

故障排除

API 密钥未找到：

# 检查 API 密钥是否设置
./scripts/check-api-key.sh

文件过大：

使用文件 API 对于 > 20MB 的文件
向脚本添加 --use-file-api 标志

视觉功能不工作：

确保文件为 PDF 格式
其他格式（TXT、HTML）不支持视觉处理

支持

API 文档：https://ai.google.dev/gemini-api/docs/document-processing
获取 API 密钥：https://aistudio.google.com/apikey
模型信息：https://ai.google.dev/gemini-api/docs/models/gemini