方法:model.generateContent
透過指定輸入 GenerateContentRequest
從模型產生回應。
端點
則貼文
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:generateContent
。
路徑參數
model
string
必要欄位。用於產生完成項目的 Model
名稱。
格式:name=models/{model}
。格式為 models/{model}
。
要求主體
要求主體的資料會採用以下結構:
contents[]
object (Content
)
必要欄位。目前與模型對話的內容。
如果是單輪查詢,這只是單一例項。如為多輪查詢,則這指的是包含對話記錄和最新要求的重複欄位。
tools[]
object (Tool
)
選用設定。模型可以用來產生下一次回應的 Tools
清單。
Tool
是一段程式碼,可讓系統與外部系統互動,在模型知識和範圍外,執行操作或一組動作。目前唯一支援的工具是 Function
。
toolConfig
object (ToolConfig
)
選用設定。要求中指定任何 Tool
的工具設定。
safetySettings[]
object (SafetySetting
)
選用設定。用於封鎖不安全內容的不重複 SafetySetting
執行個體清單。
這將在 GenerateContentRequest.contents
和 GenerateContentResponse.candidates
強制執行。每個 SafetyCategory
類型只能有一項設定。如果內容和回應未達到這些設定所設門檻,API 就會封鎖相關內容。這份清單會覆寫 safetySettings 中所指定的各項 SafetyCategory
預設設定。如果清單中的指定 SafetyCategory
沒有任何 SafetySetting
,API 會使用該類別的預設安全性設定。支援有害類別 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT。
systemInstruction
object (Content
)
選用設定。開發人員設定系統操作說明。目前僅支援文字。
generationConfig
object (GenerationConfig
)
選用設定。模型產生和輸出的設定選項。
cachedContent
string
選用設定。為提供預測而使用的快取內容名稱。注意:僅適用於明確快取,使用者能控制快取內容 (例如要快取的內容),同時保證能節省成本。格式:cachedContents/{cachedContent}
要求範例
文字
Python
Node.js
Kotlin
Swift
Dart
Java
圖片
Python
Node.js
Kotlin
Swift
Dart
Java
音訊
Python
Node.js
影片
Python
Node.js
即時通訊
Python
Node.js
貝殼
Kotlin
Swift
Dart
Java
快取
Python
Node.js
調整後模型
Python
JSON 模式
Python
Node.js
Kotlin
Swift
Dart
Java
程式碼執行
Python
Kotlin
Java
函式呼叫
Python
Node.js
Kotlin
Swift
Dart
Java
產生設定
Python
Node.js
貝殼
Kotlin
Swift
Dart
Java
安全性設定
Python
Node.js
貝殼
Kotlin
Swift
Dart
Java
系統操作說明
Python
Node.js
Kotlin
Swift
Dart
Java
回應主體
如果成功,回應主體會包含 GenerateContentResponse
的執行例項。
方法:model.streamGenerateContent
根據輸入的 GenerateContentRequest
從模型產生串流回應。
端點
則貼文
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:streamGenerateContent
。
路徑參數
model
string
必要欄位。用於產生完成項目的 Model
名稱。
格式:name=models/{model}
。格式為 models/{model}
。
要求主體
要求主體的資料會採用以下結構:
contents[]
object (Content
)
必要欄位。目前與模型對話的內容。
如果是單輪查詢,這只是單一例項。如為多輪查詢,則這指的是包含對話記錄和最新要求的重複欄位。
tools[]
object (Tool
)
選用設定。模型可以用來產生下一次回應的 Tools
清單。
Tool
是一段程式碼,可讓系統與外部系統互動,在模型知識和範圍外,執行操作或一組動作。目前唯一支援的工具是 Function
。
toolConfig
object (ToolConfig
)
選用設定。要求中指定任何 Tool
的工具設定。
safetySettings[]
object (SafetySetting
)
選用設定。用於封鎖不安全內容的不重複 SafetySetting
執行個體清單。
這將在 GenerateContentRequest.contents
和 GenerateContentResponse.candidates
強制執行。每個 SafetyCategory
類型只能有一項設定。如果內容和回應未達到這些設定所設門檻,API 就會封鎖相關內容。這份清單會覆寫 safetySettings 中所指定的各項 SafetyCategory
預設設定。如果清單中的指定 SafetyCategory
沒有任何 SafetySetting
,API 會使用該類別的預設安全性設定。支援有害類別 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT。
systemInstruction
object (Content
)
選用設定。開發人員設定系統操作說明。目前僅支援文字。
generationConfig
object (GenerationConfig
)
選用設定。模型產生和輸出的設定選項。
cachedContent
string
選用設定。為提供預測而使用的快取內容名稱。注意:僅適用於明確快取,使用者能控制快取內容 (例如要快取的內容),同時保證能節省成本。格式:cachedContents/{cachedContent}
要求範例
文字
Python
Node.js
Kotlin
Swift
Dart
Java
圖片
Python
Node.js
Kotlin
Swift
Dart
Java
影片
Python
Node.js
Kotlin
Java
即時通訊
Python
Node.js
貝殼
Kotlin
Swift
Dart
Java
回應主體
如果成功,回應主體會包含 GenerateContentResponse
執行個體的串流。
GenerateContentResponse
支援多個候選項目的模型回應。
安全評分和內容篩選功能的注意事項。系統會在 GenerateContentResponse.prompt_feedback
中針對每位候選人回報提示,而 finishReason
和 safetyRatings
也會為每位候選人回報。API 合約代表:系統會傳回所有要求的候選對象,或是完全不傳回候選人,只有在提示出現錯誤時,才會傳回任何候選人 (請參閱 promptFeedback
)。透過 finishReason
和 safetyRatings
回報每位候選人的意見回饋。
JSON 表示法 |
---|
{ "candidates": [ { object ( |
candidates[]
object (Candidate
)
模型中的候選回應。
promptFeedback
object (PromptFeedback
)
傳回與內容篩選器相關的提示意見回饋。
usageMetadata
object (UsageMetadata
)
僅供輸出。產生要求的中繼資料權杖的使用情形
PromptFeedback
GenerateContentRequest.content
中指定提示的一組意見回饋中繼資料。
JSON 表示法 |
---|
{ "blockReason": enum ( |
blockReason
enum (BlockReason
)
選用設定。如果已設定,系統會封鎖提示,且不會傳回任何候選文字。請修改提示。
safetyRatings[]
object (SafetyRating
)
用於確保提示安全性的評分。每個類別最多有一個評分。
BlockReason
說明封鎖提示的原因。
列舉 | |
---|---|
BLOCK_REASON_UNSPECIFIED |
預設值。這個值未使用。 |
SAFETY |
基於安全考量,提示遭到封鎖。您可以查看「safetyRatings 」以瞭解哪個安全性類別遭到封鎖。 |
OTHER |
提示因不明原因而遭到封鎖。 |
UsageMetadata
產生要求權杖用量的中繼資料。
JSON 表示法 |
---|
{ "promptTokenCount": integer, "cachedContentTokenCount": integer, "candidatesTokenCount": integer, "totalTokenCount": integer } |
promptTokenCount
integer
提示中的權杖數量。設定快取 Content 後,這仍是有效的提示總大小。例如:這包括快取內容中的符記數量。
cachedContentTokenCount
integer
提示中快取部分 (例如快取內容) 中的權杖數量。
candidatesTokenCount
integer
所有已產生的候選項目權杖總數。
totalTokenCount
integer
產生要求的符記總數 (提示 + 候選)。
候選人
- JSON 表示法
- FinishReason
- GroundingAttribution
- AttributionSourceId
- GroundingPassageId
- SemanticRetrieverChunk
模型產生的回應候選項目。
JSON 表示法 |
---|
{ "content": { object ( |
content
object (Content
)
僅供輸出。模型傳回的內容。
finishReason
enum (FinishReason
)
選用設定。僅供輸出。模型停止產生權杖的原因。
如果留空,模型就不會停止產生權杖。
safetyRatings[]
object (SafetyRating
)
回覆候選者安全性的評分清單。
每個類別最多有一個評分。
citationMetadata
object (CitationMetadata
)
僅供輸出。模型產生的候選項目引用資訊。
這個欄位可能會填入 content
中任何文字的引用資訊。這些是「被引用」的段落擷取及儲存大量著作權內容
tokenCount
integer
僅供輸出。這個候選項目的符記數量。
groundingAttributions[]
object (GroundingAttribution
)
僅供輸出。產生基準答案的來源適用的作者資訊。
系統會為 GenerateAnswer
呼叫填入這個欄位。
index
integer
僅供輸出。候選人清單中的候選人索引。
FinishReason
定義模型停止產生權杖的原因。
列舉 | |
---|---|
FINISH_REASON_UNSPECIFIED |
預設值。這個值未使用。 |
STOP |
模型或提供的停靠序列的自然停靠點。 |
MAX_TOKENS |
已達要求中指定的權杖數量上限。 |
SAFETY |
該候選人內容已基於安全理由遭到檢舉。 |
RECITATION |
該候選人內容因轉介原因而遭到檢舉。 |
LANGUAGE |
候選內容遭檢舉使用不支援的語言。 |
OTHER |
不明原因。 |
GroundingAttribution
資訊來源的作者資訊。
JSON 表示法 |
---|
{ "sourceId": { object ( |
sourceId
object (AttributionSourceId
)
僅供輸出。歸因來源的 ID。
content
object (Content
)
構成歸因的來源內容依據。
AttributionSourceId
歸因來源的 ID。
JSON 表示法 |
---|
{ // Union field |
聯集欄位 source
。
source
只能採用下列其中一種設定:
groundingPassage
object (GroundingPassageId
)
內嵌段落的 ID。
semanticRetrieverChunk
object (SemanticRetrieverChunk
)
透過語意擷取工具擷取的 Chunk
ID。
GroundingPassageId
GroundingPassage
內特定部分的 ID。
JSON 表示法 |
---|
{ "passageId": string, "partIndex": integer } |
passageId
string
僅供輸出。與 GenerateAnswerRequest
的 GroundingPassage.id
相符的段落 ID。
partIndex
integer
僅供輸出。GenerateAnswerRequest
的 GroundingPassage.content
中部分的索引。
SemanticRetrieverChunk
使用 SemanticRetrieverConfig
在 GenerateAnswerRequest
中指定的語意擷取工具擷取的 Chunk
ID。
JSON 表示法 |
---|
{ "source": string, "chunk": string } |
source
string
僅供輸出。與要求 SemanticRetrieverConfig.source
相符的來源名稱。範例:corpora/123
或 corpora/123/documents/abc
chunk
string
僅供輸出。含有歸因文字的 Chunk
名稱。範例:corpora/123/documents/abc/chunks/xyz
CitationMetadata
一段內容的來源出處。
JSON 表示法 |
---|
{
"citationSources": [
{
object ( |
citationSources[]
object (CitationSource
)
特定回覆的引用來源。
CitationSource
在特定回覆中引用資料來源。
JSON 表示法 |
---|
{ "startIndex": integer, "endIndex": integer, "uri": string, "license": string } |
startIndex
integer
選用設定。歸因於這個來源的回應開頭。
索引代表區隔開端 (以位元組為單位)。
endIndex
integer
選用設定。歸因區隔的結尾 (不含)。
uri
string
選用設定。歸因為部分文字來源的 URI。
license
string
選用設定。GitHub 專案授權,歸因於區隔來源。
必須提供授權資訊才能引用代碼。
GenerationConfig
模型產生和輸出的設定選項。不是每個模型都可以設定部分參數。
JSON 表示法 |
---|
{
"stopSequences": [
string
],
"responseMimeType": string,
"responseSchema": {
object ( |
stopSequences[]
string
選用設定。將停止產生輸出內容的字元序列 (最多 5 個)。如果有指定,API 會在停止序列第一次出現時停止。停止序列不會納入回應。
responseMimeType
string
選用設定。產生的候選文字的輸出回應 MIME 類型。支援的 MIME 類型:text/plain
:(預設) 文字輸出。application/json
:候選中的 JSON 回應。
responseSchema
object (Schema
)
選用設定。當回應 MIME 類型可以有結構定義時,產生的候選文字的輸出回應結構定義。結構定義可以是物件、原始或陣列,也是 OpenAPI 結構定義的子集。
如果已設定,則必須一併設定相容的 responseMimeType。相容的 MIME 類型:application/json
:JSON 回應的結構定義。
candidateCount
integer
選用設定。要傳回的回應數。
這個值目前只能設為 1。如未設定,這個項目會預設為 1。
maxOutputTokens
integer
選用設定。候選項目中的符記數量上限。
注意:預設值因模型而異,請參閱 getModel
函式所傳回 Model
的 Model.output_token_limit
屬性。
temperature
number
選用設定。控管輸出內容的隨機程度。
注意:預設值因模型而異,請參閱 getModel
函式所傳回 Model
的 Model.temperature
屬性。
值的範圍為 [0.0, 2.0]。
topP
number
選用設定。取樣時考量的符記累計機率上限。
這個模型採用 Top-k 和 nucleus 綜合取樣。
系統會依據指派的機率排序權杖,只考慮最有可能的符記。「Top-K」取樣會直接限制要考慮的符記數量上限,Nucleus 取樣功能則會根據累積機率限制符記數量。
注意:預設值因模型而異,請參閱 getModel
函式所傳回 Model
的 Model.top_p
屬性。
topK
integer
選用設定。取樣時可指定的符記數量上限。
模型會採用核能取樣,或將 Top-K 和細胞核的取樣組合納入考量。「Top-K」取樣會考量一組可能性最高的符記組合 (共 topK
個)。以 Nucleus 取樣執行的模型不允許使用 TopK 設定。
注意:預設值因模型而異,請參閱 getModel
函式所傳回 Model
的 Model.top_k
屬性。Model
中的 topK
欄位空白,代表模型不會套用「前 K 個」取樣,並不允許在要求中設定 topK
。
HarmCategory
評分的類別。
這些類別涵蓋開發人員可能想調整的各種危害。
列舉 | |
---|---|
HARM_CATEGORY_UNSPECIFIED |
未指定類別。 |
HARM_CATEGORY_DEROGATORY |
針對特定身分和/或受保護屬性發表負面或有害言論。 |
HARM_CATEGORY_TOXICITY |
粗魯無禮、不尊重或不雅的內容。 |
HARM_CATEGORY_VIOLENCE |
描述對個人或群體施暴的情境,或描述血腥的血腥描述。 |
HARM_CATEGORY_SEXUAL |
提及性行為或其他猥褻情事的內容。 |
HARM_CATEGORY_MEDICAL |
宣傳未經證實的醫療建議。 |
HARM_CATEGORY_DANGEROUS |
宣傳、鼓吹或助長有害舉動的「危險內容」。 |
HARM_CATEGORY_HARASSMENT |
騷擾內容。 |
HARM_CATEGORY_HATE_SPEECH |
仇恨言論和內容。 |
HARM_CATEGORY_SEXUALLY_EXPLICIT |
情色露骨內容。 |
HARM_CATEGORY_DANGEROUS_CONTENT |
危險內容。 |
SafetyRating
內容的安全評分。
安全分級包含危害類別,以及與該內容類別相同的危險機率等級。這些類型的內容應視為安全類別,並涵蓋多項危害類別,以及傷害可能性分類的可能性。
JSON 表示法 |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
必要欄位。這個評分的類別。
probability
enum (HarmProbability
)
必要欄位。這類內容的傷害機率。
blocked
boolean
這則內容是因為這個分級而遭到封鎖嗎?
HarmProbability
特定內容有害的機率。
分類系統會判定內容不安全的可能性。這不代表內容傷害的嚴重性。
列舉 | |
---|---|
HARM_PROBABILITY_UNSPECIFIED |
未指定機率。 |
NEGLIGIBLE |
內容不太可能不安全。 |
LOW |
內容不太可能不安全。 |
MEDIUM |
內容不太可能不安全。 |
HIGH |
內容很有可能不安全。 |
SafetySetting
會影響安全封鎖行為的安全設定。
只要傳遞特定類別的安全性設定,就會改變內容遭封鎖的機率。
JSON 表示法 |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
必要欄位。這項設定的類別。
threshold
enum (HarmBlockThreshold
)
必要欄位。控管造成損害的機率門檻。
HarmBlockThreshold
在指定損害可能性的情況下封鎖。
列舉 | |
---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED |
未指定門檻。 |
BLOCK_LOW_AND_ABOVE |
我們允許發布含有 NEGLIGIBLE 的內容。 |
BLOCK_MEDIUM_AND_ABOVE |
系統允許放送內容為 NEGLIGIBLE 和 LOW 的內容。 |
BLOCK_ONLY_HIGH |
系統允許發布「NEGLIGIBLE」、「LOW」和「MEDIUM」這類內容的內容。 |
BLOCK_NONE |
允許所有內容。 |