Caching

تتيح لك ميزة "التخزين المؤقت للسياق" حفظ رموز الإدخال التي تم احتسابها مسبقًا وإعادة استخدامها بشكل متكرر، مثلاً عند طرح أسئلة مختلفة حول ملف الوسائط نفسه. يمكن أن يؤدي ذلك إلى توفير التكاليف والوقت، وذلك حسب الاستخدام. للحصول على مقدّمة تفصيلية، يُرجى الاطّلاع على دليل التخزين المؤقت للسياق.

الطريقة: cachedContents.create

تنشئ هذه الطريقة مورد CachedContent.

نقطة نهاية

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

نص الطلب

يحتوي نص الطلب على مثال CachedContent.

الحقول
contents[] object (Content)

اختياريّ. الإدخال فقط غير قابل للتغيير المحتوى المطلوب تخزينه مؤقتًا

tools[] object (Tool)

اختياريّ. الإدخال فقط غير قابل للتغيير قائمة Tools قد يستخدمها النموذج لإنشاء الرد التالي

expiration Union type
تحدّد هذه السمة وقت انتهاء صلاحية هذا المورد. يمكن أن يكون التعليق expiration إحدى القيم التالية فقط:
expireTime string (Timestamp format)

طابع زمني بالتوقيت العالمي المتفق عليه يحدّد وقت انتهاء صلاحية هذا المرجع. يتم تقديم هذا الرد دائمًا عند الإخراج، بغض النظر عن ما تم إرساله عند الإدخال.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

ttl string (Duration format)

الإدخال فقط مدة البقاء الجديدة لهذا المورد، يجب إدخالها فقط.

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"

displayName string

اختياريّ. غير قابل للتغيير اسم العرض ذو الدلالة الذي يحدّده المستخدم للمحتوى المخزّن مؤقتًا ‫128 حرف Unicode كحدّ أقصى

model string

الحقل مطلوب. غير قابل للتغيير اسم Model المطلوب استخدامه للمحتوى المخزّن مؤقتًا. التنسيق: models/{model}

systemInstruction object (Content)

اختياريّ. الإدخال فقط غير قابل للتغيير تعليمات النظام التي يضبطها المطوّر تتوفّر الميزة حاليًا للنصوص فقط.

toolConfig object (ToolConfig)

اختياريّ. الإدخال فقط غير قابل للتغيير إعدادات الأداة تتم مشاركة هذا الإعداد مع جميع الأدوات.

مثال على الطلب

التذكرة الأساسية

Python

from google import genai
from google.genai import types

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

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

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

Node.js

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

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

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

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

Go

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

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

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

محارة

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

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

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

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

اسم المرسِل

Python

from google import genai
from google.genai import types

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

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

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

Node.js

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

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

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

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

Go

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

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

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

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

من محادثة

Python

from google import genai
from google.genai import types

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

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

response = chat.send_message(
    message=["Hi, could you summarize this transcript?", document]
)
print("\n\nmodel:  ", response.text)
response = chat.send_message(
    message=["Okay, could you tell me more about the trans-lunar injection"]
)
print("\n\nmodel:  ", response.text)

# To cache the conversation so far, pass the chat history as the list of contents.
cache = client.caches.create(
    model=model_name,
    config={
        "contents": chat.get_history(),
        "system_instruction": system_instruction,
    },
)
# Continue the conversation using the cached content.
chat = client.chats.create(
    model=model_name,
    config=types.GenerateContentConfig(cached_content=cache.name),
)
response = chat.send_message(
    message="I didn't understand that last part, could you explain it in simpler language?"
)
print("\n\nmodel:  ", response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const modelName = "gemini-1.5-flash-001";
const systemInstruction = "You are an expert analyzing transcripts.";

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

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

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

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

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

Go

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

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

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

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

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

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

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

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

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

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

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نصها على مثال تم إنشاؤه حديثًا CachedContent.

الطريقة: cachedContents.list

تعرض هذه الطريقة محتوى القوائم المخزّن مؤقتًا.

نقطة نهاية

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

مَعلمات طلب البحث

pageSize integer

اختياريّ. تعرض هذه المَعلمة أكبر عدد ممكن من المحتوى المخزّن مؤقتًا. قد تعرض الخدمة عددًا أقل من هذه القيمة. في حال عدم تحديدها، سيتم عرض عدد تلقائي (أقل من الحد الأقصى) من العناصر. الحد الأقصى للقيمة هو 1000، وسيتم فرض القيمة 1000 على القيم الأكبر من 1000.

pageToken string

اختياريّ. رمز مميز للصفحة تم تلقّيه من طلب cachedContents.list سابق. يجب تقديم هذا الرمز لاسترداد الصفحة التالية.

عند تقسيم النتائج إلى صفحات، يجب أن تتطابق جميع المَعلمات الأخرى المقدَّمة إلى cachedContents.list مع الطلب الذي قدّم رمز الصفحة المميز.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

الردّ مع قائمة CachedContents

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

الحقول
cachedContents[] object (CachedContent)

قائمة بالمحتوى المخزَّن مؤقتًا

nextPageToken string

رمز مميز يمكن إرساله كـ pageToken لاسترداد الصفحة التالية في حال حذف هذا الحقل، لن تكون هناك صفحات لاحقة.

تمثيل JSON
{
  "cachedContents": [
    {
      object (CachedContent)
    }
  ],
  "nextPageToken": string
}

الطريقة: cachedContents.get

قراءة مورد CachedContent

نقطة نهاية

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

مَعلمات المسار

name string

الحقل مطلوب. اسم المورد الذي يشير إلى إدخال ذاكرة التخزين المؤقت للمحتوى التنسيق: cachedContents/{id} ويكون بالتنسيق التالي: cachedContents/{cachedcontent}.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

مثال على الطلب

Python

from google import genai

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

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

Node.js

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

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

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

Go

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

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

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

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

محارة

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

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال CachedContent.

الطريقة: cachedContents.patch

تعدّل هذه الطريقة مورد CachedContent (يمكن تعديل تاريخ انتهاء الصلاحية فقط).

نقطة نهاية

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

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

مَعلمات المسار

cachedContent.name string

النتائج فقط. المعرّف. اسم المرجع الذي يشير إلى المحتوى المخزّن مؤقتًا التنسيق: cachedContents/{id} ويكون بالتنسيق التالي: cachedContents/{cachedcontent}.

مَعلمات طلب البحث

updateMask string (FieldMask format)

قائمة الحقول التي سيتم تعديلها.

هذه قائمة قيم مفصولة بفاصلة تتضمّن الأسماء المؤهَّلة بالكامل للحقول. مثال: "user.displayName,photo"

نص الطلب

يحتوي نص الطلب على مثال CachedContent.

الحقول
expiration Union type
تحدّد هذه السمة وقت انتهاء صلاحية هذا المورد. يمكن أن يكون التعليق expiration إحدى القيم التالية فقط:
expireTime string (Timestamp format)

طابع زمني بالتوقيت العالمي المتفق عليه يحدّد وقت انتهاء صلاحية هذا المرجع. يتم تقديم هذا الرد دائمًا عند الإخراج، بغض النظر عن ما تم إرساله عند الإدخال.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

ttl string (Duration format)

الإدخال فقط مدة البقاء الجديدة لهذا المورد، يجب إدخالها فقط.

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"

مثال على الطلب

Python

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

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

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

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

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

Node.js

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

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

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

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

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

Go

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

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

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

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

محارة

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

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال CachedContent.

الطريقة: cachedContents.delete

يحذف هذا الإجراء مورد CachedContent.

نقطة نهاية

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

مَعلمات المسار

name string

الحقل مطلوب. اسم المرجع الذي يشير إلى إدخال ذاكرة التخزين المؤقت للمحتوى بالتنسيق: cachedContents/{id} ويكون بالتنسيق cachedContents/{cachedcontent}.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

مثال على الطلب

Python

from google import genai

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

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

Node.js

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

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

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

Go

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

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

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

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

محارة

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

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيكون نص الاستجابة عبارة عن كائن JSON فارغ.

مورد REST: ‏ cachedContents

المورد: CachedContent

المحتوى الذي تمت معالجته مسبقًا ويمكن استخدامه في طلب لاحق إلى GenerativeService

لا يمكن استخدام المحتوى المخزّن مؤقتًا إلا مع النموذج الذي تم إنشاؤه من أجله.

الحقول
contents[] object (Content)

اختياريّ. الإدخال فقط غير قابل للتغيير المحتوى المطلوب تخزينه مؤقتًا

tools[] object (Tool)

اختياريّ. الإدخال فقط غير قابل للتغيير قائمة Tools قد يستخدمها النموذج لإنشاء الرد التالي

createTime string (Timestamp format)

النتائج فقط. وقت إنشاء إدخال ذاكرة التخزين المؤقت

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

النتائج فقط. وقت آخر تعديل لإدخال ذاكرة التخزين المؤقت بالتوقيت العالمي المنسّق

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

usageMetadata object (UsageMetadata)

النتائج فقط. البيانات الوصفية المتعلقة باستخدام المحتوى المخزَّن مؤقتًا

expiration Union type
تحدّد هذه السمة وقت انتهاء صلاحية هذا المورد. يمكن أن يكون التعليق expiration إحدى القيم التالية فقط:
expireTime string (Timestamp format)

طابع زمني بالتوقيت العالمي المتفق عليه يحدّد وقت انتهاء صلاحية هذا المرجع. يتم تقديم هذا الرد دائمًا عند الإخراج، بغض النظر عن ما تم إرساله عند الإدخال.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

ttl string (Duration format)

الإدخال فقط مدة البقاء الجديدة لهذا المورد، يجب إدخالها فقط.

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "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)
  },

  // expiration
  "expireTime": string,
  "ttl": string
  // Union type
  "name": string,
  "displayName": string,
  "model": string,
  "systemInstruction": {
    object (Content)
  },
  "toolConfig": {
    object (ToolConfig)
  }
}

المحتوى

نوع البيانات المنظَّمة الأساسي الذي يحتوي على محتوى متعدد الأجزاء لرسالة

يتضمّن Content حقل role يحدّد منتج Content وحقل parts يحتوي على بيانات متعدّدة الأجزاء تتضمّن محتوى دور الرسالة.

الحقول
parts[] object (Part)

Parts بالترتيب التي تشكّل رسالة واحدة قد يكون للأجزاء أنواع MIME مختلفة.

role string

اختياريّ. تمثّل هذه السمة منتج المحتوى. يجب أن تكون القيمة إما "user" أو "model".

يجب ضبط هذا الحقل للمحادثات المتعددة الجولات، وإلا يمكن تركه فارغًا أو بدون ضبط.

تمثيل JSON
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

الجزء

نوع بيانات يحتوي على وسائط تشكّل جزءًا من رسالة Content متعددة الأجزاء.

يتألف Part من بيانات لها نوع بيانات مرتبط بها. لا يمكن أن يحتوي Part إلا على نوع واحد من الأنواع المقبولة في Part.data.

يجب أن يحتوي Part على نوع MIME ثابت من هيئة أرقام الإنترنت المخصّصة (IANA) يحدّد نوع الوسائط ونوعها الفرعي إذا كان الحقل inlineData مملوءًا بوحدات بايت أولية.

الحقول
thought boolean

اختياريّ. تشير إلى ما إذا كان الجزء مستنتجًا من النموذج.

thoughtSignature string (bytes format)

اختياريّ. توقيع غير شفاف للفكرة حتى يمكن إعادة استخدامه في الطلبات اللاحقة.

سلسلة مرمّزة باستخدام Base64

partMetadata object (Struct format)

بيانات وصفية مخصّصة مرتبطة بالجزء قد يحتاج الوكلاء الذين يستخدمون genai.Part كتمثيل للمحتوى إلى تتبُّع المعلومات الإضافية. على سبيل المثال، يمكن أن يكون اسم ملف أو مصدر ينشأ منه الجزء أو طريقة لدمج عدة تدفقات أجزاء.

mediaResolution object (MediaResolution)

اختياريّ. تمثّل هذه السمة دقة الوسائط المُدخَلة.

data Union type
يمكن أن يكون التعليق data إحدى القيم التالية فقط:
text string

نص مضمّن

inlineData object (Blob)

وحدات بايت الوسائط المضمّنة

functionCall object (FunctionCall)

FunctionCall متوقّع يتم عرضه من النموذج يحتوي على سلسلة تمثّل FunctionDeclaration.name مع الوسيطات وقيمها

functionResponse object (FunctionResponse)

يتم استخدام نتيجة تنفيذ FunctionCall التي تحتوي على سلسلة تمثّل FunctionDeclaration.name وعنصر JSON منظَّم يحتوي على أي ناتج من الدالة كسياق للنموذج.

fileData object (FileData)

البيانات المستندة إلى معرّف الموارد المنتظم (URI)

executableCode object (ExecutableCode)

الرمز الذي أنشأه النموذج والمخصّص للتنفيذ

codeExecutionResult object (CodeExecutionResult)

نتيجة تنفيذ ExecutableCode

toolCall object (ToolCall)

استدعاء أداة من جهة الخادم يتم ملء هذا الحقل عندما يتوقّع النموذج استدعاء أداة يجب تنفيذها على الخادم. من المتوقّع أن يعيد العميل إرسال هذه الرسالة إلى واجهة برمجة التطبيقات.

toolResponse object (ToolResponse)

الناتج من تنفيذ ToolCall من جهة الخادم يملأ العميل هذا الحقل بنتائج تنفيذ ToolCall المقابل.

metadata Union type
تتحكّم هذه السمة في المعالجة المسبقة الإضافية للبيانات. يمكن أن يكون التعليق metadata إحدى القيم التالية فقط:
videoMetadata object (VideoMetadata)

اختياريّ. البيانات الوصفية للفيديو يجب تحديد البيانات الوصفية فقط أثناء عرض بيانات الفيديو في inlineData أو fileData.

تمثيل JSON
{
  "thought": boolean,
  "thoughtSignature": string,
  "partMetadata": {
    object
  },
  "mediaResolution": {
    object (MediaResolution)
  },

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

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

بلوب

وحدات بايت الوسائط الأولية

يجب عدم إرسال النص كبايتات أولية، بل استخدام الحقل "text".

الحقول
mimeType string

نوع MIME المعياري الخاص بـ IANA لبيانات المصدر أمثلة: - image/png - image/jpeg في حال تقديم نوع MIME غير متوافق، سيتم عرض رسالة خطأ. للحصول على قائمة كاملة بالأنواع المتوافقة، راجِع تنسيقات الملفات المتوافقة.

data string (bytes format)

وحدات البايت الأولية لتنسيقات الوسائط

سلسلة مرمّزة باستخدام Base64

تمثيل JSON
{
  "mimeType": string,
  "data": string
}

FunctionCall

FunctionCall متوقّع يتم عرضه من النموذج يحتوي على سلسلة تمثّل FunctionDeclaration.name مع الوسيطات وقيمها

الحقول
id string

اختياريّ. المعرّف الفريد لاستدعاء الدالة. في حال توفُّرها، يجب أن ينفّذ العميل functionCall ويعرض الردّ مع id المطابق.

name string

الحقل مطلوب. اسم الدالة المطلوب استدعاؤها. يجب أن يتضمّن أحرفًا صغيرة (a-z) أو أحرفًا كبيرة (A-Z) أو أرقامًا (0-9) أو شرطات سفلية وواصلات، وبحد أقصى 128 حرفًا.

args object (Struct format)

اختياريّ. مَعلمات الدالة وقيمها بتنسيق عنصر JSON

تمثيل JSON
{
  "id": string,
  "name": string,
  "args": {
    object
  }
}

FunctionResponse

يتم استخدام نتيجة الإخراج من FunctionCall التي تحتوي على سلسلة تمثّل FunctionDeclaration.name وعنصر JSON منظَّم يحتوي على أي إخراج من الدالة كسياق للنموذج. يجب أن يحتوي هذا الحقل على نتيجة FunctionCall تم إجراؤها استنادًا إلى توقّع النموذج.

الحقول
id string

اختياريّ. معرّف استدعاء الدالة الذي يخصّه هذا الردّ. يتم ملء هذا الحقل من خلال العميل لمطابقة استدعاء الدالة id المقابل.

name string

الحقل مطلوب. اسم الدالة المطلوب استدعاؤها. يجب أن يتضمّن أحرفًا صغيرة (a-z) أو أحرفًا كبيرة (A-Z) أو أرقامًا (0-9) أو شرطات سفلية وواصلات، وبحد أقصى 128 حرفًا.

response object (Struct format)

الحقل مطلوب. ردّ الدالة بتنسيق عنصر JSON. يمكن للمتصلين استخدام أي مفاتيح يختارونها وتناسب بنية الدالة لعرض ناتج الدالة، مثل "output" أو "result" أو غير ذلك. وعلى وجه الخصوص، إذا تعذّر تنفيذ استدعاء الدالة، يمكن أن يتضمّن الردّ المفتاح "error" لعرض تفاصيل الخطأ للنموذج.

parts[] object (FunctionResponsePart)

اختياريّ. Parts مرتّبة تشكّل ردّ الدالة قد تتضمّن الأجزاء أنواع MIME مختلفة من IANA.

willContinue boolean

اختياريّ. تشير إلى أنّ استدعاء الدالة مستمر، وسيتم عرض المزيد من الردود، ما يحوّل استدعاء الدالة إلى مولّد. لا ينطبق إلا على استدعاءات الدوال NON_BLOCKING، ويتم تجاهله في الحالات الأخرى. في حال ضبطها على "خطأ"، لن يتم النظر في الردود المستقبلية. يُسمح بعرض 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)
}

FunctionResponsePart

نوع بيانات يحتوي على وسائط تشكّل جزءًا من رسالة FunctionResponse.

يتألف FunctionResponsePart من بيانات لها نوع بيانات مرتبط بها. لا يمكن أن يحتوي FunctionResponsePart إلا على نوع واحد من الأنواع المقبولة في FunctionResponsePart.data.

يجب أن يحتوي FunctionResponsePart على نوع MIME ثابت من هيئة أرقام الإنترنت المخصّصة (IANA) يحدّد نوع الوسائط ونوعها الفرعي إذا كان الحقل inlineData مملوءًا بوحدات بايت أولية.

الحقول
data Union type
تمثّل هذه السمة بيانات جزء استجابة الدالة. يمكن أن يكون التعليق data إحدى القيم التالية فقط:
inlineData object (FunctionResponseBlob)

وحدات بايت الوسائط المضمّنة

تمثيل JSON
{

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

FunctionResponseBlob

وحدات بايت الوسائط الأولية لردّ الدالة

يجب عدم إرسال النص كبايتات أولية، بل استخدام الحقل FunctionResponse.response.

الحقول
mimeType string

نوع MIME المعياري الخاص بـ IANA لبيانات المصدر أمثلة: - image/png - image/jpeg في حال تقديم نوع MIME غير متوافق، سيتم عرض رسالة خطأ. للحصول على قائمة كاملة بالأنواع المتوافقة، راجِع تنسيقات الملفات المتوافقة.

data string (bytes format)

وحدات البايت الأولية لتنسيقات الوسائط

سلسلة مرمّزة باستخدام Base64

تمثيل JSON
{
  "mimeType": string,
  "data": string
}

الجدولة

تحدّد هذه السمة كيفية جدولة الرد في المحادثة.

عمليات التعداد
SCHEDULING_UNSPECIFIED هذه القيمة غير مستخدَمة.
SILENT يجب إضافة النتيجة إلى سياق المحادثة فقط، وعدم مقاطعة عملية الإنشاء أو بدءها.
WHEN_IDLE أضِف النتيجة إلى سياق المحادثة، واطلب إنشاء الناتج بدون مقاطعة عملية الإنشاء الجارية.
INTERRUPT إضافة النتيجة إلى سياق المحادثة وإيقاف عملية الإنشاء الجارية مؤقتًا وطلب إنشاء الناتج

FileData

البيانات المستندة إلى معرّف الموارد المنتظم (URI)

الحقول
mimeType string

اختياريّ. نوع MIME المعياري الخاص بـ IANA لبيانات المصدر

fileUri string

الحقل مطلوب. URI.

تمثيل JSON
{
  "mimeType": string,
  "fileUri": string
}

ExecutableCode

الرمز الذي ينشئه النموذج والمخصّص للتنفيذ، والنتيجة التي يتم إرجاعها إلى النموذج

يتم إنشاؤه فقط عند استخدام أداة CodeExecution، حيث سيتم تنفيذ الرمز تلقائيًا، وسيتم أيضًا إنشاء CodeExecutionResult مطابق.

الحقول
id string

اختياريّ. المعرّف الفريد ExecutableCode للجزء. يعرض الخادم CodeExecutionResult مع id المطابق.

language enum (Language)

الحقل مطلوب. لغة البرمجة الخاصة بـ code

code string

الحقل مطلوب. الرمز المطلوب تنفيذه

تمثيل JSON
{
  "id": string,
  "language": enum (Language),
  "code": string
}

اللغة

لغات البرمجة المتوافقة مع الرمز البرمجي الذي تم إنشاؤه

عمليات التعداد
LANGUAGE_UNSPECIFIED لغة غير محدّدة يجب عدم استخدام هذه القيمة.
PYTHON الإصدار 3.10 من Python أو إصدار أحدث، مع توفّر numpy وsimpy لغة Python هي اللغة التلقائية.

CodeExecutionResult

نتيجة تنفيذ ExecutableCode

يتم إنشاؤها فقط عند استخدام الأداة CodeExecution.

الحقول
id string

اختياريّ. تمثّل هذه السمة معرّف جزء ExecutableCode الذي تعود إليه هذه النتيجة. لا تتم تعبئة هذا الحقل إلا إذا كان ExecutableCode المقابل يتضمّن معرّفًا.

outcome enum (Outcome)

الحقل مطلوب. نتيجة تنفيذ الرمز البرمجي

output string

اختياريّ. يحتوي على stdout عند تنفيذ الرمز البرمجي بنجاح، أو stderr أو وصف آخر في الحالات الأخرى.

تمثيل JSON
{
  "id": string,
  "outcome": enum (Outcome),
  "output": string
}

النتيجة

تعداد النتائج المحتملة لتنفيذ الرمز البرمجي

عمليات التعداد
OUTCOME_UNSPECIFIED حالة غير محدَّدة يجب عدم استخدام هذه القيمة.
OUTCOME_OK اكتمل تنفيذ الرمز البرمجي بنجاح. يحتوي output على stdout، إذا كان متاحًا.
OUTCOME_FAILED تعذّر تنفيذ الرمز البرمجي. يحتوي output على stderr وstdout، إذا كانا متوفرَين.
OUTCOME_DEADLINE_EXCEEDED استغرق تنفيذ الرمز البرمجي وقتًا طويلاً جدًا وتم إلغاؤه. قد يكون هناك output جزئي أو لا يكون.

ToolCall

تم عرض الخطأ ToolCall المتوقّع من جهة الخادم من النموذج. تحتوي هذه الرسالة على معلومات حول أداة يريد النموذج استخدامها. لا يُتوقّع من العميل تنفيذ ToolCall هذا. بدلاً من ذلك، يجب أن يمرّر العميل هذا ToolCall مرة أخرى إلى واجهة برمجة التطبيقات في ردّ لاحق ضمن رسالة Content، بالإضافة إلى ToolResponse المقابل.

الحقول
id string

اختياريّ. المعرّف الفريد لاستدعاء الأداة. يعرض الخادم ردّ الأداة مع id المطابق.

toolType enum (ToolType)

الحقل مطلوب. نوع الأداة التي تم استدعاؤها.

args object (Struct format)

اختياريّ. وسيطات استدعاء الأداة مثال: {"arg1" : "value1", "arg2" : "value2" , ...}

تمثيل JSON
{
  "id": string,
  "toolType": enum (ToolType),
  "args": {
    object
  }
}

ToolType

نوع الأداة في استدعاء الدالة

عمليات التعداد
TOOL_TYPE_UNSPECIFIED نوع الأداة غير محدَّد.
GOOGLE_SEARCH_WEB أداة البحث من Google، ويتم ربطها بـ Tool.google_search.search_types.web_search.
GOOGLE_SEARCH_IMAGE أداة البحث بالصور، ويتم ربطها بـ Tool.google_search.search_types.image_search.
URL_CONTEXT أداة سياق عنوان URL، ويتم ربطها بـ Tool.url_context.
GOOGLE_MAPS أداة "خرائط Google"، ويتم ربطها بـ Tool.google_maps.

ToolResponse

الناتج من تنفيذ ToolCall من جهة الخادم تحتوي هذه الرسالة على نتائج استدعاء أداة بدأها ToolCall من النموذج. على العميل إعادة تمرير ToolResponse إلى واجهة برمجة التطبيقات في ردّ لاحق ضمن رسالة Content، بالإضافة إلى ToolCall المقابل.

الحقول
id string

اختياريّ. معرّف استدعاء الأداة الذي تم إعداد هذا الردّ له.

toolType enum (ToolType)

الحقل مطلوب. نوع الأداة التي تم استدعاؤها، والتي تتطابق مع toolType في ToolCall المقابل

response object (Struct format)

اختياريّ. استجابة الأداة

تمثيل JSON
{
  "id": string,
  "toolType": enum (ToolType),
  "response": {
    object
  }
}

VideoMetadata

تم إيقاف هذه السياسة نهائيًا، لذا يُرجى استخدام سياسة GenerateContentRequest.processing_options بدلاً منها. تصف البيانات الوصفية محتوى الفيديو الذي يتم إدخاله.

الحقول
startOffset string (Duration format)

اختياريّ. إزاحة بدء الفيديو

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"

endOffset string (Duration format)

اختياريّ. إزاحة نهاية الفيديو

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"

fps number

اختياريّ. تمثّل هذه السمة عدد اللقطات في الثانية للفيديو الذي تم إرساله إلى النموذج. إذا لم يتم تحديدها، ستكون القيمة التلقائية 1.0. نطاق عدد اللقطات في الثانية هو (0.0, 24.0].

تمثيل JSON
{
  "startOffset": string,
  "endOffset": string,
  "fps": number
}

MediaResolution

درجة دقة الوسائط لإنشاء الرموز المميّزة

الحقول
value Union type
مستوى دقة الوسائط يمكن أن يكون التعليق value إحدى القيم التالية فقط:
level enum (Level)

جودة تقسيم المحتوى إلى رموز مميّزة المستخدَمة للوسائط المحدّدة للحصول على دعم بشأن Gemini API .

تمثيل JSON
{

  // value
  "level": enum (Level)
  // Union type
}

المستوى

مستوى دقة الوسائط

عمليات التعداد
MEDIA_RESOLUTION_UNSPECIFIED لم يتم ضبط دقة الوسائط.
MEDIA_RESOLUTION_LOW تم ضبط دقة الوسائط على منخفضة.
MEDIA_RESOLUTION_MEDIUM تم ضبط دقة الوسائط على متوسطة.
MEDIA_RESOLUTION_HIGH تم ضبط دقة الوسائط على "عالية".
MEDIA_RESOLUTION_ULTRA_HIGH تم ضبط دقة الوسائط على فائقة الدقة.

الأداة

تفاصيل الأداة التي قد يستخدمها النموذج لإنشاء الرد

Tool هي جزء من الرمز البرمجي يتيح للنظام التفاعل مع أنظمة خارجية لتنفيذ إجراء أو مجموعة من الإجراءات خارج نطاق معرفة النموذج.

المعرّف التالي: 15

الحقول
functionDeclarations[] object (FunctionDeclaration)

اختياريّ. قائمة FunctionDeclarations متاحة للنموذج ويمكن استخدامها في استدعاء الدوال.

لا ينفّذ النموذج أو النظام الوظيفة. بدلاً من ذلك، قد يتم عرض الدالة المحدّدة كـ FunctionCall مع وسيطات من جهة العميل لتنفيذها. قد يقرّر النموذج استدعاء مجموعة فرعية من هذه الدوال عن طريق ملء FunctionCall في الردّ. قد تتضمّن الجولة التالية من المحادثة FunctionResponse مع سياق إنشاء Content.role "الوظيفة" لجولة النموذج التالية.

googleSearchRetrieval object (GoogleSearchRetrieval)

اختياريّ. أداة استرجاع مدعومة من "بحث Google"

codeExecution object (CodeExecution)

اختياريّ. تتيح هذه السمة للنموذج تنفيذ الرمز البرمجي كجزء من عملية الإنشاء.

computerUse object (ComputerUse)

اختياريّ. أداة تتيح للتصميم التفاعل مباشرةً مع الكمبيوتر في حال تفعيل هذا الخيار، يتم تلقائيًا ملء "تعريفات الدوال" الخاصة باستخدام الكمبيوتر.

urlContext object (UrlContext)

اختياريّ. أداة للمساعدة في استرداد سياق عنوان URL

mcpServers[] object (McpServer)

اختياريّ. خوادم MCP التي سيتم الاتصال بها

googleMaps object (GoogleMaps)

اختياريّ. أداة تتيح تحديد مصدر ردّ النموذج بالسياق الجغرافي المكاني المرتبط بطلب المستخدم

تمثيل JSON
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  },
  "googleSearch": {
    object (GoogleSearch)
  },
  "computerUse": {
    object (ComputerUse)
  },
  "urlContext": {
    object (UrlContext)
  },
  "fileSearch": {
    object (FileSearch)
  },
  "mcpServers": [
    {
      object (McpServer)
    }
  ],
  "googleMaps": {
    object (GoogleMaps)
  }
}

FunctionDeclaration

تمثيل منظَّم لتعريف دالة كما هو محدّد في مواصفات OpenAPI 3.03 يتضمّن هذا التعريف اسم الدالة ومعلَماتها. تمثّل FunctionDeclaration مجموعة من الرموز البرمجية التي يمكن استخدامها كـ Tool من قِبل النموذج وتنفيذها من قِبل العميل.

الحقول
name string

الحقل مطلوب. اسم الدالة يجب أن يتضمّن أحرفًا من a إلى z أو من A إلى Z أو من 0 إلى 9، أو أن يحتوي على شرطات سفلية ونقطتين رأسيتين ونقاط وشرطات، وبحد أقصى 128 حرفًا.

description string

الحقل مطلوب. وصف موجز للدالة

behavior enum (Behavior)

اختياريّ. تحدّد هذه السمة سلوك الدالة. لا تتوافق هذه السمة حاليًا إلا مع طريقة BidiGenerateContent.

parameters object (Schema)

اختياريّ. توضّح هذه السمة المَعلمات الخاصة بهذه الدالة. تعكس هذه السمة مفتاح السلسلة "عنصر المَعلمة" في Open API 3.03: اسم المَعلمة. أسماء المَعلمات حسّاسة لحالة الأحرف. قيمة المخطط: المخطط الذي يحدّد النوع المستخدَم للمَعلمة.

parametersJsonSchema value (Value format)

اختياريّ. تصف هذه السمة المَعلمات الخاصة بالدالة بتنسيق JSON Schema. يجب أن يصف المخطط كائنًا تكون خصائصه هي مَعلمات الدالة. على سبيل المثال:

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

لا يمكن استخدام هذا الحقل مع parameters.

response object (Schema)

اختياريّ. تصف هذه السمة الناتج من هذه الدالة بتنسيق JSON Schema. تعكس هذه السمة "كائن الرد" في Open API 3.03. يحدّد المخطط نوع القيمة المستخدَمة في قيمة استجابة الدالة.

responseJsonSchema value (Value format)

اختياريّ. تصف هذه السمة الناتج من هذه الدالة بتنسيق JSON Schema. القيمة المحدّدة بواسطة المخطط هي قيمة الاستجابة للدالة.

لا يمكن استخدام هذا الحقل مع response.

تمثيل JSON
{
  "name": string,
  "description": string,
  "behavior": enum (Behavior),
  "parameters": {
    object (Schema)
  },
  "parametersJsonSchema": value,
  "response": {
    object (Schema)
  },
  "responseJsonSchema": value
}

المخطط

يسمح العنصر Schema بتحديد أنواع بيانات الإدخال والإخراج. يمكن أن تكون هذه الأنواع كائنات، ولكن أيضًا أنواعًا أولية ومصفوفات. يمثّل مجموعة فرعية محدّدة من كائن مخطط OpenAPI 3.0.

الحقول
type enum (Type)

الحقل مطلوب. نوع البيانات

format string

اختياريّ. تنسيق البيانات يُسمح بأي قيمة، ولكن معظمها لا يؤدي إلى تشغيل أي وظائف خاصة.

title string

اختياريّ. تمثّل هذه السمة عنوان المخطط.

description string

اختياريّ. وصف موجز للمَعلمة يمكن أن يحتوي ذلك على أمثلة على الاستخدام. قد يتم تنسيق وصف المَعلمة على شكل Markdown.

nullable boolean

اختياريّ. تشير إلى ما إذا كان يمكن أن تكون القيمة فارغة.

enum[] string

اختياريّ. القيم المحتملة لعنصر Type.STRING بتنسيق enum. على سبيل المثال، يمكننا تحديد تعداد Direction على النحو التالي : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

maxItems string (int64 format)

اختياريّ. الحدّ الأقصى لعدد العناصر من النوع Type.ARRAY

minItems string (int64 format)

اختياريّ. الحد الأدنى لعدد العناصر في Type.ARRAY

properties map (key: string, value: object (Schema))

اختياريّ. خصائص Type.OBJECT

عنصر يحتوي على قائمة بأزواج "key": value مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

required[] string

اختياريّ. السمات المطلوبة من النوع Type.OBJECT

minProperties string (int64 format)

اختياريّ. الحدّ الأدنى لعدد السمات الخاصة بـ Type.OBJECT

maxProperties string (int64 format)

اختياريّ. الحدّ الأقصى لعدد السمات من النوع OBJECT

minLength string (int64 format)

اختياريّ. حقول المخطط من النوع STRING، الحد الأدنى لطول النوع STRING

maxLength string (int64 format)

اختياريّ. الحد الأقصى لطول Type.STRING

pattern string

اختياريّ. نمط Type.STRING لحصر سلسلة بتعبير عادي

example value (Value format)

اختياريّ. مثال على العنصر سيتم ملء هذا الحقل فقط عندما يكون العنصر هو العنصر الجذر.

anyOf[] object (Schema)

اختياريّ. يجب التحقّق من صحة القيمة مقارنةً بأي من المخططات الفرعية (واحد أو أكثر) في القائمة.

propertyOrdering[] string

اختياريّ. ترتيب السمات ليس حقلاً عاديًا في مواصفات Open API، ويُستخدم لتحديد ترتيب السمات في الاستجابة.

default value (Value format)

اختياريّ. القيمة التلقائية للحقل وفقًا لمخطط JSON، هذا الحقل مخصّص لأدوات إنشاء المستندات ولا يؤثر في عملية التحقّق من الصحة. لذلك، يتم تضمينه هنا وتجاهله حتى لا تظهر للمطوّرين الذين يرسلون مخططات تتضمّن الحقل default أخطاء الحقل غير المعروف.

items object (Schema)

اختياريّ. مخطط عناصر Type.ARRAY

minimum number

اختياريّ. حقول المخطط لنوع العدد الصحيح (INTEGER) والرقم (NUMBER) الحد الأدنى لقيمة النوع INTEGER والرقم 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 في حال ضبطها، لن ينتظر النظام تلقّي ردّ الدالة. بدلاً من ذلك، سيحاول التعامل مع ردود الوظائف فور توفّرها مع الحفاظ على المحادثة بين المستخدم والنموذج.

GoogleSearchRetrieval

أداة لاسترداد بيانات الويب المتاحة للجميع من أجل تحديد المصدر، وهي من تطوير Google.

الحقول
dynamicRetrievalConfig object (DynamicRetrievalConfig)

تحدّد هذه السمة إعدادات الاسترجاع الديناميكي للمصدر المحدّد.

تمثيل JSON
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

توضّح هذه السمة خيارات تخصيص الاسترجاع الديناميكي.

الحقول
mode enum (Mode)

وضع أداة التوقّع التي سيتم استخدامها في الاسترجاع الديناميكي.

dynamicThreshold number

الحدّ المستخدَم في الاسترجاع الديناميكي. في حال عدم ضبط هذه السياسة، يتم استخدام قيمة تلقائية للنظام.

تمثيل JSON
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

الوضع

وضع أداة التوقّع التي سيتم استخدامها في الاسترجاع الديناميكي.

عمليات التعداد
MODE_UNSPECIFIED تفعيل عملية الاسترداد دائمًا
MODE_DYNAMIC إجراء عملية الاسترجاع فقط عندما يقرّر النظام أنّها ضرورية

CodeExecution

لا يتضمّن هذا النوع أي حقول.

أداة تنفّذ الرمز الذي ينشئه النموذج وتعرض النتيجة تلقائيًا على النموذج.

يمكنك الاطّلاع أيضًا على ExecutableCode وCodeExecutionResult اللذين يتم إنشاؤهما فقط عند استخدام هذه الأداة.

GoogleSearch

نوع أداة GoogleSearch أداة لدعم "بحث Google" في Model بواسطة Google.

الحقول
timeRangeFilter object (Interval)

اختياريّ. فلترة نتائج البحث لتظهر خلال نطاق زمني محدّد إذا حدّد العملاء وقت بدء، عليهم تحديد وقت انتهاء (والعكس صحيح).

searchTypes object (SearchTypes)

اختياريّ. مجموعة أنواع البحث التي سيتم تفعيلها. في حال عدم ضبط هذه السياسة، يتم تفعيل "بحث الويب" تلقائيًا.

تمثيل JSON
{
  "timeRangeFilter": {
    object (Interval)
  },
  "searchTypes": {
    object (SearchTypes)
  }
}

الفاصل الزمني

يمثّل فاصلاً زمنيًا محدّدًا يتم ترميزه بطابع زمني للبداية (مشمولة) وطابع زمني للنهاية (غير مشمولة).

يجب أن تكون البداية مساوية أو أقدم من النهاية. إذا كانت البداية مساوية للنهاية، يكون الفاصل فارغًا (أي لا يطابق أي وقت). وإذا لم يتم تحديد البداية والنهاية، يطابق الفاصل أي وقت.

الحقول
startTime string (Timestamp format)

اختياريّ. يمثّل بداية الفاصل الزمني (مشمولة).

إذا تم تحديد هذا الحقل، يجب أن يكون أي طابع زمني يطابق هذا الفاصل مساويًا أو لاحقًا لوقت البداية.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

اختياري. يمثّل نهاية الفاصل الزمني (غير مشمولة).

إذا تم تحديد هذا الحقل، يجب أن يكون أي طابع زمني يطابق هذا الفاصل قبل وقت النهاية.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

تمثيل JSON
{
  "startTime": string,
  "endTime": string
}

SearchTypes

أنواع مختلفة من عمليات البحث التي يمكن تفعيلها في أداة GoogleSearch

الحقول
تمثيل JSON
{
  "webSearch": {
    object (WebSearch)
  },
  "imageSearch": {
    object (ImageSearch)
  }
}

WebSearch

لا يتضمّن هذا النوع أي حقول.

بحث الويب العادي لتحديد المصدر والإعدادات ذات الصلة

ImageSearch

لا يتضمّن هذا النوع أي حقول.

البحث عن الصور لتحديد المعلومات الأساسية والإعدادات ذات الصلة

ComputerUse

نوع أداة "استخدام الكمبيوتر"

الحقول
environment enum (Environment)

الحقل مطلوب. البيئة التي يتم تشغيلها

excludedPredefinedFunctions[] string

اختياريّ. يتم تضمين الدوال المحدّدة مسبقًا في طلب النموذج النهائي تلقائيًا. يمكن استبعاد بعضها بشكل صريح من تضمينها تلقائيًا. يمكن أن يخدم ذلك غرضَين: 1. استخدام مساحة إجراءات أكثر تقييدًا أو مختلفة 2. تحسين تعريفات / تعليمات الدوال المحدّدة مسبقًا

تمثيل JSON
{
  "environment": enum (Environment),
  "excludedPredefinedFunctions": [
    string
  ]
}

البيئة

تمثّل هذه السمة البيئة التي يتم تشغيلها، مثل متصفّح الويب.

عمليات التعداد
ENVIRONMENT_UNSPECIFIED القيمة التلقائية هي "المتصفّح".
ENVIRONMENT_BROWSER تعمل في متصفّح ويب.

UrlContext

لا يتضمّن هذا النوع أي حقول.

أداة للمساعدة في استرداد سياق عنوان URL

FileSearch

أداة FileSearch التي تسترد المعلومات من مجموعات بيانات Semantic Retrieval. يتم استيراد الملفات إلى مجموعات مستندات أداة الاسترجاع الدلالي باستخدام ImportFile API.

الحقول
fileSearchStoreNames[] string

الحقل مطلوب. أسماء fileSearchStores التي سيتم استردادها. مثلاً: fileSearchStores/my-file-search-store-123

metadataFilter string

اختياريّ. فلتر البيانات الوصفية الذي سيتم تطبيقه على المستندات والأجزاء التي يتم استرجاعها دلاليًا.

topK integer

اختياريّ. عدد أجزاء الاسترجاع الدلالي المطلوب استرجاعها.

تمثيل JSON
{
  "fileSearchStoreNames": [
    string
  ],
  "metadataFilter": string,
  "topK": integer
}

McpServer

خادم MCPServer هو خادم يمكن للنموذج استدعاؤه لتنفيذ إجراءات. وهو خادم ينفّذ بروتوكول MCP. معرّف العنصر التالي: 5

الحقول
name string

تمثّل هذه السمة اسم MCPServer.

transport Union type
بروتوكول النقل الذي سيتم استخدامه للاتصال بخادم MCPServer. يمكن أن يكون التعليق transport إحدى القيم التالية فقط:
streamableHttpTransport object (StreamableHttpTransport)

نقل يمكنه بث طلبات واستجابات HTTP

تمثيل JSON
{
  "name": string,

  // transport
  "streamableHttpTransport": {
    object (StreamableHttpTransport)
  }
  // Union type
}

StreamableHttpTransport

نقل يمكنه بث طلبات واستجابات HTTP معرّف العنصر التالي: 6

الحقول
url string

عنوان URL الكامل لنقطة نهاية MCPServer مثال: "https://api.example.com/mcp"

headers map (key: string, value: string)

اختياري: حقول لعناوين المصادقة ومهلات الانتظار وما إلى ذلك، إذا لزم الأمر

عنصر يحتوي على قائمة بأزواج "key": value مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

timeout string (Duration format)

مهلة HTTP للعمليات العادية

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"

sseReadTimeout string (Duration format)

مهلة عمليات القراءة في SSE

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"

terminateOnClose boolean

تحديد ما إذا كان سيتم إغلاق جلسة العميل عند إغلاق النقل

تمثيل JSON
{
  "url": string,
  "headers": {
    string: string,
    ...
  },
  "timeout": string,
  "sseReadTimeout": string,
  "terminateOnClose": boolean
}

GoogleMaps

أداة GoogleMaps التي توفّر سياقًا جغرافيًا مكانيًا لطلب بحث المستخدم.

الحقول
enableWidget boolean

اختياريّ. تحديد ما إذا كان سيتم عرض رمز مميّز لسياق الأداة في GroundingMetadata الخاص بالردّ. يمكن للمطوّرين استخدام رمز سياق الأداة لعرض أداة "خرائط Google" تتضمّن سياقًا جغرافيًا مكانيًا ذا صلة بالأماكن التي يشير إليها النموذج في الردّ.

تمثيل JSON
{
  "enableWidget": boolean
}

ToolConfig

إعدادات الأداة التي تحتوي على مَعلمات لتحديد استخدام Tool في الطلب

الحقول
functionCallingConfig object (FunctionCallingConfig)

اختياريّ. إعدادات استدعاء الدالة

retrievalConfig object (RetrievalConfig)

اختياريّ. إعدادات الاسترجاع

includeServerSideToolInvocations boolean

اختياريّ. إذا كانت القيمة صحيحة، سيتضمّن ردّ واجهة برمجة التطبيقات طلبات الأدوات وردودها من جهة الخادم ضمن رسالة Content. يتيح ذلك للعملاء مراقبة تفاعلات الخادم مع الأدوات.

تمثيل JSON
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  },
  "retrievalConfig": {
    object (RetrievalConfig)
  },
  "includeServerSideToolInvocations": boolean
}

FunctionCallingConfig

إعدادات لتحديد سلوك استدعاء الدوال

الحقول
mode enum (Mode)

اختياريّ. تحدّد هذه السمة الوضع الذي يجب أن يتم فيه تنفيذ ميزة "استدعاء الدوال". في حال عدم تحديدها، سيتم ضبط القيمة التلقائية على AUTO.

allowedFunctionNames[] string

اختياريّ. مجموعة من أسماء الدوال التي تحدّ من الدوال التي سيستدعيها النموذج عند توفيرها.

يجب ضبط هذه السمة فقط عندما يكون الوضع ANY أو VALIDATED. يجب أن تتطابق أسماء الدوال مع [FunctionDeclaration.name]. عند ضبط هذه السمة، سيتوقّع النموذج استدعاء دالة من أسماء الدوال المسموح بها فقط.

تمثيل JSON
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}

الوضع

تحدّد هذه السمة سلوك التنفيذ الخاص بميزة "استدعاء الدوال" من خلال تحديد وضع التنفيذ.

عمليات التعداد
MODE_UNSPECIFIED وضع طلب غير محدّد للدالة يجب عدم استخدام هذه القيمة.
AUTO السلوك التلقائي للنموذج، حيث يقرر النموذج التنبؤ إما باستدعاء دالة أو ردّ باللغة الطبيعية.
ANY يقتصر النموذج على توقّع استدعاء دالة فقط. في حال ضبط "allowedFunctionNames"، سيقتصر طلب استدعاء الدالة المتوقّعة على أيّ من "allowedFunctionNames"، وإلا سيكون طلب استدعاء الدالة المتوقّعة أيًّا من "functionDeclarations" المقدَّمة.
NONE لن يتوقّع النموذج أي استدعاء دالة. يكون سلوك النموذج هو نفسه عند عدم تمرير أي تعريفات للدوال.
VALIDATED يقرّر النموذج توقّع إما استدعاء دالة أو ردّ باللغة الطبيعية، ولكنّه سيتحقّق من صحة استدعاءات الدوال باستخدام فك الترميز المقيد. في حال ضبط "allowedFunctionNames"، سيقتصر طلب استدعاء الدالة المتوقّعة على أيّ من "allowedFunctionNames"، وإلا سيكون طلب استدعاء الدالة المتوقّعة أيًّا من "functionDeclarations" المقدَّمة.

RetrievalConfig

إعدادات الاسترجاع

الحقول
latLng object (LatLng)

اختياريّ. الموقع الجغرافي للمستخدم

languageCode string

اختياريّ. رمز لغة المستخدم. تمثّل هذه السمة رمز اللغة الخاص بالمحتوى. استخدِم علامات اللغة المحدّدة في BCP47.

تمثيل JSON
{
  "latLng": {
    object (LatLng)
  },
  "languageCode": string
}

LatLng

كائن يمثّل زوجًا من خطوط الطول والعرض. يتم التعبير عن ذلك كزوج من الأرقام المضاعفة لتمثيل درجات خط العرض ودرجات خط الطول. ما لم يُحدّد خلاف ذلك، يجب أن يتوافق هذا العنصر مع معيار WGS84. يجب أن تكون القيم ضمن النطاقات العادية.

الحقول
latitude number

تمثّل هذه السمة خط العرض بالدرجات. يجب أن يكون ضمن النطاق [-90.0, +90.0].

longitude number

تمثّل هذه السمة خط الطول بالدرجات. يجب أن تكون القيمة ضمن النطاق [-180.0, +180.0].

تمثيل JSON
{
  "latitude": number,
  "longitude": number
}

UsageMetadata

البيانات الوصفية المتعلقة باستخدام المحتوى المخزَّن مؤقتًا

الحقول
totalTokenCount integer

إجمالي عدد الرموز المميزة التي يستهلكها المحتوى المخزّن مؤقتًا

تمثيل JSON
{
  "totalTokenCount": integer
}