文件解讀

如要查看文件理解的範例，請在下列其中一個環境中執行「Document Processing with Gemini」筆記本：

在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Vertex AI Workbench 中開啟 | 在 GitHub 上查看

你可以在 Gemini 要求中加入文件 (PDF 和 TXT 檔案)，執行需要瞭解所含文件內容的工作。本頁面說明如何使用 Google Cloud 控制台和 Vertex AI API，在 Vertex AI 中將 PDF 新增至 Gemini 的要求。

支援的模型

下表列出支援文件理解功能的模型：

型號	媒體詳細資料	MIME 類型
Gemini 2.5 Flash (預先發布版)	每個提示的檔案數量上限： 3,000 個 每個檔案的頁數上限： 1,000 透過 API 或 Cloud Storage 匯入時，每個檔案的大小上限： 50 MB 透過控制台直接上傳的檔案大小上限： 7 MB	application/pdf text/plain
Gemini 2.5 Flash-Lite (預先發布版)	每個提示的檔案數量上限： 3,000 個 每個檔案的頁數上限： 1,000 每個檔案的大小上限： 50 MB	application/pdf text/plain
Gemini 2.5 Flash Image	每個提示的檔案數量上限： 3 每個檔案的頁數上限： 3 每個檔案的大小上限： 50 MB (透過 API 和 Cloud Storage 匯入) 或 7 MB (透過 Google Cloud 控制台直接上傳)	application/pdf text/plain
Gemini 2.5 Flash-Lite	每個提示的檔案數量上限： 3,000 個 每個檔案的頁數上限： 1,000 每個檔案的大小上限： 50 MB	application/pdf text/plain
Gemini 2.0 Flash (可生成圖片) (預先發布版)	每個提示的檔案數量上限： 3,000 個 每個檔案的頁數上限： 1,000 每個檔案的大小上限： 50 MB	application/pdf text/plain
Gemini 2.5 Pro	每個提示的檔案數量上限： 3,000 個 每個檔案的頁數上限： 1,000 透過 API 或 Cloud Storage 匯入時，每個檔案的大小上限： 50 MB 透過控制台直接上傳的檔案大小上限： 7 MB	application/pdf text/plain
Gemini 2.5 Flash	每個提示的檔案數量上限： 3,000 個 每個檔案的頁數上限： 1,000 透過 API 或 Cloud Storage 匯入時，每個檔案的大小上限： 50 MB 透過控制台直接上傳的檔案大小上限： 7 MB	application/pdf text/plain
Gemini 2.0 Flash	每個提示的檔案數量上限： 3,000 個 每個檔案的頁數上限： 1,000 透過 API 或 Cloud Storage 匯入時，每個檔案的大小上限： 50 MB 透過控制台直接上傳的檔案大小上限： 7 MB 每個專案每分鐘最多可使用的權杖數 (TPM)1： 美國/亞洲： 340 萬 歐盟： 340 萬	application/pdf text/plain
Gemini 2.0 Flash-Lite	每個提示的檔案數量上限： 3,000 個 每個檔案的頁數上限： 1,000 透過 API 或 Cloud Storage 匯入時，每個檔案的大小上限： 50 MB 透過控制台直接上傳的檔案大小上限： 7 MB 每個專案每分鐘最多可使用的權杖數 (TPM)1： 美國/亞洲： 340 萬 歐盟： 340 萬

¹：這是專案所有要求的文件輸入內容中，最高的 TPM。其他模式也請使用最大 TPM。

配額指標為 generate_content_document_input_per_base_model_id_and_resolution。

如需 Gemini 模型支援的語言清單，請參閱Google 模型的資訊。如要進一步瞭解如何設計多模態提示，請參閱「設計多模態提示」。如要直接從行動和網頁應用程式使用 Gemini，請參閱 Firebase AI Logic 用戶端 SDK，瞭解如何用於 Swift、Android、網頁、Flutter 和 Unity 應用程式。

在要求中新增文件

下列程式碼範例顯示如何在提示要求中加入 PDF。這個 PDF 範例適用於所有 Gemini 多模態模型。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.5-flash"

prompt = """
You are a highly skilled document summarization specialist.
Your task is to provide a concise executive summary of no more than 300 words.
Please summarize the given document for a general audience.
"""

pdf_file = Part.from_uri(
    file_uri="gs://cloud-samples-data/generative-ai/pdf/1706.03762v7.pdf",
    mime_type="application/pdf",
)

response = client.models.generate_content(
    model=model_id,
    contents=[pdf_file, prompt],
)

print(response.text)
# Example response:
# Here is a summary of the document in 300 words.
#
# The paper introduces the Transformer, a novel neural network architecture for
# sequence transduction tasks like machine translation. Unlike existing models that rely on recurrent or
# convolutional layers, the Transformer is based entirely on attention mechanisms.
# ...

Go

瞭解如何安裝或更新 Go。

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/genai"
)

// generateTextWithPDF shows how to generate text using a PDF file input.
func generateTextWithPDF(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: `You are a highly skilled document summarization specialist.
	Your task is to provide a concise executive summary of no more than 300 words.
	Please summarize the given document for a general audience.`},
			{FileData: &genai.FileData{
				FileURI:  "gs://cloud-samples-data/generative-ai/pdf/1706.03762v7.pdf",
				MIMEType: "application/pdf",
			}},
		},
			Role: "user"},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// "Attention Is All You Need" introduces the Transformer,
	// a groundbreaking neural network architecture designed for...
	// ...

	return nil
}

Java

瞭解如何安裝或更新 Java。

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Part;

public class TextGenerationWithPdf {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text with PDF file input
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      String prompt =
          "You are a highly skilled document summarization specialist.\n"
              + " Your task is to provide a concise executive summary of no more than 300 words.\n"
              + " Please summarize the given document for a general audience";

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              Content.fromParts(
                  Part.fromUri(
                      "gs://cloud-samples-data/generative-ai/pdf/1706.03762v7.pdf",
                      "application/pdf"),
                  Part.fromText(prompt)),
              null);

      System.out.print(response.text());
      // Example response:
      // The document introduces the Transformer, a novel neural network architecture designed for
      // sequence transduction tasks, such as machine translation. Unlike previous dominant models
      // that rely on complex recurrent or convolutional neural networks, the Transformer proposes a
      // simpler, more parallelizable design based *solely* on attention mechanisms, entirely
      // dispensing with recurrence and convolutions...

      return response.text();
    }
  }
}

Node.js

安裝

npm install @google/genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateText(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const prompt = `You are a highly skilled document summarization specialist.
    Your task is to provide a concise executive summary of no more than 300 words.
    Please summarize the given document for a general audience.`;

  const pdfFile = {
    fileData: {
      fileUri: 'gs://cloud-samples-data/generative-ai/pdf/1706.03762v7.pdf',
      mimeType: 'application/pdf',
    },
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: [pdfFile, prompt],
  });

  console.log(response.text);

  // Example response:
  //  Here is a summary of the document in 300 words.
  //  The paper introduces the Transformer, a novel neural network architecture for
  //  sequence transduction tasks like machine translation. Unlike existing models that rely on recurrent or
  //  convolutional layers, the Transformer is based entirely on attention mechanisms.
  //  ...

  return response.text;
}

REST

設定環境後，即可使用 REST 測試文字提示。下列範例會將要求傳送至發布商模型端點。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：您的專案 ID。
• FILE_URI： 要納入提示的檔案 URI 或網址。可接受的值包括：
  • Cloud Storage 值區 URI：物件必須可公開讀取，或位於傳送要求的 Google Cloud 專案中。對於 gemini-2.0-flash 和 gemini-2.0-flash-lite，大小上限為 2 GB。
  • HTTP 網址：檔案網址必須可公開讀取。每項要求可指定一個影片檔案、一個音訊檔案，以及最多 10 個圖片檔案。音訊檔、影片檔和文件不得超過 15 MB。
  • YouTube 影片網址：YouTube 影片必須由您用來登入 Google Cloud 控制台的帳戶擁有，或是設為公開。每個要求僅支援一個 YouTube 影片網址。

  指定 fileURI 時，您也必須指定檔案的媒體類型 (mimeType)。如果啟用 VPC Service Controls，系統不支援為 fileURI 指定媒體檔案網址。

  如果 Cloud Storage 中沒有 PDF 檔案，可以使用下列公開檔案： gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf，MIME 類型為 application/pdf。如要查看這份 PDF，請開啟範例 PDF 檔案。

• MIME_TYPE： data 或 fileUri 欄位中指定檔案的媒體類型。可接受的值包括：

  按一下即可展開 MIME 類型

  • application/pdf
  • audio/mpeg
  • audio/mp3
  • audio/wav
  • image/png
  • image/jpeg
  • image/webp
  • text/plain
  • video/mov
  • video/mpeg
  • video/mp4
  • video/mpg
  • video/avi
  • video/wmv
  • video/mpegps
  • video/flv
• TEXT： 提示中要加入的文字指令。 例如： You are a very professional document summarization specialist. Please summarize the given document.

如要傳送要求，請選擇以下其中一個選項：

curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

接著，請執行下列指令來傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.0-flash:generateContent"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.0-flash:generateContent" | Select-Object -Expand Content

您應該會收到類似如下的 JSON 回應。

回應

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "This report presents Gemini 2.0 Pro.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.13273923,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.08819004
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.1046602,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.0996453
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.15987214,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.098946586
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.056966383,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.075721376
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 19882,
    "candidatesTokenCount": 336,
    "totalTokenCount": 20218
  }
}

請注意這個範例網址中的以下部分：

• 使用 generateContent 方法，要求在完整生成回覆後傳回。如要減少人類觀眾的延遲感，請使用 streamGenerateContent 方法，在生成回覆的同時串流回覆內容。
• 多模態模型 ID 位於網址尾端，方法之前 (例如 gemini-2.0-flash)。這個範例也可能支援其他模型。

控制台

如要使用 Google Cloud 控制台傳送多模態提示，請按照下列步驟操作：

1. 在 Google Cloud 控制台的 Vertex AI 專區中，前往「Vertex AI Studio」頁面。

   前往 Vertex AI Studio

2. 按一下「建立提示」。

3. 選用步驟：設定模型和參數：

   • 模型：選取模型。

4. 選用步驟：如要設定進階參數，請按一下「進階」，然後按照下列方式設定：

   按一下即可展開進階設定

   • Top-K：使用滑桿或文字方塊輸入 Top-K 的值。

     「Top-K」會影響模型選取輸出符記的方式。如果 Top-K 設為 1，代表下一個所選詞元是模型詞彙表的所有詞元中可能性最高者 (也稱為「貪婪解碼」)。如果 Top-K 設為 3，則代表模型會依據 temperature，從可能性最高的 3 個詞元中選取下一個詞元。

     在每個符記選取步驟中，模型會對機率最高的「Top-K」符記取樣，接著進一步根據「Top-P」篩選詞元，最後依 temperature 選出最終詞元。

     如要取得較不隨機的回覆，請指定較低的值；如要取得較隨機的回覆，請調高此值。

   • Top-P：使用滑桿或文字方塊輸入 Top-P 的值。 模型會按照可能性最高到最低的順序選取符記，直到所選符記的可能性總和等於 Top-P 值。如要讓結果的變化性降到最低，請將 Top-P 設為 0。
   • 最多回應數：使用滑桿或文字方塊輸入要生成的回應數值。
   • 串流回應：啟用後，系統會在生成回應時顯示回應。
   • 安全篩選器門檻：選取門檻，調整看見可能有害回應的機率。
   • 啟用基礎：多模態提示不支援基礎功能。
   • 區域：選取要使用的區域。
   • 溫度：使用滑桿或文字方塊輸入溫度值。

         
     The temperature is used for sampling during response generation, which occurs when topP
     and topK are applied. Temperature controls the degree of randomness in token selection.
     Lower temperatures are good for prompts that require a less open-ended or creative response, while
     higher temperatures can lead to more diverse or creative results. A temperature of 0
     means that the highest probability tokens are always selected. In this case, responses for a given
     prompt are mostly deterministic, but a small amount of variation is still possible.
     
     If the model returns a response that's too generic, too short, or the model gives a fallback
     response, try increasing the temperature.
     </li>
       <li>**Output token limit**: Use the slider or textbox to enter a value for
         the max output limit.
     
         
     Maximum number of tokens that can be generated in the response. A token is
     approximately four characters. 100 tokens correspond to roughly 60-80 words.
     
     Specify a lower value for shorter responses and a higher value for potentially longer
     responses.
     </li>
       <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a
         series of characters that includes spaces. If the model encounters a
         stop sequence, the response generation stops. The stop sequence isn't
         included in the response, and you can add up to five stop sequences.</li>
     </ul>
     

5. 按一下「插入媒體」，然後選取檔案來源。

   上傳

   選取要上傳的檔案，然後按一下「開啟」。

   使用網址上傳

   輸入要使用的檔案網址，然後按一下「插入」。

   Cloud Storage

   選取值區，然後從值區中選取要匯入的檔案，並按一下「選取」。

   Google 雲端硬碟

   1. 選擇帳戶，並在首次選取這個選項時，授權 Vertex AI Studio 存取您的帳戶。你可以上傳多個檔案，總大小上限為 10 MB。單一檔案不得超過 7 MB。
   2. 按一下要新增的檔案。

   3. 按一下「選取」。

      檔案縮圖會顯示在「提示」窗格中。系統也會顯示權杖總數。如果提示資料超過符記上限，系統會截斷符記，且不會將其納入資料處理程序。

6. 在「提示」窗格中輸入文字提示。

7. 選用：如要查看「權杖 ID 對應的文字」和「權杖 ID」，請按一下「提示」窗格中的「權杖數量」。

   注意： 系統不支援媒體權杖。

8. 按一下「提交」。

9. 選用：如要將提示詞儲存至「我的提示詞」，請按一下 「儲存」。

10. 選用：如要取得提示的 Python 程式碼或 curl 指令，請依序點選 「Build with code」(使用程式碼建構) >「Get code」(取得程式碼)。

設定選用模型參數

每個模型都有一組可供設定的選用參數。詳情請參閱內容生成參數。

文件權杖化

PDF 代碼化

PDF 會視為圖片，因此系統會以處理圖片的方式，為 PDF 的每個頁面建立權杖。

此外，PDF 的費用也適用 Gemini 圖片定價。舉例來說，如果您在 Gemini API 呼叫中加入兩頁的 PDF，系統會將其視為兩張圖片，並收取輸入費用。

PDF 最佳做法

使用 PDF 時，請參考下列最佳做法和資訊，以獲得最佳結果：

• 如果提示包含單一 PDF，請在要求中將 PDF 放在文字提示之前。
• 如果文件很長，建議將其拆成多個 PDF 檔案，再進行處理。
• 使用以文字形式呈現文字的 PDF，而非掃描圖片中的文字。這種格式可確保文字能以機器可讀取的形式呈現，因此與掃描的 PDF 圖片相比，模型更容易編輯、搜尋及處理文字。處理合約等文字量大的文件時，這項做法可提供最佳結果。

限制

雖然 Gemini 多模態模型在許多多模態應用情境中都非常強大，但請務必瞭解模型的限制：

• 空間推理：模型無法精確找出 PDF 中的文字或物件。他們可能只會傳回物件的概略計數。
• 準確度：模型在解讀 PDF 文件中的手寫文字時，可能會產生幻覺。

後續步驟

• 開始使用 Gemini 多模態模型建構內容 - 新客戶可獲得價值 $300 美元的免費抵免額 Google Cloud ，探索 Gemini 的功能。
• 瞭解如何傳送即時通訊提示要求。
• 瞭解負責任的 AI 最佳做法和 Vertex AI 的安全篩選器。