您可以透過脈絡快取功能,儲存及重複使用您想重複使用的預先計算輸入符記,例如在針對同一媒體檔案提出不同問題時。視用量而定,這可能有助於節省成本和加快速度。如需詳細的介紹,請參閱內容快取指南。
方法:cachedContents.create
建立 CachedContent 資源。
端點
post https://generativelanguage.googleapis.com/v1beta/cachedContents要求主體
要求主體包含 CachedContent
的例項。
contents[]
object (Content
)
選用設定。僅限輸入。不可變動。要快取的內容。
tools[]
object (Tool
)
選用設定。僅限輸入。不可變動。模型可以用來產生下一次回應的 Tools
清單
expiration
。指定這項資源的到期日。expiration
只能是下列其中一項:expireTime
string (Timestamp
format)
資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會顯示在輸出內容中。
RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。例如 "2014-10-02T15:01:23Z"
和 "2014-10-02T15:01:23.045123456Z"
。
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
)
選用設定。僅限輸入。不可變動。工具設定。這項設定會與所有工具共用。
要求範例
基本
Python
Node.js
Go
貝殼
寄件者名稱
Python
Node.js
Go
透過即時通訊
Python
Node.js
Go
回應主體
如果成功,回應主體會包含新建立的 CachedContent
例項。
方法:cachedContents.list
列出 CachedContents。
端點
get https://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 資源。
端點
get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}路徑參數
name
string
必要欄位。指的是內容快取項目的資源名稱。格式:cachedContents/{id}
格式為 cachedContents/{cachedcontent}
。
要求主體
要求主體必須為空白。
要求範例
Python
Node.js
Go
貝殼
回應主體
如果成功,回應主體會包含 CachedContent
的執行例項。
方法:cachedContents.patch
更新 CachedContent 資源 (僅限更新到期日)。
端點
patch https://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
。指定這項資源的到期日。expiration
只能採用下列其中一種設定:expireTime
string (Timestamp
format)
資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會顯示在輸出內容中。
RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。例如 "2014-10-02T15:01:23Z"
和 "2014-10-02T15:01:23.045123456Z"
。
ttl
string (Duration
format)
僅限輸入。這項資源的新存留時間 (僅限輸入)。
時間長度以秒為單位,最多可有 9 個小數位數,並應以「s
」結尾,例如:"3.5s"
。
name
string
選用設定。ID。參照快取內容的資源名稱。格式:cachedContents/{id}
要求範例
Python
Node.js
Go
貝殼
回應主體
如果成功,回應主體會包含 CachedContent
的執行例項。
方法:cachedContents.delete
刪除 CachedContent 資源。
端點
delete https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}路徑參數
name
string
必要欄位。參照內容快取項目的資源名稱格式:cachedContents/{id}
格式為 cachedContents/{cachedcontent}
。
要求主體
要求主體必須為空白。
要求範例
Python
Node.js
Go
貝殼
回應主體
如果成功,回應主體會留白。
REST 資源:cachedContents
- 資源:CachedContent
- 內容
- Part
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- 語言
- CodeExecutionResult
- 結果
- 工具
- FunctionDeclaration
- 結構定義
- 類型
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- 模式
- CodeExecution
- ToolConfig
- FunctionCallingConfig
- 模式
- UsageMetadata
- 方法
資源:CachedContent
已預先處理的內容,可用於後續向 GenerativeService 要求
快取內容只能用於建立該內容的模型。
contents[]
object (Content
)
選用設定。僅限輸入。不可變動。要快取的內容。
tools[]
object (Tool
)
選用設定。僅限輸入。不可變動。模型可能用來產生下一個回應的 Tools
清單
createTime
string (Timestamp
format)
僅供輸出。快取項目的建立時間。
RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。範例:"2014-10-02T15:01:23Z"
和 "2014-10-02T15:01:23.045123456Z"
。
updateTime
string (Timestamp
format)
僅供輸出。快取項目上次更新的時間 (以世界標準時間為準)。
RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。例如 "2014-10-02T15:01:23Z"
和 "2014-10-02T15:01:23.045123456Z"
。
usageMetadata
object (UsageMetadata
)
僅供輸出。快取內容的使用情形中繼資料。
expiration
。指定這項資源的到期日。expiration
只能是下列其中一項:expireTime
string (Timestamp
format)
資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會顯示在輸出內容中。
RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。例如 "2014-10-02T15:01:23Z"
和 "2014-10-02T15:01:23.045123456Z"
。
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 類型,用於識別媒體的類型和子類型。
聯集欄位 data
。
data
只能採用下列其中一種設定:
text
string
內嵌文字。
inlineData
object (Blob
)
內嵌媒體位元組。
functionCall
object (FunctionCall
)
模型傳回的預測 FunctionCall
,其中包含代表 FunctionDeclaration.name
的字串,以及引數和引數值。
functionResponse
object (FunctionResponse
)
FunctionCall
的結果輸出內容包含代表 FunctionDeclaration.name
的字串,以及包含函式任何輸出的結構化 JSON 物件,用於模型的背景。
fileData
object (FileData
)
以 URI 為基礎的資料。
executableCode
object (ExecutableCode
)
由模型產生要執行的程式碼。
codeExecutionResult
object (CodeExecutionResult
)
執行 ExecutableCode
的結果。
JSON 表示法 |
---|
{ // Union field |
Blob
FunctionCall
模型傳回的預測 FunctionCall
,其中包含代表 FunctionDeclaration.name
的字串,以及引數和引數值。
name
string
必要欄位。要呼叫的函式名稱。必須是 a-z、A-Z、0-9,或包含底線和破折號,長度上限為 63 個字元。
args
object (Struct
format)
選用設定。以 JSON 物件格式呈現的函式參數和值。
JSON 表示法 |
---|
{ "name": string, "args": { object } } |
FunctionResponse
來自 FunctionCall
的結果輸出,其中包含代表 FunctionDeclaration.name
的字串,以及包含函式任何輸出的結構化 JSON 物件,會做為模型的內容。這應該包含根據模型預測結果做出的FunctionCall
。
name
string
必要欄位。要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線和破折號,長度上限為 63 個字元。
response
object (Struct
format)
必要欄位。JSON 物件格式的函式回應。
JSON 表示法 |
---|
{ "name": string, "response": { object } } |
FileData
以 URI 為基礎的資料。
mimeType
string
選用設定。來源資料的 IANA 標準 MIME 類型。
fileUri
string
必要欄位。URI。
JSON 表示法 |
---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
語言
產生程式碼的支援程式設計語言。
列舉 | |
---|---|
LANGUAGE_UNSPECIFIED |
未指定語言。請勿使用這個值。 |
PYTHON |
Python 3.10 以上版本,並提供 numpy 和 simpy。 |
CodeExecutionResult
結果
列舉程式碼執行作業的可能結果。
列舉 | |
---|---|
OUTCOME_UNSPECIFIED |
未指定的狀態。請勿使用此值。 |
OUTCOME_OK |
程式碼執行作業已順利完成。 |
OUTCOME_FAILED |
程式碼執行作業已完成,但發生錯誤。stderr 應包含原因。 |
OUTCOME_DEADLINE_EXCEEDED |
程式碼執行時間過長,已遭到取消。部分輸出內容可能會出現。 |
工具
模型可能用來產生回覆的工具詳細資料。
Tool
是一小段程式碼,可讓系統與外部系統互動,執行模型知識和範圍以外的動作或一組動作。
functionDeclarations[]
object (FunctionDeclaration
)
選用設定。可供模型使用的 FunctionDeclarations
清單,可用於函式呼叫。
模型或系統未執行函式。相反地,定義的函式可能會以 FunctionCall
的形式傳回,並將引數傳送至用戶端執行。模型可能會在回應中填入 FunctionCall
,決定呼叫這些函式的子集。下一個對話回合可能會包含 FunctionResponse
,其中包含 Content.role
「函式」產生下一個模型回合的背景資訊。
googleSearchRetrieval
object (GoogleSearchRetrieval
)
選用設定。採用 Google 搜尋技術的擷取工具。
codeExecution
object (CodeExecution
)
選用設定。讓模型在生成期間執行程式碼。
JSON 表示法 |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
根據 OpenAPI 3.03 規範定義的函式宣告結構化表示法。此宣告包含函式名稱和參數。這個 FunctionDeclaration 是程式碼區塊的表示法,可由模型用作 Tool
,並由用戶端執行。
name
string
必要欄位。函式的名稱。必須是 a-z、A-Z、0-9,或包含底線和破折號,長度上限為 63 個字元。
description
string
必要欄位。簡短說明功能。
parameters
object (Schema
)
選用設定。說明此函式的參數。反映 Open API 3.03 參數物件字串值鍵:參數名稱。參數名稱區分大小寫。結構定義值:定義參數所用型別的結構定義。
JSON 表示法 |
---|
{
"name": string,
"description": string,
"parameters": {
object ( |
結構定義
Schema
物件可定義輸入和輸出資料類型。這些類型可以是物件,也可以是基本類型和陣列。代表 OpenAPI 3.0 結構定義物件的選取子集。
type
enum (Type
)
必要欄位。資料類型。
format
string
選用設定。資料格式。這只適用於基本資料類型。支援的格式:NUMBER 類型:float、double;INTEGER 類型:int32、int64;STRING 類型:enum
description
string
選用設定。簡短說明參數。包含使用範例。參數說明的格式必須為 Markdown。
nullable
boolean
選用設定。指出值是否可能為空值。
enum[]
string
選用設定。使用列舉格式的 Type.STRING 元素可能的值。舉例來說,我們可以將 Enum 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 的必要屬性。
items
object (Schema
)
選用設定。Type.ARRAY 元素的結構定義。
類型
Type 包含 https://spec.openapis.org/oas/v3.0.3#data-types 所定義的 OpenAPI 資料類型清單
列舉 | |
---|---|
TYPE_UNSPECIFIED |
未指定,請勿使用。 |
STRING |
字串類型。 |
NUMBER |
數字類型。 |
INTEGER |
整數類型。 |
BOOLEAN |
布林值類型。 |
ARRAY |
陣列類型。 |
OBJECT |
物件類型。 |
GoogleSearchRetrieval
運用 Google 技術擷取公開網路資料的擷取工具。
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
指定指定來源的動態擷取設定。
JSON 表示法 |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
模式
在動態擷取中使用的預測器模式。
列舉 | |
---|---|
MODE_UNSPECIFIED |
一律觸發擷取作業。 |
MODE_DYNAMIC |
只有在系統判斷有必要時才執行擷取作業。 |
CodeExecution
這個類型沒有任何欄位。
執行模型產生的程式碼,並自動將結果傳回模型。
另請參閱 ExecutableCode
和 CodeExecutionResult
,這兩個欄位只會在使用這項工具時產生。
ToolConfig
工具設定,其中包含用於指定要求中 Tool
用法的參數。
functionCallingConfig
object (FunctionCallingConfig
)
選用設定。函式呼叫設定。
JSON 表示法 |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
模式
定義執行模式,以便定義函式呼叫的執行行為。
列舉 | |
---|---|
MODE_UNSPECIFIED |
未指定的函式呼叫模式。請勿使用此值。 |
AUTO |
預設模型行為,模型會決定預測函式呼叫或自然語言回應。 |
ANY |
模型只能預測函式呼叫。如果已設定「allowedFunctionNames」,則預測的函式呼叫會限制為「allowedFunctionNames」中的任一函式,否則預測的函式呼叫會是提供的「functionDeclarations」中的任一函式。 |
NONE |
模型不會預測任何函式呼叫。模型的行為與未傳遞任何函式宣告時相同。 |
UsageMetadata
快取內容的使用情形中繼資料。
totalTokenCount
integer
快取內容耗用的權杖總數。
JSON 表示法 |
---|
{ "totalTokenCount": integer } |