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 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"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

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

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

選用設定。要傳回的快取內容數量上限。服務傳回的產品數量可能會少於這個值。如未指定,系統會傳回部分預設 (低於上限) 項目數量。值的數量上限是 1000;超過 1000 個值會強制轉換為 1000。

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)

貝殼

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

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

查詢參數

updateMask string (FieldMask format)

要更新的欄位清單。

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

要求主體

要求主體包含 CachedContent 的例項。

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

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

RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"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 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 的執行例項。

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

貝殼

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

updateTime string (Timestamp format)

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

RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

usageMetadata object (UsageMetadata)

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

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

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

RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"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 包含指定 Content 生產者的 role 欄位,以及包含包含訊息回合內容的多部分資料的 parts 欄位。

,瞭解如何調查及移除這項存取權。
欄位
parts[] object (Part)

已排序的 Parts,構成單一訊息。部分的 MIME 類型可能不同。

role string

選用設定。內容的製作者。必須是「user」或「模型」

適合設為多輪對話,否則可留空或未設定。

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,其中包含字串,代表具有引數及其值的 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 參數物件字串金鑰:參數名稱。參數名稱須區分大小寫。結構定義值:定義參數所用類型的結構定義。

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

結構定義

Schema 物件可讓您定義輸入和輸出資料類型。這些型別可以是物件,也可以是原始和陣列。代表 OpenAPI 3.0 結構定義物件的選取子集。

,瞭解如何調查及移除這項存取權。
欄位
type enum (Type)

必要欄位。資料類型。

format string

選用設定。資料的格式,僅適用於原始資料類型。支援的格式:NUMBER 類型:浮點值,INTEGER 類型雙倍數:int32,STRING 類型 int64:列舉

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 的元素數量上限。

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

類型

類型包含由 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] 相符。如果將 mode 設為 Any,模型會根據提供的函式名稱集預測函式呼叫。

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

模式

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

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

UsageMetadata

快取內容使用方式的中繼資料。

,瞭解如何調查及移除這項存取權。
欄位
totalTokenCount integer

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

JSON 表示法
{
  "totalTokenCount": integer
}