內容快取功能可讓您儲存並重複使用預先計算的輸入權杖,比如說,當您詢問關於同一個媒體檔案的不同問題時,就能重複使用這些權杖。視用量而定,這麼做可以節省成本和速度。如需詳細的介紹,請參閱內容快取指南。
方法:cacheContents.create
建立 CachedContent 資源。
端點
則貼文
https://generativelanguage.googleapis.com/v1beta/cachedContents
要求主體
要求主體包含 CachedContent
的例項。
contents[]
object (Content
)
選用設定。僅限輸入。不可變動。要快取的內容。
tools[]
object (Tool
)
選用設定。僅限輸入。不可變動。模型可以用來產生下一次回應的 Tools
清單
expiration
。指定這項資源的到期日。expiration
只能採用下列其中一種設定:
expireTime
string (Timestamp
format)
資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會在輸出內容中提供。
RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"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
例項。
方法:cacheContents.list
列出 CachedContents。
端點
取得
https://generativelanguage.googleapis.com/v1beta/cachedContents
查詢參數
pageSize
integer
選用設定。要傳回的快取內容數量上限。服務傳回的產品數量可能會少於這個值。如未指定,系統會傳回部分預設 (低於上限) 項目數量。值的數量上限是 1000;超過 1000 個值會強制轉換為 1000。
pageToken
string
選用設定。屬於接收自前一個 cachedContents.list
呼叫的網頁權杖。提供此項目即可擷取後續網頁。
進行分頁時,提供至 cachedContents.list
的所有其他參數須與提供網頁權杖的呼叫相符。
要求主體
要求主體必須為空白。
回應主體
含有 CachedContents 清單的回應。
如果成功,回應主體會含有以下結構的資料:
cachedContents[]
object (CachedContent
)
快取內容清單。
nextPageToken
string
可做為 pageToken
傳送的權杖,用於擷取後續網頁。如果省略這個欄位,就不會有後續頁面。
JSON 表示法 |
---|
{
"cachedContents": [
{
object ( |
方法:cacheContents.get
讀取 CachedContent 資源。
端點
取得
https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}
路徑參數
name
string
必要欄位。參照內容快取項目的資源名稱。格式:cachedContents/{id}
格式為 cachedContents/{cachedcontent}
。
要求主體
要求主體必須為空白。
要求範例
Python
Node.js
Go
貝殼
回應主體
如果成功,回應主體會包含 CachedContent
的執行例項。
方法:cacheContents.patch
更新 CachedContent 資源 (只有到期時間才會更新)。
端點
修補程式
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」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"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
的執行例項。
方法:cacheContents.delete
刪除 CachedContent 資源。
端點
刪除
https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}
路徑參數
name
string
必要欄位。參照內容快取項目格式的資源名稱:cachedContents/{id}
,格式為 cachedContents/{cachedcontent}
。
要求主體
要求主體必須為空白。
要求範例
Python
Node.js
Go
貝殼
回應主體
如果成功,回應主體會是空白的。
REST 資源:CacheContents
- 資源:CachedContent
- 內容
- 零件
- Blob
- FunctionCall (函式呼叫)
- FunctionResponse
- 檔案資料
- ExecutableCode
- 語言
- CodeExecutionResult
- 結果
- 工具
- 函式宣告
- 結構定義
- 類型
- CodeExecution
- 工具設定
- FunctionCallingConfig
- 模式
- 使用中繼資料
- 方法
資源:CachedContent
已預先處理的內容,可用於後續向 GenerativeService 要求
快取內容只能用於建立時使用的模型。
contents[]
object (Content
)
選用設定。僅限輸入。不可變動。要快取的內容。
tools[]
object (Tool
)
選用設定。僅限輸入。不可變動。模型可以用來產生下一次回應的 Tools
清單
createTime
string (Timestamp
format)
僅供輸出。快取項目的建立時間。
RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"2014-10-02T15:01:23Z"
和 "2014-10-02T15:01:23.045123456Z"
。
updateTime
string (Timestamp
format)
僅供輸出。快取項目的上次更新時間 (世界標準時間)。
RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"2014-10-02T15:01:23Z"
和 "2014-10-02T15:01:23.045123456Z"
。
usageMetadata
object (UsageMetadata
)
僅供輸出。快取內容使用方式的中繼資料。
expiration
。指定這項資源的到期日。expiration
只能採用下列其中一種設定:
expireTime
string (Timestamp
format)
資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會在輸出內容中提供。
RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"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
,其中包含字串,代表具有引數及其值的 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][content.part.function_call] 並使用用戶端的引數來執行。模型可能會在回應中填入 [FunctionCall][content.part.function_call] 決定呼叫這些函式的子集。下一個對話回合可能會含有帶有 [content.role]「function」的 [FunctionResponse][content.part.function_response]生成背景資訊。
codeExecution
object (CodeExecution
)
選用設定。可讓模型在產生過程中執行程式碼。
JSON 表示法 |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
根據 OpenAPI 3.03 規格定義的函式宣告結構化表示法。此宣告中包含函式名稱和參數。此函式宣告是程式碼區塊的表示法,可由模型做為 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 類型:浮點值,INTEGER 類型雙倍數:int32,STRING 類型 int64:列舉
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 的元素數量上限。
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 元素的結構定義。
類型
類型包含由 https://spec.openapis.org/oas/v3.0.3#data-types 定義的 OpenAPI 資料類型清單
列舉 | |
---|---|
TYPE_UNSPECIFIED |
未指定,請勿使用。 |
STRING |
字串類型。 |
NUMBER |
數字類型。 |
INTEGER |
整數類型。 |
BOOLEAN |
布林值類型。 |
ARRAY |
陣列類型。 |
OBJECT |
物件類型。 |
CodeExecution
這個類型沒有任何欄位。
可執行模型產生的程式碼,並自動將結果傳回模型的工具。
另請參閱僅在使用這項工具時產生的 ExecutableCode
和 CodeExecutionResult
。
ToolConfig
此工具設定包含可在要求中指定 Tool
使用方式的參數。
functionCallingConfig
object (FunctionCallingConfig
)
選用設定。函式呼叫設定。
JSON 表示法 |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
指定函式呼叫行為的設定。
mode
enum (Mode
)
選用設定。指定應執行函式呼叫的模式,如果未指定,預設值將設為「AUTO」。
allowedFunctionNames[]
string
選用設定。一組函式名稱,如果提供此組合,可限制模型將呼叫的函式。
只有在模式為「任意」時才需要設定這個屬性。函式名稱應與 [FunctionDeclaration.name] 相符。如果將 mode 設為 Any,模型會根據提供的函式名稱集預測函式呼叫。
JSON 表示法 |
---|
{
"mode": enum ( |
模式
定義執行模式,以定義函式呼叫的執行行為。
列舉 | |
---|---|
MODE_UNSPECIFIED |
未指定的函式呼叫模式。請勿使用這個值。 |
AUTO |
預設模型行為,模型會決定預測函式呼叫或自然語言回應。 |
ANY |
模型只能預測函式呼叫。如果「allowedFunctionNames」已設定後,預測函式呼叫將僅限於「allowedFunctionNames」中的任一條件,否則預測函式呼叫會是提供的任一「functionDeclarations」。 |
NONE |
模型不會預測任何函式呼叫。模型行為與傳遞任何函式宣告時的行為相同。 |
UsageMetadata
快取內容使用方式的中繼資料。
totalTokenCount
integer
快取內容耗用的權杖總數。
JSON 表示法 |
---|
{ "totalTokenCount": integer } |