Caching

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

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

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
print(cache)

model = genai.GenerativeModel.from_cached_content(cache)
response = model.generate_content("Please summarize this transcript")
print(response.text)

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

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
cache_name = cache.name  # Save the name for later

# Later
cache = genai.caching.CachedContent.get(cache_name)
apollo_model = genai.GenerativeModel.from_cached_content(cache)
response = apollo_model.generate_content("Find a lighthearted moment from this transcript")
print(response.text)

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

model_name = "gemini-1.5-flash-001"
system_instruction = "You are an expert analyzing transcripts."

model = genai.GenerativeModel(model_name=model_name, system_instruction=system_instruction)
chat = model.start_chat()
document = genai.upload_file(path=media / "a11.txt")
response = chat.send_message(["Hi, could you summarize this transcript?", document])
print("\n\nmodel:  ", response.text)
response = chat.send_message(
    ["Okay, could you tell me more about the trans-lunar injection"]
)
print("\n\nmodel:  ", response.text)

# To cache the conversation so far, pass the chat history as the list of "contents".
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction=system_instruction,
    contents=chat.history,
)
model = genai.GenerativeModel.from_cached_content(cached_content=cache)

# Continue the chat where you left off.
chat = model.start_chat()
response = chat.send_message(
    "I didn't understand that last part, could you explain it in simpler language?"
)
print("\n\nmodel:  ", response.text)

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

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

方法:cachedContents.get

读取 CachedContent 资源。

端点

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

路径参数

name string

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

请求正文

请求正文必须为空。

示例请求

Python

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
print(genai.caching.CachedContent.get(name=cache.name))

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。指定此资源何时过期。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

import datetime

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)

# You can update the ttl
cache.update(ttl=datetime.timedelta(hours=2))
print(f"After update:\n {cache}")

# Or you can update the expire_time
cache.update(expire_time=datetime.datetime.now() + datetime.timedelta(minutes=15))

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

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
cache.delete()

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"

响应正文

如果成功,则响应正文为空。

REST 资源:cachedContents

资源: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)
    }
  ],
  "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)
  }
}

内容

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

Content 包括一个用于指定 Content 提供方的 role 字段,以及一个包含多部分数据(包含消息回合内容)的 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

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 data can be only one of the following:
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  }
  // End of list of possible types for union field data.
}

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 的字符串以及参数及其值。

字段
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

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

仅在使用 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)
  }
}

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)
  }
}

架构

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 元素的架构。

JSON 表示法
{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    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 提供支持。

字段
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,它们仅在使用此工具时生成。

ToolConfig

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

字段
functionCallingConfig object (FunctionCallingConfig)

可选。函数调用配置。

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

FunctionCallingConfig

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

字段
mode enum (Mode)

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

allowedFunctionNames[] string

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

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

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

模式

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

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

UsageMetadata

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

字段
totalTokenCount integer

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

JSON 表示法
{
  "totalTokenCount": integer
}