文档理解
Gemini 模型可以处理 PDF 格式的文档,使用原生视觉来理解整个文档上下文。这不仅仅是文本提取,允许 Gemini :
分析和解释内容,包括文本、图像、图表、图表和表格,甚至是长达 1000 页的长文档。
将信息提取到 结构化输出 格式。
根据文档中的视觉和文本元素总结并回答问题。
转录文档内容(例如,转换为 HTML),保留布局和格式,以供下游应用程序使用。
您还可以传递 Microsoft Office 和 OpenDocument 文件,例如 Word 文档、PowerPoint 演示文稿和 Excel 电子表格。详细信息请参见 Office 和 OpenDocument 文件。其他非 PDF 文档(例如 TXT、Markdown 或 HTML 文件)将作为纯文本进行处理,从而消除了图表或格式等上下文。
内联传递 PDF 数据 #
您可以将 PDF 数据内嵌在请求中传递给 generateContent。这最适合较小的文档或临时处理,您不需要在后续请求中引用该文件。我们建议使用 Files API 用于在多轮交互中需要参考的较大文档,以改善请求延迟并减少带宽使用。
以下示例向您展示如何从 URL 获取 PDF 并将其转换为字节进行处理:
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)
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();
package main
import (
"context"
"fmt"
"io"
"net/http"
"os"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
pdfResp, _ := http.Get("https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf")
var pdfBytes []byte
if pdfResp != nil && pdfResp.Body != nil {
pdfBytes, _ = io.ReadAll(pdfResp.Body)
pdfResp.Body.Close()
}
parts := []*genai.Part{
&genai.Part{
InlineData: &genai.Blob{
MIMEType: "application/pdf",
Data: pdfBytes,
},
},
genai.NewPartFromText("Summarize this document"),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-4-hydrogen",
contents,
nil,
)
fmt.Println(result.Text())
}
DOC_URL="https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
PROMPT="Summarize this document"
DISPLAY_NAME="base64_pdf"
# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"
# Check for FreeBSD base64 and set flags accordingly
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
# Base64 encode the PDF
ENCODED_PDF=$(base64 $B64FLAGS "${DISPLAY_NAME}.pdf")
# Generate content using the base64 encoded PDF
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"inline_data": {"mime_type": "application/pdf", "data": "'"$ENCODED_PDF"'"}},
{"text": "'$PROMPT'"}
]
}]
}' 2> /dev/null > response.json
cat response.json
echo
jq ".candidates[].content.parts[].text" response.json
# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"
您还可以从本地文件读取 PDF 进行处理:
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)
import { GoogleGenAI } from "@google/genai";
import * as fs from 'fs';
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const contents = [
{ text: "Summarize this document" },
{
inlineData: {
mimeType: 'application/pdf',
data: Buffer.from(fs.readFileSync("content/343019_3_art_0_py4t4l_convrt.pdf")).toString("base64")
}
}
];
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: contents
});
console.log(response.text);
}
await main();
package main
import (
"context"
"fmt"
"os"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
pdfBytes, _ := os.ReadFile("path/to/your/file.pdf")
parts := []*genai.Part{
&genai.Part{
InlineData: &genai.Blob{
MIMEType: "application/pdf",
Data: pdfBytes,
},
},
genai.NewPartFromText("Summarize this document"),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-4-hydrogen",
contents,
nil,
)
fmt.Println(result.Text())
}
使用 Files API 上传 PDF #
我们建议您将 Files API 用于较大的文件或当您打算跨多个请求重复使用文档时。通过将文件上传与模型请求解耦,可以改善请求延迟并减少带宽使用。
来自 URL 的大型 PDF #
使用文件 API 简化从 URL 上传和处理大型 PDF 文件的过程:
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)
import { createPartFromUri, GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const pdfBuffer = await fetch("https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf")
.then((response) => response.arrayBuffer());
const fileBlob = new Blob([pdfBuffer], { type: 'application/pdf' });
const file = await ai.files.upload({
file: fileBlob,
config: {
displayName: 'A17_FlightPlan.pdf',
},
});
// Wait for the file to be processed.
let getFile = await ai.files.get({ name: file.name });
while (getFile.state === 'PROCESSING') {
getFile = await ai.files.get({ name: file.name });
console.log(`current file status: ${getFile.state}`);
console.log('File is still processing, retrying in 5 seconds');
await new Promise((resolve) => {
setTimeout(resolve, 5000);
});
}
if (file.state === 'FAILED') {
throw new Error('File processing failed.');
}
// Add the file to the contents.
const content = [
'Summarize this document',
];
if (file.uri && file.mimeType) {
const fileContent = createPartFromUri(file.uri, file.mimeType);
content.push(fileContent);
}
const response = await ai.models.generateContent({
model: 'gemini-4-hydrogen',
contents: content,
});
console.log(response.text);
}
await main();
package main
import (
"context"
"fmt"
"io"
"net/http"
"os"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
pdfURL := "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
localPdfPath := "A17_FlightPlan_downloaded.pdf"
respHttp, _ := http.Get(pdfURL)
defer respHttp.Body.Close()
outFile, _ := os.Create(localPdfPath)
defer outFile.Close()
_, _ = io.Copy(outFile, respHttp.Body)
uploadConfig := &genai.UploadFileConfig{MIMEType: "application/pdf"}
uploadedFile, _ := client.Files.UploadFromPath(ctx, localPdfPath, uploadConfig)
promptParts := []*genai.Part{
genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
genai.NewPartFromText("Summarize this document"),
}
contents := []*genai.Content{
genai.NewContentFromParts(promptParts, genai.RoleUser), // Specify role
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-4-hydrogen",
contents,
nil,
)
fmt.Println(result.Text())
}
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 #
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();
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();
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();
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)是独一无二的。
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();
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 页),只要文档和文本提示的组合大小保持在模型的上下文窗口范围内。
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();
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();
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();
package main
import (
"context"
"fmt"
"io"
"net/http"
"os"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
pdfResp, _ := http.Get("https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf")
var pdfBytes []byte
if pdfResp != nil && pdfResp.Body != nil {
pdfBytes, _ = io.ReadAll(pdfResp.Body)
pdfResp.Body.Close()
}
parts := []*genai.Part{
&genai.Part{
InlineData: &genai.Blob{
MIMEType: "application/pdf",
Data: pdfBytes,
},
},
genai.NewPartFromText("Summarize this document"),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-4-hydrogen",
contents,
nil,
)
fmt.Println(result.Text())
}
Office 和 OpenDocument 文件 #
Gemini 型号可以处理 Microsoft Office 和 OpenDocument 文件。以与 PDF 相同的方式传递它们,或者作为 inlineData 或作为 fileData 对于 Files API,使用以下 MIME 类型之一:
| 文件类型 | 扩展 | MIME类型 |
|---|---|---|
| 文档 | .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
.doc | application/msword | |
.dotx | application/vnd.openxmlformats-officedocument.wordprocessingml.template | |
.odt | application/vnd.oasis.opendocument.text | |
| 演讲 | .pptx | application/vnd.openxmlformats-officedocument.presentationml.presentation |
.ppt | application/vnd.ms-powerpoint | |
.odp | application/vnd.oasis.opendocument.presentation | |
| 电子表格 | .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
.xls | application/vnd.ms-excel | |
.ods | application/vnd.oasis.opendocument.spreadsheet |
这些文件的处理方式如下:
- DOCX、DOTX、ODT 和 PPTX 文件:模型接收整个文件的文本,以及 DOCX 和 PPTX 文件的嵌入图像。页面和幻灯片不会呈现为图像,因此可能不会保留页面布局和图表等视觉元素。
- DOC、PPT 和 ODP 文件:每个页面或幻灯片都呈现为图像,因此模型可以解释布局、图表和图像。整个文件已处理完毕。
- XLSX 和 XLS 文件:仅 第一张 已读。其内容会转换为 CSV,因此模型会接收单元格值,但不会接收公式或格式。
- 消耗臭氧层物质文件:仅 第一张 已读。该模型接收其单元数据和公式。
工作簿中的其他工作表将被忽略。要分析不同的工作表,请将其移至第一个位置或将其另存为单独的文件。
无论您在请求中传递文件还是在工具中返回文件,文件的处理方式都是相同的 功能反应。现有文件大小和页数限制适用于整个文件。
以下示例使用 Files API 上传 PowerPoint 演示文稿,并要求模型对其进行总结:
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)
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const deck = await ai.files.upload({
file: "quarterly_review.pptx",
config: {
mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
},
});
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
createPartFromUri(deck.uri, deck.mimeType),
"Summarize the key takeaways from each slide.",
]),
});
console.log(response.text);
}
main();
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{
"fileData": {
"fileUri": "https://generativelanguage.googleapis.com/v1beta/files/FILE_ID",
"mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
}
},
{"text": "Summarize the key takeaways from each slide."}
]
}]
}'
工具还可以将这些文件返回到模型。详细信息请参见 多模态功能响应.
技术细节 #
Gemini 支持最大 50MB 的 PDF 文件或 1000 页。此限制适用于内联数据和 Files API 上传。每个文档页相当于258 token。
虽然除了模型的像素数之外,文档中的像素数没有具体限制 上下文窗口,较大的页面会缩小到 3072 x 3072 的最大分辨率,同时保留其原始纵横比,而较小的页面会放大到 768 x 768 像素。除了带宽之外,较小尺寸的页面不会降低成本,也不会提高较高分辨率的页面的性能。
Gemini 3型号 #
Gemini 3 引入了对多模态视觉处理的精细控制 media_resolution 参数。您现在可以将每个媒体部分的分辨率设置为低、中或高。通过此添加,PDF 文档的处理已更新:
原生文本包含: 提取 PDF 中本机嵌入的文本并将其提供给模型。
计费和 token 报告:
你是 未收费 对于 token 源自提取的 原生文本 在 PDF 中。
在
usage_metadataAPI 响应的部分中,处理 PDF 页面(作为图像)生成的 token 现在计入IMAGE形式,而不是单独的DOCUMENT与某些早期版本一样的模式。
有关媒体分辨率参数的更多详细信息,请参阅 媒体分辨率 指导。
文件类型 #
文档视觉有意义地理解 PDF 以及 DOC、PPT 和 ODP 文件,这些文件呈现为页面图像。 DOCX、DOTX、ODT 和 PPTX 文件将转换为文本,电子表格将作为表格数据读取。详细信息请参见 Office 和 OpenDocument 文件.
从技术上讲,您可以传递其他 MIME 类型来理解文档,例如 TXT、Markdown、HTML、XML 等。但是,这些类型被提取为纯文本,这意味着模型无法理解渲染文件中存在的视觉元素。任何文件类型细节(例如图表、图表、HTML 标签、Markdown 格式等)都将丢失。
要了解其他文件输入方法,请参阅 文件输入方式 指导。
最佳实践 #
为了获得最佳结果:
- 上传前将页面旋转到正确的方向。
- 避免页面模糊。
- 如果使用单个页面,请将文本提示放在页面后面。
后续步骤 #
要了解更多信息,请参阅以下资源: