REST Resource: cachedContents

資源：CachedContent

已預先處理的內容，可用於後續向 GenerativeService 要求

快取內容只能用於建立時使用的模型。

JSON 表示法 
{
  "contents": [
    {
      object (Content)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "usageMetadata": {
    object (UsageMetadata)
  },

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
  "name": string,
  "displayName": string,
  "model": string,
  "systemInstruction": {
    object (Content)
  },
  "toolConfig": {
    object (ToolConfig)
  }
}
欄位
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)

選用設定。僅限輸入。不可變動。工具設定。所有工具都會共用這項設定。

內容

包含訊息多部分內容的基本結構化資料類型。

Content 包含指定 Content 生產者的 role 欄位，以及包含包含訊息回合內容的多部分資料的 parts 欄位。

JSON 表示法 
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}
欄位
parts[]

object (Part)

已排序的 Parts，構成單一訊息。部分的 MIME 類型可能不同。
role

string

選用設定。內容的製作者。必須為「user」或「model」。

適合設為多輪對話，否則可留空或未設定。

配件

包含媒體為多部分 Content 訊息一部分的資料類型。

Part 包含具有相關資料類型的資料。Part 只能包含 Part.data 中系統接受的類型。

如果 inlineData 欄位已填入原始位元組，Part 就必須有固定的 IANA MIME 類型，以識別媒體的類型和子類型。

JSON 表示法 
{

  // Union field data can be only one of the following:
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  }
  // End of list of possible types for union field data.
}
欄位

聯集欄位 data。

data 只能採用下列其中一種設定：
text

string

內嵌文字。
inlineData

object (Blob)

內嵌媒體位元組。
functionCall

object (FunctionCall)

模型傳回的預測 FunctionCall，其中包含字串，代表具有引數及其值的 FunctionDeclaration.name。
functionResponse

object (FunctionResponse)

FunctionCall 的結果輸出中包含代表 FunctionDeclaration.name 的字串，以及包含函式任何輸出內容的結構化 JSON 物件，會做為模型的內容使用。
fileData

object (FileData)

以 URI 為基礎的資料。

Blob

原始媒體位元組。

文字不應以原始位元組的形式傳送，請使用「text」欄位。

JSON 表示法 
{
  "mimeType": string,
  "data": string
}
欄位
mimeType

string

來源資料的 IANA 標準 MIME 類型。範例：- image/png - image/jpeg 如果提供的 MIME 類型不受支援，系統會傳回錯誤。如需支援類型的完整清單，請參閱「支援的檔案格式」。
data

string (bytes format)

媒體格式的原始位元組。

Base64 編碼的字串。

FunctionCall

模型傳回的預測 FunctionCall，其中包含字串，代表具有引數及其值的 FunctionDeclaration.name。

JSON 表示法 
{
  "name": string,
  "args": {
    object
  }
}
欄位
name

string

必要欄位。要呼叫的函式名稱。必須為 a-z、A-Z、0-9，或包含底線和破折號，長度上限為 63 個字元。
args

object (Struct format)

選用設定。JSON 物件格式的函式參數和值。

FunctionResponse

來自 FunctionCall 的結果輸出，其中包含代表 FunctionDeclaration.name 的字串，以及包含函式任何輸出的結構化 JSON 物件，會做為模型的內容。這應包含根據模型預測結果產生的 FunctionCall 結果。

JSON 表示法 
{
  "name": string,
  "response": {
    object
  }
}
欄位
name

string

必要欄位。要呼叫的函式名稱。必須為 a-z、A-Z、0-9，或包含底線和破折號，長度上限為 63 個字元。
response

object (Struct format)

必要欄位。JSON 物件格式的函式回應。

FileData

以 URI 為基礎的資料。

JSON 表示法 
{
  "mimeType": string,
  "fileUri": string
}
欄位
mimeType

string

選用設定。來源資料的 IANA 標準 MIME 類型。
fileUri

string

必要欄位。URI。

工具

模型可能用來產生回應的工具詳細資料。

Tool 是一段程式碼，可讓系統與外部系統互動，在模型知識和範圍外，執行操作或一組動作。

JSON 表示法 
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ]
}
欄位
functionDeclarations[]

object (FunctionDeclaration)

選用設定。可用於函式呼叫的模型可用的 FunctionDeclarations 清單。

模型或系統不會執行該函式。相反地，系統可能會將已定義的函式傳回為 [FunctionCall][content.part.function_call] 並使用用戶端的引數來執行。模型可能會在回應中填入 [FunctionCall][content.part.function_call] 決定呼叫部分函式。下一個對話回合可能會包含 [FunctionResponse][content.part.function_response] 和 [content.role]「function」生成背景資訊，供下次模型轉彎使用。

FunctionDeclaration

根據 OpenAPI 3.03 規格定義的函式宣告結構化表示法。此宣告中包含函式名稱和參數。此函式宣告是程式碼區塊的表示法，可由模型做為 Tool 使用，並由用戶端執行。

JSON 表示法 
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  }
}
欄位
name

string

必要欄位。函式的名稱。必須為 a-z、A-Z、0-9，或包含底線和破折號，長度上限為 63 個字元。
description

string

必要欄位。這個函式的簡短說明。
parameters

object (Schema)

選用設定。說明這個函式的參數。反映 Open API 3.03 參數物件字串金鑰：參數名稱。參數名稱須區分大小寫。結構定義值：定義參數所用類型的結構定義。

結構定義

Schema 物件可讓您定義輸入和輸出資料類型。這些型別可以是物件，也可以是原始和陣列。代表 OpenAPI 3.0 結構定義物件的選取子集。

JSON 表示法 
{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "items": {
    object (Schema)
  }
}
欄位
type

enum (Type)

必要欄位。資料類型。
format

string

選用設定。資料的格式，僅適用於原始資料類型。支援的格式：NUMBER 類型：浮點值、INTEGER 類型雙倍數：int32、int64
description

string

選用設定。參數的簡短說明。包含使用範例。參數說明的格式必須為 Markdown。
nullable

boolean

選用設定。指出值是否為空值。
enum[]

string

選用設定。Type.STRING 元素的可能值採用列舉格式。舉例來說，我們可以將 Enum Direction 定義為：{type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
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 物件類型。

ToolConfig

此工具設定包含可在要求中指定 Tool 使用方式的參數。

JSON 表示法 
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  }
}
欄位
functionCallingConfig

object (FunctionCallingConfig)

選用設定。函式呼叫設定。

FunctionCallingConfig

指定函式呼叫行為的設定。

JSON 表示法 
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}
欄位
mode

enum (Mode)

選用設定。指定應執行函式呼叫的模式，如果未指定，預設值將設為「AUTO」。
allowedFunctionNames[]

string

選用設定。一組函式名稱，如果提供此組合，可限制模型將呼叫的函式。

只有在模式為「任意」時才需要設定這個屬性。函式名稱應與 [FunctionDeclaration.name] 相符。如果將 mode 設為 Any，模型會根據提供的函式名稱集預測函式呼叫。

模式

定義執行模式，以定義函式呼叫的執行行為。

列舉
MODE_UNSPECIFIED 未指定的函式呼叫模式。請勿使用這個值。
AUTO 預設模型行為，模型會決定預測函式呼叫或自然語言回應。
ANY 模型只能預測函式呼叫。如果設定「allowedFunctionNames」，則預測函式呼叫將只限於「allowedFunctionNames」的其中一項，否則系統預測的函式呼叫將會是上述任一提供的「functionDeclarations」。
NONE 模型不會預測任何函式呼叫。模型行為與傳遞任何函式宣告時的行為相同。

UsageMetadata

快取內容使用方式的中繼資料。

JSON 表示法 
{
  "totalTokenCount": integer
}
欄位
totalTokenCount

integer

快取內容耗用的權杖總數。

方法

create

 建立 CachedContent 資源。

delete

 刪除 CachedContent 資源。

get

 讀取 CachedContent 資源。

list

 列出 CachedContents。

patch

 更新 CachedContent 資源 (只有到期時間才會更新)。