Caching

שמירת מטמון לפי הקשר מאפשרת לשמור אסימוני קלט שחושבו מראש ולהשתמש בהם שוב ושוב, למשל כששואלים שאלות שונות על אותו קובץ מדיה. כך אפשר לחסוך בעלויות ובמהירות, בהתאם לשימוש. מבוא מפורט זמין במדריך בנושא אחסון ב-cache של הקשר.

שיטה: cachedContents.create

יצירת משאב CachedContent.

נקודת קצה

פרסום https://generativelanguage.googleapis.com/v1beta/cachedContents

גוף הבקשה

גוף הבקשה מכיל מופע של CachedContent.

שדות
contents[] object (Content)

זה שינוי אופציונלי. קלט בלבד. קבוע. התוכן שרוצים לשמור במטמון.

tools[] object (Tool)

זה שינוי אופציונלי. קלט בלבד. קבוע. רשימה של Tools שהמודל יכול להשתמש בהם כדי ליצור את התשובה הבאה

שדה האיחוד expiration. מתי יפוג תוקף המשאב הזה. הערך של expiration יכול להיות רק אחת מהאפשרויות הבאות:
expireTime string (Timestamp format)

חותמת הזמן לפי שעון UTC שמציינת שהתוקף של המשאב הזה פג. הערך הזה תמיד מופיע בפלט, ללא קשר למה שנשלח בקלט.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

קלט בלבד. TTL חדש למשאב הזה, קלט בלבד.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".

name string

זה שינוי אופציונלי. מזהה. שם המשאב שמתייחס לתוכן שנשמר במטמון. פורמט: cachedContents/{id}

displayName string

זה שינוי אופציונלי. קבוע. שם התצוגה המשמעותי שנוצר על ידי המשתמש של התוכן שנשמר במטמון. 128 תווי Unicode לכל היותר.

model string

חובה. קבוע. השם של ה-Model לשימוש בפורמט התוכן ששמור במטמון: models/{model}

systemInstruction object (Content)

זה שינוי אופציונלי. קלט בלבד. בלתי ניתן לשינוי. הוראות מערכת שהגדיר המפתח. בשלב הזה אפשר לצרף רק טקסט.

toolConfig object (ToolConfig)

זה שינוי אופציונלי. קלט בלבד. קבוע. הגדרת הכלי. ההגדרה הזו משותפת לכל הכלים.

בקשה לדוגמה

בסיסית

Python

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
print(cache)

model = genai.GenerativeModel.from_cached_content(cache)
response = model.generate_content("Please summarize this transcript")
print(response.text)

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});

console.log(cacheResult);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModelFromCachedContent(cacheResult);
const result = await model.generateContent(
  "Please summarize this transcript.",
);
console.log(result.response.text());

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

modelWithCache := client.GenerativeModelFromCachedContent(cc)
prompt := "Please summarize this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

קונכייה

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.

שיטה: 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

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

זה שינוי אופציונלי. מזהה. שם המשאב שמתייחס לתוכן שנשמר במטמון. פורמט: cachedContents/{id} הוא מופיע בצורה cachedContents/{cachedcontent}.

פרמטרים של שאילתה

updateMask string (FieldMask format)

רשימת השדות שרוצים לעדכן.

זוהי רשימה מופרדת בפסיקים של שמות שדות מלאים. דוגמה: "user.displayName,photo"

גוף הבקשה

גוף הבקשה מכיל מופע של CachedContent.

שדות
שדה איחוד expiration. מציינת מתי יפוג תוקף המשאב. expiration יכול להיות רק אחת מהאפשרויות הבאות:
expireTime string (Timestamp format)

חותמת הזמן לפי שעון UTC שמציינת שהתוקף של המשאב הזה פג. הערך הזה תמיד מופיע בפלט, ללא קשר למה שנשלח בקלט.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

קלט בלבד. TTL חדש למשאב הזה, קלט בלבד.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".

name string

זה שינוי אופציונלי. מזהה. שם המשאב שמתייחס לתוכן שנשמר במטמון. פורמט: cachedContents/{id}

דוגמה לבקשה

Python

import datetime

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)

# You can update the ttl
cache.update(ttl=datetime.timedelta(hours=2))
print(f"After update:\n {cache}")

# Or you can update the expire_time
cache.update(expire_time=datetime.datetime.now() + datetime.timedelta(minutes=15))

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
console.log("initial cache data:", cacheResult);
const cacheUpdateResult = await cacheManager.update(cacheResult.name, {
  cachedContent: {
    // 2 hours
    ttlSeconds: 60 * 60 * 2,
  },
});
console.log("updated cache data:", cacheUpdateResult);

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

קונכייה

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

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)

פלט בלבד. מועד היצירה של רשומת המטמון.

חותמת זמן בפורמט 'Zulu' בפורמט RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות אחרי הנקודה. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".

updateTime string (Timestamp format)

פלט בלבד. המועד שבו עודכנה לאחרונה רשומת המטמון לפי שעון UTC.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".

usageMetadata object (UsageMetadata)

פלט בלבד. מטא-נתונים לגבי השימוש בתוכן שנשמר במטמון.

שדה איחוד expiration. מתי יפוג תוקף המשאב הזה. הערך של expiration יכול להיות רק אחת מהאפשרויות הבאות:
expireTime string (Timestamp format)

חותמת הזמן לפי שעון UTC שמציינת שהתוקף של המשאב הזה פג. הערך הזה תמיד מופיע בפלט, ללא קשר למה שנשלח בקלט.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

קלט בלבד. TTL חדש למשאב הזה, קלט בלבד.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".

name string

זה שינוי אופציונלי. מזהה. שם המשאב שמתייחס לתוכן שנשמר במטמון. פורמט: cachedContents/{id}

displayName string

זה שינוי אופציונלי. קבוע. שם התצוגה המשמעותי שנוצר על ידי המשתמש של התוכן שנשמר במטמון. 128 תווי Unicode לכל היותר.

model string

חובה. קבוע. השם של ה-Model לשימוש בפורמט התוכן ששמור במטמון: models/{model}

systemInstruction object (Content)

זה שינוי אופציונלי. קלט בלבד. בלתי ניתן לשינוי. הוראות מערכת שהגדיר המפתח. בשלב הזה אפשר לצרף רק טקסט.

toolConfig object (ToolConfig)

זה שינוי אופציונלי. קלט בלבד. קבוע. הגדרת הכלי. ההגדרה הזו משותפת לכל הכלים.

ייצוג JSON
{
  "contents": [
    {
      object (Content)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "usageMetadata": {
    object (UsageMetadata)
  },

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
  "name": string,
  "displayName": string,
  "model": string,
  "systemInstruction": {
    object (Content)
  },
  "toolConfig": {
    object (ToolConfig)
  }
}

תוכן

סוג הנתונים המובנה הבסיסי שמכיל תוכן של הודעה שמחולק למספר חלקים.

Content כולל שדה role שמציין את היוצר של Content ושדה parts שמכיל נתונים בכמה חלקים שמכילים את תוכן תור ההודעה.

שדות
parts[] object (Part)

Parts מסודרים שמרכיבים הודעה אחת. לחלקים יכולים להיות סוגים שונים של MIME.

role string

זה שינוי אופציונלי. היוצר של התוכן. הערך חייב להיות 'משתמש' או 'מודל'.

כדאי להגדיר את הערך הזה בשיחות עם כמה תורנים. אחרת, אפשר להשאיר את השדה ריק או לא להגדיר אותו.

ייצוג ב-JSON
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

חלק

טיפוס נתונים שמכיל מדיה שחלק מתוך הודעה Content שמכילה כמה חלקים.

Part מורכב מנתונים שיש להם סוג נתונים משויך. השדה Part יכול להכיל רק אחד מהסוגים הקבילים ב-Part.data.

אם השדה inlineData מלא בייטים גולמיים, ל-Part חייב להיות סוג MIME קבוע של IANA שמזהה את הסוג ואת תת-הסוג של המדיה.

שדות

שדה איחוד 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

סוג MIME של תקן IANA של נתוני המקור. דוגמאות: ‎- image/png ‎- image/jpeg אם יצוין סוג MIME שאינו נתמך, תוחזר שגיאה. רשימה מלאה של הסוגים הנתמכים זמינה במאמר פורמטים נתמכים של קבצים.

data string (bytes format)

בייטים גולמיים לפורמטים של מדיה.

מחרוזת בקידוד Base64.

ייצוג ב-JSON
{
  "mimeType": string,
  "data": string
}

FunctionCall

הערך המשוער של FunctionCall שהמודל מחזיר, שמכיל מחרוזת שמייצגת את FunctionDeclaration.name עם הארגומנטים והערכים שלהם.

שדות
name string

חובה. השם של הפונקציה שרוצים להפעיל. השם חייב להכיל את התווים a-z,‏ A-Z,‏ 0-9 או קווים תחתונים ומקפים, באורך מקסימלי של 63 תווים.

args object (Struct format)

זה שינוי אופציונלי. הפרמטרים והערכים של הפונקציה בפורמט אובייקט JSON.

ייצוג ב-JSON
{
  "name": string,
  "args": {
    object
  }
}

FunctionResponse

הפלט של התוצאה מ-FunctionCall שמכיל מחרוזת שמייצגת את FunctionDeclaration.name ואובייקט JSON מובנה שמכיל את כל הפלט מהפונקציה משמשים כהקשר של המודל. השדה הזה אמור להכיל את התוצאה של FunctionCall שנוצרה על סמך תחזית המודל.

שדות
name string

חובה. השם של הפונקציה שרוצים להפעיל. השם חייב להכיל את התווים a-z,‏ A-Z,‏ 0-9 או קווים תחתונים ומקפים, באורך מקסימלי של 63 תווים.

response object (Struct format)

חובה. תגובת הפונקציה בפורמט של אובייקט JSON.

ייצוג JSON
{
  "name": string,
  "response": {
    object
  }
}

FileData

נתונים המבוססים על URI.

שדות
mimeType string

זה שינוי אופציונלי. סוג ה-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 הרצת הקוד נמשכה יותר מדי זמן והיא בוטלה. יכול להיות שיופיע פלט חלקי או לא.

כלי

פרטי הכלי שהמודל עשוי להשתמש בהם כדי ליצור תשובה.

Tool הוא קטע קוד שמאפשר למערכת לקיים אינטראקציה עם מערכות חיצוניות כדי לבצע פעולה או קבוצת פעולות מחוץ לידע ולהיקף של המודל.

שדות
functionDeclarations[] object (FunctionDeclaration)

זה שינוי אופציונלי. רשימה של FunctionDeclarations שזמינים למודל ואפשר להשתמש בהם לקריאה לפונקציות.

המודל או המערכת לא מריצים את הפונקציה. במקום זאת, אפשר להחזיר את הפונקציה שהוגדרה כ-FunctionCall עם ארגומנטים לצד הלקוח לצורך ביצוע. המודל עשוי להחליט לקרוא לקבוצת משנה של הפונקציות האלה על ידי אכלוס FunctionCall בתגובה. תור השיחה הבא עשוי לכלול FunctionResponse עם ההקשר של יצירת Content.role 'פונקציה' לתור הבא של המודל.

googleSearchRetrieval object (GoogleSearchRetrieval)

זה שינוי אופציונלי. כלי אחזור שמופעל על ידי חיפוש Google.

codeExecution object (CodeExecution)

זה שינוי אופציונלי. ההגדרה הזו מאפשרת למודל להפעיל קוד כחלק מהיצירה.

ייצוג ב-JSON
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  }
}

FunctionDeclaration

ייצוג מובנה של הצהרת פונקציה כפי שהוגדר במפרט OpenAPI 3.03. ההצהרה הזו כוללת את שם הפונקציה ואת הפרמטרים שלה. FunctionDeclaration הזה מייצג בלוק קוד שאפשר להשתמש בו כ-Tool על ידי המודל ולהריץ אותו על ידי הלקוח.

שדות
name string

חובה. שם הפונקציה. השם חייב להכיל את התווים a-z,‏ A-Z,‏ 0-9 או קווים תחתונים ומקפים, באורך מקסימלי של 63 תווים.

description string

חובה. תיאור קצר של הפונקציה.

parameters object (Schema)

זה שינוי אופציונלי. תיאור הפרמטרים של הפונקציה הזו. משקף את מפתח המחרוזת של אובייקט הפרמטר ב-Open API 3.03: שם הפרמטר. שמות הפרמטרים הם תלויי אותיות רישיות. ערך הסכימה: הסכימה שמגדירה את הסוג שבו נעשה שימוש בפרמטר.

ייצוג ב-JSON
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  }
}

סכימה

האובייקט Schema מאפשר להגדיר את סוגי הנתונים של הקלט והפלט. הסוגים האלה יכולים להיות אובייקטים, אבל גם פרימיטיביים ומערכים. מייצג קבוצת משנה נבחרת של אובייקט הסכימה של OpenAPI 3.0.

שדות
type enum (Type)

חובה. סוג הנתונים.

format string

זה שינוי אופציונלי. הפורמט של הנתונים האפשרות הזו משמשת רק לסוגי נתונים פרימיטיביים. הפורמטים הנתמכים: לסוג NUMBER: float, ‏ double לסוג INTEGER: int32, ‏ int64 לסוג STRING: enum

description string

זה שינוי אופציונלי. תיאור קצר של הפרמטר. המידע הזה יכול לכלול דוגמאות לשימוש. הפורמט של תיאור הפרמטר יכול להיות Markdown.

nullable boolean

זה שינוי אופציונלי. מציין אם הערך יכול להיות null.

enum[] string

זה שינוי אופציונלי. ערכים אפשריים של המרכיב מסוג Type.STRING בפורמט enum. לדוגמה, אפשר להגדיר כיוון של Enum כך : {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 מכיל את רשימת סוגי הנתונים של OpenAPI כפי שהוגדרו במאמר https://spec.openapis.org/oas/v3.0.3#data-types

טיפוסים בני מנייה (enum)
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
}

מצב

המצב של החזוי שישמש לאחזור דינמי.

טיפוסים בני מנייה (enum)
MODE_UNSPECIFIED תמיד מפעילים אחזור.
MODE_DYNAMIC הפעלת אחזור רק כשהמערכת מחליטה שזה נחוץ.

CodeExecution

אין שדות לסוג הזה.

כלי שמפעיל קוד שנוצר על ידי המודל, ומחזיר את התוצאה באופן אוטומטי למודל.

אפשר לעיין גם ב-ExecutableCode וב-CodeExecutionResult, שנוצרים רק כשמשתמשים בכלי הזה.

ToolConfig

הגדרת הכלי שמכילה פרמטרים לציון השימוש של Tool בבקשה.

שדות
functionCallingConfig object (FunctionCallingConfig)

זה שינוי אופציונלי. הגדרה של קריאה לפונקציה.

ייצוג ב-JSON
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  }
}

FunctionCallingConfig

הגדרה של התנהגות קריאה לפונקציה.

שדות
mode enum (Mode)

זה שינוי אופציונלי. מציין את המצב שבו צריך להפעיל את קריאת הפונקציה. אם לא צוין ערך, ערך ברירת המחדל יוגדר כ-auto (אוטומטי).

allowedFunctionNames[] string

זה שינוי אופציונלי. קבוצה של שמות פונקציות, שמספקת הגבלה על הפונקציות שהמודל יפעיל.

צריך להגדיר את האפשרות הזו רק כשהאפשרות Mode מוגדרת כ-ANY. שמות הפונקציות צריכים להתאים ל-[FunctionDeclaration.name]. כשהמצב מוגדר ל-ANY, המודל ינבא קריאה לפונקציה מתוך קבוצת שמות הפונקציות שסופקו.

ייצוג JSON
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}

מצב

המדיניות מגדירה את התנהגות הביצוע של קריאות לפונקציות על ידי הגדרת מצב הביצוע.

טיפוסים בני מנייה (enum)
MODE_UNSPECIFIED מצב קריאה לא מוגדר של פונקציה. לא צריך להשתמש בערך הזה.
AUTO התנהגות ברירת המחדל של המודל, המודל מחליט לחזות קריאה לפונקציה או תגובה משפה טבעית.
ANY המודל מוגבל תמיד לחזות קריאה לפונקציה בלבד. אם מוגדרת האפשרות allowedFunctionNames, קריאת הפונקציה הצפויה תהיה מוגבלת לאחת מהאפשרויות של allowedFunctionNames. אחרת, קריאת הפונקציה הצפויה תהיה אחת מהאפשרויות של functionDeclarations שצוינו.
NONE המודלים לא יחזו קריאות לפונקציות. התנהגות המודל זהה להתנהגות במקרה שלא מעבירים הצהרות על פונקציה.

UsageMetadata

מטא-נתונים לגבי השימוש בתוכן שנשמר במטמון.

שדות
totalTokenCount integer

המספר הכולל של האסימונים שהתוכן ששמור במטמון צורך.

ייצוג ב-JSON
{
  "totalTokenCount": integer
}