借助上下文缓存,您可以保存和重复使用预计算的输入 token,例如在询问同一媒体文件的不同问题时。这可能会节省费用并提高速度,具体取决于使用情况。如需详细了解,请参阅上下文缓存指南。
方法:cachedContents.create
创建 CachedContent 资源。
端点
帖子https://generativelanguage.googleapis.com/v1beta/cachedContents
请求正文
请求正文包含一个 CachedContent
实例。
contents[]
object (Content
)
可选。仅限输入。不可变。要缓存的内容。
tools[]
object (Tool
)
可选。仅限输入。不可变。模型可能用于生成下一个回答的 Tools
列表
expiration
Union type
expiration
只能是下列其中一项:expireTime
string (Timestamp
format)
资源被视为过期时的时间戳(世界协调时间)。无论输入中发送的是什么内容,输出中始终都会提供此时间戳。
采用 RFC 3339 标准,生成的输出将始终在末尾带 Z,并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例:"2014-10-02T15:01:23Z"
、"2014-10-02T15:01:23.045123456Z"
或 "2014-10-02T15:01:23+05:30"
。
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
)
可选。仅限输入。不可变。工具配置。此配置会供所有工具共用。
响应正文
如果成功,响应正文将包含一个新创建的 CachedContent
实例。
方法:cachedContents.list
列出 CachedContent。
端点
gethttps://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 资源。
端点
gethttps://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}
路径参数
name
string
必需。引用内容缓存条目的资源名称。格式:cachedContents/{id}
采用 cachedContents/{cachedcontent}
格式。
请求正文
请求正文必须为空。
响应正文
如果成功,则响应正文包含一个 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
Union type
expiration
只能是下列其中一项:expireTime
string (Timestamp
format)
资源被视为过期时的时间戳(世界协调时间)。无论输入中发送的是什么内容,输出中始终都会提供此时间戳。
采用 RFC 3339 标准,生成的输出将始终在末尾带 Z,并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例:"2014-10-02T15:01:23Z"
、"2014-10-02T15:01:23.045123456Z"
或 "2014-10-02T15:01:23+05:30"
。
ttl
string (Duration
format)
仅限输入。此资源的新 TTL,仅限输入。
该时长以秒为单位,最多包含九个小数位,以“s
”结尾。示例:"3.5s"
。
name
string
可选。标识符。引用缓存内容的资源名称。格式:cachedContents/{id}
响应正文
如果成功,则响应正文包含一个 CachedContent
实例。
方法:cachedContents.delete
删除 CachedContent 资源。
端点
删除https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}
路径参数
name
string
必需。引用内容缓存条目的资源名称。格式:cachedContents/{id}
。采用 cachedContents/{cachedcontent}
格式。
请求正文
请求正文必须为空。
响应正文
如果成功,则响应正文为空的 JSON 对象。
REST 资源:cachedContents
- 资源:CachedContent
- 内容
- 部分
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- 语言
- CodeExecutionResult
- 结果
- 工具
- FunctionDeclaration
- 架构
- 类型
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- Mode
- CodeExecution
- GoogleSearch
- ToolConfig
- FunctionCallingConfig
- Mode
- UsageMetadata
- 方法
资源:CachedContent
已预处理的内容,可在后续向 GenerativeService 发出的请求中使用。
缓存的内容只能与其创建时所用的模型搭配使用。
contents[]
object (Content
)
可选。仅限输入。不可变。要缓存的内容。
tools[]
object (Tool
)
可选。仅限输入。不可变。模型可能用于生成下一个回答的 Tools
列表
createTime
string (Timestamp
format)
仅限输出。缓存条目的创建时间。
采用 RFC 3339 标准,生成的输出将始终在末尾带 Z,并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例:"2014-10-02T15:01:23Z"
、"2014-10-02T15:01:23.045123456Z"
或 "2014-10-02T15:01:23+05:30"
。
updateTime
string (Timestamp
format)
仅限输出。缓存条目的上次更新时间(世界协调时间)。
采用 RFC 3339 标准,生成的输出将始终在末尾带 Z,并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例:"2014-10-02T15:01:23Z"
、"2014-10-02T15:01:23.045123456Z"
或 "2014-10-02T15:01:23+05:30"
。
usageMetadata
object (UsageMetadata
)
仅限输出。有关缓存内容使用情况的元数据。
expiration
Union type
expiration
只能是下列其中一项:expireTime
string (Timestamp
format)
资源被视为过期时的时间戳(世界协调时间)。无论输入中发送的是什么内容,输出中始终都会提供此时间戳。
采用 RFC 3339 标准,生成的输出将始终在末尾带 Z,并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例:"2014-10-02T15:01:23Z"
、"2014-10-02T15:01:23.045123456Z"
或 "2014-10-02T15:01:23+05:30"
。
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 类型来标识媒体的类型和子类型。
thought
boolean
可选。指示相应部件是否是从模型中推断出来的。
data
Union type
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 表示法 |
---|
{ "thought": boolean, // data "text": string, "inlineData": { object ( |
Blob
FunctionCall
从模型返回的预测 FunctionCall
,其中包含表示 FunctionDeclaration.name
的字符串以及参数及其值。
id
string
可选。函数调用的唯一 ID。如果已填充,客户端会执行 functionCall
并返回包含匹配 id
的响应。
name
string
必需。要调用的函数名称。必须是 a-z、A-Z、0-9 或包含下划线和短划线,长度上限为 63。
args
object (Struct
format)
可选。以 JSON 对象格式表示的函数参数和值。
JSON 表示法 |
---|
{ "id": string, "name": string, "args": { object } } |
FunctionResponse
FunctionCall
的结果输出,其中包含表示 FunctionDeclaration.name
的字符串和包含函数的任何输出的结构化 JSON 对象,用作模型的上下文。这应包含根据模型预测生成的 FunctionCall
的结果。
id
string
可选。此响应对应的函数调用的 ID。由客户端填充,以匹配相应的函数调用 id
。
name
string
必需。要调用的函数名称。必须是 a-z、A-Z、0-9 或包含下划线和短划线,长度上限为 63。
response
object (Struct
format)
必需。以 JSON 对象格式表示的函数响应。
JSON 表示法 |
---|
{ "id": string, "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
)
可选。让模型能够在生成过程中执行代码。
googleSearch
object (GoogleSearch
)
可选。GoogleSearch 工具类型。用于在模型中支持 Google 搜索的工具。由 Google 提供支持。
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 参数对象字符串键:参数的名称。参数名称区分大小写。架构值:用于定义参数所用类型的架构。
response
object (Schema
)
可选。以 JSON 架构格式描述此函数的输出。反映 Open API 3.03 响应对象。架构定义了用于函数响应值的类型。
架构
Schema
对象允许定义输入和输出数据类型。这些类型可以是对象,也可以是基元和数组。表示 OpenAPI 3.0 架构对象的选定子集。
type
enum (Type
)
必需。数据类型。
format
string
可选。数据的格式。此方法仅适用于基元数据类型。支持的格式:对于 NUMBER 类型:float、double;对于 INTEGER 类型:int32、int64;对于 STRING 类型:枚举、日期时间
title
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 的必需属性。
minProperties
string (int64 format)
可选。Type.OBJECT 的属性数量下限。
maxProperties
string (int64 format)
可选。Type.OBJECT 的属性数量上限。
minLength
string (int64 format)
可选。适用于类型 STRING 的架构字段
maxLength
string (int64 format)
可选。Type.STRING 的长度上限
pattern
string
可选。类型为 Type.STRING 的模式,用于将字符串限制为正则表达式。
example
value (Value
format)
可选。对象示例。仅当对象是根对象时才会填充。
anyOf[]
object (Schema
)
可选。该值应根据列表中的任何(一个或多个)子架构进行验证。
propertyOrdering[]
string
可选。属性的顺序。不是 OpenAPI 规范中的标准字段。用于确定响应中属性的顺序。
default
value (Value
format)
可选。字段的默认值。根据 JSON 架构,此字段适用于文档生成器,不会影响验证。因此,我们将其包含在此处并忽略,以便发送包含 default
字段的架构的开发者不会收到未知字段错误。
items
object (Schema
)
可选。Type.ARRAY 元素的架构。
minimum
number
可选。适用于类型 INTEGER 和 NUMBER 的架构字段 Type.INTEGER 和 Type.NUMBER 的最小值
maximum
number
可选。Type.INTEGER 和 Type.NUMBER 的最大值
JSON 表示法 |
---|
{ "type": enum ( |
类型
Type 包含 https://spec.openapis.org/oas/v3.0.3#data-types 中定义的 OpenAPI 数据类型列表
枚举 | |
---|---|
TYPE_UNSPECIFIED |
未指定,不应使用。 |
STRING |
字符串类型。 |
NUMBER |
号码类型。 |
INTEGER |
整数类型。 |
BOOLEAN |
布尔值类型。 |
ARRAY |
数组类型。 |
OBJECT |
对象类型。 |
NULL |
null 类型。 |
GoogleSearchRetrieval
此工具由 Google 提供支持,可检索公开 Web 数据以建立依据。
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
指定给定来源的动态检索配置。
JSON 表示法 |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
模式
要在动态检索中使用的预测器模式。
枚举 | |
---|---|
MODE_UNSPECIFIED |
始终触发检索。 |
MODE_DYNAMIC |
仅在系统判定有必要时运行检索。 |
CodeExecution
此类型没有字段。
用于执行模型生成的代码并自动将结果返回给模型的工具。
另请参阅 ExecutableCode
和 CodeExecutionResult
,它们仅在使用此工具时生成。
GoogleSearch
此类型没有字段。
GoogleSearch 工具类型。用于在模型中支持 Google 搜索的工具。由 Google 提供支持。
ToolConfig
工具配置,其中包含用于在请求中指定 Tool
用法的参数。
functionCallingConfig
object (FunctionCallingConfig
)
可选。函数调用配置。
JSON 表示法 |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
模式
通过定义执行模式来定义函数调用的执行行为。
枚举 | |
---|---|
MODE_UNSPECIFIED |
未指定函数调用模式。请勿使用此值。 |
AUTO |
默认模型行为,模型决定预测函数调用或自然语言回答。 |
ANY |
模型会受到限制,始终仅预测函数调用。如果设置了“allowedFunctionNames”,则预测的函数调用将仅限于“allowedFunctionNames”中的任一函数,否则预测的函数调用将是提供的“functionDeclarations”中的任一函数。 |
NONE |
模型不会预测任何函数调用。模型行为与不传递任何函数声明时的行为相同。 |
VALIDATED |
模型决定预测函数调用或自然语言回答,但会使用受限解码来验证函数调用。 |
UsageMetadata
有关缓存内容使用情况的元数据。
totalTokenCount
integer
缓存内容消耗的令牌总数。
JSON 表示法 |
---|
{ "totalTokenCount": integer } |