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

name string

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

displayName string

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

model string

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

systemInstruction object (Content)

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

toolConfig object (ToolConfig)

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

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

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

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

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

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

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

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

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.

نقطة نهاية

الحصول على 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

نقطة نهاية

الحصول على https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

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

name string

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

نص الطلب

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

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

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

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 (لا يمكن تعديل سوى تاريخ انتهاء الصلاحية)

نقطة نهاية

تصحيح 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".

name string

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

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

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

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

نقطة نهاية

حذف https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

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

name string

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

نص الطلب

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

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

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

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"

نص الاستجابة

إذا كانت الاستجابة ناجحة، يكون نص الاستجابة هو عنصر 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 بالكيلوبايت الأوّلي.

الحقول
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

تمثيل JSON
{

  // data
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  }
  // 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 أو أن يحتوي على شرطات سفلية وشرطة، ويجب ألا يزيد طوله عن 63 حرفًا.

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 أو أن يحتوي على شرطات سفلية وشرطة، ويجب ألا يزيد طوله عن 63 حرفًا.

response object (Struct format)

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

تمثيل JSON
{
  "id": string,
  "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_UNSPECIFIED لغة غير محدّدة يجب عدم استخدام هذه القيمة.
PYTHON الإصدار 3.10 من لغة Python أو الإصدارات الأحدث، مع توفّر مكتبتَي 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" للردّ التالي في النموذج.

googleSearchRetrieval object (GoogleSearchRetrieval)

اختيارية: أداة استرجاع مستندات مستندة إلى "بحث Google"

codeExecution object (CodeExecution)

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

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

FunctionDeclaration

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

الحقول
name string

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

description string

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

parameters object (Schema)

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

response object (Schema)

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

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

المخطط

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

الحقول
type enum (Type)

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

format string

اختيارية: تنسيق البيانات لا يُستخدَم هذا الإجراء إلا مع أنواع البيانات الأساسية. التنسيقات المتوافقة: لنوع NUMBER: float وdouble لنوع INTEGER: int32 وint64 لنوع STRING: enum وdate-time

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

اختيارية: خصائص Type.OBJECT.

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

required[] string

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

propertyOrdering[] string

اختيارية: ترتيب السمات ليس حقلًا عاديًا في مواصفات واجهة برمجة التطبيقات المفتوحة. يُستخدَم لتحديد ترتيب المواقع في الاستجابة.

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
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

النوع

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

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

GoogleSearchRetrieval

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

الحقول
dynamicRetrievalConfig object (DynamicRetrievalConfig)

تُحدِّد إعدادات الاسترجاع الديناميكي للمصدر المحدّد.

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

DynamicRetrievalConfig

يصف خيارات تخصيص الاسترجاع الديناميكي.

الحقول
mode enum (Mode)

وضع المتنبّئ الذي سيتم استخدامه في الاسترجاع الديناميكي

dynamicThreshold number

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

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

الوضع

وضع المتنبّئ الذي سيتم استخدامه في الاسترجاع الديناميكي

عمليات التعداد
MODE_UNSPECIFIED بدء عملية الاسترداد دائمًا
MODE_DYNAMIC لا يتم تنفيذ عملية الاسترداد إلا عندما يقرر النظام أنّ ذلك ضروري.

CodeExecution

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

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

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

GoogleSearch

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

نوع أداة "بحث Google" أداة لدعم "بحث Google" في النموذج متوفّر من خلال Google

ToolConfig

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

الحقول
functionCallingConfig object (FunctionCallingConfig)

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

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

FunctionCallingConfig

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

الحقول
mode enum (Mode)

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

allowedFunctionNames[] string

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

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

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

الوضع

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

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

UsageMetadata

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

الحقول
totalTokenCount integer

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

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