Caching

การแคชบริบทช่วยให้คุณบันทึกและนำโทเค็นอินพุตที่คำนวณไว้ล่วงหน้าซึ่งคุณต้องการใช้ซ้ำมาใช้ได้ เช่น เมื่อถามคำถามต่างๆ เกี่ยวกับไฟล์สื่อเดียวกัน ซึ่งอาจช่วยประหยัดค่าใช้จ่ายและเพิ่มความเร็วได้ ทั้งนี้ขึ้นอยู่กับการใช้งาน ดูคำแนะนำแบบละเอียดได้ที่หัวข้อการแคชบริบท

เมธอด: cachedContents.create

สร้างทรัพยากร CachedContent

ปลายทาง

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

เนื้อความของคำขอ

เนื้อความของคำขอมีอินสแตนซ์ของ CachedContent

ฟิลด์
contents[] object (Content)

ไม่บังคับ อินพุตเท่านั้น เปลี่ยนแปลงไม่ได้ เนื้อหาที่จะแคช

tools[] object (Tool)

ไม่บังคับ อินพุตเท่านั้น เปลี่ยนแปลงไม่ได้ รายการToolsที่โมเดลอาจใช้เพื่อสร้างคำตอบถัดไป

expiration Union type
ระบุว่าทรัพยากรนี้จะหมดอายุเมื่อใด expiration ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
expireTime string (Timestamp format)

การประทับเวลาใน UTC ของเวลาที่ถือว่าทรัพยากรนี้หมดอายุ ระบบจะระบุข้อมูลนี้ในเอาต์พุตเสมอ ไม่ว่าอินพุตจะเป็นอะไรก็ตาม

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย ตัวอย่าง: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"

ttl string (Duration format)

อินพุตเท่านั้น TTL ใหม่สำหรับทรัพยากรนี้ ซึ่งเป็นอินพุตเท่านั้น

ระยะเวลาเป็นวินาทีที่มีเศษทศนิยมได้สูงสุด 9 หลัก โดยลงท้ายด้วย 's' เช่น "3.5s"

displayName string

ไม่บังคับ เปลี่ยนแปลงไม่ได้ ชื่อที่แสดงที่มีความหมายซึ่งผู้ใช้สร้างขึ้นของเนื้อหาที่แคชไว้ มีอักขระ Unicode ได้สูงสุด 128 ตัว

model string

ต้องระบุ เปลี่ยนแปลงไม่ได้ ชื่อของ Model ที่จะใช้สำหรับเนื้อหาที่แคช รูปแบบ: models/{model}

systemInstruction object (Content)

ไม่บังคับ อินพุตเท่านั้น เปลี่ยนแปลงไม่ได้ นักพัฒนาตั้งค่าคำสั่งของระบบ ปัจจุบันมีเฉพาะข้อความ

toolConfig object (ToolConfig)

ไม่บังคับ อินพุตเท่านั้น เปลี่ยนแปลงไม่ได้ การกำหนดค่าเครื่องมือ การกำหนดค่านี้ใช้ร่วมกันสำหรับเครื่องมือทั้งหมด

ตัวอย่างคำขอ

พื้นฐาน

Python

from google import genai
from google.genai import types

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
    ),
)
print(cache)

response = client.models.generate_content(
    model=model_name,
    contents="Please summarize this transcript",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
console.log("Cache created:", cache);

const response = await ai.models.generateContent({
  model: modelName,
  contents: "Please summarize this transcript",
  config: { cachedContent: cache.name },
});
console.log("Response text:", response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"), 
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents: contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)

// Use the cache for generating content.
response, err := client.Models.GenerateContent(
	ctx,
	modelName,
	genai.Text("Please summarize this transcript"),
	&genai.GenerateContentConfig{
		CachedContent: cache.Name,
	},
)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

เปลือกหอย

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=$GEMINI_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=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

ชื่อผู้ส่ง

Python

from google import genai
from google.genai import types

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
    ),
)
cache_name = cache.name  # Save the name for later

# Later retrieve the cache
cache = client.caches.get(name=cache_name)
response = client.models.generate_content(
    model=model_name,
    contents="Find a lighthearted moment from this transcript",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
const cacheName = cache.name; // Save the name for later

// Later retrieve the cache
const retrievedCache = await ai.caches.get({ name: cacheName });
const response = await ai.models.generateContent({
  model: modelName,
  contents: "Find a lighthearted moment from this transcript",
  config: { cachedContent: retrievedCache.name },
});
console.log("Response text:", response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}
cacheName := cache.Name

// Later retrieve the cache.
cache, err = client.Caches.Get(ctx, cacheName, &genai.GetCachedContentConfig{})
if err != nil {
	log.Fatal(err)
}

response, err := client.Models.GenerateContent(
	ctx,
	modelName,
	genai.Text("Find a lighthearted moment from this transcript"),
	&genai.GenerateContentConfig{
		CachedContent: cache.Name,
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Response from cache (create from name):")
printResponse(response)

จากแชท

Python

from google import genai
from google.genai import types

client = genai.Client()
model_name = "gemini-1.5-flash-001"
system_instruction = "You are an expert analyzing transcripts."

# Create a chat session with the given system instruction.
chat = client.chats.create(
    model=model_name,
    config=types.GenerateContentConfig(system_instruction=system_instruction),
)
document = client.files.upload(file=media / "a11.txt")

response = chat.send_message(
    message=["Hi, could you summarize this transcript?", document]
)
print("\n\nmodel:  ", response.text)
response = chat.send_message(
    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 = client.caches.create(
    model=model_name,
    config={
        "contents": chat.get_history(),
        "system_instruction": system_instruction,
    },
)
# Continue the conversation using the cached content.
chat = client.chats.create(
    model=model_name,
    config=types.GenerateContentConfig(cached_content=cache.name),
)
response = chat.send_message(
    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 the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const modelName = "gemini-1.5-flash-001";
const systemInstruction = "You are an expert analyzing transcripts.";

// Create a chat session with the system instruction.
const chat = ai.chats.create({
  model: modelName,
  config: { systemInstruction: systemInstruction },
});
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);

let response = await chat.sendMessage({
  message: createUserContent([
    "Hi, could you summarize this transcript?",
    createPartFromUri(document.uri, document.mimeType),
  ]),
});
console.log("\n\nmodel:", response.text);

response = await chat.sendMessage({
  message: "Okay, could you tell me more about the trans-lunar injection",
});
console.log("\n\nmodel:", response.text);

// To cache the conversation so far, pass the chat history as the list of contents.
const chatHistory = chat.getHistory();
const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: chatHistory,
    systemInstruction: systemInstruction,
  },
});

// Continue the conversation using the cached content.
const chatWithCache = ai.chats.create({
  model: modelName,
  config: { cachedContent: cache.name },
});
response = await chatWithCache.sendMessage({
  message:
    "I didn't understand that last part, could you explain it in simpler language?",
});
console.log("\n\nmodel:", response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
systemInstruction := "You are an expert analyzing transcripts."

// Create initial chat with a system instruction.
chat, err := client.Chats.Create(ctx, modelName, &genai.GenerateContentConfig{
	SystemInstruction: genai.NewContentFromText(systemInstruction, genai.RoleUser),
}, nil)
if err != nil {
	log.Fatal(err)
}

document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}

// Send first message with the transcript.
parts := make([]genai.Part, 2)
parts[0] = genai.Part{Text: "Hi, could you summarize this transcript?"}
parts[1] = genai.Part{
	FileData: &genai.FileData{
		FileURI :      document.URI,
		MIMEType: document.MIMEType,
	},
}

// Send chat message.
resp, err := chat.SendMessage(ctx, parts...)
if err != nil {
	log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())

resp, err = chat.SendMessage(
	ctx, 
	genai.Part{
		Text: "Okay, could you tell me more about the trans-lunar injection",
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())

// To cache the conversation so far, pass the chat history as the list of contents.
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          chat.History(false),
	SystemInstruction: genai.NewContentFromText(systemInstruction, genai.RoleUser),
})
if err != nil {
	log.Fatal(err)
}

// Continue the conversation using the cached history.
chat, err = client.Chats.Create(ctx, modelName, &genai.GenerateContentConfig{
	CachedContent: cache.Name,
}, nil)
if err != nil {
	log.Fatal(err)
}

resp, err = chat.SendMessage(
	ctx, 
	genai.Part{
		Text: "I didn't understand that last part, could you explain it in simpler language?",
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())

เนื้อหาการตอบกลับ

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีอินสแตนซ์ 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

from google import genai

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)
print(client.caches.get(name=cache.name))

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
const retrievedCache = await ai.caches.get({ name: cache.name });
console.log("Retrieved Cache:", retrievedCache);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}

cache, err = client.Caches.Get(ctx, cache.Name, &genai.GetCachedContentConfig{})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Retrieved cache:")
fmt.Println(cache)

เปลือกหอย

curl "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_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

เอาต์พุตเท่านั้น ตัวระบุ ชื่อทรัพยากรที่อ้างอิงถึงเนื้อหาที่แคชไว้ รูปแบบ: cachedContents/{id} มีรูปแบบเป็น cachedContents/{cachedcontent}

พารามิเตอร์การค้นหา

updateMask string (FieldMask format)

รายการช่องที่จะอัปเดต

ซึ่งเป็นรายการชื่อฟิลด์แบบสมบูรณ์ในตัวเองที่คั่นด้วยคอมมา ตัวอย่าง: "user.displayName,photo"

เนื้อความของคำขอ

เนื้อความของคำขอมีอินสแตนซ์ของ CachedContent

ฟิลด์
expiration Union type
ระบุว่าทรัพยากรนี้จะหมดอายุเมื่อใด expiration ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
expireTime string (Timestamp format)

การประทับเวลาใน UTC ของเวลาที่ถือว่าทรัพยากรนี้หมดอายุ ระบบจะระบุข้อมูลนี้ในเอาต์พุตเสมอ ไม่ว่าอินพุตจะเป็นอะไรก็ตาม

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย ตัวอย่าง: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"

ttl string (Duration format)

อินพุตเท่านั้น TTL ใหม่สำหรับทรัพยากรนี้ ซึ่งเป็นอินพุตเท่านั้น

ระยะเวลาเป็นวินาทีที่มีเศษทศนิยมได้สูงสุด 9 หลัก โดยลงท้ายด้วย 's' เช่น "3.5s"

ตัวอย่างคำขอ

Python

from google import genai
from google.genai import types
import datetime

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)

# Update the cache's time-to-live (ttl)
ttl = f"{int(datetime.timedelta(hours=2).total_seconds())}s"
client.caches.update(
    name=cache.name, config=types.UpdateCachedContentConfig(ttl=ttl)
)
print(f"After update:\n {cache}")

# Alternatively, update the expire_time directly
# Update the expire_time directly in valid RFC 3339 format (UTC with a "Z" suffix)
expire_time = (
    (
        datetime.datetime.now(datetime.timezone.utc)
        + datetime.timedelta(minutes=15)
    )
    .isoformat()
    .replace("+00:00", "Z")
)
client.caches.update(
    name=cache.name,
    config=types.UpdateCachedContentConfig(expire_time=expire_time),
)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

let cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});

// Update the cache's time-to-live (ttl)
const ttl = `${2 * 3600}s`; // 2 hours in seconds
cache = await ai.caches.update({
  name: cache.name,
  config: { ttl },
});
console.log("After update (TTL):", cache);

// Alternatively, update the expire_time directly (in RFC 3339 format with a "Z" suffix)
const expireTime = new Date(Date.now() + 15 * 60000)
  .toISOString()
  .replace(/\.\d{3}Z$/, "Z");
cache = await ai.caches.update({
  name: cache.name,
  config: { expireTime: expireTime },
});
console.log("After update (expire_time):", cache);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}

_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)

เปลือกหอย

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_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

from google import genai

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)
client.caches.delete(name=cache.name)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
await ai.caches.delete({ name: cache.name });
console.log("Cache deleted:", cache.name);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}

_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)

เปลือกหอย

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

เนื้อหาการตอบกลับ

หากทำสำเร็จ เนื้อหาการตอบกลับจะเป็นออบเจ็กต์ JSON ว่าง

ทรัพยากร REST: cachedContents

ทรัพยากร: CachedContent

เนื้อหาที่ประมวลผลล่วงหน้าแล้วและใช้ในคำขอที่ตามมาไปยัง GenerativeService ได้

เนื้อหาที่แคชไว้จะใช้ได้กับโมเดลที่ใช้สร้างเท่านั้น

ฟิลด์
contents[] object (Content)

ไม่บังคับ อินพุตเท่านั้น เปลี่ยนแปลงไม่ได้ เนื้อหาที่จะแคช

tools[] object (Tool)

ไม่บังคับ อินพุตเท่านั้น เปลี่ยนแปลงไม่ได้ รายการToolsที่โมเดลอาจใช้เพื่อสร้างคำตอบถัดไป

createTime string (Timestamp format)

เอาต์พุตเท่านั้น เวลาที่สร้างรายการแคช

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย ตัวอย่าง: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"

updateTime string (Timestamp format)

เอาต์พุตเท่านั้น เวลา UTC ที่อัปเดตรายการแคชครั้งล่าสุด

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย ตัวอย่าง: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"

usageMetadata object (UsageMetadata)

เอาต์พุตเท่านั้น ข้อมูลเมตาเกี่ยวกับการใช้งานเนื้อหาที่แคชไว้

expiration Union type
ระบุว่าทรัพยากรนี้จะหมดอายุเมื่อใด expiration ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
expireTime string (Timestamp format)

การประทับเวลาใน UTC ของเวลาที่ถือว่าทรัพยากรนี้หมดอายุ ระบบจะระบุข้อมูลนี้ในเอาต์พุตเสมอ ไม่ว่าอินพุตจะเป็นอะไรก็ตาม

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย ตัวอย่าง: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"

ttl string (Duration format)

อินพุตเท่านั้น TTL ใหม่สำหรับทรัพยากรนี้ ซึ่งเป็นอินพุตเท่านั้น

ระยะเวลาเป็นวินาทีที่มีเศษทศนิยมได้สูงสุด 9 หลัก โดยลงท้ายด้วย 's' เช่น "3.5s"

name string

เอาต์พุตเท่านั้น ตัวระบุ ชื่อทรัพยากรที่อ้างอิงถึงเนื้อหาที่แคชไว้ รูปแบบ: cachedContents/{id}

displayName string

ไม่บังคับ เปลี่ยนแปลงไม่ได้ ชื่อที่แสดงที่มีความหมายซึ่งผู้ใช้สร้างขึ้นของเนื้อหาที่แคชไว้ มีอักขระ Unicode ได้สูงสุด 128 ตัว

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

  // expiration
  "expireTime": string,
  "ttl": string
  // Union type
  "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

Part ต้องมีประเภท MIME ของ IANA ที่กำหนดไว้ซึ่งระบุประเภทและประเภทย่อยของสื่อ หากมีการป้อนไบต์ดิบในช่อง inlineData

ฟิลด์
thought boolean

ไม่บังคับ ระบุว่าโมเดลคิดว่าส่วนนั้นเป็นส่วนใด

thoughtSignature string (bytes format)

ไม่บังคับ ลายเซ็นที่ไม่โปร่งใสสำหรับความคิดเพื่อให้สามารถนำไปใช้ซ้ำในคำขอที่ตามมาได้

สตริงที่เข้ารหัส Base64

data Union type
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

metadata Union type
ควบคุมการประมวลผลข้อมูลล่วงหน้าเพิ่มเติม metadata ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
videoMetadata object (VideoMetadata)

ไม่บังคับ ข้อมูลเมตาของวิดีโอ ควรระบุข้อมูลเมตาเฉพาะในขณะที่แสดงข้อมูลวิดีโอใน inlineData หรือ fileData

การแสดง JSON
{
  "thought": boolean,
  "thoughtSignature": string,

  // data
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  }
  // Union type

  // metadata
  "videoMetadata": {
    object (VideoMetadata)
  }
  // Union type
}

Blob

ไบต์ของสื่อดิบ

ไม่ควรส่งข้อความเป็นไบต์ดิบ ให้ใช้ช่อง "text"

ฟิลด์
mimeType string

ประเภท MIME มาตรฐาน IANA ของข้อมูลต้นทาง ตัวอย่าง: - image/png - image/jpeg หากระบุประเภท MIME ที่ไม่รองรับ ระบบจะแสดงข้อผิดพลาด ดูรายการประเภทที่รองรับทั้งหมดได้ที่รูปแบบไฟล์ที่รองรับ

data string (bytes format)

ไบต์ดิบสำหรับรูปแบบสื่อ

สตริงที่เข้ารหัส Base64

การแสดง JSON
{
  "mimeType": string,
  "data": string
}

FunctionCall

FunctionCall ที่คาดการณ์ซึ่งแสดงผลจากโมเดลที่มีสตริงที่แสดง FunctionDeclaration.name พร้อมอาร์กิวเมนต์และค่าของอาร์กิวเมนต์

ฟิลด์
id string

ไม่บังคับ รหัสที่ไม่ซ้ำกันของการเรียกใช้ฟังก์ชัน หากมีการระบุไว้ ไคลเอ็นต์จะดำเนินการ functionCall และส่งคืนการตอบกลับพร้อม id ที่ตรงกัน

name string

ต้องระบุ ชื่อฟังก์ชันที่จะเรียกใช้ ต้องเป็น a-z, A-Z, 0-9 หรือมีขีดล่างและขีดกลาง โดยมีความยาวสูงสุด 63 อักขระ

args object (Struct format)

ไม่บังคับ พารามิเตอร์และค่าของฟังก์ชันในรูปแบบออบเจ็กต์ JSON

การแสดง JSON
{
  "id": string,
  "name": string,
  "args": {
    object
  }
}

FunctionResponse

เอาต์พุตผลลัพธ์จาก FunctionCall ที่มีสตริงซึ่งแสดง FunctionDeclaration.name และออบเจ็กต์ JSON ที่มีโครงสร้างซึ่งมีเอาต์พุตจากฟังก์ชันจะใช้เป็นบริบทสำหรับโมเดล ซึ่งควรมีผลลัพธ์ของFunctionCallที่สร้างขึ้นตามการคาดการณ์ของโมเดล

ฟิลด์
id string

ไม่บังคับ รหัสของการเรียกใช้ฟังก์ชันที่การตอบกลับนี้มีไว้สำหรับ ไคลเอ็นต์จะสร้างขึ้นเพื่อให้ตรงกับการเรียกฟังก์ชันที่เกี่ยวข้อง id

name string

ต้องระบุ ชื่อฟังก์ชันที่จะเรียกใช้ ต้องเป็น a-z, A-Z, 0-9 หรือมีขีดล่างและขีดกลาง โดยมีความยาวสูงสุด 63 อักขระ

response object (Struct format)

ต้องระบุ การตอบกลับของฟังก์ชันในรูปแบบออบเจ็กต์ JSON

willContinue boolean

ไม่บังคับ สัญญาณที่ระบุว่าการเรียกใช้ฟังก์ชันยังคงดำเนินต่อไป และจะมีการแสดงผลคำตอบเพิ่มเติม ซึ่งจะเปลี่ยนการเรียกใช้ฟังก์ชันให้เป็นเครื่องกำเนิด ใช้ได้กับการเรียกฟังก์ชัน NON_BLOCKING เท่านั้น มิเช่นนั้นระบบจะไม่สนใจ หากตั้งค่าเป็น "เท็จ" ระบบจะไม่พิจารณาคำตอบในอนาคต อนุญาตให้ส่งคืน response ที่ว่างเปล่าพร้อม willContinue=False เพื่อส่งสัญญาณว่าการเรียกฟังก์ชันเสร็จสิ้นแล้ว ซึ่งอาจยังคงทริกเกอร์การสร้างโมเดล หากต้องการหลีกเลี่ยงการเรียกใช้การสร้างและสิ้นสุดการเรียกใช้ฟังก์ชัน ให้ตั้งค่า scheduling เป็น SILENT เพิ่มเติม

scheduling enum (Scheduling)

ไม่บังคับ ระบุวิธีกำหนดเวลาการตอบกลับในการสนทนา ใช้ได้กับการเรียกใช้ฟังก์ชัน NON_BLOCKING เท่านั้น มิเช่นนั้นระบบจะไม่สนใจ ค่าเริ่มต้นคือ WHEN_IDLE

การแสดง JSON
{
  "id": string,
  "name": string,
  "response": {
    object
  },
  "willContinue": boolean,
  "scheduling": enum (Scheduling)
}

Scheduling

ระบุวิธีกำหนดเวลาการตอบกลับในการสนทนา

Enum
SCHEDULING_UNSPECIFIED ค่านี้ไม่ได้ใช้
SILENT เพิ่มผลลัพธ์ลงในบริบทการสนทนาเท่านั้น อย่าขัดจังหวะหรือทริกเกอร์การสร้าง
WHEN_IDLE เพิ่มผลลัพธ์ลงในบริบทการสนทนา แล้วป้อนพรอมต์เพื่อสร้างเอาต์พุตโดยไม่ขัดจังหวะการสร้างที่กำลังดำเนินการอยู่
INTERRUPT เพิ่มผลลัพธ์ลงในบริบทของการสนทนา ขัดจังหวะการสร้างที่กำลังดำเนินการอยู่ และป้อนพรอมต์เพื่อสร้างเอาต์พุต

FileData

ข้อมูลที่อิงตาม URI

ฟิลด์
mimeType string

ไม่บังคับ ประเภท MIME มาตรฐาน IANA ของข้อมูลต้นทาง

fileUri string

ต้องระบุ URI

การแสดง JSON
{
  "mimeType": string,
  "fileUri": string
}

ExecutableCode

โค้ดที่โมเดลสร้างขึ้นซึ่งมีไว้เพื่อดำเนินการ และผลลัพธ์ที่ส่งคืนไปยังโมเดล

สร้างขึ้นเมื่อใช้เครื่องมือ CodeExecution เท่านั้น ซึ่งระบบจะเรียกใช้โค้ดโดยอัตโนมัติ และจะสร้าง CodeExecutionResult ที่เกี่ยวข้องด้วย

ฟิลด์
language enum (Language)

ต้องระบุ ภาษาโปรแกรมของ code

code string

ต้องระบุ โค้ดที่จะดำเนินการ

การแสดง JSON
{
  "language": enum (Language),
  "code": string
}

ภาษา

ภาษาโปรแกรมที่รองรับสำหรับโค้ดที่สร้างขึ้น

Enum
LANGUAGE_UNSPECIFIED ไม่ได้ระบุภาษา ไม่ควรใช้ค่านี้
PYTHON Python >= 3.10 พร้อมใช้งาน numpy และ simpy

CodeExecutionResult

ผลลัพธ์ของการเรียกใช้ ExecutableCode

สร้างขึ้นเมื่อใช้ CodeExecution เท่านั้น และจะอยู่หลัง part ที่มี ExecutableCode เสมอ

ฟิลด์
outcome enum (Outcome)

ต้องระบุ ผลลัพธ์ของการเรียกใช้โค้ด

output string

ไม่บังคับ มี stdout เมื่อการดำเนินการโค้ดสำเร็จ, stderr หรือคำอธิบายอื่นๆ ในกรณีอื่นๆ

การแสดง JSON
{
  "outcome": enum (Outcome),
  "output": string
}

ผลลัพธ์

การแจงนับผลลัพธ์ที่เป็นไปได้ของการเรียกใช้โค้ด

Enum
OUTCOME_UNSPECIFIED สถานะที่ไม่ได้ระบุ ไม่ควรใช้ค่านี้
OUTCOME_OK การดำเนินการกับโค้ดเสร็จสมบูรณ์แล้ว
OUTCOME_FAILED การเรียกใช้โค้ดเสร็จสมบูรณ์แล้ว แต่ไม่สำเร็จ stderr ควรมีเหตุผล
OUTCOME_DEADLINE_EXCEEDED ระบบยกเลิกการดำเนินการโค้ดเนื่องจากใช้เวลานานเกินไป อาจมีหรือไม่มีเอาต์พุตบางส่วน

VideoMetadata

ข้อมูลเมตาจะอธิบายเนื้อหาวิดีโอที่ป้อน

ฟิลด์
startOffset string (Duration format)

ไม่บังคับ ออฟเซ็ตเริ่มต้นของวิดีโอ

ระยะเวลาเป็นวินาทีที่มีเศษทศนิยมได้สูงสุด 9 หลัก โดยลงท้ายด้วย 's' เช่น "3.5s"

endOffset string (Duration format)

ไม่บังคับ ออฟเซ็ตสิ้นสุดของวิดีโอ

ระยะเวลาเป็นวินาทีที่มีเศษทศนิยมได้สูงสุด 9 หลัก โดยลงท้ายด้วย 's' เช่น "3.5s"

fps number

ไม่บังคับ อัตราเฟรมของวิดีโอที่ส่งไปยังโมเดล หากไม่ได้ระบุ ค่าเริ่มต้นจะเป็น 1.0 ช่วง FPS คือ (0.0, 24.0]

การแสดง JSON
{
  "startOffset": string,
  "endOffset": string,
  "fps": number
}

เครื่องมือ

รายละเอียดเครื่องมือที่โมเดลอาจใช้เพื่อสร้างคำตอบ

Tool คือโค้ดที่ช่วยให้ระบบโต้ตอบกับระบบภายนอกเพื่อดำเนินการหรือชุดการดำเนินการนอกเหนือจากความรู้และขอบเขตของโมเดล

ฟิลด์
functionDeclarations[] object (FunctionDeclaration)

ไม่บังคับ รายการของ FunctionDeclarations ที่พร้อมใช้งานสำหรับโมเดลซึ่งใช้สำหรับการเรียกใช้ฟังก์ชันได้

โมเดลหรือระบบไม่ดำเนินการฟังก์ชัน แต่ระบบอาจแสดงผลฟังก์ชันที่กำหนดเป็น FunctionCall พร้อมอาร์กิวเมนต์ไปยังฝั่งไคลเอ็นต์เพื่อดำเนินการแทน โมเดลอาจตัดสินใจเรียกใช้ฟังก์ชันย่อยเหล่านี้โดยการป้อนข้อมูล FunctionCall ในการตอบกลับ การสนทนาครั้งถัดไปอาจมี FunctionResponse พร้อมบริบทการสร้าง Content.role "ฟังก์ชัน" สำหรับการสนทนาครั้งถัดไปของโมเดล

googleSearchRetrieval object (GoogleSearchRetrieval)

ไม่บังคับ เครื่องมือดึงข้อมูลที่ขับเคลื่อนโดย Google Search

codeExecution object (CodeExecution)

ไม่บังคับ ช่วยให้โมเดลสามารถเรียกใช้โค้ดเป็นส่วนหนึ่งของการสร้าง

urlContext object (UrlContext)

ไม่บังคับ เครื่องมือที่รองรับการดึงข้อมูลบริบทของ URL

การแสดง JSON
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  },
  "googleSearch": {
    object (GoogleSearch)
  },
  "urlContext": {
    object (UrlContext)
  }
}

FunctionDeclaration

การแสดงการประกาศฟังก์ชันที่มีโครงสร้างตามที่กำหนดโดยข้อกำหนด OpenAPI 3.03 โดยการประกาศนี้จะรวมชื่อฟังก์ชันและพารามิเตอร์ FunctionDeclaration คือการแสดงบล็อกโค้ดที่โมเดลใช้เป็น Tool และไคลเอ็นต์เรียกใช้ได้

ฟิลด์
name string

ต้องระบุ ชื่อฟังก์ชัน ต้องเป็น a-z, A-Z, 0-9 หรือมีขีดล่างและขีดกลาง โดยมีความยาวสูงสุด 63 อักขระ

description string

ต้องระบุ คำอธิบายสั้นๆ ของฟังก์ชัน

behavior enum (Behavior)

ไม่บังคับ ระบุลักษณะการทำงานของฟังก์ชัน ปัจจุบันรองรับเฉพาะเมธอด BidiGenerateContent

parameters object (Schema)

ไม่บังคับ อธิบายพารามิเตอร์ของฟังก์ชันนี้ แสดงถึงคีย์สตริงของออบเจ็กต์พารามิเตอร์ Open API 3.03: ชื่อของพารามิเตอร์ ชื่อพารามิเตอร์จะคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ค่าสคีมา: สคีมาที่กำหนดประเภทที่ใช้สำหรับพารามิเตอร์

parametersJsonSchema value (Value format)

ไม่บังคับ อธิบายพารามิเตอร์ของฟังก์ชันในรูปแบบ JSON Schema สคีมาต้องอธิบายออบเจ็กต์ที่พร็อพเพอร์ตี้เป็นพารามิเตอร์ของฟังก์ชัน เช่น

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "additionalProperties": false,
  "required": ["name", "age"],
  "propertyOrdering": ["name", "age"]
}

ฟิลด์นี้จะใช้ร่วมกับ parameters ไม่ได้

response object (Schema)

ไม่บังคับ อธิบายเอาต์พุตจากฟังก์ชันนี้ในรูปแบบ JSON Schema แสดงออบเจ็กต์การตอบกลับของ Open API 3.03 สคีมาจะกำหนดประเภทที่ใช้สำหรับค่าการตอบกลับของฟังก์ชัน

responseJsonSchema value (Value format)

ไม่บังคับ อธิบายเอาต์พุตจากฟังก์ชันนี้ในรูปแบบ JSON Schema ค่าที่ระบุโดยสคีมาคือค่าการตอบกลับของฟังก์ชัน

ฟิลด์นี้จะใช้ร่วมกับ response ไม่ได้

การแสดง JSON
{
  "name": string,
  "description": string,
  "behavior": enum (Behavior),
  "parameters": {
    object (Schema)
  },
  "parametersJsonSchema": value,
  "response": {
    object (Schema)
  },
  "responseJsonSchema": value
}

สคีมา

ออบเจ็กต์ Schema ช่วยให้กำหนดประเภทข้อมูลอินพุตและเอาต์พุตได้ ประเภทเหล่านี้อาจเป็นออบเจ็กต์ แต่ก็อาจเป็นค่าดั้งเดิมและอาร์เรย์ได้เช่นกัน แสดงถึงชุดย่อยที่เลือกของออบเจ็กต์สคีมา OpenAPI 3.0

ฟิลด์
type enum (Type)

ต้องระบุ ประเภทข้อมูล

format string

ไม่บังคับ รูปแบบของข้อมูล ใช้สำหรับประเภทข้อมูลพื้นฐานเท่านั้น รูปแบบที่รองรับ: สำหรับประเภท NUMBER: float, double สำหรับประเภท INTEGER: int32, int64 สำหรับประเภท STRING: enum, date-time

title string

ไม่บังคับ ชื่อของสคีมา

description string

ไม่บังคับ คำอธิบายพารามิเตอร์โดยย่อ ซึ่งอาจมีตัวอย่างการใช้งาน คำอธิบายพารามิเตอร์อาจจัดรูปแบบเป็นมาร์กดาวน์

nullable boolean

ไม่บังคับ ระบุว่าค่าอาจเป็น Null หรือไม่

enum[] string

ไม่บังคับ ค่าที่เป็นไปได้ขององค์ประกอบของ Type.STRING ที่มีรูปแบบ enum เช่น เราสามารถกำหนด 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

minProperties string (int64 format)

ไม่บังคับ จำนวนพร็อพเพอร์ตี้ขั้นต่ำสำหรับ Type.OBJECT

maxProperties string (int64 format)

ไม่บังคับ จำนวนพร็อพเพอร์ตี้สูงสุดสำหรับ Type.OBJECT

minLength string (int64 format)

ไม่บังคับ ฟิลด์สคีมาสำหรับประเภท STRING ความยาวขั้นต่ำของ Type.STRING

maxLength string (int64 format)

ไม่บังคับ ความยาวสูงสุดของ Type.STRING

pattern string

ไม่บังคับ รูปแบบของ Type.STRING เพื่อจำกัดสตริงให้นิพจน์ทั่วไป

example value (Value format)

ไม่บังคับ ตัวอย่างออบเจ็กต์ จะมีการป้อนข้อมูลเมื่อออบเจ็กต์เป็นรูทเท่านั้น

anyOf[] object (Schema)

ไม่บังคับ ค่าควรได้รับการตรวจสอบกับสคีมาย่อย (อย่างน้อย 1 รายการ) ในรายการ

propertyOrdering[] string

ไม่บังคับ ลำดับของพร็อพเพอร์ตี้ ไม่ใช่ฟิลด์มาตรฐานในข้อกำหนด Open API ใช้เพื่อกำหนดลำดับของพร็อพเพอร์ตี้ในการตอบกลับ

default value (Value format)

ไม่บังคับ ค่าเริ่มต้นของฟิลด์ ตามสคีมา JSON ฟิลด์นี้มีไว้สำหรับเครื่องมือสร้างเอกสารและไม่มีผลต่อการตรวจสอบ ดังนั้น เราจึงรวมไว้ที่นี่และละเว้นเพื่อให้ผู้พัฒนาที่ส่งสคีมาที่มีฟิลด์ default ไม่ได้รับข้อผิดพลาดเกี่ยวกับฟิลด์ที่ไม่รู้จัก

items object (Schema)

ไม่บังคับ สคีมาขององค์ประกอบของ Type.ARRAY

minimum number

ไม่บังคับ ฟิลด์สคีมาสำหรับประเภทจำนวนเต็มและตัวเลข ค่าต่ำสุดของ Type.INTEGER และ Type.NUMBER

maximum number

ไม่บังคับ ค่าสูงสุดของ Type.INTEGER และ Type.NUMBER

การแสดง JSON
{
  "type": enum (Type),
  "format": string,
  "title": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "minProperties": string,
  "maxProperties": string,
  "minLength": string,
  "maxLength": string,
  "pattern": string,
  "example": value,
  "anyOf": [
    {
      object (Schema)
    }
  ],
  "propertyOrdering": [
    string
  ],
  "default": value,
  "items": {
    object (Schema)
  },
  "minimum": number,
  "maximum": number
}

ประเภท

Type มีรายการประเภทข้อมูล OpenAPI ตามที่กำหนดโดย https://spec.openapis.org/oas/v3.0.3#data-types

Enum
TYPE_UNSPECIFIED ไม่ควรใช้เนื่องจากไม่ได้ระบุ
STRING ประเภทสตริง
NUMBER ประเภทหมายเลข
INTEGER ประเภทจำนวนเต็ม
BOOLEAN ประเภทบูลีน
ARRAY ประเภทอาร์เรย์
OBJECT ประเภทออบเจ็กต์
NULL ประเภท Null

พฤติกรรม

กำหนดลักษณะการทำงานของฟังก์ชัน ค่าเริ่มต้นคือ BLOCKING

Enum
UNSPECIFIED ค่านี้ไม่ได้ใช้
BLOCKING หากตั้งค่าไว้ ระบบจะรอรับการตอบกลับฟังก์ชันก่อนที่จะสนทนาต่อ
NON_BLOCKING หากตั้งค่าไว้ ระบบจะไม่รอรับการตอบกลับของฟังก์ชัน แต่จะพยายามจัดการการตอบกลับของฟังก์ชันเมื่อพร้อมใช้งานในขณะที่ยังคงการสนทนาระหว่างผู้ใช้กับโมเดล

GoogleSearchRetrieval

เครื่องมือดึงข้อมูลเว็บสาธารณะเพื่อการอ้างอิง ซึ่งขับเคลื่อนโดย Google

ฟิลด์
dynamicRetrievalConfig object (DynamicRetrievalConfig)

ระบุการกำหนดค่าการดึงข้อมูลแบบไดนามิกสำหรับแหล่งที่มาที่ระบุ

การแสดง JSON
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

อธิบายตัวเลือกในการปรับแต่งการดึงข้อมูลแบบไดนามิก

ฟิลด์
mode enum (Mode)

โหมดของตัวทำนายที่จะใช้ในการดึงข้อมูลแบบไดนามิก

dynamicThreshold number

เกณฑ์ที่จะใช้ในการดึงข้อมูลแบบไดนามิก หากไม่ได้ตั้งค่า ระบบจะใช้ค่าเริ่มต้นของระบบ

การแสดง JSON
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

โหมด

โหมดของตัวทำนายที่จะใช้ในการดึงข้อมูลแบบไดนามิก

Enum
MODE_UNSPECIFIED ทริกเกอร์การดึงข้อมูลเสมอ
MODE_DYNAMIC เรียกใช้การดึงข้อมูลเมื่อระบบเห็นว่าจำเป็นเท่านั้น

CodeExecution

ประเภทนี้ไม่มีฟิลด์

เครื่องมือที่เรียกใช้โค้ดที่โมเดลสร้างขึ้น และส่งคืนผลลัพธ์ไปยังโมเดลโดยอัตโนมัติ

ดูExecutableCodeและCodeExecutionResultซึ่งจะสร้างขึ้นเมื่อใช้เครื่องมือนี้เท่านั้น

GoogleSearch

ประเภทเครื่องมือ GoogleSearch เครื่องมือที่รองรับ Google Search ในโมเดล ขับเคลื่อนโดย Google

ฟิลด์
timeRangeFilter object (Interval)

ไม่บังคับ กรองผลการค้นหาตามช่วงเวลาที่เฉพาะเจาะจง หากลูกค้าตั้งค่าเวลาเริ่มต้น ก็ต้องตั้งค่าเวลาสิ้นสุดด้วย (และในทางกลับกัน)

การแสดง JSON
{
  "timeRangeFilter": {
    object (Interval)
  }
}

ช่วงเวลา

แสดงช่วงเวลาที่เข้ารหัสเป็นการประทับเวลาเริ่มต้น (รวม) และการประทับเวลาสิ้นสุด (ไม่รวม)

ค่าเริ่มต้นต้องน้อยกว่าหรือเท่ากับค่าสิ้นสุด เมื่อเวลาเริ่มต้นเท่ากับเวลาสิ้นสุด ช่วงเวลาจะว่างเปล่า (ไม่ตรงกับเวลาใดๆ) เมื่อไม่ได้ระบุทั้งจุดเริ่มต้นและจุดสิ้นสุด ช่วงเวลาจะตรงกับเวลาใดก็ได้

ฟิลด์
startTime string (Timestamp format)

ไม่บังคับ จุดเริ่มต้นของช่วงเวลา (รวมวันที่เริ่มต้น)

หากมีการระบุ การประทับเวลาที่ตรงกับช่วงเวลานี้จะต้องเป็นเวลาเดียวกันหรือหลังจากเวลาเริ่มต้น

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย ตัวอย่าง: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"

endTime string (Timestamp format)

ไม่บังคับ จุดสิ้นสุดของช่วงเวลา (ไม่รวมวันที่สิ้นสุด)

หากระบุไว้ การประทับเวลาที่ตรงกับช่วงเวลานี้จะต้องอยู่ก่อนสิ้นสุด

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย ตัวอย่าง: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"

การแสดง JSON
{
  "startTime": string,
  "endTime": string
}

UrlContext

ประเภทนี้ไม่มีฟิลด์

เครื่องมือที่รองรับการดึงข้อมูลบริบทของ URL

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

โหมด

กำหนดลักษณะการทำงานของการเรียกใช้ฟังก์ชันโดยกำหนดโหมดการดำเนินการ

Enum
MODE_UNSPECIFIED โหมดการเรียกใช้ฟังก์ชันที่ไม่ได้ระบุ ไม่ควรใช้ค่านี้
AUTO ลักษณะการทำงานของโมเดลเริ่มต้น โมเดลจะตัดสินใจคาดการณ์การเรียกใช้ฟังก์ชันหรือคำตอบภาษาธรรมชาติ
ANY โมเดลถูกจำกัดให้คาดการณ์การเรียกใช้ฟังก์ชันเท่านั้นเสมอ หากตั้งค่า "allowedFunctionNames" ไว้ การเรียกใช้ฟังก์ชันที่คาดการณ์ไว้จะจำกัดอยู่เพียงหนึ่งใน "allowedFunctionNames" ไม่เช่นนั้น การเรียกใช้ฟังก์ชันที่คาดการณ์ไว้จะเป็นหนึ่งใน "functionDeclarations" ที่ระบุ
NONE โมเดลจะไม่คาดการณ์การเรียกใช้ฟังก์ชันใดๆ ลักษณะการทำงานของโมเดลจะเหมือนกับเมื่อไม่ได้ส่งการประกาศฟังก์ชันใดๆ
VALIDATED โมเดลจะตัดสินใจว่าจะคาดการณ์การเรียกใช้ฟังก์ชันหรือคำตอบที่เป็นภาษาธรรมชาติ แต่จะตรวจสอบการเรียกใช้ฟังก์ชันด้วยการถอดรหัสแบบจำกัด

UsageMetadata

ข้อมูลเมตาเกี่ยวกับการใช้งานเนื้อหาที่แคชไว้

ฟิลด์
totalTokenCount integer

จำนวนโทเค็นทั้งหมดที่เนื้อหาที่แคชใช้

การแสดง JSON
{
  "totalTokenCount": integer
}