你可以在 Gemini 要求中加入文件 (PDF 和 TXT 檔案),執行需要瞭解所含文件內容的工作。本頁面說明如何使用 Google Cloud 控制台和 Vertex AI API,在 Vertex AI 中將 PDF 新增至 Gemini 的要求。
支援的模型
下表列出支援文件理解功能的模型:
| 型號 | 媒體詳細資料 | MIME 類型 |
|---|---|---|
| Gemini 3 Pro 預先發布版模型 |
|
|
| Gemini 3 Pro Image 預先發布版模型 |
|
|
| Gemini 2.5 Pro |
|
|
| Gemini 2.5 Flash 預先發布版模型 |
|
|
| Gemini 2.5 Flash-Lite 預先發布版模型 |
|
|
| Gemini 2.5 Flash Image |
|
|
| Gemini 2.5 Flash |
|
|
| Gemini 2.5 Flash-Lite |
|
|
| Gemini 2.0 Flash (可生成圖片) 預先發布模型 |
|
|
| Gemini 2.0 Flash |
|
|
| Gemini 2.0 Flash-Lite |
|
|
1:這是專案所有要求的文件輸入內容 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
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
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
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
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 檔案。- Cloud Storage 值區 URI:物件必須可公開讀取,或位於傳送要求的 Google Cloud 專案中。對於
MIME_TYPE:data或fileUri欄位中指定檔案的媒體類型。可接受的值包括:按一下即可展開 MIME 類型
application/pdfaudio/mpegaudio/mp3audio/wavimage/pngimage/jpegimage/webptext/plainvideo/movvideo/mpegvideo/mp4video/mpgvideo/avivideo/wmvvideo/mpegpsvideo/flv
TEXT: 要加入提示的文字指令。 例如:You are a very professional document summarization specialist. Please summarize the given document.
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 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
將要求主體儲存在名為 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 回應。
請注意這個範例網址中的以下項目:- 使用
generateContent方法,要求在完整生成回覆後再傳回。 如要減少人類觀眾對延遲的感受,請使用streamGenerateContent方法,在生成回覆的同時串流回覆內容。 - 多模態模型 ID 位於網址尾端,方法之前 (例如
gemini-2.0-flash)。這個範例也可能支援其他模型。
控制台
如要使用 Google Cloud 控制台傳送多模態提示,請按照下列步驟操作:在 Google Cloud 控制台的 Vertex AI 專區中,前往「Vertex AI Studio」頁面。
按一下「建立提示」。
選用步驟:設定模型和參數:
- 模型:選取模型。
選用步驟:如要設定進階參數,請按一下「進階」,然後按照下列步驟操作:
按一下即可展開進階設定
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 whenandtopPtopKare 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 of0means 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. If the model enters infinite generation, increasing the temperature to at least
0.1may lead to improved results.1.0is the recommended starting value for 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>
按一下「插入媒體」,然後選取檔案來源。
上傳
選取要上傳的檔案,然後按一下「開啟」。
使用網址上傳
輸入要使用的檔案網址,然後按一下「插入」。
Cloud Storage
選取值區,然後從值區中選取要匯入的檔案,並按一下「選取」。
Google 雲端硬碟
- 選擇帳戶,並在首次選取這個選項時,同意 Vertex AI Studio 存取您的帳戶。你可以上傳多個檔案,總大小上限為 10 MB。單一檔案不得超過 7 MB。
- 按一下要新增的檔案。
按一下「選取」。
檔案縮圖會顯示在「提示」窗格中。系統也會顯示權杖總數。如果提示資料超過符記上限,系統會截斷符記,且不會將其納入資料處理程序。
在「提示」窗格中輸入文字提示。
選用:如要查看「Token ID to text」(權杖 ID 對應文字) 和「Token IDs」(權杖 ID),請按一下「提示」窗格中的「權杖數量」。
按一下「提交」。
選用:如要將提示儲存至「我的提示」,請按一下 「儲存」。
選用:如要取得提示的 Python 程式碼或 curl 指令,請依序點選 「Build with code」(使用程式碼建構) >「Get code」(取得程式碼)。
設定選用模型參數
每個模型都有一組可供設定的選用參數。詳情請參閱內容生成參數。
文件權杖化
Gemini 3 Pro 的文件權杖化功能採用可變動的序列長度,取代先前模型使用的 Pan and Scan 方法,可提升品質並縮短延遲時間。
您可以為 PDF 輸入內容指定媒體解析度,這會影響文件的權杖化方式,以及每個文件使用的權杖數量。您可以設定 media_resolution,然後在 generationConfig 中套用至要求中的所有媒體,也可以為個別媒體部分設定,這會覆寫頂層設定。
Gemini 3 Pro 支援下列解析度:
MEDIA_RESOLUTION_HIGH:PDF 檔案為 1120 個權杖MEDIA_RESOLUTION_MEDIUM:PDF 檔案為 560 個權杖MEDIA_RESOLUTION_LOW:PDF 為 280 個權杖MEDIA_RESOLUTION_UNSPECIFIED:PDF 為 560 (預設)
這個程式碼範例示範如何調整 media_resolution:
from google import genai from google.genai import types client = genai.Client() response = client.models.generate_content( model="gemini-3-pro-preview", contents=[ types.Part( file_data=types.FileData( file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png", mime_type="image/jpeg", ), media_resolution=types.PartMediaResolution( level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH ), ), Part( file_data=types.FileData( file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4", mime_type="video/mp4", ), media_resolution=types.PartMediaResolution( level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW ), ), "When does the image appear in the video? What is the context?", ], ) print(response.text)
PDF 最佳做法
使用 PDF 時,請參考下列最佳做法和資訊,以獲得最佳結果:
- 如果提示包含單一 PDF,請在要求中將 PDF 放在文字提示之前。
- 如果文件很長,建議將其拆分成多個 PDF 檔案,再進行處理。
- 使用以文字形式呈現文字的 PDF,而非掃描圖片中的文字。這種格式可確保文字能以機器可讀取的形式呈現,因此與掃描的 PDF 圖片相比,模型更容易編輯、搜尋及處理文字。處理合約等文字量大的文件時,這項做法可提供最佳結果。
限制
雖然 Gemini 多模態模型在許多多模態應用情境中都非常強大,但請務必瞭解模型的限制:
- 空間推理:模型無法精確找出 PDF 中的文字或物件。他們可能只會傳回物件的概略計數。
- 準確度:模型在解讀 PDF 文件中的手寫文字時,可能會產生幻覺。
後續步驟
- 開始使用 Gemini 多模態模型建構內容 - 新客戶可獲得價值 $300 美元的免費抵免額 Google Cloud ,探索 Gemini 的功能。
- 瞭解如何傳送即時通訊提示要求。
- 瞭解負責任的 AI 最佳做法和 Vertex AI 的安全篩選器。