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 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。例如 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

ttl string (Duration format)

僅限輸入。這項資源的新存留時間 (僅限輸入)。

時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"

name string

選用設定。ID。參照快取內容的資源名稱。格式:cachedContents/{id}

displayName string

選用設定。不可變動。使用者為快取內容產生的有意義的顯示名稱。最多 128 個 Unicode 字元。

model string

必要欄位。不可變動。要用於快取內容的 Model 名稱。格式:models/{model}

systemInstruction object (Content)

選用設定。僅限輸入。不可變動。開發人員設定系統操作說明。目前僅限文字。

toolConfig object (ToolConfig)

選用設定。僅限輸入。不可變動。工具設定。這項設定會與所有工具共用。

要求範例

基本

Python

import google.generativeai as genai

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)

貝殼

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

import google.generativeai as genai

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

import google.generativeai as genai

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

選用設定。要傳回的快取內容數量上限。服務傳回的產品數量可能會少於這個值。如未指定,系統會傳回部分預設 (低於上限) 項目數量。許可的最大值為 1000;超出的數值將一律指定為 1000。

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

import google.generativeai as genai

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)

貝殼

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

回應主體

如果成功,回應主體會包含 CachedContent 的執行例項。

方法:cachedContents.patch

更新 CachedContent 資源 (僅限更新到期日)。

端點

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

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

路徑參數

cachedContent.name string

選用設定。ID。參照快取內容的資源名稱。格式:cachedContents/{id} 格式為 cachedContents/{cachedcontent}

查詢參數

updateMask string (FieldMask format)

要更新的欄位清單。

這是以半形逗號分隔的完整欄位名稱清單。範例:"user.displayName,photo"

要求主體

要求主體包含 CachedContent 的例項。

欄位
聯集欄位 expiration。指定這項資源的到期日。expiration 只能採用下列其中一種設定:
expireTime string (Timestamp format)

資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會顯示在輸出內容中。

RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。例如 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

ttl string (Duration format)

僅限輸入。這項資源的新存留時間 (僅限輸入)。

時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"

name string

選用設定。ID。參照快取內容的資源名稱。格式:cachedContents/{id}

要求範例

Python

import google.generativeai as genai

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)

貝殼

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 資源。

端點

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

路徑參數

name string

必要欄位。參照內容快取項目的資源名稱格式:cachedContents/{id} 格式為 cachedContents/{cachedcontent}

要求主體

要求主體必須為空白。

要求範例

Python

import google.generativeai as genai

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)

貝殼

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 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。範例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

updateTime string (Timestamp format)

僅供輸出。快取項目上次更新的時間 (以世界標準時間為準)。

RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。例如 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

usageMetadata object (UsageMetadata)

僅供輸出。快取內容的使用情形中繼資料。

聯集欄位 expiration。指定這項資源的到期日。expiration 只能是下列其中一項:
expireTime string (Timestamp format)

資源到期時間的時間戳記 (世界標準時間)。不論輸入什麼內容,這項資訊「一律」會顯示在輸出內容中。

RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,最多九個小數位數。例如 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

ttl string (Duration format)

僅限輸入。這項資源的新存留時間 (僅限輸入)。

時間長度以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:"3.5s"

name string

選用設定。ID。參照快取內容的資源名稱。格式: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 包含 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

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

選用設定。當程式碼執行成功時,會包含 stdout;否則會包含 stderr 或其他說明。

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 類型:enum

description string

選用設定。簡短說明參數。包含使用範例。參數說明的格式必須為 Markdown。

nullable boolean

選用設定。指出值是否可能為空值。

enum[] string

選用設定。使用列舉格式的 Type.STRING 元素可能的值。舉例來說,我們可以將 Enum Direction 定義為:{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

選用設定。一組函式名稱,提供後可限制模型要呼叫的函式。

只有在模式為 ANY 時,才應設定此值。函式名稱應與 [FunctionDeclaration.name] 相符。將模式設為「ANY」時,模型會從提供的函式名稱集合中預測函式呼叫。

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

模式

定義執行模式,以便定義函式呼叫的執行行為。

列舉
MODE_UNSPECIFIED 未指定的函式呼叫模式。請勿使用此值。
AUTO 預設模型行為,模型會決定預測函式呼叫或自然語言回應。
ANY 模型只能預測函式呼叫。如果已設定「allowedFunctionNames」,則預測的函式呼叫會限制為「allowedFunctionNames」中的任一函式,否則預測的函式呼叫會是提供的「functionDeclarations」中的任一函式。
NONE 模型不會預測任何函式呼叫。模型的行為與未傳遞任何函式宣告時相同。

UsageMetadata

快取內容的使用情形中繼資料。

欄位
totalTokenCount integer

快取內容耗用的權杖總數。

JSON 表示法
{
  "totalTokenCount": integer
}