Caching

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

שיטה: cachedContents.create

יצירת משאב CachedContent.

נקודת קצה

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

גוף הבקשה

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

שדות
contents[] object (Content)

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

tools[] object (Tool)

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

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

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

חותמת זמן בפורמט 'Zulu' בפורמט RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות אחרי הנקודה. דוגמאות: "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

import google.generativeai as genai

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

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

Node.js

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

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

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

console.log(cacheResult);

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

Go

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

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

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

printResponse(resp)

קונכייה

wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-1.5-flash-001",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d @request.json \
 > cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-001:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

מהשם

Python

import google.generativeai as genai

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

# Later
cache = genai.caching.CachedContent.get(cache_name)
apollo_model = genai.GenerativeModel.from_cached_content(cache)
response = apollo_model.generate_content("Find a lighthearted moment from this transcript")
print(response.text)

Node.js

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

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

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

// Later
const getCacheResult = await cacheManager.get(cacheName);
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModelFromCachedContent(getCacheResult);
model.generateContent("Please summarize this transcript.");

Go

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

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

// Save the name for later
cacheName := cc.Name

// ... Later
cc2, err := client.GetCachedContent(ctx, cacheName)
if err != nil {
	log.Fatal(err)
}
modelWithCache := client.GenerativeModelFromCachedContent(cc2)
prompt := "Find a lighthearted moment from this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

מצ'אט

Python

import google.generativeai as genai

model_name = "gemini-1.5-flash-001"
system_instruction = "You are an expert analyzing transcripts."

model = genai.GenerativeModel(model_name=model_name, system_instruction=system_instruction)
chat = model.start_chat()
document = genai.upload_file(path=media / "a11.txt")
response = chat.send_message(["Hi, could you summarize this transcript?", document])
print("\n\nmodel:  ", response.text)
response = chat.send_message(
    ["Okay, could you tell me more about the trans-lunar injection"]
)
print("\n\nmodel:  ", response.text)

# To cache the conversation so far, pass the chat history as the list of "contents".
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction=system_instruction,
    contents=chat.history,
)
model = genai.GenerativeModel.from_cached_content(cached_content=cache)

# Continue the chat where you left off.
chat = model.start_chat()
response = chat.send_message(
    "I didn't understand that last part, could you explain it in simpler language?"
)
print("\n\nmodel:  ", response.text)

Node.js

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

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash-001" });
const chat = model.startChat();

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

let result = await chat.sendMessage([
  "Hi, could you summarize this transcript?",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(`\n\nmodel: ${result.response.text()}`);
result = await chat.sendMessage(
  "Okay, could you tell me more about the trans-lunar injection",
);
console.log(`\n\nmodel: ${result.response.text()}`);

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: await chat.getHistory(),
});

const newModel = genAI.getGenerativeModelFromCachedContent(cacheResult);

const newChat = newModel.startChat();
result = await newChat.sendMessage(
  "I didn't understand that last part, could you explain it in simpler language?",
);
console.log(`\n\nmodel: ${result.response.text()}`);

Go

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

modelName := "gemini-1.5-flash-001"
model := client.GenerativeModel(modelName)
model.SystemInstruction = genai.NewUserContent(genai.Text("You are an expert analyzing transcripts."))

cs := model.StartChat()
resp, err := cs.SendMessage(ctx, genai.Text("Hi, could you summarize this transcript?"), fd)
if err != nil {
	log.Fatal(err)
}

resp, err = cs.SendMessage(ctx, genai.Text("Okay, could you tell me more about the trans-lunar injection"))
if err != nil {
	log.Fatal(err)
}

// To cache the conversation so far, pass the chat history as the list of
// contents.

argcc := &genai.CachedContent{
	Model:             modelName,
	SystemInstruction: model.SystemInstruction,
	Contents:          cs.History,
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

modelWithCache := client.GenerativeModelFromCachedContent(cc)
cs = modelWithCache.StartChat()
resp, err = cs.SendMessage(ctx, genai.Text("I didn't understand that last part, could you please explain it in simpler language?"))
if err != nil {
	log.Fatal(err)
}
printResponse(resp)

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע חדש של CachedContent.

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

קונכייה

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

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

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

updateMask string (FieldMask format)

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

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

גוף הבקשה

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

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

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

חותמת זמן בפורמט 'Zulu' בפורמט RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות אחרי הנקודה. דוגמאות: "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 google.generativeai as genai

import datetime

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

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

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

Node.js

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

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

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

Go

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

קונכייה

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

גוף התשובה

אם הפעולה מצליחה, גוף התגובה מכיל מופע של CachedContent.

שיטה: cachedContents.delete

מחיקה של משאב CachedContent.

נקודת קצה

מחיקת https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

פרמטרים של נתיב

name string

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

גוף הבקשה

גוף הבקשה חייב להיות ריק.

בקשה לדוגמה

Python

import google.generativeai as genai

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

Node.js

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

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

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

Go

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

קונכייה

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

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יהיה ריק.

משאב REST: cachedContents

משאב: CachedContent

תוכן שעבר עיבוד מראש ואפשר להשתמש בו בבקשה הבאה ל-GenerativeService.

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

שדות
contents[] object (Content)

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

tools[] object (Tool)

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

createTime string (Timestamp format)

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

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

updateTime string (Timestamp format)

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

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

usageMetadata object (UsageMetadata)

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

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

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

חותמת זמן בפורמט 'Zulu' בפורמט RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות אחרי הנקודה. דוגמאות: "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), כפול עבור סוג INTEGER: int32, int64 עבור סוג מחרוזת: 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
}