GeminiWithFiles
v2.0.2
تستمر واجهة برمجة تطبيقات Gemini في النمو. في 5 أغسطس 2024، قمت بتحديث GeminiWithFiles إلى حد كبير إلى الإصدار v2.xx. وبهذا التحديث الكبير، تم تغيير الإصدار من الإصدار v1 إلى الإصدار 2.
إذا كنت تريد استخدام GeminiWithFiles v1.xx، يرجى الاطلاع هنا.
هذه مكتبة Google Apps Script لـ Gemini API مع الملفات.
تعمل مكتبة Google Apps Script الجديدة المسماة GeminiWithFiles على تبسيط استخدام Gemini، وهو نموذج لغة كبير، لمعالجة البيانات غير المنظمة مثل الصور وملفات PDF. يمكن لـ GeminiWithFiles تحميل الملفات وإنشاء المحتوى وإنشاء أوصاف من صور متعددة في وقت واحد. وهذا يقلل بشكل كبير من عبء العمل ويوسع إمكانيات استخدام الجوزاء.
في الآونة الأخيرة، جلب نموذج Gemini، وهو نموذج لغة كبير من Google AI، إمكانيات جديدة لمختلف المهام من خلال تمكين استخدام البيانات غير المنظمة كبيانات منظمة. وهذا مهم بشكل خاص لأن كمية هائلة من المعلومات موجودة في تنسيقات غير منظمة مثل المستندات النصية والصور ومقاطع الفيديو.
تعمل واجهة برمجة تطبيقات Gemini 1.5، التي تم إصدارها مؤخرًا، على توسيع هذه القدرات بشكل كبير. يمكنه إنشاء محتوى بما يصل إلى مليون رمز، وهي زيادة كبيرة مقارنة بالإصدارات السابقة. بالإضافة إلى ذلك، يمكن لـ Gemini 1.5 الآن معالجة ما يصل إلى 3000 ملف صورة، وهو ما يتجاوز بشكل كبير حد Gemini 1.0 البالغ 16 صورة. المرجع
على الرغم من أن Gemini لا يمكنه العمل مباشرة مع تنسيقات Google Drive مثل المستندات وجداول البيانات والعروض التقديمية، إلا أن هناك حلول بديلة. في المرحلة الحالية، يمكن معالجة بيانات PDF مباشرة باستخدام Gemini API. باستخدام هذا، يتم تحويل ملفات Google Docs إلى PDF واستخدامها مع Gemini API. المرجع
يقدم هذا التقرير مكتبة Google Apps Script جديدة تسمى "GeminiWithFiles" والتي تعمل على تبسيط هذه العملية. يتيح برنامج GeminiWithFiles للمستخدمين إمكانية تحميل الملفات وإنشاء المحتوى بسهولة باستخدام إمكانات Gemini القوية. كما أنه يتيح إنشاء وصف فعال من صور متعددة من خلال استدعاء واجهة برمجة التطبيقات (API) واحد، مما يقلل بشكل كبير من عبء العمل مقارنة بمعالجة كل صورة على حدة كما هو موضح في تقريري السابق. المرجع
من خلال تبسيط العملية وتوسيع القدرات، يعد برنامج GeminiWithFiles بحالات استخدام متنوعة عبر مجالات مختلفة. يعد هذا التقرير بمثابة نهج موسع للتقرير السابق، ويهدف إلى تقليل تكاليف العملية بشكل أكبر وتحسين الكفاءة عند العمل مع Gemini والبيانات غير المنظمة.
لقد قمت بإنشاء هذه المكتبة بناءً على التقارير التالية.
تتيح لك مكتبة GeminiWithFiles هذه التفاعل مع Gemini، وهي منصة قوية لمعالجة المستندات وإدارتها، من خلال واجهة برمجة تطبيقات سهلة الاستخدام. إليك ما يمكنك تحقيقه باستخدام هذه المكتبة:
إدارة الملفات:
تحميل المحتوى:
إدارة سجل الدردشة:
إنشاء المحتوى:
مواصفات الإخراج:
حدد تنسيق الإخراج المطلوب للنتائج التي تم إنشاؤها بواسطة Gemini API.
باستخدام response_mime_type ومخطط JSON، يتم التحكم في تنسيق الإخراج. المرجع
من أجل اختبار هذا البرنامج النصي، يرجى القيام بالخطوات التالية.
الرجاء الوصول إلى https://makerssuite.google.com/app/apikey وإنشاء مفتاح واجهة برمجة التطبيقات (API) الخاص بك. في ذلك الوقت، يرجى تمكين Geneative Language API في وحدة تحكم API. يتم استخدام مفتاح API هذا لنموذج البرنامج النصي هذا.
يمكن أيضًا رؤية هذه الوثيقة الرسمية. المرجع.
الرجاء إنشاء مشروع Google Apps Script مستقل. بالطبع، يمكن أيضًا استخدام هذا البرنامج النصي مع البرنامج النصي المرتبط بالحاوية.
ويرجى فتح محرر البرامج النصية لمشروع Google Apps Script.
هناك نمطان لاستخدام GeminiWithFiles.
إذا كنت تستخدم هذه المكتبة كمكتبة Google Apps Script، فيرجى تثبيت المكتبة على مشروع Google Apps Script الخاص بك على النحو التالي.
أنشئ مشروع Google Apps Script. أو افتح مشروع Google Apps Script الخاص بك.
قم بتثبيت هذه المكتبة.
1dolXnIeXKz-BH1BlwRDaKhzC2smJcGyVxMxGYhaY2kqiLa857odLXrIC
إذا كنت تستخدم هذه المكتبة في مشروع Google Apps Script الخاص بك، فيرجى نسخ ولصق النص البرمجي "classGeminiWithFiles.js" في مشروع Google Apps Script. من خلال هذا، يمكن استخدام البرنامج النصي.
يتم استخدام "main.js" لمكتبة Google Apps Script. لذلك، في هذا النمط، لا يطلب منك استخدامه.
تستخدم هذه المكتبة النطاقين التاليين.
https://www.googleapis.com/auth/script.external_requesthttps://www.googleapis.com/auth/driveإذا كنت تريد استخدام رمز الوصول، فيرجى ربط مشروع Google Cloud Platform بمشروع Google Apps Script. ويرجى إضافة النطاق التالي.
https://www.googleapis.com/auth/generative-languageيمكنك أيضًا الاطلاع على الوثيقة الرسمية لـ Gemini API على https://ai.google.dev/api/rest.
| طُرق | وصف |
|---|---|
| setFileIds(fileIds, asImage = false) | تعيين معرفات الملفات. |
| مجموعة النقط (النقط) | تعيين النقط. |
| معUploadedFilesByGenerateContent(fileList = []) | قم بإنشاء كائن لاستخدام طريقة generatorContent. |
| تحميل الملفات (ن = 50) | تحميل الملفات إلى الجوزاء. |
| قائمة الملف () | الحصول على قائمة الملفات في الجوزاء. |
| حذف الملفات (الأسماء، ن = 50) | حذف الملفات من الجوزاء. |
| إنشاء المحتوى (كائن) | الطريقة الرئيسية. إنشاء محتوى بواسطة Gemini API. |
| setFileIdsOrUrlsWithResumableUpload(object) | يمكن تحميل ملف يزيد حجمه عن 50 ميجابايت إلى Gemini. |
عند تثبيت GeminiWithFiles كمكتبة لمشروع Google Apps Script، يرجى استخدام النص البرمجي التالي.
const g = GeminiWithFiles . geminiWithFiles ( object ) ;أو
عندما تقوم بنسخ ولصق البرنامج النصي لـ Class GeminiWithFiles مباشرة في مشروع Google Apps Script، يرجى استخدام البرنامج النصي التالي.
const g = new GeminiWithFiles ( object ) ; قيمة object هي كما يلي.
{Object} object API key or access token for using Gemini API.
{String} object.apiKey API key.
{String} object.accessToken Access token.
{String} object.model Model. Default is "models/gemini-1.5-pro-latest".
{String} object.version Version of API. Default is "v1beta".
{Boolean} object.doCountToken Default is false. If this is true, when Gemini API is requested, the token of request is shown in the log.
{Array} object.history History for continuing chat.
{Array} object.functions If you want to give the custom functions, please use this.
{String} object.response_mime_type In the current stage, only "application/json" can be used.
{String} object.responseMimeType In the current stage, only "application/json" can be used.
{Object} object.response_schema JSON schema for controlling the output format.
{Object} object.responseSchema JSON schema for controlling the output format.
{Number} object.temperature Control the randomness of the output.
{Object} object.systemInstruction Ref: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/gemini.
{Boolean} object.exportTotalTokens When this is true, the total tokens are exported as the result value. At that time, the generated content and the total tokens are returned as an object.
{Boolean} object.exportRawData The default value is false. When this is true, the raw data returned from Gemini API is returned.
{Object} object.toolConfig The default is null. If you want to directly give the object of "toolConfig", please use this.
{Array} object.tools The default value is null. For example, when you want to use "codeExecution", please set `tools: [{ codeExecution: {}}]`.
{PropertiesService.Properties} object.propertiesService PropertiesService.getScriptProperties()
{Boolean} object.resumableUploadAsNewUpload When you want to upload the data with the resumable upload as new upload, please set this as true. The default is false.
عندما تريد استخدام response_mime_type ، يرجى إعطاء jsonSchema لطريقة إنشاء المحتوى. في المرحلة الحالية، يمكن استخدام "application/json" فقط response_mime_type .
عندما تريد استخدام systemInstruction ، يرجى تأكيد الوثيقة الرسمية المرجع.
يتم استخدام Gemini 1.5 Flash Last ( models/gemini-1.5-flash-latest ) كنموذج افتراضي. عندما تريد استخدام Gemini 1.5 Pro الأحدث ( models/gemini-1.5-pro-latest )، يرجى استخدامه مثل const g = GeminiWithFiles.geminiWithFiles({ apiKey, model: "models/gemini-1.5-pro-latest" }) .
في المرحلة الحالية، عند استخدام response_schema ، يتم استخدام response_mime_type: "application/json" تلقائيًا.
تعيين معرفات الملفات. يتم تحميل ملفات معرفات الملفات إلى Gemini.
في هذه الحالة، يتم استخدام المزامنة/الانتظار في الوظيفة.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const folderId = "###" ; // Please set your folder ID including images.
let fileIds = [ ] ;
const files = DriveApp . getFolderById ( folderId ) . getFiles ( ) ;
while ( files . hasNext ( ) ) {
const file = files . next ( ) ;
fileIds . push ( file . getId ( ) ) ;
}
const g = GeminiWithFiles . geminiWithFiles ( { apiKey } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const res = g . setFileIds ( fileIds , false ) . uploadFiles ( ) ;
console . log ( res ) ;
}setFileIds هي String[] (معرفات الملفات على Google Drive) والوسيطة المنطقية، على التوالي. إذا كانت الوسيطة الثانية خاطئة، فسيتم تحميل الملفات المدخلة لمعرفات الملفات كبيانات أولية. إذا كانت الوسيطة الثانية صحيحة، فسيتم تحويل الملفات المدخلة لمعرفات الملفات إلى بيانات صورة ويتم تحميلها. الافتراضي للوسيطة الثانية غير صحيح.false في هذه الطريقة مثل setFileIds(fileIds, false) . تعيين النقط. يتم تحميل النقط إلى الجوزاء.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const folderId = "###" ; // Please set your folder ID including images.
const blobs = [ ] ;
const files = DriveApp . getFolderById ( folderId ) . getFiles ( ) ;
while ( files . hasNext ( ) ) {
blobs . push ( files . next ( ) . getBlob ( ) ) ;
}
const g = GeminiWithFiles . geminiWithFiles ( { apiKey } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const res = g . setBlobs ( blobs ) . uploadFiles ( ) ;
console . log ( res ) ;
}setBlobs هي Blob[].قم بإنشاء كائن لاستخدام طريقة generatorContent.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const q = "###" ; // Please set your question.
const g = GeminiWithFiles . geminiWithFiles ( { apiKey } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const fileList = g . getFileList ( ) ;
const res = g
. withUploadedFilesByGenerateContent ( fileList )
. generateContent ( { q } ) ;
console . log ( res ) ;
}withUploadedFilesByGenerateContent على وسيطة واحدة فقط. هذه هي القيمة من طريقة getFileList. يمكنك رؤية القيم الفعلية بعد تحميل الملفات.تحميل الملفات إلى الجوزاء. يتم تحميل الملفات إلى Gemini باستخدام معرفات الملفات المدخلة أو النقط.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const fileIds = [ "###fileId1###" , "###fileId2###" , , , ] ; // Please set your file IDs in this array.
const g = GeminiWithFiles . geminiWithFiles ( { apiKey } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const res = g . setFileIds ( fileIds , false ) . uploadFiles ( ) ;
console . log ( res ) ;
} في هذا البرنامج النصي، يتم تحميل ملفات fileIds إلى Gemini مع البيانات الأولية. إذا تم تعديل setFileIds(fileIds, false) إلى setFileIds(fileIds, true) ، فسيتم تحميل الملفات إلى Gemini كصور.
عند استخدام Blob مباشرة، يمكنك استخدام البرنامج النصي التالي.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const fileIds = [ "###fileId1###" , "###fileId2###" , , , ] ; // Please set your file IDs in this array.
const blobs = fileIds . map ( id => DriveApp . getFileById ( id ) . getBlob ( ) ) ;
const g = GeminiWithFiles . geminiWithFiles ( { apiKey } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const res = g . setBlobs ( blobs ) . uploadFiles ( ) ;
console . log ( res ) ;
} الحصول على قائمة الملفات في الجوزاء.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const g = GeminiWithFiles . geminiWithFiles ( { apiKey } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const res = g . getFileList ( ) ;
console . log ( res ) ;
} حذف الملفات من الجوزاء.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const g = GeminiWithFiles . geminiWithFiles ( { apiKey } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const names = g . getFileList ( ) . map ( ( { name } ) => name ) ;
if ( names . length == 0 ) return ;
g . deleteFiles ( names ) ;
console . log ( ` ${ names . length } files were deleted.` ) ;
}الطريقة الرئيسية. إنشاء محتوى بواسطة Gemini API. يمكن رؤية المزيد من نماذج البرامج النصية في قسم "نماذج البرامج النصية" التالي.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const g = GeminiWithFiles . geminiWithFiles ( { apiKey } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const res = g . generateContent ( { q : "What is Google Apps Script?" } ) ;
console . log ( res ) ;
}في هذا البرنامج النصي، يتم إنشاء المحتوى باستخدام استدعاء الوظيفة.
عندما تريد استخدام response_mime_type ، يرجى إعطاء jsonSchema طريقة إنشاء المحتوى على النحو التالي. في هذه الحالة، من خلال إعطاء مخطط JSON فقط، يمكن لهذه المكتبة إرجاع كائن صالح. يمكنك أيضًا الاطلاع على المعلومات التفصيلية حول response_mime_type في تقريري.
function myFunction ( ) {
const apiKey = "###" ; // Please set your API key.
const g = GeminiWithFiles . geminiWithFiles ( {
apiKey ,
response_mime_type : "application/json" ,
} ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey, response_mime_type: "application/json" }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const jsonSchema = {
title : "5 popular cookie recipes" ,
description : "List 5 popular cookie recipes." ,
type : "array" ,
items : {
type : "object" ,
properties : {
recipe_name : {
description : "Names of recipe." ,
type : "string" ,
} ,
} ,
} ,
} ;
const res = g . generateContent ( { jsonSchema } ) ;
console . log ( res ) ;
}عند تشغيل هذا البرنامج النصي، يتم الحصول على النتيجة التالية.
[
{ "recipe_name" : " Chocolate Chip Cookies " },
{ "recipe_name" : " Peanut Butter Cookies " },
{ "recipe_name" : " Oatmeal Cookies " },
{ "recipe_name" : " Sugar Cookies " },
{ "recipe_name" : " Snickerdoodle Cookies " }
]يمكن لهذه الطريقة تحميل ملفات يزيد حجمها عن 50 ميجابايت.
من v2.xx، يمكن تحقيق ذلك. هذا من المرجع والمرجع.
من الإصدار 2.0.3، عند استخدام هذا الأسلوب، يرجى تضمين propertiesService: PropertiesService.getScriptProperties() في الكائن الأولي كما يلي. لأنه عند استخدام PropertiesService.getScriptProperties() في المكتبة، يتم وضع القيم في المكتبة. عندما قمت بإنشاء Ref وRef، افترضت أن البرنامج النصي يستخدم عن طريق النسخ واللصق بدلاً من المكتبة. لذلك، قمت بتضمين PropertiesService.getScriptProperties() في البرنامج النصي. لكنني لاحظت أنه عند استخدام هذا مع GeminiWithFiles، يُطلب من كل مستخدم استخدام PropertiesService.getScriptProperties() . لذلك، قمت بتعديل هذا.
نموذج البرنامج النصي كما يلي.
function myFunction ( ) {
// This URL is from https://github.com/google/generative-ai-docs/blob/main/site/en/gemini-api/docs/prompting_with_media.ipynb
const url = "https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4" ; // 64,657,027 bytes
const apiKey = "###" ; // Please set your API key.
const q = "Description this video." ;
const g = GeminiWithFiles . geminiWithFiles ( { apiKey , propertiesService : PropertiesService . getScriptProperties ( ) } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey, propertiesService: PropertiesService.getScriptProperties() }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const fileList = g . setFileIdsOrUrlsWithResumableUpload ( [ { url } ] ) . uploadFiles ( ) ;
Utilities . sleep ( 10000 ) ; // This might be required to be used because the state of the uploaded file might not be active.
const res = g . withUploadedFilesByGenerateContent ( fileList ) . generateContent ( { q } ) ;
console . log ( res ) ;
}عند تشغيل هذا البرنامج النصي، يمكن رؤية السجل التالي في السجل.
- Get metadata
- Calculate chunks
- Get location
- Download and upload data.
- Now... 1/4
- Start downloading data with 0-16777215
- Finished downloading data with 0-16777215
- Start uploading data with 0-16777215
- Finished uploading data with 0-16777215
- Upload the next chunk.
- Now... 2/4
- Start downloading data with 16777216-33554431
- Finished downloading data with 16777216-33554431
- Start uploading data with 16777216-33554431
- Finished uploading data with 16777216-33554431
- Upload the next chunk.
- Now... 3/4
- Start downloading data with 33554432-50331647
- Finished downloading data with 33554432-50331647
- Start uploading data with 33554432-50331647
- Finished uploading data with 33554432-50331647
- Upload the next chunk.
- Now... 4/4
- Start downloading data with 50331648-64657026
- Finished downloading data with 50331648-64657026
- Start uploading data with 50331648-64657026
- Finished uploading data with 50331648-64657026
- Done.
- Now, the state of the uploaded files "url@https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4$page@1$maxPage@1" is not active. So, it will wait until it is active. Please wait for 10 seconds. Retry (1/3)
- 1 uploaded files are used with generateCotent.
- The video is a cartoon that shows a large, white rabbit in a field. The rabbit is shown waking up from a nap and then is seen eating an apple. After eating the apple, the rabbit is approached by a bird. The rabbit is scared of the bird and tries to hide from it. The bird flies away. The rabbit is seen smiling and then a squirrel flies toward the rabbit. The squirrel is startled by the rabbit and flies away. The rabbit is then seen catching another squirrel with its vine and the scene ends with a close-up of the rabbit's face.
إذا كان ملفك كبيرًا ولم تكن حالة الملف الذي تم تحميله "نشطة"، فيرجى اختبار البرنامج النصي التالي.
function myFunction ( ) {
// This URL is from https://github.com/google/generative-ai-docs/blob/main/site/en/gemini-api/docs/prompting_with_media.ipynb
const url = "https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4" ; // 64,657,027 bytes
const apiKey = "###" ; // Please set your API key.
const q = "Description this video." ;
const g = GeminiWithFiles . geminiWithFiles ( { apiKey , propertiesService : PropertiesService . getScriptProperties ( ) } ) ; // This is for installing GeminiWithFiles as a library.
// const g = new GeminiWithFiles({ apiKey, propertiesService: PropertiesService.getScriptProperties() }); // This is for directly copying and pasting Class GeminiWithFiles into your Google Apps Script project.
const fileList = g . setFileIdsOrUrlsWithResumableUpload ( [ { url } ] ) . uploadFiles ( ) ;
console . log ( JSON . stringify ( fileList ) ) ;
// Please copy the value of "fileList".
}وبهذا يمكن تحميل الملف. ويمكنك استخدام الملف الذي تم تحميله بعد أن ينتظر وقتًا كافيًا لتغيير الحالة إلى "نشط". يمكن استخدام الملف الذي تم تحميله على النحو التالي.
