探索 Gemini API 的文档处理功能

Gemini API 支持 PDF 输入,包括长篇幅文档(最多 3, 600 页)。Gemini 模型使用原生视觉功能处理 PDF,因此能够理解文档中的文本和图片内容。借助原生 PDF 视觉支持,Gemini 模型能够:

  • 分析文档中的图表、图表和表格。
  • 将信息提取为结构化输出格式。
  • 回答与文档中的视觉内容和文本内容相关的问题。
  • 生成文档摘要。
  • 转写文档内容(例如转写为 HTML),同时保留布局和格式,以便在下游应用(例如 RAG 流水线)中使用。

本教程演示了将 Gemini API 与 PDF 文档搭配使用的一些可能方式。所有输出均为文本。

开始前须知:设置项目和 API 密钥

在调用 Gemini API 之前,您需要设置项目并配置 API 密钥。

使用 PDF 文件提示

本指南演示了如何使用 File API 或将 PDF 作为内嵌数据包含来上传和处理 PDF。

技术详情

Gemini 1.5 Pro 和 1.5 Flash 最多支持 3,600 个文档页面。文档页面必须采用以下文本数据 MIME 类型之一:

  • PDF - application/pdf
  • JavaScript - application/x-javascripttext/javascript
  • Python - application/x-pythontext/x-python
  • TXT - text/plain
  • HTML - text/html
  • CSS - text/css
  • Markdown - text/md
  • CSV - text/csv
  • XML - text/xml
  • RTF - text/rtf

每页文档相当于 258 个词元。

除了模型的上下文窗口之外,文档中的像素数量没有具体限制,但较大的页面会缩小到最大分辨率 3072x3072,同时保留其原始宽高比,较小的页面会放大到 768x768 像素。除了带宽外,较小尺寸的网页不会降低费用,较高分辨率的网页也不会提升性能。

为了达到最佳效果,请注意以下事项:

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

PDF 输入

对于小于 20MB 的 PDF 载荷,您可以选择上传 base64 编码的文档,也可以直接上传本地存储的文件。

Base64 编码的文件

您可以直接通过网址处理 PDF 文档。以下代码段展示了如何执行此操作:

import httpx
import base64

model = genai.GenerativeModel("gemini-1.5-flash")
doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"  # Replace with the actual URL of your PDF

# Retrieve and encode the PDF
doc_data = base64.standard_b64encode(httpx.get(doc_url).content).decode("utf-8")

prompt = "Summarize this document"

response = model.generate_content([{'mime_type':'application/pdf', 'data': doc_data}, prompt])
print(response.text)

本地存储的 PDF 文件

对于本地存储的 PDF 文件,您可以使用以下方法:

import base64

model = genai.GenerativeModel("gemini-1.5-flash")
doc_path = "/path/to/file.pdf" # Replace with the actual path to your local PDF

# Read and encode the local file
with open(doc_path, "rb") as doc_file:
    doc_data = base64.standard_b64encode(doc_file.read()).decode("utf-8")

prompt = "Summarize this document"

response = model.generate_content([{'mime_type': 'application/pdf', 'data': doc_data}, prompt])

print(response.text)

大型 PDF 文件

您可以使用 File API 上传任何大小的文档。当请求总大小(包括文件、文本提示、系统说明等)超过 20 MB 时,请始终使用 File API。

调用 media.upload 以使用 File API 上传文件。以下代码会上传文档文件,然后在对 models.generateContent 的调用中使用该文件。

通过网址提交的大型 PDF 文件 (:#large-pdfs-urls)

将 File API 用于可通过网址获取的大型 PDF 文件,简化直接通过网址上传和处理这些文档的过程:

import io
import httpx

model = genai.GenerativeModel("gemini-1.5-flash")
long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf" # Replace with the actual URL of your large PDF

# Retrieve and upload the PDF using the File API
doc_data = io.BytesIO(httpx.get(long_context_pdf_path).content)
sample_doc = genai.upload_file(data=doc_data, mime_type='application/pdf')

prompt = "Summarize this document"

response = model.generate_content([sample_doc, prompt])
print(response.text)

在本地存储的大型 PDF 文件 (:#large-pdfs-local)

import google.generativeai as genai

model = genai.GenerativeModel("gemini-1.5-flash")
sample_pdf = genai.upload_file(media / "test.pdf")
response = model.generate_content(["Give me a summary of this pdf file.", sample_pdf])
print(response.text)

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

import google.generativeai as genai

myfile = genai.upload_file(media / "poem.txt")
file_name = myfile.name
print(file_name)  # "files/*"

myfile = genai.get_file(file_name)
print(myfile)

多个 PDF 文件

Gemini API 能够在单个请求中处理多个 PDF 文档,前提是文档和文本提示的总大小在模型的上下文窗口内。

import io
import httpx

model = genai.GenerativeModel("gemini-1.5-flash")

doc_url_1 = "https://arxiv.org/pdf/2312.11805" # Replace with the URL to your first PDF
doc_url_2 = "https://arxiv.org/pdf/2403.05530" # Replace with the URL to your second PDF

# Retrieve and upload both PDFs using the File API
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 = genai.upload_file(data=doc_data_1, mime_type='application/pdf')
sample_pdf_2 = genai.upload_file(data=doc_data_2, mime_type='application/pdf')

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

response = model.generate_content([sample_pdf_1, sample_pdf_2, prompt])
print(response.text)

列出文件

您可以使用 files.list 列出使用 File API 上传的所有文件及其 URI。

import google.generativeai as genai

print("My files:")
for f in genai.list_files():
    print("  ", f.name)

删除文件

使用 File API 上传的文件会在 2 天后自动删除。您也可以使用 files.delete 手动删除它们。

import google.generativeai as genai

myfile = genai.upload_file(media / "poem.txt")

myfile.delete()

try:
    # Error.
    model = genai.GenerativeModel("gemini-1.5-flash")
    result = model.generate_content([myfile, "Describe this file."])
except google.api_core.exceptions.PermissionDenied:
    pass

使用 PDF 文件进行上下文缓存

import os
from google.generativeai import caching
import io
import httpx

# Define the path to the PDF document (or use a URL)
long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf" # Replace with the URL of your large PDF
doc_data = io.BytesIO(httpx.get(long_context_pdf_path).content)

# Upload the PDF document using the File API
document = genai.upload_file(data=doc_data, mime_type='application/pdf')

# Specify the model name and system instruction for caching
model_name = "gemini-1.5-flash-002" # Ensure this matches the model you intend to use
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = caching.CachedContent.create(
    model=model_name,
    system_instruction=system_instruction,
    contents=[document], # The document(s) and other content you wish to cache
)

# Display the cache details
print(cache)

# Initialize a generative model from the cached content
model = genai.GenerativeModel.from_cached_content(cache)

# Generate content using the cached prompt and document
response = model.generate_content("Please summarize this transcript")

# (Optional) Print usage metadata for insights into the API call
print(response.usage_metadata)

# Print the generated text
print(response.text)

列出缓存

您无法检索或查看缓存的内容,但可以检索缓存元数据(namemodeldisplay_nameusage_metadatacreate_timeupdate_timeexpire_time)。

如需列出所有已上传缓存的元数据,请使用 CachedContent.list()

for c in caching.CachedContent.list():
  print(c)

更新缓存

您可以为缓存设置新的 ttlexpire_time。不支持更改缓存的任何其他内容。

以下示例展示了如何使用 CachedContent.update() 更新缓存的 ttl

import datetime

cache.update(ttl=datetime.timedelta(hours=2))

删除缓存

缓存服务提供了删除操作,用于手动从缓存中移除内容。以下示例展示了如何使用 CachedContent.delete() 删除缓存。

cache.delete()

后续步骤

本指南介绍了如何使用 generateContent 以及如何根据处理后的文档生成文本输出。如需了解详情,请参阅以下资源:

  • 文件提示策略:Gemini API 支持使用文本、图片、音频和视频数据进行提示,也称为多模式提示。
  • 系统指令:借助系统指令,您可以根据自己的特定需求和使用情形来控制模型的行为。
  • 安全指南:生成式 AI 模型有时会生成意外的输出,例如不准确、有偏见或令人反感的输出。后处理和人工评估对于限制此类输出造成伤害的风险至关重要。