Caching

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

الطريقة: cacheContents.create

لإنشاء مورد CachedContent

نقطة نهاية

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

نص الطلب

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

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

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

tools[] object (Tool)

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

حقل الربط expiration تُستخدَم لتحديد وقت انتهاء صلاحية هذا المورد. يمكن أن يكون expiration واحدًا فقط مما يلي:
expireTime string (Timestamp format)

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

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"

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)

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

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

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

Python

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

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

Node.js

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

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

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

console.log(cacheResult);

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

البدء

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

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

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

printResponse(resp)

صَدفة

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

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

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

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

من الاسم

Python

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

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

Node.js

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

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

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

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

البدء

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

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

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

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

printResponse(resp)

من المحادثة

Python

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

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

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

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

Node.js

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

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

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

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

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

const newModel = genAI.getGenerativeModelFromCachedContent(cacheResult);

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

البدء

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

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

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

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

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

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

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

نص الاستجابة

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

الطريقة: cachedContents.list

يسرد CachedContents.

نقطة نهاية

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

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

pageSize integer

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

pageToken string

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

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

نص الطلب

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

نص الاستجابة

استجابة تتضمّن قائمة CachedContents

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

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

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

nextPageToken string

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

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

الطريقة: cacheContents.get

قراءة مورد CachedContent.

نقطة نهاية

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

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

name string

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

نص الطلب

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

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

Python

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

Node.js

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

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

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

البدء

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

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

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

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

printResponse(resp)

صَدفة

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

نص الاستجابة

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

الطريقة: cachedContents.patch

تعديل مورد CachedContent (لا يمكن تعديل سوى تاريخ انتهاء الصلاحية)

نقطة نهاية

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 تحدِّد هذه السياسة تاريخ انتهاء صلاحية هذا المورد. يمكن أن يكون expiration واحدًا فقط مما يلي:
expireTime string (Timestamp format)

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

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"

ttl string (Duration format)

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

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

name string

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

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

Python

import datetime

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

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

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

Node.js

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

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

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

البدء

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

صَدفة

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

نص الاستجابة

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

الطريقة: cachedContents.delete

لحذف المرجع CachedContent

نقطة نهاية

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

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

name string

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

نص الطلب

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

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

Python

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

Node.js

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

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

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

البدء

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

صَدفة

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

نص الاستجابة

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

مورد REST: cachedContents

المورد: CachedContent

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

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

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

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

tools[] object (Tool)

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

createTime string (Timestamp format)

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

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

updateTime string (Timestamp format)

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

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

usageMetadata object (UsageMetadata)

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

حقل الاتحاد expiration. تحدِّد هذه السياسة تاريخ انتهاء صلاحية هذا المورد. يمكن أن يكون expiration واحدًا فقط مما يلي:
expireTime string (Timestamp format)

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

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"

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

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

المحتوى

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

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

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

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

role string

اختياريّ. منتج المحتوى. يجب أن تكون "user" أو "model".

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

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

الجزء

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

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

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

الحقول

حقل الاتحاد data.

يمكن أن يكون data واحدًا فقط مما يلي:

text string

نص مضمّن.

inlineData object (Blob)

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

functionCall object (FunctionCall)

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

functionResponse object (FunctionResponse)

إنّ ناتج FunctionCall الذي يتضمّن سلسلة تمثّل FunctionDeclaration.name وكائن JSON منظمًا يحتوي على أي ناتج من الدالة يُستخدم كسياق للنموذج.

fileData object (FileData)

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

executableCode object (ExecutableCode)

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

codeExecutionResult object (CodeExecutionResult)

نتيجة تنفيذ ExecutableCode

تمثيل JSON
{

  // Union field data can be only one of the following:
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  }
  // End of list of possible types for union field data.
}

بلوب

وحدات البايت للوسائط غير المُعدَّة

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

الحقول
mimeType string

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

data string (bytes format)

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

سلسلة بترميز base64

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

FunctionCall

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

الحقول
name string

مطلوب. اسم الدالة المطلوب استدعاؤها يجب أن يكون من a-z أو A-Z أو 0-9 أو أن يحتوي على شرطات سفلية وشرطة، ويجب ألا يزيد طوله عن 63 حرفًا.

args object (Struct format)

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

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

FunctionResponse

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

الحقول
name string

مطلوب. اسم الدالة المطلوب استدعاؤها يجب أن يكون النص a-z أو A-Z أو 0-9 أو يحتوي على شرطات سفلية وشرطات، ولا يزيد طولها عن 63 حرفًا.

response object (Struct format)

مطلوب. استجابة الدالة بتنسيق عنصر JSON

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

FileData

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

الحقول
mimeType string

اختياريّ. تمثّل هذه السمة نوع MIME العادي لبيانات المصدر الصادر عن هيئة أرقام الإنترنت المخصصة (IANA).

fileUri string

مطلوب. معرّف الموارد المنتظم (URI).

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

ExecutableCode

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

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

الحقول
language enum (Language)

مطلوب. لغة البرمجة الخاصة بالملف code

code string

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

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

Language

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

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

CodeExecutionResult

نتيجة تنفيذ ExecutableCode.

لا يتم إنشاؤه إلا عند استخدام CodeExecution، ويتبع دائمًا part يحتوي على ExecutableCode.

الحقول
outcome enum (Outcome)

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

output string

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

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

النتيجة

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

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

الأداة

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

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

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

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

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

codeExecution object (CodeExecution)

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

تمثيل JSON
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "codeExecution": {
    object (CodeExecution)
  }
}

FunctionDeclaration

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

الحقول
name string

مطلوب. اسم الدالة يجب أن يكون النص a-z أو A-Z أو 0-9 أو يحتوي على شرطات سفلية وشرطات، ولا يزيد طولها عن 63 حرفًا.

description string

مطلوب. تمثّل هذه السمة وصفًا موجزًا للدالة.

parameters object (Schema)

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

تمثيل JSON
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  }
}

المخطط

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

الحقول
type enum (Type)

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

format string

اختياريّ. تنسيق البيانات لا يُستخدَم هذا الإجراء إلا مع أنواع البيانات الأساسية. التنسيقات المتوافقة: لنوع NUMBER: عدد عشري، ومزدوج لنوع العدد الصحيح: int32، وint64 لنوع السلسلة: enum.

description string

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

nullable boolean

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

enum[] string

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

maxItems string (int64 format)

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

minItems string (int64 format)

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

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

اختياريّ. خصائص النوع.OBJECT.

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

required[] string

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

items object (Schema)

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

تمثيل JSON
{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "items": {
    object (Schema)
  }
}

النوع

يحتوي النوع على قائمة بأنواع بيانات OpenAPI كما هو موضح في https://spec.openapis.org/oas/v3.0.3#data-types

عمليات التعداد
TYPE_UNSPECIFIED لم يتم تحديده، ولا يُسمح باستخدامه.
STRING نوع السلسلة
NUMBER نوع الرقم
INTEGER نوع عدد صحيح
BOOLEAN نوع منطقي
ARRAY نوع المصفوفة
OBJECT نوع الكائن:

CodeExecution

لا يحتوي هذا النوع على أي حقول.

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

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

ToolConfig

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

الحقول
functionCallingConfig object (FunctionCallingConfig)

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

تمثيل JSON
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  }
}

FunctionCallingConfig

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

الحقول
mode enum (Mode)

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

allowedFunctionNames[] string

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

يجب ضبط هذا الإعداد فقط عندما يكون الوضع "Any". يجب أن تتطابق أسماء الدوال مع [FunctionDeclaration.name]. عند تعيين الوضع على "أي"، يتوقع النموذج استدعاء الدالة من مجموعة أسماء الدوال المتوفرة.

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

الوضع

تحدد سلوك التنفيذ لاستدعاء الدوال من خلال تحديد وضع التنفيذ.

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

UsageMetadata

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

الحقول
totalTokenCount integer

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

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