Caching

ذخیره سازی زمینه به شما امکان می‌دهد تا توکن‌های ورودی از پیش محاسبه شده‌ای را که می‌خواهید بارها از آنها استفاده کنید، ذخیره و دوباره استفاده کنید، به عنوان مثال هنگام پرسیدن سوالات مختلف در مورد یک فایل رسانه‌ای مشابه. این می‌تواند بسته به نوع استفاده، منجر به صرفه‌جویی در هزینه و سرعت شود. برای آشنایی بیشتر، به راهنمای ذخیره سازی زمینه مراجعه کنید.

متد: cachedContents.create

منبع CachedContent را ایجاد می‌کند.

نقطه پایانی

پست https: / /generativelanguage.googleapis.com /v1beta /cachedContents

درخواست بدنه

بدنه درخواست شامل نمونه‌ای از CachedContent است.

فیلدها
contents[] object ( Content )

اختیاری. فقط ورودی. تغییرناپذیر. محتوایی که باید ذخیره شود.

tools[] object ( Tool )

اختیاری. فقط ورودی. تغییرناپذیر. فهرستی از Tools مدل ممکن است برای تولید پاسخ بعدی استفاده کند

Union type expiration
مشخص می‌کند که این منبع چه زمانی منقضی می‌شود. expiration فقط می‌تواند یکی از موارد زیر باشد:
string ( Timestamp format) expireTime (با فرمت Timestamp)

مهر زمانی بر حسب UTC که نشان می‌دهد این منبع منقضی شده است. این مهر زمانی همیشه در خروجی ارائه می‌شود، صرف نظر از اینکه چه چیزی در ورودی ارسال شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رشته ttl string ( Duration format)

فقط ورودی. TTL جدید برای این منبع، فقط ورودی.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

string displayName

اختیاری. تغییرناپذیر. نام نمایشی معنادار تولید شده توسط کاربر برای محتوای ذخیره شده. حداکثر ۱۲۸ کاراکتر یونیکد.

string model

الزامی. تغییرناپذیر. نام Model که برای محتوای ذخیره‌شده استفاده می‌شود. قالب: models/{model}

شیء systemInstruction object ( Content )

اختیاری. فقط ورودی. تغییرناپذیر. دستورالعمل سیستم تنظیم‌شده توسط توسعه‌دهنده. در حال حاضر فقط متن.

شیء toolConfig object ( ToolConfig )

اختیاری. فقط ورودی. تغییرناپذیر. پیکربندی ابزار. این پیکربندی برای همه ابزارها مشترک است.

درخواست نمونه

پایه

پایتون

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)

نود جی اس

// 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);

برو

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'"
    }'

از نام

پایتون

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)

نود جی اس

// 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);

برو

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)

از چت

پایتون

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)

نود جی اس

// 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);

برو

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

نقطه پایانی

دریافت https: / /generativelanguage.googleapis.com /v1beta /cachedContents

پارامترهای پرس و جو

integer pageSize

اختیاری. حداکثر تعداد محتویات ذخیره شده برای برگرداندن. سرویس ممکن است کمتر از این مقدار را برگرداند. اگر مشخص نشود، تعداد پیش‌فرضی (کمتر از حداکثر) از موارد برگردانده می‌شود. حداکثر مقدار ۱۰۰۰ است؛ مقادیر بالاتر از ۱۰۰۰ به ۱۰۰۰ محدود می‌شوند.

string pageToken

اختیاری. یک توکن صفحه که از فراخوانی قبلی cachedContents.list دریافت شده است. این را برای بازیابی صفحه بعدی ارائه دهید.

هنگام صفحه‌بندی، تمام پارامترهای دیگر ارائه شده به cachedContents.list باید با فراخوانی که توکن صفحه را ارائه داده است، مطابقت داشته باشند.

درخواست بدنه

بدنه درخواست باید خالی باشد.

بدنه پاسخ

پاسخ با لیست CachedContents.

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

فیلدها
object ( CachedContent ) cachedContents[] (محتوای ذخیره شده)

فهرست محتویات ذخیره شده در حافظه پنهان.

string nextPageToken

یک توکن، که می‌تواند به عنوان pageToken برای بازیابی صفحه بعدی ارسال شود. اگر این فیلد حذف شود، صفحات بعدی وجود نخواهند داشت.

نمایش JSON
{
  "cachedContents": [
    {
      object (CachedContent)
    }
  ],
  "nextPageToken": string
}

روش: cachedContents.get

منبع CachedContent را می‌خواند.

نقطه پایانی

دریافت https: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}

پارامترهای مسیر

string name

الزامی. نام منبعی که به ورودی حافظه پنهان محتوا اشاره دارد. قالب: cachedContents/{id} به شکل cachedContents/{cachedcontent} است.

درخواست بدنه

بدنه درخواست باید خالی باشد.

درخواست نمونه

پایتون

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

نود جی اس

// 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);

برو

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 را به‌روزرسانی می‌کند (فقط تاریخ انقضا قابل به‌روزرسانی است).

نقطه پایانی

وصله https: / /generativelanguage.googleapis.com /v1beta /{cachedContent.name=cachedContents /*}
PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}

پارامترهای مسیر

string cachedContent.name

فقط خروجی. شناسه. نام منبعی که به محتوای ذخیره شده اشاره دارد. قالب: cachedContents/{id} به شکل cachedContents/{cachedcontent} است.

پارامترهای پرس و جو

رشته updateMask string ( FieldMask format)

لیست فیلدهایی که باید به‌روزرسانی شوند.

این لیستی از نام‌های کامل فیلدها است که با کاما از هم جدا شده‌اند. مثال: "user.displayName,photo" .

درخواست بدنه

بدنه درخواست شامل نمونه‌ای از CachedContent است.

فیلدها
Union type expiration
مشخص می‌کند که این منبع چه زمانی منقضی می‌شود. expiration فقط می‌تواند یکی از موارد زیر باشد:
string ( Timestamp format) expireTime (با فرمت Timestamp)

مهر زمانی بر حسب UTC که نشان می‌دهد این منبع منقضی شده است. این مهر زمانی همیشه در خروجی ارائه می‌شود، صرف نظر از اینکه چه چیزی در ورودی ارسال شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رشته ttl string ( Duration format)

فقط ورودی. TTL جدید برای این منبع، فقط ورودی.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

درخواست نمونه

پایتون

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

نود جی اس

// 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);

برو

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 /*}

پارامترهای مسیر

string name

الزامی. نام منبعی که به ورودی حافظه پنهان محتوا اشاره دارد. قالب: cachedContents/{id} به شکل cachedContents/{cachedcontent} است.

درخواست بدنه

بدنه درخواست باید خالی باشد.

درخواست نمونه

پایتون

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)

نود جی اس

// 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);

برو

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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

شیء usageMetadata object ( UsageMetadata )

فقط خروجی. فراداده در مورد استفاده از محتوای ذخیره شده.

Union type expiration
مشخص می‌کند که این منبع چه زمانی منقضی می‌شود. expiration فقط می‌تواند یکی از موارد زیر باشد:
string ( Timestamp format) expireTime (با فرمت Timestamp)

مهر زمانی بر حسب UTC که نشان می‌دهد این منبع منقضی شده است. این مهر زمانی همیشه در خروجی ارائه می‌شود، صرف نظر از اینکه چه چیزی در ورودی ارسال شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رشته ttl string ( Duration format)

فقط ورودی. TTL جدید برای این منبع، فقط ورودی.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

string name

فقط خروجی. شناسه. نام منبعی که به محتوای ذخیره شده اشاره دارد. قالب: cachedContents/{id}

string displayName

اختیاری. تغییرناپذیر. نام نمایشی معنادار تولید شده توسط کاربر برای محتوای ذخیره شده. حداکثر ۱۲۸ کاراکتر یونیکد.

string model

الزامی. تغییرناپذیر. نام 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 متفاوتی داشته باشند.

string role

اختیاری. تولیدکننده محتوا. باید «کاربر» یا «مدل» باشد.

برای تنظیم مکالمات چند نوبتی مفید است، در غیر این صورت می‌توان آن را خالی گذاشت یا تنظیم نکرد.

نمایش JSON
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

قسمت

نوع داده‌ای که شامل رسانه‌ای است که بخشی از یک پیام Content است.

یک Part شامل داده‌هایی است که یک نوع داده مرتبط دارند. یک Part فقط می‌تواند شامل یکی از انواع پذیرفته شده در Part.data باشد.

اگر فیلد inlineData با بایت‌های خام پر شده باشد، یک Part باید یک نوع MIME IANA ثابت داشته باشد که نوع و زیرنوع رسانه را مشخص کند.

فیلدها
thought boolean

اختیاری. نشان می‌دهد که آیا قطعه از روی مدل ساخته شده است یا خیر.

string ( bytes format) thoughtSignature (با فرمت بایت)

اختیاری. یک امضای غیرشفاف برای فکر تا بتوان در درخواست‌های بعدی از آن استفاده مجدد کرد.

یک رشته کدگذاری شده با base64.

شیء partMetadata object ( Struct format)

فراداده‌های سفارشی مرتبط با قطعه. عامل‌هایی که از genai.Part به عنوان نمایش محتوا استفاده می‌کنند، ممکن است نیاز به پیگیری اطلاعات اضافی داشته باشند. به عنوان مثال، می‌تواند نام فایل/منبعی باشد که قطعه از آن سرچشمه می‌گیرد یا راهی برای مالتی‌پلکس کردن چندین جریان قطعه.

Union type data اتحادیه
data می‌توانند فقط یکی از موارد زیر باشند:
string text

متن درون خطی.

شیء 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 .

Union type metadata
پیش‌پردازش اضافی داده‌ها را کنترل می‌کند. metadata فقط می‌تواند یکی از موارد زیر باشد:
شیء فراداده videoMetadata object ( VideoMetadata )

اختیاری. فراداده ویدئو. فراداده فقط باید زمانی مشخص شود که داده‌های ویدئو در inlineData یا fileData ارائه شده باشند.

نمایش JSON
{
  "thought": boolean,
  "thoughtSignature": string,
  "partMetadata": {
    object
  },

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

لکه

بایت‌های رسانه‌ای خام.

متن نباید به صورت بایت‌های خام ارسال شود، از فیلد «متن» استفاده کنید.

فیلدها
string mimeType

نوع MIME استاندارد IANA برای داده‌های منبع. مثال‌ها: - image/png - image/jpeg اگر نوع MIME پشتیبانی نشده‌ای ارائه شود، خطایی برگردانده می‌شود. برای لیست کاملی از انواع پشتیبانی شده، به فرمت‌های فایل پشتیبانی شده مراجعه کنید.

رشته data string ( bytes format)

بایت‌های خام برای فرمت‌های رسانه‌ای.

یک رشته کدگذاری شده با base64.

نمایش JSON
{
  "mimeType": string,
  "data": string
}

فراخوانی تابع

یک FunctionCall پیش‌بینی‌شده که از مدل برگردانده شده و شامل رشته‌ای است که نشان‌دهنده‌ی FunctionDeclaration.name به همراه آرگومان‌ها و مقادیر آنهاست.

فیلدها
string id

اختیاری. شناسه منحصر به فرد فراخوانی تابع. در صورت پر شدن، کلاینت functionCall اجرا می‌کند و پاسخی را با id منطبق برمی‌گرداند.

string name

الزامی. نام تابعی که قرار است فراخوانی شود. باید az، AZ، ​​0-9 باشد، یا شامل زیرخط و خط تیره باشد، با حداکثر طول 64.

شیء args object ( Struct format)

اختیاری. پارامترها و مقادیر تابع در قالب شیء JSON.

نمایش JSON
{
  "id": string,
  "name": string,
  "args": {
    object
  }
}

تابع پاسخ

خروجی نتیجه از یک FunctionCall که شامل رشته‌ای است که نشان‌دهنده FunctionDeclaration.name و یک شیء JSON ساختاریافته حاوی هرگونه خروجی از تابع است، به عنوان زمینه برای مدل استفاده می‌شود. این باید شامل نتیجه یک FunctionCall باشد که بر اساس پیش‌بینی مدل انجام شده است.

فیلدها
string id

اختیاری. شناسه تابعی که این پاسخ برای آن فراخوانی شده است. توسط کلاینت پر می‌شود تا با id تابع فراخوانی شده مربوطه مطابقت داشته باشد.

string name

الزامی. نام تابعی که قرار است فراخوانی شود. باید az، AZ، ​​0-9 باشد، یا شامل زیرخط و خط تیره باشد، با حداکثر طول 64.

شیء response object ( Struct format)

الزامی. پاسخ تابع در قالب شیء JSON. فراخوانی‌کنندگان می‌توانند از هر کلید دلخواهی که با سینتکس تابع مطابقت دارد برای بازگرداندن خروجی تابع استفاده کنند، مثلاً "خروجی"، "نتیجه" و غیره. به طور خاص، اگر فراخوانی تابع با شکست مواجه شود، پاسخ می‌تواند یک کلید "خطا" داشته باشد تا جزئیات خطا را به مدل برگرداند.

parts[] object ( FunctionResponsePart )

اختیاری. Parts مرتب شده که یک پاسخ تابع را تشکیل می‌دهند. قطعات ممکن است انواع MIME IANA متفاوتی داشته باشند.

boolean willContinue

اختیاری. سیگنال‌هایی مبنی بر ادامه فراخوانی تابع و بازگشت پاسخ‌های بیشتر، فراخوانی تابع را به یک مولد تبدیل می‌کند. فقط برای فراخوانی‌های تابع NON_BLOCKING قابل اجرا است، در غیر این صورت نادیده گرفته می‌شود. اگر روی false تنظیم شود، پاسخ‌های آینده در نظر گرفته نمی‌شوند. مجاز است response خالی را با willContinue=False برگرداند تا نشان دهد که فراخوانی تابع پایان یافته است. این ممکن است همچنان تولید مدل را آغاز کند. برای جلوگیری از آغاز تولید و پایان فراخوانی تابع، scheduling نیز روی SILENT تنظیم کنید.

scheduling enum ( Scheduling )

اختیاری. نحوه‌ی زمان‌بندی پاسخ در مکالمه را مشخص می‌کند. فقط برای فراخوانی‌های تابع NON_BLOCKING قابل اجرا است، در غیر این صورت نادیده گرفته می‌شود. پیش‌فرض WHEN_IDLE است.

نمایش JSON
{
  "id": string,
  "name": string,
  "response": {
    object
  },
  "parts": [
    {
      object (FunctionResponsePart)
    }
  ],
  "willContinue": boolean,
  "scheduling": enum (Scheduling)
}

بخش پاسخ تابع

یک نوع داده حاوی رسانه‌ای که بخشی از یک پیام FunctionResponse است.

یک FunctionResponsePart شامل داده‌هایی است که یک نوع داده مرتبط دارند. یک FunctionResponsePart فقط می‌تواند شامل یکی از انواع پذیرفته شده در FunctionResponsePart.data باشد.

اگر فیلد inlineData با بایت‌های خام پر شده باشد، یک FunctionResponsePart باید یک نوع MIME IANA ثابت داشته باشد که نوع و زیرنوع رسانه را مشخص کند.

فیلدها
Union type data اتحادیه
داده‌های بخش پاسخ تابع. data می‌توانند فقط یکی از موارد زیر باشند:
شیء inlineData object ( FunctionResponseBlob )

بایت‌های رسانه درون‌خطی.

نمایش JSON
{

  // data
  "inlineData": {
    object (FunctionResponseBlob)
  }
  // Union type
}

تابعپاسخBlob

بایت‌های رسانه خام برای پاسخ تابع.

متن نباید به صورت بایت‌های خام ارسال شود، از فیلد 'FunctionResponse.response' استفاده کنید.

فیلدها
string mimeType

نوع MIME استاندارد IANA برای داده‌های منبع. مثال‌ها: - image/png - image/jpeg اگر نوع MIME پشتیبانی نشده‌ای ارائه شود، خطایی برگردانده می‌شود. برای لیست کاملی از انواع پشتیبانی شده، به فرمت‌های فایل پشتیبانی شده مراجعه کنید.

رشته data string ( bytes format)

بایت‌های خام برای فرمت‌های رسانه‌ای.

یک رشته کدگذاری شده با base64.

نمایش JSON
{
  "mimeType": string,
  "data": string
}

زمان‌بندی

نحوه‌ی زمان‌بندی پاسخ در مکالمه را مشخص می‌کند.

انوم‌ها
SCHEDULING_UNSPECIFIED این مقدار بلااستفاده است.
SILENT فقط نتیجه را به متن مکالمه اضافه کنید، وقفه ایجاد نکنید یا تولید را آغاز نکنید.
WHEN_IDLE نتیجه را به متن مکالمه اضافه کنید و از آن بخواهید بدون ایجاد وقفه در تولید مداوم، خروجی تولید کند.
INTERRUPT نتیجه را به متن مکالمه اضافه کنید، تولید مداوم را متوقف کنید و از ما بخواهید خروجی تولید کنیم.

فایل دیتا

داده‌های مبتنی بر URI

فیلدها
string mimeType

اختیاری. نوع MIME استاندارد IANA از داده‌های منبع.

string fileUri

الزامی. آدرس اینترنتی.

نمایش JSON
{
  "mimeType": string,
  "fileUri": string
}

کد اجرایی

کدی که توسط مدل تولید شده و قرار است اجرا شود و نتیجه به مدل بازگردانده می‌شود.

فقط هنگام استفاده از ابزار CodeExecution تولید می‌شود، که در آن کد به طور خودکار اجرا می‌شود و یک CodeExecutionResult مربوطه نیز تولید می‌شود.

فیلدها
شمارش language enum ( Language )

زبان code مورد نیاز.

string code

الزامی. کدی که باید اجرا شود.

نمایش JSON
{
  "language": enum (Language),
  "code": string
}

زبان

زبان‌های برنامه‌نویسی پشتیبانی‌شده برای کد تولید شده.

انوم‌ها
LANGUAGE_UNSPECIFIED زبان نامشخص. این مقدار نباید استفاده شود.
PYTHON پایتون >= 3.10، با numpy و simpy در دسترس است.

نتیجه اجرای کد

نتیجه اجرای ExecutableCode .

فقط هنگام استفاده از CodeExecution تولید می‌شود و همیشه پس از part حاوی ExecutableCode قرار می‌گیرد.

فیلدها
شمارش outcome enum ( Outcome )

الزامی. نتیجه اجرای کد.

string output

اختیاری. در صورت موفقیت‌آمیز بودن اجرای کد، شامل stdout و در غیر این صورت شامل stderr یا توضیحات دیگر می‌شود.

نمایش JSON
{
  "outcome": enum (Outcome),
  "output": string
}

نتیجه

شمارش نتایج احتمالی اجرای کد.

انوم‌ها
OUTCOME_UNSPECIFIED وضعیت نامشخص. این مقدار نباید استفاده شود.
OUTCOME_OK اجرای کد با موفقیت انجام شد.
OUTCOME_FAILED اجرای کد تمام شد اما با شکست مواجه شد. stderr باید دلیل آن را ذکر کند.
OUTCOME_DEADLINE_EXCEEDED اجرای کد برای مدت طولانی ادامه داشت و لغو شد. ممکن است خروجی جزئی وجود داشته باشد یا نباشد.

ویدئوفراداده

متادیتا محتوای ویدیوی ورودی را توصیف می‌کند.

فیلدها
رشته startOffset string ( Duration format)

اختیاری. نقطه شروع ویدیو.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

رشته endOffset string ( Duration format)

اختیاری. آفست انتهای ویدیو.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

number fps

اختیاری. نرخ فریم ویدئوی ارسال شده به مدل. در صورت عدم تعیین، مقدار پیش‌فرض ۱.۰ خواهد بود. محدوده فریم بر ثانیه (۰.۰، ۲۴.۰) است.

نمایش JSON
{
  "startOffset": string,
  "endOffset": string,
  "fps": number
}

ابزار

جزئیات ابزاری که مدل ممکن است برای تولید پاسخ از آنها استفاده کند.

Tool ، قطعه کدی است که سیستم را قادر می‌سازد تا با سیستم‌های خارجی تعامل داشته باشد تا یک یا مجموعه‌ای از اقدامات را خارج از دانش و محدوده مدل انجام دهد.

شناسه بعدی: ۱۲

فیلدها
شیء functionDeclarations[] object ( FunctionDeclaration )

اختیاری. فهرستی از FunctionDeclarations موجود در مدل که می‌توانند برای فراخوانی تابع استفاده شوند.

مدل یا سیستم تابع را اجرا نمی‌کند. در عوض، تابع تعریف‌شده ممکن است به عنوان یک FunctionCall با آرگومان‌هایی برای اجرا به سمت کلاینت بازگردانده شود. مدل ممکن است تصمیم بگیرد با قرار دادن FunctionCall در پاسخ، زیرمجموعه‌ای از این توابع را فراخوانی کند. نوبت بعدی مکالمه ممکن است شامل یک FunctionResponse با زمینه تولید "تابع" Content.role برای نوبت بعدی مدل باشد.

شیء googleSearchRetrieval object ( GoogleSearchRetrieval )

اختیاری. ابزار بازیابی که توسط جستجوی گوگل پشتیبانی می‌شود.

شیء codeExecution object ( CodeExecution )

اختیاری. مدل را قادر می‌سازد تا کد را به عنوان بخشی از تولید اجرا کند.

شیء computerUse object ( ComputerUse )

اختیاری. ابزاری برای پشتیبانی از تعامل مستقیم مدل با کامپیوتر. در صورت فعال بودن، به طور خودکار اعلان‌های تابع مخصوص استفاده از کامپیوتر را پر می‌کند.

شیء urlContext object ( UrlContext )

اختیاری. ابزاری برای پشتیبانی از بازیابی متن URL.

object ( GoogleMaps ) googleMaps (گوگل مپ)

اختیاری. ابزاری که امکان پایه‌گذاری پاسخ مدل با زمینه جغرافیایی مرتبط با پرس‌وجوی کاربر را فراهم می‌کند.

نمایش JSON
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  },
  "googleSearch": {
    object (GoogleSearch)
  },
  "computerUse": {
    object (ComputerUse)
  },
  "urlContext": {
    object (UrlContext)
  },
  "fileSearch": {
    object (FileSearch)
  },
  "googleMaps": {
    object (GoogleMaps)
  }
}

اعلان تابع

نمایش ساختاریافته‌ی اعلان یک تابع، همانطور که توسط مشخصات OpenAPI 3.03 تعریف شده است. نام تابع و پارامترها در این اعلان گنجانده شده‌اند. این اعلان تابع، نمایش بلوکی از کد است که می‌تواند به عنوان یک Tool توسط مدل استفاده و توسط کلاینت اجرا شود.

فیلدها
string name

الزامی. نام تابع. باید az، AZ، ​​اعداد ۰-۹ باشد، یا شامل زیرخط، دونقطه، نقطه و خط تیره باشد، با حداکثر طول ۶۴.

string description

الزامی. شرح مختصری از تابع.

behavior enum ( Behavior )

اختیاری. رفتار تابع را مشخص می‌کند. در حال حاضر فقط توسط متد BidiGenerateContent پشتیبانی می‌شود.

شیء parameters object ( Schema )

اختیاری. پارامترهای این تابع را توصیف می‌کند. رشته شیء پارامتر Open API 3.03 را منعکس می‌کند. کلید: نام پارامتر. نام پارامترها به حروف کوچک و بزرگ حساس هستند. مقدار طرحواره: طرحواره‌ای که نوع مورد استفاده برای پارامتر را تعریف می‌کند.

value ( Value format) parametersJsonSchema (قالب مقدار)

اختیاری. پارامترهای تابع را در قالب 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 است. Schema نوع مورد استفاده برای مقدار پاسخ تابع را تعریف می‌کند.

مقدار responseJsonSchema value ( Value format)

اختیاری. خروجی این تابع را در قالب JSON Schema توصیف می‌کند. مقداری که توسط 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 )

نوع داده. الزامی.

string format

اختیاری. قالب داده‌ها. هر مقداری مجاز است، اما اکثر آنها هیچ عملکرد خاصی را فعال نمی‌کنند.

string title

اختیاری. عنوان طرحواره.

string description

اختیاری. شرح مختصری از پارامتر. این می‌تواند شامل مثال‌هایی از کاربرد باشد. شرح پارامتر می‌تواند به صورت Markdown قالب‌بندی شود.

boolean nullable

اختیاری. نشان می‌دهد که آیا مقدار می‌تواند تهی (null) باشد یا خیر.

string enum[]

اختیاری. مقادیر ممکن برای عنصر Type.STRING با فرمت enum. برای مثال، می‌توانیم یک جهت شمارشی (Enum Direction) را به صورت زیر تعریف کنیم: {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

string ( int64 format) maxItems (با فرمت int64)

اختیاری. حداکثر تعداد عناصر برای 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" } .

string required[]

اختیاری. ویژگی‌های الزامی Type.OBJECT.

رشته minProperties string ( int64 format)

اختیاری. حداقل تعداد ویژگی‌های Type.OBJECT.

string ( int64 format) maxProperties (با فرمت int64)

اختیاری. حداکثر تعداد ویژگی‌های Type.OBJECT.

رشته minLength string ( int64 format)

اختیاری. فیلدهای طرحواره برای نوع رشته حداقل طول Type.STRING

string ( int64 format) maxLength (با فرمت int64)

اختیاری. حداکثر طول Type.STRING

string pattern

اختیاری. الگوی Type.STRING برای محدود کردن یک رشته به یک عبارت منظم.

مقدار example value ( Value format)

اختیاری. مثالی از شیء. فقط زمانی که شیء ریشه باشد، پر می‌شود.

anyOf[] object ( Schema )

اختیاری. مقدار باید در برابر هر (یک یا چند) زیرطرحواره موجود در لیست اعتبارسنجی شود.

string propertyOrdering[]

اختیاری. ترتیب ویژگی‌ها. یک فیلد استاندارد در open api spec نیست. برای تعیین ترتیب ویژگی‌ها در پاسخ استفاده می‌شود.

مقدار default value ( Value format)

اختیاری. مقدار پیش‌فرض فیلد. طبق JSON Schema، این فیلد برای مولدهای مستندات در نظر گرفته شده است و بر اعتبارسنجی تأثیری ندارد. بنابراین در اینجا گنجانده شده و نادیده گرفته می‌شود تا توسعه‌دهندگانی که طرحواره‌هایی با فیلد 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
}

نوع

نوع شامل لیستی از انواع داده OpenAPI است که توسط https://spec.openapis.org/oas/v3.0.3#data-types تعریف شده است.

انوم‌ها
TYPE_UNSPECIFIED مشخص نشده، نباید استفاده شود.
STRING نوع رشته.
NUMBER نوع شماره.
INTEGER نوع عدد صحیح.
BOOLEAN نوع بولی.
ARRAY نوع آرایه.
OBJECT نوع شیء.
NULL نوع تهی.

رفتار

رفتار تابع را تعریف می‌کند. مقدار پیش‌فرض آن BLOCKING است.

انوم‌ها
UNSPECIFIED این مقدار بلااستفاده است.
BLOCKING در صورت تنظیم، سیستم قبل از ادامه مکالمه منتظر دریافت پاسخ تابع خواهد ماند.
NON_BLOCKING در صورت تنظیم، سیستم منتظر دریافت پاسخ تابع نمی‌ماند. در عوض، سعی می‌کند پاسخ‌های تابع را به محض دریافت، مدیریت کند و در عین حال، مکالمه بین کاربر و مدل را حفظ کند.

بازیابی جستجوی گوگل

ابزاری برای بازیابی داده‌های وب عمومی برای اتصال به زمین، ارائه شده توسط گوگل.

فیلدها
شیء dynamicRetrievalConfig object ( DynamicRetrievalConfig )

پیکربندی بازیابی پویا را برای منبع داده شده مشخص می‌کند.

نمایش JSON
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

پیکربندی بازیابی پویا

گزینه‌های سفارشی‌سازی بازیابی پویا را شرح می‌دهد.

فیلدها
شمارشی mode enum ( Mode )

حالت پیش‌بینی‌کننده‌ای که قرار است در بازیابی پویا استفاده شود.

number dynamicThreshold

آستانه‌ای که در بازیابی پویا مورد استفاده قرار می‌گیرد. در صورت عدم تنظیم، از مقدار پیش‌فرض سیستم استفاده می‌شود.

نمایش JSON
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

حالت

حالت پیش‌بینی‌کننده‌ای که قرار است در بازیابی پویا استفاده شود.

انوم‌ها
MODE_UNSPECIFIED همیشه بازیابی را فعال کنید.
MODE_DYNAMIC بازیابی را فقط زمانی اجرا کنید که سیستم تشخیص دهد لازم است.

اجرای کد

این نوع هیچ فیلدی ندارد.

ابزاری که کد تولید شده توسط مدل را اجرا می‌کند و به طور خودکار نتیجه را به مدل برمی‌گرداند.

همچنین به ExecutableCode و CodeExecutionResult که فقط هنگام استفاده از این ابزار تولید می‌شوند، مراجعه کنید.

جستجوی گوگل

نوع ابزار جستجوی گوگل. ابزاری برای پشتیبانی از جستجوی گوگل در مدل. ارائه شده توسط گوگل.

فیلدها
شیء timeRangeFilter object ( Interval )

اختیاری. نتایج جستجو را در یک محدوده زمانی خاص فیلتر کنید. اگر مشتریان زمان شروع را تعیین کنند، باید زمان پایان را نیز تعیین کنند (و برعکس).

نمایش JSON
{
  "timeRangeFilter": {
    object (Interval)
  }
}

فاصله

یک بازه زمانی را نشان می‌دهد که به صورت یک Timestamp شروع (شامل) و یک Timestamp پایان (منحصراً) کدگذاری شده است.

شروع باید کوچکتر یا مساوی پایان باشد. وقتی شروع با پایان برابر باشد، بازه خالی است (با هیچ زمانی مطابقت ندارد). وقتی هم شروع و هم پایان مشخص نشده باشند، بازه با هر زمانی مطابقت دارد.

فیلدها
string ( Timestamp format) startTime (با فرمت مهر زمان)

اختیاری. شروع فراگیر بازه.

در صورت مشخص شدن، مهر زمانی که با این بازه مطابقت دارد باید یکسان یا بعد از شروع باشد.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رشته endTime string ( Timestamp format)

اختیاری. پایان انحصاری بازه.

در صورت مشخص شدن، یک مهر زمانی (Timestamp) که با این بازه مطابقت دارد، باید قبل از پایان باشد.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

نمایش JSON
{
  "startTime": string,
  "endTime": string
}

استفاده از کامپیوتر

نوع ابزار استفاده از کامپیوتر.

فیلدها
شمارش environment enum ( Environment )

الزامی. محیطی که در آن عملیات انجام می‌شود.

string excludedPredefinedFunctions[]

اختیاری. به طور پیش‌فرض، توابع از پیش تعریف شده در فراخوانی نهایی مدل گنجانده می‌شوند. برخی از آنها را می‌توان به صراحت از شمول خودکار مستثنی کرد. این می‌تواند دو هدف را دنبال کند: ۱. استفاده از یک فضای عمل محدودتر/متفاوت. ۲. بهبود تعاریف/دستورالعمل‌های توابع از پیش تعریف شده.

نمایش JSON
{
  "environment": enum (Environment),
  "excludedPredefinedFunctions": [
    string
  ]
}

محیط زیست

نشان دهنده محیطی است که در حال اجرا است، مانند یک مرورگر وب.

انوم‌ها
ENVIRONMENT_UNSPECIFIED پیش‌فرض روی مرورگر.
ENVIRONMENT_BROWSER در یک مرورگر وب کار می‌کند.

متن آدرس

این نوع هیچ فیلدی ندارد.

ابزاری برای پشتیبانی از بازیابی متن URL.

جستجوی فایل

ابزار FileSearch که دانش را از پیکره‌های بازیابی معنایی بازیابی می‌کند. فایل‌ها با استفاده از رابط برنامه‌نویسی کاربردی ImportFile به پیکره‌های بازیابی معنایی وارد می‌شوند.

فیلدها
شیء retrievalResources[] object ( RetrievalResource )

الزامی. منابع بازیابی معنایی برای بازیابی. در حال حاضر فقط از یک پیکره زبانی پشتیبانی می‌کند. در آینده ممکن است پشتیبانی از چندین پیکره زبانی را نیز فعال کنیم.

شیء retrievalConfig object ( RetrievalConfig )

اختیاری. پیکربندی برای بازیابی.

نمایش JSON
{
  "retrievalResources": [
    {
      object (RetrievalResource)
    }
  ],
  "retrievalConfig": {
    object (RetrievalConfig)
  }
}

بازیابی منبع

منبع بازیابی معنایی که باید از آن بازیابی شود.

فیلدها
string ragStoreName

الزامی. نام منبع بازیابی معنایی که قرار است از آن بازیابی شود. مثال: ragStores/my-rag-store-123

نمایش JSON
{
  "ragStoreName": string
}

پیکربندی بازیابی

پیکربندی بازیابی معنایی.

فیلدها
string metadataFilter

اختیاری. فیلتر فراداده برای اعمال روی اسناد و تکه‌های بازیابی معنایی.

integer topK

اختیاری. تعداد تکه‌های بازیابی معنایی که باید بازیابی شوند.

نمایش JSON
{
  "metadataFilter": string,
  "topK": integer
}

گوگل مپ

ابزار GoogleMaps که زمینه جغرافیایی را برای جستجوی کاربر فراهم می‌کند.

فیلدها
enableWidget boolean

اختیاری. اینکه آیا توکن زمینه ویجت در GroundingMetadata پاسخ برگردانده شود یا خیر. توسعه‌دهندگان می‌توانند از توکن زمینه ویجت برای رندر کردن یک ویجت Google Maps با زمینه مکانی مرتبط با مکان‌هایی که مدل در پاسخ به آنها اشاره می‌کند، استفاده کنند.

نمایش JSON
{
  "enableWidget": boolean
}

پیکربندی ابزار

پیکربندی ابزار شامل پارامترهایی برای تعیین استفاده از Tool در درخواست.

فیلدها
شیء functionCallingConfig object ( FunctionCallingConfig )

اختیاری. پیکربندی فراخوانی تابع.

شیء retrievalConfig object ( RetrievalConfig )

اختیاری. پیکربندی بازیابی.

نمایش JSON
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  },
  "retrievalConfig": {
    object (RetrievalConfig)
  }
}

پیکربندی فراخوانی تابع

پیکربندی برای مشخص کردن رفتار فراخوانی تابع.

فیلدها
شمارشی mode enum ( Mode )

اختیاری. حالتی را که فراخوانی تابع باید در آن اجرا شود مشخص می‌کند. اگر مشخص نشود، مقدار پیش‌فرض روی AUTO تنظیم می‌شود.

string allowedFunctionNames[]

اختیاری. مجموعه‌ای از نام‌های تابع که در صورت ارائه، توابعی را که مدل فراخوانی خواهد کرد محدود می‌کنند.

این فقط باید زمانی تنظیم شود که حالت (Mode) روی ANY یا VALIDATED باشد. نام توابع باید با [FunctionDeclaration.name] مطابقت داشته باشد. وقتی تنظیم شود، مدل فراخوانی تابع را فقط از نام‌های تابع مجاز پیش‌بینی می‌کند.

نمایش JSON
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}

حالت

با تعریف حالت اجرا، رفتار اجرایی را برای فراخوانی تابع تعریف می‌کند.

انوم‌ها
MODE_UNSPECIFIED حالت فراخوانی تابع نامشخص. این مقدار نباید استفاده شود.
AUTO رفتار پیش‌فرض مدل، مدل تصمیم می‌گیرد که یا یک فراخوانی تابع یا یک پاسخ زبان طبیعی را پیش‌بینی کند.
ANY مدل محدود به پیش‌بینی فقط فراخوانی یک تابع است. اگر "allowedFunctionNames" تنظیم شده باشد، فراخوانی تابع پیش‌بینی‌شده به هر یک از "allowedFunctionNames" محدود خواهد شد، در غیر این صورت فراخوانی تابع پیش‌بینی‌شده هر یک از "functionDeclarations" ارائه شده خواهد بود.
NONE مدل هیچ فراخوانی تابعی را پیش‌بینی نمی‌کند. رفتار مدل مانند زمانی است که هیچ اعلان تابعی ارسال نمی‌شود.
VALIDATED مدل تصمیم می‌گیرد که یا یک فراخوانی تابع یا یک پاسخ زبان طبیعی را پیش‌بینی کند، اما فراخوانی‌های تابع را با رمزگشایی محدود اعتبارسنجی می‌کند. اگر "allowedFunctionNames" تنظیم شده باشد، فراخوانی تابع پیش‌بینی‌شده به هر یک از "allowedFunctionNames" محدود خواهد شد، در غیر این صورت فراخوانی تابع پیش‌بینی‌شده هر یک از "functionDeclarations" ارائه شده خواهد بود.

پیکربندی بازیابی

پیکربندی بازیابی.

فیلدها
شیء latLng object ( LatLng )

اختیاری. موقعیت مکانی کاربر.

string languageCode

اختیاری. کد زبان کاربر. کد زبان برای محتوا. از برچسب‌های زبان تعریف‌شده توسط BCP47 استفاده کنید.

نمایش JSON
{
  "latLng": {
    object (LatLng)
  },
  "languageCode": string
}

لات‌لنگ

شیء‌ای که یک جفت عرض/طول جغرافیایی را نشان می‌دهد. این به صورت یک جفت دوتایی بیان می‌شود تا درجه عرض جغرافیایی و درجه طول جغرافیایی را نشان دهد. مگر اینکه خلاف آن مشخص شده باشد، این شیء باید با استاندارد WGS84 مطابقت داشته باشد. مقادیر باید در محدوده نرمال باشند.

فیلدها
number latitude

عرض جغرافیایی بر حسب درجه. باید در محدوده [-90.0، +90.0] باشد.

number longitude

طول جغرافیایی بر حسب درجه. باید در محدوده [-۱۸۰.۰، +۱۸۰.۰] باشد.

نمایش JSON
{
  "latitude": number,
  "longitude": number
}

کاربردفراداده

فراداده (metadata) در مورد استفاده از محتوای ذخیره شده.

فیلدها
integer totalTokenCount

تعداد کل توکن‌هایی که محتوای ذخیره‌شده مصرف می‌کند.

نمایش JSON
{
  "totalTokenCount": integer
}