您可以透過脈絡快取功能儲存並重複使用預先計算的輸入權杖,例如對同一媒體檔案提出不同問題時。視使用情況而定,這可節省成本和時間。如需詳細簡介,請參閱「情境快取」指南。
方法:cachedContents.create
建立 CachedContent 資源。
端點
posthttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
要求主體
要求主體包含 CachedContent 的例項。
contents[]
object (Content)
(選用步驟) 僅限輸入。不可變動。要快取的內容。
tools[]
object (Tool)
(選用步驟) 僅限輸入。不可變動。Tools模型可能用來生成下一個回應的清單
expiration
Union type
expiration 只能是下列其中一項:expireTime
string (Timestamp format)
資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會顯示在輸出內容中。
使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
ttl
string (Duration format)
僅限輸入。這項資源的新存留時間,僅供輸入。
時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"。
displayName
string
(選用步驟) 不可變動。使用者為快取內容產生的有意義顯示名稱。最多 128 個 Unicode 字元。
model
string
必填。不可變動。用於快取內容的 Model 名稱。格式:models/{model}
systemInstruction
object (Content)
(選用步驟) 僅限輸入。不可變動。開發人員設定系統指令。目前僅支援文字。
toolConfig
object (ToolConfig)
(選用步驟) 僅限輸入。不可變動。工具設定。所有工具都會共用這項設定。
要求範例
基本
Python
Node.js
Go
貝殼
寄件者名稱
Python
Node.js
Go
來自即時通訊
Python
Node.js
Go
回應主體
如果成功,回應主體會包含新建立的 CachedContent 執行個體。
方法:cachedContents.list
列出 CachedContents。
端點
gethttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
查詢參數
pageSize
integer
(選用步驟) 要傳回的快取內容數量上限。服務傳回的產品數量可能會少於這個值。如未指定,系統會傳回預設 (上限以下) 數量的項目。許可的最大值為 1000;超出的數值將一律指定為 1000。
pageToken
string
(選用步驟) 屬於接收自前一個 cachedContents.list 呼叫的網頁權杖。提供此項目即可擷取後續網頁。
進行分頁時,提供至 cachedContents.list 的所有其他參數須與提供網頁權杖的呼叫相符。
要求主體
要求主體必須為空白。
回應主體
回應包含 CachedContents 清單。
如果成功,回應主體會含有以下結構的資料:
cachedContents[]
object (CachedContent)
快取內容清單。
nextPageToken
string
可做為 pageToken 傳送的權杖,用於擷取後續網頁。如果省略這個欄位,就不會有後續頁面。
| JSON 表示法 |
|---|
{
"cachedContents": [
{
object ( |
方法:cachedContents.get
讀取 CachedContent 資源。
端點
gethttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
路徑參數
name
string
必填。參照內容快取項目的資源名稱。格式:cachedContents/{id}。格式為 cachedContents/{cachedcontent}。
要求主體
要求主體必須為空白。
要求範例
Python
Node.js
Go
貝殼
回應主體
如果成功,回應主體會包含 CachedContent 的執行個體。
方法:cachedContents.patch
更新 CachedContent 資源 (只能更新到期時間)。
端點
patchhttps: / /generativelanguage.googleapis.com /v1beta /{cachedContent.name=cachedContents /*}
PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
路徑參數
cachedContent.name
string
僅供輸出。ID。參照快取內容的資源名稱。格式:cachedContents/{id}。格式為 cachedContents/{cachedcontent}。
查詢參數
updateMask
string (FieldMask format)
要更新的欄位清單。
這是以半形逗號分隔的完整欄位名稱清單,範例:"user.displayName,photo"。
要求主體
要求主體包含 CachedContent 的例項。
expiration
Union type
expiration 只能是下列其中一項:expireTime
string (Timestamp format)
資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會顯示在輸出內容中。
使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
ttl
string (Duration format)
僅限輸入。這項資源的新存留時間,僅供輸入。
時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"。
要求範例
Python
Node.js
Go
貝殼
回應主體
如果成功,回應主體會包含 CachedContent 的執行個體。
方法:cachedContents.delete
刪除 CachedContent 資源。
端點
deletehttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
路徑參數
name
string
必填。參照內容快取項目的資源名稱。格式:cachedContents/{id}。格式為 cachedContents/{cachedcontent}。
要求主體
要求主體必須為空白。
要求範例
Python
Node.js
Go
貝殼
回應主體
如果成功,回應主體會是空白的 JSON 物件。
REST 資源:cachedContents
- 資源:CachedContent
- 內容
- Part
- Blob
- FunctionCall
- FunctionResponse
- FunctionResponsePart
- FunctionResponseBlob
- 排程
- FileData
- ExecutableCode
- 語言
- CodeExecutionResult
- 結果
- ToolCall
- ToolType
- ToolResponse
- VideoMetadata
- MediaResolution
- 等級
- 工具
- FunctionDeclaration
- 結構定義
- 類型
- 行為
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- 眾數
- CodeExecution
- GoogleSearch
- 間隔
- SearchTypes
- WebSearch
- ImageSearch
- ComputerUse
- 環境
- UrlContext
- FileSearch
- McpServer
- StreamableHttpTransport
- GoogleMaps
- ToolConfig
- FunctionCallingConfig
- 眾數
- RetrievalConfig
- LatLng
- UsageMetadata
- 方法
資源:CachedContent
已預先處理的內容,可用於後續對 GenerativeService 的要求。
快取內容只能搭配建立時使用的模型。
contents[]
object (Content)
(選用步驟) 僅限輸入。不可變動。要快取的內容。
tools[]
object (Tool)
(選用步驟) 僅限輸入。不可變動。Tools模型可能用來生成下一個回應的清單
createTime
string (Timestamp format)
僅供輸出。快取項目的建立時間。
使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime
string (Timestamp format)
僅供輸出。快取項目上次更新的時間 (世界標準時間)。
使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
usageMetadata
object (UsageMetadata)
僅供輸出。快取內容的使用中繼資料。
expiration
Union type
expiration 只能是下列其中一項:expireTime
string (Timestamp format)
資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會顯示在輸出內容中。
使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
ttl
string (Duration format)
僅限輸入。這項資源的新存留時間,僅供輸入。
時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"。
name
string
僅供輸出。ID。參照快取內容的資源名稱。格式:cachedContents/{id}
displayName
string
(選用步驟) 不可變動。使用者為快取內容產生的有意義顯示名稱。最多 128 個 Unicode 字元。
model
string
必填。不可變動。用於快取內容的 Model 名稱。格式:models/{model}
systemInstruction
object (Content)
(選用步驟) 僅限輸入。不可變動。開發人員設定系統指令。目前僅支援文字。
toolConfig
object (ToolConfig)
(選用步驟) 僅限輸入。不可變動。工具設定。所有工具都會共用這項設定。
| JSON 表示法 |
|---|
{ "contents": [ { object ( |
內容
配件
包含媒體的資料型別,是多部分 Content 訊息的一部分。
Part 包含與相關聯資料類型對應的資料。Part 只能包含 Part.data 中其中一種可接受的類型。
如果 inlineData 欄位填入原始位元組,Part 就必須有固定的 IANA MIME 類型,用來識別媒體的類型和子類型。
thought
boolean
(選用步驟) 指出該部分是否為模型所想。
thoughtSignature
string (bytes format)
(選用步驟) 想法的不透明簽章,可在後續要求中重複使用。
Base64 編碼字串。
partMetadata
object (Struct format)
與 Part 相關聯的自訂中繼資料。使用 genai.Part 做為內容表示法的代理程式可能需要追蹤額外資訊。例如,這可以是 Part 來源的檔案/來源名稱,或是多工處理多個 Part 串流的方式。
mediaResolution
object (MediaResolution)
(選用步驟) 輸入媒體的媒體解析度。
data
Union type
data 只能是下列其中一項:text
string
內嵌文字。
inlineData
object (Blob)
內嵌媒體位元組。
functionCall
object (FunctionCall)
模型傳回的預測 FunctionCall,其中包含代表 FunctionDeclaration.name 的字串,以及引數和引數值。
functionResponse
object (FunctionResponse)
含有代表 FunctionDeclaration.name 的字串,以及含有函式任何輸出內容的結構化 JSON 物件的 FunctionCall 結果輸出內容,會做為模型的背景資訊。
fileData
object (FileData)
以 URI 為基礎的資料。
executableCode
object (ExecutableCode)
模型生成的程式碼,可供執行。
codeExecutionResult
object (CodeExecutionResult)
執行 ExecutableCode 的結果。
toolCall
object (ToolCall)
伺服器端工具呼叫。如果模型預測應在伺服器上執行的工具呼叫,系統會在此欄位中填入資料。用戶端應將這則訊息回送給 API。
toolResponse
object (ToolResponse)
伺服器端 ToolCall 執行的輸出內容。這個欄位由用戶端填入,內容是執行對應 ToolCall 的結果。
metadata
Union type
metadata 只能是下列其中一項:videoMetadata
object (VideoMetadata)
(選用步驟) 影片中繼資料。只有在影片資料以 inlineData 或 fileData 形式呈現時,才應指定中繼資料。
| JSON 表示法 |
|---|
{ "thought": boolean, "thoughtSignature": string, "partMetadata": { object }, "mediaResolution": { object ( |
Blob
FunctionCall
模型傳回的預測 FunctionCall,其中包含代表 FunctionDeclaration.name 的字串,以及引數和引數值。
id
string
(選用步驟) 函式呼叫的專屬 ID。如果已填入,用戶端會執行 functionCall,並傳回含有相符 id 的回應。
name
string
必填。要呼叫的函式名稱。必須是 a-z、A-Z、0-9,或包含底線和破折號,長度上限為 128。
args
object (Struct format)
(選用步驟) JSON 物件格式的函式參數和值。
| JSON 表示法 |
|---|
{ "id": string, "name": string, "args": { object } } |
FunctionResponse
含有代表 FunctionDeclaration.name 的字串,以及含有函式任何輸出內容的結構化 JSON 物件的 FunctionCall 結果輸出內容,會做為模型的背景資訊。這應包含根據模型預測結果進行 FunctionCall 的結果。
id
string
(選用步驟) 這個回覆所屬的函式呼叫 ID。由用戶端填入,以符合對應的函式呼叫 id。
name
string
必填。要呼叫的函式名稱。必須是 a-z、A-Z、0-9,或包含底線和破折號,長度上限為 128。
response
object (Struct format)
必填。JSON 物件格式的函式回應。呼叫端可以使用符合函式語法的任何鍵,傳回函式輸出內容,例如「output」、「result」等。特別是,如果函式呼叫執行失敗,回應可以有「error」鍵,將錯誤詳細資料傳回模型。
parts[]
object (FunctionResponsePart)
(選用步驟) 構成函式回應的已排序 Parts。各部分可能會有不同的 IANA MIME 類型。
willContinue
boolean
(選用步驟) 表示函式呼叫會繼續,並傳回更多回應,將函式呼叫變成產生器。僅適用於 NON_BLOCKING 函式呼叫,否則會遭到忽略。如果設為 False,系統就不會考慮之後的回覆。允許傳回空白 response 和 willContinue=False,表示函式呼叫已完成。這項操作仍可能會觸發模型生成。如要避免觸發生成作業並完成函式呼叫,請額外將 scheduling 設為 SILENT。
scheduling
enum (Scheduling)
(選用步驟) 指定在對話中安排回覆的方式。僅適用於 NON_BLOCKING 函式呼叫,否則會遭到忽略。預設為 WHEN_IDLE。
| JSON 表示法 |
|---|
{ "id": string, "name": string, "response": { object }, "parts": [ { object ( |
FunctionResponsePart
包含媒體的資料型別,是 FunctionResponse 訊息的一部分。
FunctionResponsePart 包含與相關聯資料類型對應的資料。FunctionResponsePart 只能包含 FunctionResponsePart.data 中其中一種可接受的類型。
如果 inlineData 欄位填入原始位元組,FunctionResponsePart 就必須有固定的 IANA MIME 類型,用來識別媒體的類型和子類型。
| JSON 表示法 |
|---|
{
// data
"inlineData": {
object ( |
FunctionResponseBlob
排程
指定在對話中安排回覆的方式。
| 列舉 | |
|---|---|
SCHEDULING_UNSPECIFIED |
這個值不會使用。 |
SILENT |
只將結果新增至對話內容,請勿中斷或觸發生成作業。 |
WHEN_IDLE |
將結果新增至對話內容,並提示生成輸出內容,不必中斷正在進行的生成作業。 |
INTERRUPT |
將結果新增至對話內容、中斷正在進行的生成作業,並提示生成輸出內容。 |
FileData
以 URI 為基礎的資料。
mimeType
string
(選用步驟) 來源資料的 IANA 標準 MIME 類型。
fileUri
string
必填。URI。
| JSON 表示法 |
|---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
模型生成的程式碼 (用於執行),以及傳回模型的結果。
只有在使用 CodeExecution 工具時才會產生,系統會自動執行程式碼,並產生對應的 CodeExecutionResult。
id
string
(選用步驟) ExecutableCode 零件的專屬 ID。伺服器會傳回相符的 id 和 CodeExecutionResult。
language
enum (Language)
必填。code 的程式設計語言。
code
string
必填。要執行的程式碼。
| JSON 表示法 |
|---|
{
"id": string,
"language": enum ( |
語言
生成程式碼支援的程式設計語言。
| 列舉 | |
|---|---|
LANGUAGE_UNSPECIFIED |
未指定語言。請勿使用此值。 |
PYTHON |
Python >= 3.10,並提供 numpy 和 simpy。預設語言為 Python。 |
CodeExecutionResult
執行 ExecutableCode 的結果。
只有在使用 CodeExecution 工具時才會產生。
id
string
(選用步驟) 這項結果所屬ExecutableCode部分的 ID。只有在對應的 ExecutableCode 具有 ID 時,才會填入這個欄位。
outcome
enum (Outcome)
必填。程式碼執行結果。
output
string
(選用步驟) 如果程式碼執行成功,則包含 stdout;否則包含 stderr 或其他說明。
| JSON 表示法 |
|---|
{
"id": string,
"outcome": enum ( |
結果
列舉程式碼執行的可能結果。
| 列舉 | |
|---|---|
OUTCOME_UNSPECIFIED |
未指定狀態。請勿使用此值。 |
OUTCOME_OK |
程式碼已順利執行完畢。output 包含 stdout (如有)。 |
OUTCOME_FAILED |
程式碼執行失敗。output 包含 stderr 和 stdout (如有)。 |
OUTCOME_DEADLINE_EXCEEDED |
程式碼執行時間過長,因此已取消。可能會有部分 output。 |
ToolCall
模型傳回的預測伺服器端 ToolCall。這則訊息包含模型要呼叫的工具相關資訊。用戶端「不應」執行這項 ToolCall。用戶端應在後續回合的 Content 訊息中,將這個 ToolCall 連同對應的 ToolResponse 傳回 API。
id
string
(選用步驟) 工具呼叫的專屬 ID。伺服器會傳回工具回應,其中包含相符的 id。
toolType
enum (ToolType)
必填。呼叫的工具類型。
args
object (Struct format)
(選用步驟) 工具呼叫引數。例如:{"arg1" : "value1", "arg2" : "value2" , ...}
| JSON 表示法 |
|---|
{
"id": string,
"toolType": enum ( |
ToolType
函式呼叫中的工具類型。
| 列舉 | |
|---|---|
TOOL_TYPE_UNSPECIFIED |
未指定工具類型。 |
GOOGLE_SEARCH_WEB |
Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 |
GOOGLE_SEARCH_IMAGE |
圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 |
URL_CONTEXT |
網址內容工具,對應至 Tool.url_context。 |
GOOGLE_MAPS |
Google 地圖工具,對應至 Tool.google_maps。 |
FILE_SEARCH |
檔案搜尋工具,對應至 Tool.file_search。 |
ToolResponse
伺服器端 ToolCall 執行的輸出內容。這則訊息包含模型啟動的工具呼叫結果。ToolCall用戶端應在後續回合的 Content 訊息中,將此 ToolResponse 連同對應的 ToolCall 傳回 API。
id
string
(選用步驟) 這個回應所屬的工具呼叫 ID。
toolType
enum (ToolType)
必填。所呼叫的工具類型,與對應 ToolCall 中的 toolType 相符。
response
object (Struct format)
(選用步驟) 工具回應。
| JSON 表示法 |
|---|
{
"id": string,
"toolType": enum ( |
VideoMetadata
已淘汰:請改用 GenerateContentRequest.processing_options。中繼資料會說明輸入的影片內容。
startOffset
string (Duration format)
(選用步驟) 影片的開始偏移。
時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"。
endOffset
string (Duration format)
(選用步驟) 影片的結束時間偏移。
時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"。
fps
number
(選用步驟) 傳送至模型的影片畫面更新率。如未指定,預設值為 1.0。fps 範圍為 (0.0, 24.0]。
| JSON 表示法 |
|---|
{ "startOffset": string, "endOffset": string, "fps": number } |
MediaResolution
等級
媒體解析度等級。
| 列舉 | |
|---|---|
MEDIA_RESOLUTION_UNSPECIFIED |
尚未設定媒體解析度。 |
MEDIA_RESOLUTION_LOW |
媒體解析度設為低。 |
MEDIA_RESOLUTION_MEDIUM |
媒體解析度已設為中等。 |
MEDIA_RESOLUTION_HIGH |
媒體解析度設為高。 |
MEDIA_RESOLUTION_ULTRA_HIGH |
媒體解析度設為超高。 |
工具
模型可能用來生成回覆的工具詳細資料。
Tool是一段程式碼,可讓系統與外部系統互動,執行模型知識和範圍以外的動作或一連串動作。
下一個 ID:15
functionDeclarations[]
object (FunctionDeclaration)
(選用步驟) 模型可用的 FunctionDeclarations 清單,可用於函式呼叫。
模型或系統未執行函式。而是將定義的函式做為 FunctionCall 傳回,並附上引數,供用戶端執行。模型可能會決定呼叫這些函式的部分子集,方法是在回應中填入 FunctionCall。下一個對話回合可能包含 FunctionResponse,以及下一個模型回合的 Content.role「function」生成背景資訊。
googleSearchRetrieval
object (GoogleSearchRetrieval)
(選用步驟) 由 Google 搜尋技術支援的檢索工具。
codeExecution
object (CodeExecution)
(選用步驟) 讓模型在生成內容時執行程式碼。
googleSearch
object (GoogleSearch)
(選用步驟) GoogleSearch 工具類型。支援在模型中使用 Google 搜尋的工具。體現 Google 的技術結晶
computerUse
object (ComputerUse)
(選用步驟) 這項工具可支援模型直接與電腦互動。啟用後,系統會自動填入電腦專用的函式宣告。
urlContext
object (UrlContext)
(選用步驟) 支援擷取網址背景資訊的工具。
fileSearch
object (FileSearch)
(選用步驟) FileSearch 工具類型。從語意擷取語料庫擷取知識的工具。
mcpServers[]
object (McpServer)
(選用步驟) 要連線的 MCP 伺服器。
googleMaps
object (GoogleMaps)
(選用步驟) 這項工具可根據與使用者查詢相關的地理空間脈絡,為模型回覆提供基礎。
| JSON 表示法 |
|---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
函式宣告的結構化表示法,如 OpenAPI 3.03 規格所定義。這項宣告包含函式名稱和參數。這個 FunctionDeclaration 代表程式碼區塊,可做為模型的 Tool,並由用戶端執行。
name
string
必填。函式名稱。必須是 a-z、A-Z、0-9,或包含底線、冒號、半形句點和破折號,長度上限為 128 個字元。
description
string
必填。函式的簡短說明。
behavior
enum (Behavior)
(選用步驟) 指定函式行為。目前僅支援 BidiGenerateContent 方法。
parameters
object (Schema)
(選用步驟) 說明此函式的參數。反映 Open API 3.03 參數物件字串鍵:參數名稱。參數名稱區分大小寫。結構定義值:定義參數所用類型的結構定義。
parametersJsonSchema
value (Value format)
(選用步驟) 以 JSON 結構定義格式說明函式的參數。結構定義必須說明物件,其中屬性是函式的參數。例如:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
},
"additionalProperties": false,
"required": ["name", "age"],
"propertyOrdering": ["name", "age"]
}
這個欄位與 parameters 互斥。
response
object (Schema)
(選用步驟) 以 JSON 結構定義格式說明此函式的輸出內容。反映 Open API 3.03 回應物件。結構定義函式回應值所用的型別。
responseJsonSchema
value (Value format)
(選用步驟) 以 JSON 結構定義格式說明此函式的輸出內容。架構指定的值是函式的回應值。
這個欄位與 response 互斥。
結構定義
Schema 物件可定義輸入和輸出資料類型。這些型別可以是物件,也可以是基本型別和陣列。代表 OpenAPI 3.0 架構物件的選取子集。
type
enum (Type)
必填。資料類型。
format
string
(選用步驟) 資料格式。可輸入任何值,但大多數值不會觸發任何特殊功能。
title
string
(選用步驟) 結構定義的標題。
description
string
(選用步驟) 參數的簡短說明。這可能包含使用範例。參數說明可採用 Markdown 格式。
nullable
boolean
(選用步驟) 指出值是否可能為空值。
enum[]
string
(選用步驟) Type.STRING 元素可能的值,採用列舉格式。舉例來說,我們可以將列舉「Direction」定義為:{type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
maxItems
string (int64 format)
(選用步驟) Type.ARRAY 的元素數量上限。
minItems
string (int64 format)
(選用步驟) Type.ARRAY 的元素數量下限。
properties
map (key: string, value: object (Schema))
(選用步驟) Type.OBJECT 的屬性。
這個物件中包含 "key": value 組合的清單,範例:{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
required[]
string
(選用步驟) Type.OBJECT 的必要屬性。
minProperties
string (int64 format)
(選用步驟) Type.OBJECT 的屬性數量下限。
maxProperties
string (int64 format)
(選用步驟) Type.OBJECT 的屬性數量上限。
minLength
string (int64 format)
(選用步驟) 類型為 STRING 的結構定義欄位,類型為 STRING 的長度下限
maxLength
string (int64 format)
(選用步驟) Type.STRING 的長度上限
pattern
string
(選用步驟) Type.STRING 的模式,可將字串限制為規則運算式。
example
value (Value format)
(選用步驟) 物件範例。只有在物件是根目錄時才會填入。
anyOf[]
object (Schema)
(選用步驟) 系統應根據清單中的任何 (一或多個) 子結構定義驗證值。
propertyOrdering[]
string
(選用步驟) 屬性的順序。這不是 OpenAPI 規格中的標準欄位,而是用於判斷回應中屬性的順序。
default
value (Value format)
(選用步驟) 欄位的預設值。根據 JSON 結構定義,這個欄位適用於文件產生器,不會影響驗證。因此,這裡會納入並忽略這個欄位,這樣一來,傳送含有 default 欄位結構定義的開發人員就不會收到不明欄位錯誤。
items
object (Schema)
(選用步驟) Type.ARRAY 元素的結構定義。
minimum
number
(選用步驟) SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER
maximum
number
(選用步驟) Type.INTEGER 和 Type.NUMBER 的最大值
| JSON 表示法 |
|---|
{ "type": enum ( |
類型
Type 包含 OpenAPI 資料型別清單,如 https://spec.openapis.org/oas/v3.0.3#data-types 所定義
| 列舉 | |
|---|---|
TYPE_UNSPECIFIED |
未指定,請勿使用。 |
STRING |
字串類型。 |
NUMBER |
電話號碼類型。 |
INTEGER |
整數類型。 |
BOOLEAN |
布林類型。 |
ARRAY |
陣列類型。 |
OBJECT |
物件類型。 |
NULL |
空值型別。 |
行為
定義函式行為。預設值為 BLOCKING。
| 列舉 | |
|---|---|
UNSPECIFIED |
這個值不會使用。 |
BLOCKING |
如果設定了這項屬性,系統會等待收到函式回應,再繼續對話。 |
NON_BLOCKING |
如果設定此屬性,系統就不會等待接收函式回應。而是會在函式回應可用時嘗試處理,同時維持使用者與模型之間的對話。 |
GoogleSearchRetrieval
這項工具由 Google 提供,可擷取公開網路資料做為基礎。
dynamicRetrievalConfig
object (DynamicRetrievalConfig)
指定指定來源的動態擷取設定。
| JSON 表示法 |
|---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
模式
要在動態擷取中使用的預測器模式。
| 列舉 | |
|---|---|
MODE_UNSPECIFIED |
一律觸發擷取作業。 |
MODE_DYNAMIC |
只有在系統判斷有必要時才執行擷取作業。 |
CodeExecution
這個類型沒有任何欄位。
這項工具會執行模型生成的程式碼,並自動將結果傳回模型。
另請參閱 ExecutableCode 和 CodeExecutionResult,這些內容只會在您使用這項工具時生成。
GoogleSearch
GoogleSearch 工具類型。支援在模型中使用 Google 搜尋的工具。體現 Google 的技術結晶
timeRangeFilter
object (Interval)
(選用步驟) 將搜尋結果篩選至特定時間範圍。如果顧客設定了開始時間,就必須設定結束時間 (反之亦然)。
searchTypes
object (SearchTypes)
(選用步驟) 要啟用的搜尋類型組合。如未設定,系統預設會啟用網頁搜尋。
| JSON 表示法 |
|---|
{ "timeRangeFilter": { object ( |
時間間隔
代表時間間隔,編碼以一個時間戳記開始 (含),一個時間戳記結束 (不含)。
開始時間必須小於或等於結束時間。如果開始時間等於結束時間,間隔會是空白 (不符合任何時間)。如果開始和結束時間都未指定,則間隔會符合任何時間。
startTime
string (Timestamp format)
(選用步驟) 間隔的開始時間 (含)。
如果指定了這個值,符合此間隔的時間戳記必須等於或晚於開始時間。
使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime
string (Timestamp format)
選填。間隔的結束時間 (不含)。
如果指定,符合這個間隔的時間戳記必須早於結束時間。
使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
| JSON 表示法 |
|---|
{ "startTime": string, "endTime": string } |
SearchTypes
可在 GoogleSearch 工具上啟用的搜尋類型。
webSearch
object (WebSearch)
(選用步驟) 啟用網頁搜尋功能。系統只會傳回文字結果。
imageSearch
object (ImageSearch)
(選用步驟) 啟用圖片搜尋功能。系統會傳回圖片位元組。
| JSON 表示法 |
|---|
{ "webSearch": { object ( |
WebSearch
這個類型沒有任何欄位。
標準網頁搜尋,用於基礎和相關設定。
ImageSearch
這個類型沒有任何欄位。
圖片搜尋功能,可做為基礎和相關設定。
ComputerUse
電腦使用工具類型。
environment
enum (Environment)
必填。運作中的環境。
excludedPredefinedFunctions[]
string
(選用步驟) 根據預設,最終模型呼叫會納入預先定義的函式。您可以明確排除部分項目,避免系統自動納入。這有兩個用途:1. 使用限制較多 / 不同的動作空間。2. 改善預先定義函式的定義 / 說明。
| JSON 表示法 |
|---|
{
"environment": enum ( |
環境
代表作業環境,例如網路瀏覽器。
| 列舉 | |
|---|---|
ENVIRONMENT_UNSPECIFIED |
預設為瀏覽器。 |
ENVIRONMENT_BROWSER |
透過網路瀏覽器運作。 |
UrlContext
這個類型沒有任何欄位。
支援擷取網址背景資訊的工具。
FileSearch
FileSearch 工具可從語意檢索語料庫中擷取知識。使用 ImportFile API 將檔案匯入語意擷取語料庫。
fileSearchStoreNames[]
string
必填。要從中擷取的 fileSearchStore 名稱。範例:fileSearchStores/my-file-search-store-123
metadataFilter
string
(選用步驟) 要套用至語意擷取文件和區塊的中繼資料篩選器。
topK
integer
(選用步驟) 要擷取的語意擷取區塊數量。
| JSON 表示法 |
|---|
{ "fileSearchStoreNames": [ string ], "metadataFilter": string, "topK": integer } |
McpServer
MCPServer 是模型可呼叫的伺服器,可執行動作。這是實作 MCP 通訊協定的伺服器。下一個 ID:5
name
string
MCPServer 的名稱。
transport
Union type
transport 只能是下列其中一項:streamableHttpTransport
object (StreamableHttpTransport)
可串流處理 HTTP 要求和回應的傳輸方式。
| JSON 表示法 |
|---|
{
"name": string,
// transport
"streamableHttpTransport": {
object ( |
StreamableHttpTransport
可串流處理 HTTP 要求和回應的傳輸方式。下一個 ID:6
url
string
MCPServer 端點的完整網址。例如:「https://api.example.com/mcp」
headers
map (key: string, value: string)
選用:視需要填寫驗證標頭、逾時等欄位。
這個物件中包含 "key": value 組合的清單,範例:{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
timeout
string (Duration format)
一般作業的 HTTP 逾時。
時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"。
sseReadTimeout
string (Duration format)
SSE 讀取作業的逾時時間。
時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"。
terminateOnClose
boolean
是否要在傳輸關閉時關閉用戶端工作階段。
| JSON 表示法 |
|---|
{ "url": string, "headers": { string: string, ... }, "timeout": string, "sseReadTimeout": string, "terminateOnClose": boolean } |
GoogleMaps
Google 地圖工具,可為使用者的查詢提供地理空間脈絡。
enableWidget
boolean
(選用步驟) 是否要在回應的 GroundingMetadata 中傳回小工具內容符記。開發人員可以使用小工具內容權杖,算繪出 Google 地圖小工具,並顯示模型在回覆中提及地點的相關地理空間內容。
| JSON 表示法 |
|---|
{ "enableWidget": boolean } |
ToolConfig
工具設定,內含用於在要求中指定 Tool 用途的參數。
functionCallingConfig
object (FunctionCallingConfig)
(選用步驟) 函式呼叫設定。
retrievalConfig
object (RetrievalConfig)
(選用步驟) 擷取設定。
includeServerSideToolInvocations
boolean
(選用步驟) 設為 true 時,API 回應會在 Content 訊息中納入伺服器端工具呼叫和回覆。這可讓用戶端觀察伺服器的工具互動。
| JSON 表示法 |
|---|
{ "functionCallingConfig": { object ( |
FunctionCallingConfig
模式
定義執行模式,藉此定義函式呼叫的執行行為。
| 列舉 | |
|---|---|
MODE_UNSPECIFIED |
未指定函式呼叫模式。請勿使用此值。 |
AUTO |
預設模型行為,模型會判斷要預測函式呼叫或自然語言回覆。 |
ANY |
模型一律只能預測函式呼叫。如果設定了「allowedFunctionNames」,預測的函式呼叫會限制為「allowedFunctionNames」中的任一函式;否則,預測的函式呼叫會是提供的「functionDeclarations」中的任一函式。 |
NONE |
模型不會預測任何函式呼叫。模型行為與未傳遞任何函式宣告時相同。 |
VALIDATED |
模型會決定要預測函式呼叫或自然語言回應,但會使用受限解碼驗證函式呼叫。如果設定了「allowedFunctionNames」,預測的函式呼叫會限制為「allowedFunctionNames」中的任一函式;否則,預測的函式呼叫會是提供的「functionDeclarations」中的任一函式。 |
RetrievalConfig
LatLng
代表經緯度組合的物件。這個物件會同時指出經度和緯度的度數。除非另有指定,否則這個物件必須符合 WGS84 標準。此外,值必須在正規化範圍內。
latitude
number
緯度度數,必須介於 [-90.0, +90.0] 的範圍之間。
longitude
number
經度度數,必須介於 [-180.0, +180.0] 的範圍之間。
| JSON 表示法 |
|---|
{ "latitude": number, "longitude": number } |
UsageMetadata
快取內容的使用中繼資料。
totalTokenCount
integer
快取內容消耗的權杖總數。
| JSON 表示法 |
|---|
{ "totalTokenCount": integer } |