使用 generateContent
或 streamGenerateContent
透過 Gemini 生成內容。
Gemini 模型系列包含可處理多模態提示要求的多模態模型。「多模態」一詞表示您可以在提示中使用多種模態或輸入類型。非多模態模型只接受文字提示。包括文字、音訊、影片等。
建立 Google Cloud 帳戶即可開始使用
如要開始使用 Vertex AI 的 Gemini API,請建立帳戶 Google Cloud 。
建立帳戶後,請參閱這份文件,瞭解 Gemini 模型要求主體、模型參數、回應主體,以及一些要求範例。
準備就緒後,請參閱 Vertex AI 中的 Gemini API 快速入門導覽課程,瞭解如何使用程式設計語言 SDK 或 REST API,將要求傳送至 Vertex AI 中的 Gemini API。
支援的模型
所有 Gemini 模型都支援生成內容。
參數清單
如需實作詳情,請參閱範例。
要求主體
{ "cachedContent": string, "contents": [ { "role": string, "parts": [ { // Union field data can be only one of the following: "text": string, "inlineData": { "mimeType": string, "data": string }, "fileData": { "mimeType": string, "fileUri": string }, // End of list of possible types for union field data. "videoMetadata": { "startOffset": { "seconds": integer, "nanos": integer }, "endOffset": { "seconds": integer, "nanos": integer }, "fps": double } } ] } ], "systemInstruction": { "role": string, "parts": [ { "text": string } ] }, "tools": [ { "functionDeclarations": [ { "name": string, "description": string, "parameters": { object (OpenAPI Object Schema) } } ] } ], "safetySettings": [ { "category": enum (HarmCategory), "threshold": enum (HarmBlockThreshold) } ], "generationConfig": { "temperature": number, "topP": number, "topK": number, "candidateCount": integer, "maxOutputTokens": integer, "presencePenalty": float, "frequencyPenalty": float, "stopSequences": [ string ], "responseMimeType": string, "responseSchema": schema, "seed": integer, "responseLogprobs": boolean, "logprobs": integer, "audioTimestamp": boolean }, "labels": { string: string } }
要求主體包含下列參數的資料:
參數 | |
---|---|
| 選用:
用來做為脈絡的快取內容名稱,可提供預測結果。格式:
|
|
必要條件: 目前與模型對話的內容。 如果是單輪查詢,則為單一執行個體。如果是多輪查詢,這個重複欄位會包含對話記錄和最新要求。 |
|
自由參加: 適用於 指示模型,引導模型提升成效。例如:「請盡可能簡潔地回答」或「請勿在回覆中使用技術用語」。
系統會忽略 |
|
(選用步驟) 這段程式碼可讓系統與外部系統互動,在模型知識和範圍以外執行動作或一系列動作。請參閱函式呼叫。 |
|
(選用步驟) 請參閱函式呼叫。 |
|
自由參加: 根據要求封鎖不安全內容的設定。 違規處置日期: |
|
自由參加: 生成設定。 |
|
自由參加: 您可以鍵/值組合的形式,將中繼資料新增至 API 呼叫。 |
contents
包含郵件多部分內容的基本結構化資料類型。
這個類別包含兩個主要屬性:role
和 parts
。role
屬性表示內容的製作人,而 parts
屬性包含多個元素,每個元素代表訊息中的資料區隔。
參數 | |
---|---|
|
建立訊息的實體身分。支援的值如下:
在多輪對話中,系統會使用 |
|
組成單一郵件的排序部分清單。不同部分可能會有不同的 IANA MIME 類型。 如要瞭解輸入內容的限制 (例如詞元或圖片數量上限),請參閱「Google 模型」頁面的模型規格。 如要計算要求中的權杖數量,請參閱「取得權杖數量」。 |
parts
包含媒體的資料類型,是多部分 Content
訊息的一部分。
參數 | |
---|---|
|
自由參加: 文字提示或程式碼片段。 |
|
自由參加: 以原始位元組形式內嵌資料。 如果是 |
|
自由參加: 儲存在檔案中的資料。 |
|
選用: 其中包含代表 請參閱函式呼叫。 |
|
選用:
請參閱函式呼叫。 |
|
自由參加: 如果是影片輸入內容,則為影片的開始和結束偏移量 (Duration 格式),以及影片的影格速率。舉例來說,如要指定從 1:00 開始的 10 秒片段,且影格速率為每秒 10 個影格,請設定下列項目:
只有在影片資料以 |
blob
內容 Blob。請盡可能以文字而非原始位元組的形式傳送。
參數 | |
---|---|
|
data 或 fileUri 欄位中指定檔案的媒體類型。可接受的值包括:
按一下即可展開 MIME 類型
如果是 文字檔案必須採用 UTF-8 編碼。文字檔內容會計入權杖限制。 圖片解析度沒有限制。 |
|
圖片、PDF 或影片的 Base64 編碼,可內嵌在提示中。內嵌媒體時,您也必須指定資料的媒體類型 ( 大小限制:20 MB |
FileData
URI 或網址資料。
參數 | |
---|---|
|
資料的 IANA MIME 類型。 |
|
要加入提示的檔案 URI 或網址。可接受的值包括:
指定 |
functionCall
模型傳回的預測 functionCall
,其中包含代表 functionDeclaration.name
的字串,以及包含參數及其值的結構化 JSON 物件。
參數 | |
---|---|
|
要呼叫的函式名稱。 |
|
JSON 物件格式的函式參數和值。 如需參數詳細資料,請參閱「函式呼叫」。 |
functionResponse
FunctionCall
的輸出結果會包含代表 FunctionDeclaration.name
的字串。也包含結構化 JSON 物件,內含函式的輸出內容 (並將其做為模型的背景資訊)。其中應包含根據模型預測結果建立的 FunctionCall
。
參數 | |
---|---|
|
要呼叫的函式名稱。 |
|
JSON 物件格式的函式回應。 |
videoMetadata
說明輸入影片內容的中繼資料。
參數 | |
---|---|
|
自由參加: 影片的開始偏移。 |
|
自由參加: 影片的結束時間偏移。 |
|
自由參加:
傳送至模型的影片畫面更新率。如果未指定,預設值為 |
safetySetting
安全性設定。
參數 | |
---|---|
|
自由參加:
要設定門檻的安全類別。可接受的值包括:
按一下即可展開安全類別
|
|
自由參加: 根據機率封鎖可能屬於指定安全類別的回應時,所使用的門檻。
|
|
自由參加: 指定門檻是用於機率還是嚴重程度分數。如未指定,系統會使用機率分數的門檻。 |
harmCategory
會封鎖內容的危害類別。
參數 | |
---|---|
|
未指定危害類別。 |
|
有害類別為仇恨言論。 |
|
危害類別為危險內容。 |
|
有害類別為騷擾。 |
|
危害類別為情色露骨內容。 |
harmBlockThreshold
用來封鎖回應的機率門檻層級。
參數 | |
---|---|
|
未指定危害封鎖門檻。 |
|
封鎖有害機率低等以上的內容 (即封鎖更多內容)。 |
|
封鎖有害機率中等以上的內容。 |
|
僅封鎖有害機率高的內容 (即減少封鎖)。 |
|
不封鎖任何內容。 |
|
如果所有類別都關閉,系統就會關閉安全模式 |
harmBlockMethod
系統會根據機率和嚴重程度的組合,封鎖超過機率門檻的回覆。
參數 | |
---|---|
|
未指定危害封鎖方法。 |
|
損害封鎖方法會同時使用機率和嚴重性分數。 |
|
危害封鎖方法會使用機率分數。 |
generationConfig
生成提示時使用的設定。
參數 | |
---|---|
|
自由參加:
系統會在生成回覆時使用溫度進行取樣,也就是套用 如果模型的回覆太普通、太短或提供了備用回覆,再試試看調高 Temperature。
詳情請參閱內容生成參數。 |
|
自由參加: 如果指定,系統會使用核心取樣。 Top-P 會影響模型選取輸出符記的方式。模型會按照機率最高 (請見「Top-K」) 到最低的順序選取符記,直到所選符記的機率總和等於「Top-P」值。舉例來說,假設詞元 A、B 和 C 的可能性分別為 0.3、0.2 和 0.1,而「Top-P」值為 如要取得較不隨機的回覆,請指定較低的值;如要取得較隨機的回覆,請調高此值。
|
|
自由參加: 要傳回的回應變體數量。每次提出要求時,系統會針對所有候選答案的輸出權杖收費,但只會針對輸入權杖收費一次。 指定多個候選人是預先發布功能,適用於
|
|
選用:int 回覆內可以生成的權杖數量上限。一個詞元約為四個字元。100 個符記約等於 60 到 80 個字。 如要取得較短的回覆,請指定較低的值;如要取得可能較長的回覆,請調高此值。 詳情請參閱內容生成參數。 |
|
自由參加:
指定字串清單,如果模型在回覆中遇到其中一個字串,就會停止生成文字。如果字串在回應中出現多次,系統會在第一次遇到該字串時截斷回應。字串須區分大小寫。
清單最多可有 5 個項目。 詳情請參閱內容生成參數。 |
|
自由參加: 正向處置。 正值會懲罰已出現在生成文字中的符記,提高生成更多元內容的機率。
|
|
自由參加: 正值會懲罰在生成的文字中重複出現的符記,降低重複內容的機率。
|
|
自由參加: 生成候選文字的輸出回應 MIME 類型。 支援的 MIME 類型如下:
請指定適當的回覆類型,避免發生非預期的行為。舉例來說,如果您需要 JSON 格式的回應,請指定 text/plain 不支援與 responseSchema 搭配使用。 |
|
選用:結構定義 生成候選文字時必須遵循的結構定義。詳情請參閱「控管生成的輸出內容」。 如要使用這個參數,您必須為 |
|
自由參加: 如果將種子固定為特定值,模型會盡可能為重複要求提供相同的回覆。我們不保證輸出內容具有確定性。 此外,即使使用相同的種子值,如果變更模型或參數設定 (例如溫度),回覆還是有可能不同。根據預設,系統會使用隨機種子值。 |
|
自由參加: 如果為 true,則傳回模型在每個步驟中選擇的權杖對數機率。這項參數預設為 |
|
自由參加:
在每個生成步驟中,傳回最有可能的候選符記的記錄機率。模型選取的符記可能與每個步驟中的最佳候選符記不同。請使用 您必須啟用 |
|
自由參加: 適用於下列機型:
可瞭解純音訊檔案的時間戳記。 這是預先發布版功能。 |
回應主體
{ "candidates": [ { "content": { "parts": [ { "text": string } ] }, "finishReason": enum (FinishReason), "safetyRatings": [ { "category": enum (HarmCategory), "probability": enum (HarmProbability), "blocked": boolean } ], "citationMetadata": { "citations": [ { "startIndex": integer, "endIndex": integer, "uri": string, "title": string, "license": string, "publicationDate": { "year": integer, "month": integer, "day": integer } } ] }, "avgLogprobs": double, "logprobsResult": { "topCandidates": [ { "candidates": [ { "token": string, "logProbability": float } ] } ], "chosenCandidates": [ { "token": string, "logProbability": float } ] } } ], "usageMetadata": { "promptTokenCount": integer, "candidatesTokenCount": integer, "totalTokenCount": integer }, "modelVersion": string }
回應元素 | 說明 |
---|---|
modelVersion |
用於生成內容的模型和版本。例如:
gemini-2.0-flash-lite-001 。 |
text |
生成的文字。 |
finishReason |
模型停止生成權杖的原因。如果為空白,表示模型尚未停止產生權杖。由於回覆會使用提示做為脈絡,因此無法變更模型停止生成符記的行為。
|
category |
要設定門檻的安全類別。可接受的值包括:
按一下即可展開安全類別
|
probability |
內容中的危害機率等級。
|
blocked |
與安全屬性相關聯的布林值標記,指出模型的輸入或輸出內容是否遭到封鎖。 |
startIndex |
整數,指定 content 中引文的起始位置。startIndex 以位元組為單位,是根據以 UTF-8 編碼的回應計算而得。 |
endIndex |
整數,指定 content 中引文的結尾位置。endIndex 以位元組為單位,是根據以 UTF-8 編碼的回應計算而得。 |
url |
引用來源的網址。網址來源的例子包括新聞網站或 GitHub 存放區。 |
title |
引用來源的標題。例如新聞報導或書籍的標題。 |
license |
與引文相關聯的授權。 |
publicationDate |
引用內容的發布日期。有效格式為 YYYY 、YYYY-MM 和 YYYY-MM-DD 。 |
avgLogprobs |
候選人的平均記錄機率。 |
logprobsResult |
在每個步驟中,傳回候選符記 (topCandidates ) 和實際選取的符記 (chosenCandidates )。 |
token |
生成式 AI 模型會將文字資料拆解成詞元,以便處理,詞元可以是字元、字詞或詞句。 |
logProbability |
對數機率值,表示模型對特定權杖的信心。 |
promptTokenCount |
要求中的權杖數量。 |
candidatesTokenCount |
回應中的權杖數量。 |
totalTokenCount |
要求和回覆中的權杖數量。 |
範例
文字生成
根據文字輸入生成文字回覆。
Python 適用的 Gen AI SDK
Python (OpenAI)
您可以使用 OpenAI 程式庫呼叫 Inference API。詳情請參閱「 使用 OpenAI 程式庫呼叫 Vertex AI 模型」。
Go
使用多模態提示
從多模態輸入內容 (例如文字和圖片) 生成文字回覆。
Python 適用的 Gen AI SDK
Python (OpenAI)
您可以使用 OpenAI 程式庫呼叫 Inference API。詳情請參閱「 使用 OpenAI 程式庫呼叫 Vertex AI 模型」。
Go
串流文字回覆
根據文字輸入內容生成串流模型回應。
Python 適用的 Gen AI SDK
Python (OpenAI)
您可以使用 OpenAI 程式庫呼叫 Inference API。詳情請參閱「 使用 OpenAI 程式庫呼叫 Vertex AI 模型」。
Go
模型版本
如要使用自動更新版本,請指定模型名稱,但不要加上尾端的版本號碼,例如 gemini-2.0-flash
而不是 gemini-2.0-flash-001
。
詳情請參閱「Gemini 模型版本和生命週期」。
後續步驟
- 進一步瞭解 Vertex AI 的 Gemini API。
- 進一步瞭解函式呼叫。
- 進一步瞭解為 Gemini 模型的回覆內容設定基準。