Caching

コンテキスト キャッシュを使用すると、同じメディア ファイルについて異なる質問をするときなどに、繰り返し使用する事前計算された入力トークンを保存して再利用できます。これにより、使用状況に応じて費用と速度を節約できます。詳細については、コンテキスト キャッシュのガイドをご覧ください。

メソッド: cacheContents.create

CachedContent リソースを作成します。

エンドポイント

post https://generativelanguage.googleapis.com/v1beta/cachedContents

リクエスト本文

リクエストの本文には CachedContent のインスタンスが含まれます。

フィールド
contents[] object (Content)

省略可。入力のみの変更不可。キャッシュに保存するコンテンツ。

tools[] object (Tool)

省略可。入力のみの変更不可。モデルが次のレスポンスを生成するために使用する可能性がある Tools のリスト

共用体フィールド expiration。このリソースの有効期限を指定します。expiration は次のいずれかになります。
expireTime string (Timestamp format)

このリソースの有効期限が切れたとみなされる、UTC 形式のタイムスタンプ。入力の送信内容にかかわらず、出力には常に指定されます。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

ttl string (Duration format)

入力のみのこのリソースの新しい TTL。入力のみ。

s で終わる小数 9 桁までの秒単位の期間。例: "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)

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

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

省略可。返されるキャッシュに保存されたコンテンツの最大数。サービスが返す値はこれよりも少ないことがあります。指定しない場合は、デフォルトの(最大数以下の)アイテム数が返されます。最大値は 1,000 です。1,000 を超える値は 1,000 に強制変換されます。

pageToken string

省略可。前回の cachedContents.list 呼び出しから受け取ったページトークン。後続のページを取得するにはこれを指定します。

ページ分割を行う場合、cachedContents.list に指定する他のすべてのパラメータは、ページトークンを提供した呼び出しと一致する必要があります。

リクエストの本文

リクエストの本文は空にする必要があります。

レスポンスの本文

CachedContents リストを含むレスポンス。

成功した場合、レスポンスの本文には次の構造のデータが含まれます。

フィールド
cachedContents[] object (CachedContent)

キャッシュに保存されたコンテンツのリスト。

nextPageToken string

次のページを取得するために pageToken として送信できるトークン。このフィールドを省略すると、後続のページはなくなります。

JSON 表現
{
  "cachedContents": [
    {
      object (CachedContent)
    }
  ],
  "nextPageToken": string
}

メソッド: cachedContents.get

CachedContent リソースを読み取ります。

エンドポイント

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

パスパラメータ

name string

必須。コンテンツ キャッシュ エントリを参照するリソース名。形式: cachedContents/{id} 形式は cachedContents/{cachedcontent} です。

リクエスト本文

リクエストの本文は空にする必要があります。

リクエスト例

Python

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)

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

省略可。ID。キャッシュに保存されたコンテンツを参照するリソース名。形式: cachedContents/{id}cachedContents/{cachedcontent} の形式になります。

クエリ パラメータ

updateMask string (FieldMask format)

更新するフィールドのリスト。

完全修飾フィールド名のカンマ区切りリスト。例: "user.displayName,photo"

リクエストの本文

リクエストの本文には CachedContent のインスタンスが含まれます。

フィールド
共用体フィールド expiration。このリソースの有効期限を指定します。expiration は次のいずれかになります。
expireTime string (Timestamp format)

このリソースの有効期限が切れたとみなされる、UTC 形式のタイムスタンプ。入力の送信内容にかかわらず、出力には常に指定されます。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

ttl string (Duration format)

入力のみのこのリソースの新しい TTL。入力のみ。

s で終わる小数 9 桁までの秒単位の期間。例: "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)

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

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)

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「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

updateTime string (Timestamp format)

出力専用。キャッシュ エントリが最後に更新された日時(UTC)。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

usageMetadata object (UsageMetadata)

出力専用。キャッシュに保存されたコンテンツの使用に関するメタデータ。

共用体フィールド expiration。このリソースの有効期限を指定します。expiration は次のいずれかになります。
expireTime string (Timestamp format)

このリソースの有効期限が切れたとみなされる、UTC 形式のタイムスタンプ。入力の送信内容にかかわらず、出力には常に指定されます。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

ttl string (Duration format)

入力のみのこのリソースの新しい TTL。入力のみ。

s で終わる小数 9 桁までの秒単位の期間。例: "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)

1 つのメッセージを構成する順序付きの Parts。パーツによって MIME タイプが異なる場合があります。

role string

省略可。コンテンツの制作者。「user」または「model」のいずれかを指定する必要があります。

マルチターンの会話で設定すると便利ですが、そうでない場合は空白のままにするか、未設定のままにできます。

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

パーツ

マルチパート Content メッセージの一部であるメディアを含むデータ型。

Part は、関連するデータ型を持つデータで構成されます。Part には、Part.data で許可されているタイプのいずれか 1 つだけを含めることができます。

inlineData フィールドが未加工バイトで埋め込まれている場合、Part にはメディアのタイプとサブタイプを識別する固定の IANA MIME タイプが必要です。

フィールド

共用体フィールド data

data は次のいずれかになります。

text string

インライン テキスト。

inlineData object (Blob)

インライン メディア バイト。

functionCall object (FunctionCall)

モデルから返される、予測された FunctionCall。引数とその値を含む FunctionDeclaration.name を表す文字列が含まれます。

functionResponse object (FunctionResponse)

FunctionDeclaration.name を表す文字列と、関数からの出力を含む構造化 JSON オブジェクトを含む FunctionCall の結果の出力が、モデルのコンテキストとして使用されます。

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

FunctionDeclaration.name を表す文字列と、関数からの出力を含む構造化 JSON オブジェクトを含む FunctionCall からの出力が、モデルのコンテキストとして使用されます。これには、モデル予測に基づいて作成された 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 を使用する場合にのみ生成され、常に ExecutableCode を含む part の後に続く。

フィールド
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 を入力することで、これらの関数のサブセットを呼び出すことができます。次の会話ターンには、次のモデルターンの Content.role「関数」生成コンテキストを含む FunctionResponse が含まれる場合があります。

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 パラメータ オブジェクトの文字列 Key: パラメータの名前を反映します。パラメータ名では大文字と小文字が区別されます。スキーマ値: パラメータに使用されるタイプを定義するスキーマ。

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

省略可。値が null の可能性があるかどうかを示します。

enum[] string

省略可。Type.STRING の要素の可能な値(列挙型形式)。たとえば、列挙型の方向は {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
}