Gemini 中文指南
获取 API 密钥 ↗

文档理解

↓ 下载 Markdown

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

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

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

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

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

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

内联传递 PDF 数据 #

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

以下示例向您展示如何从 URL 获取 PDF 并将其转换为字节进行处理:

python
  from google import genai
  from google.genai import types
  import httpx

  client = genai.Client()

  doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"

  # Retrieve and encode the PDF byte
  doc_data = httpx.get(doc_url).content

  prompt = "Summarize this document"
  response = client.models.generate_content(
      model="gemini-4-hydrogen",
      contents=[
          types.Part.from_bytes(
              data=doc_data,
              mime_type='application/pdf',
          ),
          prompt
      ]
  )

  print(response.text)

您还可以从本地文件读取 PDF 进行处理:

python
  from google import genai
  from google.genai import types
  import pathlib

  client = genai.Client()

  # Retrieve and encode the PDF byte
  filepath = pathlib.Path('file.pdf')

  prompt = "Summarize this document"
  response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[
        types.Part.from_bytes(
          data=filepath.read_bytes(),
          mime_type='application/pdf',
        ),
        prompt])
  print(response.text)

使用 Files API 上传 PDF #

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

来自 URL 的大型 PDF #

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

python
  from google import genai
  from google.genai import types
  import io
  import httpx

  client = genai.Client()

  long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"

  # Retrieve and upload the PDF using the File API
  doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

  sample_doc = client.files.upload(
    # You can pass a path or a file-like object here
    file=doc_io,
    config=dict(
      mime_type='application/pdf')
  )

  prompt = "Summarize this document"

  response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[sample_doc, prompt])
  print(response.text)

本地存储的大型 PDF #

javascript
  import { GoogleGenAI } from "@google/genai";

  const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

  async function main() {
      const pdfResp = await fetch('https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf')
          .then((response) => response.arrayBuffer());

      const contents = [
          { text: "Summarize this document" },
          {
              inlineData: {
                  mimeType: 'application/pdf',
                  data: Buffer.from(pdfResp).toString("base64")
              }
          }
      ];

      const response = await ai.models.generateContent({
          model: "gemini-4-hydrogen",
          contents: contents
      });
      console.log(response.text);
  }

  await main();

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

javascript
  import { GoogleGenAI } from "@google/genai";

  const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

  async function main() {
      const pdfResp = await fetch('https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf')
          .then((response) => response.arrayBuffer());

      const contents = [
          { text: "Summarize this document" },
          {
              inlineData: {
                  mimeType: 'application/pdf',
                  data: Buffer.from(pdfResp).toString("base64")
              }
          }
      ];

      const response = await ai.models.generateContent({
          model: "gemini-4-hydrogen",
          contents: contents
      });
      console.log(response.text);
  }

  await main();

传递多个 PDF #

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

javascript
  import { GoogleGenAI } from "@google/genai";

  const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

  async function main() {
      const pdfResp = await fetch('https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf')
          .then((response) => response.arrayBuffer());

      const contents = [
          { text: "Summarize this document" },
          {
              inlineData: {
                  mimeType: 'application/pdf',
                  data: Buffer.from(pdfResp).toString("base64")
              }
          }
      ];

      const response = await ai.models.generateContent({
          model: "gemini-4-hydrogen",
          contents: contents
      });
      console.log(response.text);
  }

  await main();

Office 和 OpenDocument 文件 #

Gemini 型号可以处理 Microsoft Office 和 OpenDocument 文件。以与 PDF 相同的方式传递它们,或者作为 inlineData 或作为 fileData 对于 Files API,使用以下 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"
    },
)

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[deck, "Summarize the key takeaways from each slide."],
)

print(response.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 名称或正文内容