借助上下文缓存,您可以保存和重复使用预计算的输入令牌,例如在询问同一媒体文件的不同问题时。这可能会节省费用并加快速度,具体取决于使用情况。如需了解详情,请参阅上下文缓存指南。
方法: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 世界协调时间(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
实例。
方法:cachedContents.list
列出 CachedContents。
端点
get 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 ( |
方法:cachedContents.get
读取 CachedContent 资源。
端点
获取 https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}路径参数
name
string
必需。引用内容缓存条目的资源名称。格式:cachedContents/{id}
采用 cachedContents/{cachedcontent}
格式。
请求正文
请求正文必须为空。
示例请求
Python
Node.js
Go
Shell
响应正文
如果成功,则响应正文包含一个 CachedContent
实例。
方法:cachedContents.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
实例。
方法:cachedContents.delete
删除 CachedContent 资源。
端点
删除 https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}路径参数
name
string
必需。引用内容缓存条目的资源名称。格式:cachedContents/{id}
。采用 cachedContents/{cachedcontent}
格式。
请求正文
请求正文必须为空。
示例请求
Python
Node.js
Go
Shell
响应正文
如果成功,则响应正文为空。
REST 资源:cachedContents
- 资源:CachedContent
- 内容
- 部分
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- 语言
- CodeExecutionResult
- 结果
- 工具
- FunctionDeclaration
- 架构
- 类型
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- Mode
- CodeExecution
- ToolConfig
- FunctionCallingConfig
- Mode
- UsageMetadata
- 方法
资源: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)
仅限输出。缓存条目的上次更新时间(世界协调时间)。
时间戳采用 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
返回,并将实参传递给客户端以进行执行。模型可能会决定通过在响应中填充 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 类型:枚举
description
string
可选。参数的简要说明。其中可能包含使用示例。参数说明可以采用 Markdown 格式。
nullable
boolean
可选。指示值是否为 null。
enum[]
string
可选。Type.STRING 元素可能的具有枚举格式的值。例如,我们可以将 Enum 方向定义为:{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 } |