Gemini 中文指南
获取 API 密钥 ↗

文档理解

↓ 下载 Markdown

Gemini 模型可以处理 PDF 格式的文档,使用原生视觉来理解整个文档上下文。这不仅仅是文本提取,允许 Gemini :

  • 分析和解释内容,包括文本、图像、图表、图表和表格,甚至是长达 1000 页的长文档。

  • 将信息提取到 结构化输出 格式。

  • 根据文档中的视觉和文本元素总结并回答问题。

  • 转录文档内容(例如,转换为 HTML),保留布局和格式,以供下游应用程序使用。

您还可以传递 Microsoft Office 和 OpenDocument 文件,例如 Word 文档、PowerPoint 演示文稿和 Excel 电子表格。详细信息请参见 Office 和 OpenDocument 文件。其他非 PDF 文档(例如 TXT、Markdown 或 HTML 文件)将作为纯文本进行处理,从而消除了图表或格式等上下文。

内联传递 PDF 数据 #

您可以在请求中内联传递 PDF 数据。这最适合较小的文档或临时处理,您不需要在后续请求中引用该文件。我们建议使用 Files API 用于在多轮交互中需要参考的较大文档,以改善请求延迟并减少带宽使用。

以下示例向您展示如何内联传递 PDF 数据:

python
from google import genai
import base64

client = genai.Client()

with open('path/to/document.pdf', 'rb') as f:
    pdf_bytes = f.read()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {
            "type": "document",
            "data": base64.b64encode(pdf_bytes).decode('utf-8'),
            "mime_type": "application/pdf"
        },
        {"type": "text", "text": "Summarize this document"}
    ]
)

print(interaction.output_text)

您还可以上传本地PDF文件进行处理:

python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="file.pdf")

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": uploaded_file.uri, "mime_type": uploaded_file.mime_type},
        {"type": "text", "text": "Summarize this document"}
    ]
)
print(interaction.output_text)

使用 Files API 上传 PDF #

我们建议您将 Files API 用于较大的文件或当您打算跨多个请求重复使用文档时。通过将文件上传与模型请求解耦,可以改善请求延迟并减少带宽使用。

来自 URL 的大型 PDF #

使用文件 API 简化从 URL 上传和处理大型 PDF 文件的过程:

python
from google import genai
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://arxiv.org/pdf/2312.11805"

doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

sample_doc = client.files.upload(
  file=doc_io,
  config=dict(
    mime_type='application/pdf')
)

prompt = "Summarize this document"

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": sample_doc.uri, "mime_type": sample_doc.mime_type},
        {"type": "text", "text": prompt}
    ]
)
print(interaction.output_text)

本地存储的大型 PDF #

python
from google import genai
import pathlib

client = genai.Client()

file_path = pathlib.Path('large_file.pdf')
sample_file = client.files.upload(
    file=file_path,
)

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": sample_file.uri, "mime_type": sample_file.mime_type},
        {"type": "text", "text": "Summarize this document"}
    ]
)
print(interaction.output_text)

您可以通过调用验证API是否成功存储了上传的文件并获取其元数据 files.get。只有 name (并且通过扩展, uri)是独一无二的。

python
from google import genai
import pathlib

client = genai.Client()

fpath = pathlib.Path('example.pdf')
fpath.write_text('hello')

file = client.files.upload(file='example.pdf')

file_info = client.files.get(name=file.name)
print(file_info.model_dump_json(indent=4))

传递多个 PDF #

Gemini API 能够在单个请求中处理多个 PDF 文档(最多 1000 页),只要文档和文本提示的组合大小保持在模型的上下文窗口范围内。

python
from google import genai
import io
import httpx

client = genai.Client()

doc_url_1 = "https://arxiv.org/pdf/2312.11805"
doc_url_2 = "https://arxiv.org/pdf/2403.05530"

doc_data_1 = io.BytesIO(httpx.get(doc_url_1).content)
doc_data_2 = io.BytesIO(httpx.get(doc_url_2).content)

sample_pdf_1 = client.files.upload(
  file=doc_data_1,
  config=dict(mime_type='application/pdf')
)
sample_pdf_2 = client.files.upload(
  file=doc_data_2,
  config=dict(mime_type='application/pdf')
)

prompt = "What is the difference between each of the main benchmarks between these two papers? Output these in a table."

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": sample_pdf_1.uri, "mime_type": sample_pdf_1.mime_type},
        {"type": "document", "uri": sample_pdf_2.uri, "mime_type": sample_pdf_2.mime_type},
        {"type": "text", "text": prompt}
    ]
)

print(interaction.output_text)

Office 和 OpenDocument 文件 #

Gemini 型号可以处理 Microsoft Office 和 OpenDocument 文件。使用与 PDF 相同的方式传递它们,无论是内联还是通过 Files API document 内容块和以下 MIME 类型之一:

文件类型扩展MIME类型
文档.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
.docapplication/msword
.dotxapplication/vnd.openxmlformats-officedocument.wordprocessingml.template
.odtapplication/vnd.oasis.opendocument.text
演讲.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentation
.pptapplication/vnd.ms-powerpoint
.odpapplication/vnd.oasis.opendocument.presentation
电子表格.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xlsapplication/vnd.ms-excel
.odsapplication/vnd.oasis.opendocument.spreadsheet

这些文件的处理方式如下:

  • DOCX、DOTX、ODT 和 PPTX 文件:模型接收整个文件的文本,以及 DOCX 和 PPTX 文件的嵌入图像。页面和幻灯片不会呈现为图像,因此可能不会保留页面布局和图表等视觉元素。
  • DOC、PPT 和 ODP 文件:每个页面或幻灯片都呈现为图像,因此模型可以解释布局、图表和图像。整个文件已处理完毕。
  • XLSX 和 XLS 文件:仅 第一张 已读。其内容会转换为 CSV,因此模型会接收单元格值,但不会接收公式或格式。
  • 消耗臭氧层物质文件:仅 第一张 已读。该模型接收其单元数据和公式。

工作簿中的其他工作表将被忽略。要分析不同的工作表,请将其移至第一个位置或将其另存为单独的文件。

无论您在请求中传递文件还是在工具中返回文件,文件的处理方式都是相同的 功能反应。现有文件大小和页数限制适用于整个文件。

以下示例使用 Files API 上传 PowerPoint 演示文稿,并要求模型对其进行总结:

python
from google import genai

client = genai.Client()

deck = client.files.upload(
    file="quarterly_review.pptx",
    config={
        "mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
    },
)

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": deck.uri, "mime_type": deck.mime_type},
        {"type": "text", "text": "Summarize the key takeaways from each slide."},
    ],
)

print(interaction.output_text)

工具还可以将这些文件返回到模型。详细信息请参见 多模态功能响应.

技术细节 #

Gemini 支持最大 50MB 的 PDF 文件或 1000 页。此限制适用于内联数据和 Files API 上传。每个文档页相当于258 token。

虽然除了模型的像素数之外,文档中的像素数没有具体限制 上下文窗口,较大的页面会缩小到 3072 x 3072 的最大分辨率,同时保留其原始纵横比,而较小的页面会放大到 768 x 768 像素。除了带宽之外,较小尺寸的页面不会降低成本,也不会提高较高分辨率的页面的性能。

Gemini 3型号 #

Gemini 3 引入了对多模态视觉处理的精细控制 media_resolution 参数。您现在可以将每个媒体部分的分辨率设置为低、中或高。通过此添加,PDF 文档的处理已更新:

  1. 原生文本包含: 提取 PDF 中本机嵌入的文本并将其提供给模型。

  2. 计费和 token 报告:

  • 你是 未收费 对于 token 源自提取的 原生文本 在 PDF 中。

  • 在 usage_metadata API 响应的部分中,处理 PDF 页面(作为图像)生成的 token 现在计入 IMAGE 形式,而不是单独的 DOCUMENT 与某些早期版本一样的模式。

有关媒体分辨率参数的更多详细信息,请参阅 媒体分辨率 指导。

文件类型 #

文档视觉有意义地理解 PDF 以及 DOC、PPT 和 ODP 文件,这些文件呈现为页面图像。 DOCX、DOTX、ODT 和 PPTX 文件将转换为文本,电子表格将作为表​​格数据读取。详细信息请参见 Office 和 OpenDocument 文件.

从技术上讲,您可以传递其他 MIME 类型来理解文档,例如 TXT、Markdown、HTML、XML 等。但是,这些类型被提取为纯文本,这意味着模型无法理解渲染文件中存在的视觉元素。任何文件类型细节(例如图表、图表、HTML 标签、Markdown 格式等)都将丢失。

要了解其他文件输入方法,请参阅 文件输入方式 指导。

最佳实践 #

为了获得最佳结果:

  • 上传前将页面旋转到正确的方向。
  • 避免页面模糊。
  • 如果使用单个页面,请将文本提示放在页面后面。

后续步骤 #

要了解更多信息,请参阅以下资源:

  • 文件提示策略:Gemini API 支持文字、图片、音频、视频数据提示,也称为多模态提示。

  • 系统指令:系统指令可让您根据您的特定需求和用例来控制模型的行为。

搜索标题、API 名称或正文内容