Caching

借助上下文缓存,您可以保存和重复使用预计算的输入令牌,例如在询问同一媒体文件的不同问题时。这可能会节省费用并提高速度,具体取决于使用情况。如需详细了解,请参阅上下文缓存指南。

方法: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)

可选。仅限输入。不可变。工具配置。此配置会供所有工具共用。

示例请求

基本

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});

console.log(cacheResult);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModelFromCachedContent(cacheResult);
const result = await model.generateContent(
  "Please summarize this transcript.",
);
console.log(result.response.text());

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

modelWithCache := client.GenerativeModelFromCachedContent(cc)
prompt := "Please summarize this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

Shell

wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-1.5-flash-001",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d @request.json \
 > cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-001:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

从名称

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
const cacheName = cacheResult.name; // Save the name for later.

// Later
const getCacheResult = await cacheManager.get(cacheName);
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModelFromCachedContent(getCacheResult);
model.generateContent("Please summarize this transcript.");

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

// Save the name for later
cacheName := cc.Name

// ... Later
cc2, err := client.GetCachedContent(ctx, cacheName)
if err != nil {
	log.Fatal(err)
}
modelWithCache := client.GenerativeModelFromCachedContent(cc2)
prompt := "Find a lighthearted moment from this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

通过聊天

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash-001" });
const chat = model.startChat();

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

let result = await chat.sendMessage([
  "Hi, could you summarize this transcript?",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(`\n\nmodel: ${result.response.text()}`);
result = await chat.sendMessage(
  "Okay, could you tell me more about the trans-lunar injection",
);
console.log(`\n\nmodel: ${result.response.text()}`);

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: await chat.getHistory(),
});

const newModel = genAI.getGenerativeModelFromCachedContent(cacheResult);

const newChat = newModel.startChat();
result = await newChat.sendMessage(
  "I didn't understand that last part, could you explain it in simpler language?",
);
console.log(`\n\nmodel: ${result.response.text()}`);

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

modelName := "gemini-1.5-flash-001"
model := client.GenerativeModel(modelName)
model.SystemInstruction = genai.NewUserContent(genai.Text("You are an expert analyzing transcripts."))

cs := model.StartChat()
resp, err := cs.SendMessage(ctx, genai.Text("Hi, could you summarize this transcript?"), fd)
if err != nil {
	log.Fatal(err)
}

resp, err = cs.SendMessage(ctx, genai.Text("Okay, could you tell me more about the trans-lunar injection"))
if err != nil {
	log.Fatal(err)
}

// To cache the conversation so far, pass the chat history as the list of
// contents.

argcc := &genai.CachedContent{
	Model:             modelName,
	SystemInstruction: model.SystemInstruction,
	Contents:          cs.History,
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

modelWithCache := client.GenerativeModelFromCachedContent(cc)
cs = modelWithCache.StartChat()
resp, err = cs.SendMessage(ctx, genai.Text("I didn't understand that last part, could you please explain it in simpler language?"))
if err != nil {
	log.Fatal(err)
}
printResponse(resp)

响应正文

如果成功,响应正文将包含一个新创建的 CachedContent 实例。

方法:cachedContents.list

列出 CachedContent。

端点

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 (CachedContent)
    }
  ],
  "nextPageToken": string
}

方法:cachedContents.get

读取 CachedContent 资源。

端点

get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

路径参数

name string

必需。引用内容缓存条目的资源名称。格式:cachedContents/{id} 采用 cachedContents/{cachedcontent} 格式。

请求正文

请求正文必须为空。

示例请求

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
const cacheGetResult = await cacheManager.get(cacheResult.name);
console.log(cacheGetResult);

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

// Save the name for later
cacheName := cc.Name

// ... Later
cc2, err := client.GetCachedContent(ctx, cacheName)
if err != nil {
	log.Fatal(err)
}
modelWithCache := client.GenerativeModelFromCachedContent(cc2)
prompt := "Find a lighthearted moment from this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

Shell

curl "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY"

响应正文

如果成功,则响应正文包含一个 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}

示例请求

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
console.log("initial cache data:", cacheResult);
const cacheUpdateResult = await cacheManager.update(cacheResult.name, {
  cachedContent: {
    // 2 hours
    ttlSeconds: 60 * 60 * 2,
  },
});
console.log("updated cache data:", cacheUpdateResult);

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

Shell

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

响应正文

如果成功,则响应正文包含一个 CachedContent 实例。

方法:cachedContents.delete

删除 CachedContent 资源。

端点

删除 https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

路径参数

name string

必需。引用内容缓存条目的资源名称。格式:cachedContents/{id}。采用 cachedContents/{cachedcontent} 格式。

请求正文

请求正文必须为空。

示例请求

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
await cacheManager.delete(cacheResult.name);

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

Shell

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY"

响应正文

如果成功,响应正文将为空的 JSON 对象。

REST 资源:cachedContents

资源: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)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "usageMetadata": {
    object (UsageMetadata)
  },

  // expiration
  "expireTime": string,
  "ttl": string
  // Union type
  "name": string,
  "displayName": string,
  "model": string,
  "systemInstruction": {
    object (Content)
  },
  "toolConfig": {
    object (ToolConfig)
  }
}

内容

包含消息多部分内容的基本结构化数据类型。

Content 包含一个 role 字段,用于指定 Content 的生产方,以及一个 parts 字段,用于包含包含消息回合的多部分数据。

字段
parts[] object (Part)

构成单条消息的有序 Parts。部分可能具有不同的 MIME 类型。

role string

可选。内容的生产者。必须是“user”或“model”。

适合为多轮对话进行设置,否则可以留空或未设置。

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

部分

包含属于多部分 Content 消息一部分的媒体的数据类型。

Part 由具有关联数据类型的数据组成。Part 只能包含 Part.data 中接受的类型之一。

如果 inlineData 字段填充了原始字节,Part 必须具有固定的 IANA MIME 类型,用于标识媒体的类型和子类型。

字段
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 表示法
{

  // data
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  }
  // Union type
}

Blob

原始媒体字节。

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

字段
mimeType string

来源数据的 IANA 标准 MIME 类型。示例:- image/png - image/jpeg 如果提供的 MIME 类型不受支持,系统会返回错误。如需查看支持的类型的完整列表,请参阅支持的文件格式

data string (bytes format)

媒体格式的原始字节。

使用 base64 编码的字符串。

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

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

模型生成的要执行的代码,以及返回给模型的结果。

仅在使用 CodeExecution 工具时生成,该工具会自动执行代码,并生成相应的 CodeExecutionResult

字段
language enum (Language)

必需。code 的编程语言。

code string

必需。要执行的代码。

JSON 表示法
{
  "language": enum (Language),
  "code": string
}

语言

生成的代码支持的编程语言。

枚举
LANGUAGE_UNSPECIFIED 未指定语言。请勿使用此值。
PYTHON Python 3.10 或更高版本,且支持 numpy 和 simpy。

CodeExecutionResult

执行 ExecutableCode 的结果。

仅在使用 CodeExecution 时生成,并且始终位于包含 ExecutableCodepart 后面。

字段
outcome enum (Outcome)

必需。代码执行结果。

output string

可选。代码执行成功时包含标准输出,否则包含标准错误输出或其他说明。

JSON 表示法
{
  "outcome": enum (Outcome),
  "output": string
}

结果

枚举代码执行的可能结果。

枚举
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)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  },
  "googleSearch": {
    object (GoogleSearch)
  }
}

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 响应对象。架构定义了用于函数响应值的类型。

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

架构

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 的必需属性。

propertyOrdering[] string

可选。属性的顺序。不是 OpenAPI 规范中的标准字段。用于确定响应中属性的顺序。

items object (Schema)

可选。Type.ARRAY 元素的架构。

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

类型

Type 包含 https://spec.openapis.org/oas/v3.0.3#data-types 中定义的 OpenAPI 数据类型列表

枚举
TYPE_UNSPECIFIED 未指定,不应使用。
STRING 字符串类型。
NUMBER 号码类型。
INTEGER 整数类型。
BOOLEAN 布尔值类型。
ARRAY 数组类型。
OBJECT 对象类型。

GoogleSearchRetrieval

此工具由 Google 提供支持,可检索公开 Web 数据以建立依据。

字段
dynamicRetrievalConfig object (DynamicRetrievalConfig)

指定给定来源的动态检索配置。

JSON 表示法
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

介绍了自定义动态检索的选项。

字段
mode enum (Mode)

要在动态检索中使用的预测器模式。

dynamicThreshold number

在动态检索中使用的阈值。如果未设置,则使用系统默认值。

JSON 表示法
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

模式

要在动态检索中使用的预测器模式。

枚举
MODE_UNSPECIFIED 始终触发检索。
MODE_DYNAMIC 仅在系统判定有必要时运行检索。

CodeExecution

此类型没有字段。

用于执行模型生成的代码并自动将结果返回给模型的工具。

另请参阅 ExecutableCodeCodeExecutionResult,它们仅在使用此工具时生成。

GoogleSearch

此类型没有字段。

GoogleSearch 工具类型。用于支持“在模型中使用 Google 搜索”的工具。由 Google 提供支持。

ToolConfig

工具配置,其中包含用于在请求中指定 Tool 用法的参数。

字段
functionCallingConfig object (FunctionCallingConfig)

可选。函数调用配置。

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

FunctionCallingConfig

用于指定函数调用行为的配置。

字段
mode enum (Mode)

可选。指定函数调用应采用的执行模式。如果未指定,则默认值将设为 AUTO。

allowedFunctionNames[] string

可选。一组函数名称。如果提供,则会限制模型将调用的函数。

仅当模式为“任意”时,才应设置此字段。函数名称应与 [FunctionDeclaration.name] 相匹配。将模式设置为 ANY 后,模型将从提供的一组函数名称中预测函数调用。

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

模式

通过定义执行模式来定义函数调用的执行行为。

枚举
MODE_UNSPECIFIED 未指定函数调用模式。请勿使用此值。
AUTO 默认模型行为,模型决定预测函数调用或自然语言回答。
ANY 模型被限制为始终仅预测函数调用。如果设置了“allowedFunctionNames”,则预测的函数调用将仅限于“allowedFunctionNames”中的任一函数,否则预测的函数调用将是提供的“functionDeclarations”中的任一函数。
NONE 模型不会预测任何函数调用。模型行为与不传递任何函数声明时的行为相同。

UsageMetadata

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

字段
totalTokenCount integer

缓存内容消耗的令牌总数。

JSON 表示法
{
  "totalTokenCount": integer
}