Caching

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

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

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 实例。

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

方法:cacheContents.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 实例。

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

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 实例。

方法:cacheContents.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 资源:cacheContents

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

原始媒体字节数。

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

田野
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

可选。如果代码执行成功,则包含 stdout;否则包含 stderr 或其他说明。

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

结果

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

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

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

架构

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

JSON 表示法
{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": 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 对象类型。

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
}