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 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

仅限输出。上次以世界协调时间 (UTC) 更新缓存条目的时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
usageMetadata

object (UsageMetadata)

仅限输出。关于缓存内容使用情况的元数据。
联合字段 expiration。指定此资源何时过期。expiration 只能是下列其中一项：
expireTime

string (Timestamp format)

资源被视为过期时的时间戳（世界协调时间）。无论输入中发送的是什么内容，输出中始终会提供此时间戳。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
ttl

string (Duration format)

仅限输入。此资源的新 TTL（仅限输入）。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
name

string

可选。标识符。引用缓存内容的资源名称。格式：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

原始媒体字节数。

文本不应以原始字节的形式发送，请使用“文本”字段。

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]“函数”生成上下文。

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 参数对象字符串 Key：参数的名称。参数名称区分大小写。架构值：定义参数所用类型的架构。

架构

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

可选。指示值是否为 null。
enum[]

string

可选。采用枚举格式的 Type.STRING 元素的可能值。例如，我们可以将枚举方向定义为：{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 元素的架构。

类型

Type 包含 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_UNSPECIFIED 未指定的函数调用模式。不应使用此值。
AUTO 默认的模型行为，模型决定是预测函数调用还是自然语言响应。
ANY 模型受限于始终只能预测函数调用。如果设置了“allowedFunctionNames”，则预测的函数调用将仅限于“allowedFunctionNames”中的任意一个，否则预测的函数调用将是所提供的“functionDeclarations”中的任意一个。
NONE 模型不会预测任何函数调用。模型行为与不传递任何函数声明时的行为相同。

UsageMetadata

关于缓存内容使用情况的元数据。

JSON 表示法 
{
  "totalTokenCount": integer
}
字段
totalTokenCount

integer

缓存内容使用的令牌总数。

方法

create

 创建 CachedContent 资源。

delete

 删除 CachedContent 资源。

get

 读取 CachedContent 资源。

list

 列出 CachedContents。

patch

 更新 CachedContent 资源（只有到期时间可更新）。