通过上下文缓存,您可以保存并重复使用希望重复使用的预计算输入令牌,例如,在询问有关同一媒体文件的不同问题时。这样可以节省费用和加快速度,具体取决于使用情况。如需了解详情,请参阅上下文缓存指南。
方法:cacheContents.create
创建 CachedContent 资源。
端点
帖子
https://generativelanguage.googleapis.com/v1beta/cachedContents
请求正文
请求正文包含一个 CachedContent
实例。
contents[]
object (Content
)
可选。仅限输入。不可变。要缓存的内容。
tools[]
object (Tool
)
可选。仅限输入。不可变。模型可用于生成下一个回答的 Tools
列表
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
)
可选。仅限输入。不可变。工具配置。此配置适用于所有工具。
示例请求
基本
Python
Node.js
Go
Shell
发件人名称
Python
Node.js
Go
来自聊天
Python
Node.js
Go
响应正文
如果成功,响应正文将包含一个新创建的 CachedContent
实例。
方法:cacheContents.list
列出 CachedContents。
端点
领取
https://generativelanguage.googleapis.com/v1beta/cachedContents
查询参数
pageSize
integer
可选。要返回的缓存内容的最大数量。服务返回的值可能小于此值。如果未指定,则会返回一定数量的默认(低于最大)项数。最大值为 1,000;大于 1,000 的值将被强制转换为 1,000。
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
Shell
响应正文
如果成功,则响应正文包含一个 CachedContent
实例。
方法:cacheContents.patch
更新 CachedContent 资源(只有到期时间可更新)。
端点
补丁
https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
路径参数
cachedContent.name
string
可选。标识符。引用缓存内容的资源名称。格式:cachedContents/{id}
,其格式为 cachedContents/{cachedcontent}
。
查询参数
updateMask
string (FieldMask
format)
要更新的字段列表。
这是完全限定字段名称的逗号分隔列表。示例:"user.displayName,photo"
。
请求正文
请求正文包含一个 CachedContent
实例。
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}
示例请求
Python
Node.js
Go
Shell
响应正文
如果成功,则响应正文包含一个 CachedContent
实例。
方法:cacheContents.delete
删除 CachedContent 资源。
端点
删除
https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}
路径参数
name
string
必需。引用内容缓存条目的资源名称:格式:cachedContents/{id}
,其格式为 cachedContents/{cachedcontent}
。
请求正文
请求正文必须为空。
示例请求
Python
Node.js
Go
Shell
响应正文
如果成功,则响应正文为空。
REST 资源:cacheContents
- 资源:CachedContent
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 内容
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 部分
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- Blob
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- FunctionCall
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- FunctionResponse
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- FileData
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ExecutableCode
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 语言
- CodeExecutionResult
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 结果
- 工具
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- FunctionDeclaration
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 架构
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 类型
- CodeExecution
- ToolConfig
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- FunctionCallingConfig
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- Mode
- UsageMetadata
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 方法
资源:CachedContent
经过预处理且可在后续向 GenerativeService 发出的请求中使用的内容。
缓存的内容只能与其创建时所针对的模型一起使用。
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
)
可选。仅限输入。不可变。工具配置。此配置适用于所有工具。
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][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 参数对象字符串 Key:参数的名称。参数名称区分大小写。架构值:定义参数所用类型的架构。
JSON 表示法 |
---|
{
"name": string,
"description": string,
"parameters": {
object ( |
架构
Schema
对象允许定义输入和输出数据类型。这些类型可以是对象,也可以是基元和数组。表示 OpenAPI 3.0 架构对象的选定子集。
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"]}
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 元素的架构。
类型
Type 包含 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_UNSPECIFIED |
未指定的函数调用模式。不应使用此值。 |
AUTO |
默认的模型行为,模型决定是预测函数调用还是自然语言响应。 |
ANY |
模型受限于始终只能预测函数调用。如果为“allowedFunctionNames”设置后,预测的函数调用将仅限于“allowedFunctionNames”中的任意一个,否则预测的函数调用将是所提供的“functionDeclarations”中的任意一个。 |
NONE |
模型不会预测任何函数调用。模型行为与不传递任何函数声明时的行为相同。 |
UsageMetadata
关于缓存内容使用情况的元数据。
totalTokenCount
integer
缓存内容使用的令牌总数。
JSON 表示法 |
---|
{ "totalTokenCount": integer } |