استكشاف الإمكانات البصرية باستخدام Gemini API

الاطّلاع على ai.google.dev تجربة "مفكرة Colab" عرض دفتر ملاحظات على GitHub

يمكن لنماذج Gemini معالجة الصور والفيديوهات، ما يتيح العديد من حالات استخدام المطوّرين المتقدّمة التي كانت تتطلّب في السابق نماذج خاصة بنطاق معيّن. تشمل بعض قدرات Gemini في مجال الرؤية ما يلي:

  • إضافة تعليقات توضيحية إلى الصور والإجابة عن أسئلة حولها
  • تحويل ملفات PDF إلى نص وتحليلها، بما في ذلك ما يصل إلى مليونَي رمز
  • وصف الفيديوهات التي تصل مدتها إلى 90 دقيقة وتقسيمها واستخراج المعلومات منها
  • رصد الأجسام في صورة وعرض إحداثيات مربّع الحدود لها

تم تصميم Gemini ليكون متعدّد الوسائط من البداية، ونحن نواصل توسيع حدود ما هو ممكن.

إدخال صورة

إذا كان حجم الحمولة الإجمالية للصورة أقل من 20 ميغابايت، ننصحك إما بتحميل صور مُشفَّرة بترميز base64 أو تحميل ملفات الصور المخزّنة على الجهاز مباشرةً.

العمل مع الصور المحلية

إذا كنت تستخدم مكتبة الصور في Python (Pillow )، يمكنك استخدام عناصر صور PIL أيضًا.

from google import genai
from google.genai import types

import PIL.Image

image = PIL.Image.open('/path/to/image.png')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=["What is this image?", image])

print(response.text)

صور مشفّرة بترميز Base64

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

from google import genai
from google.genai import types

import requests

image_path = "https://goo.gle/instrument-img"
image = requests.get(image_path)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What is this image?",
              types.Part.from_bytes(image.content, "image/jpeg")])

print(response.text)

صور متعددة

لطلب صور متعددة، يمكنك تقديم صور متعددة في الطلب إلى generate_content. ويمكن أن تكون هذه الصور بتنسيق متوافق، بما في ذلك base64 أو PIL.

from google import genai
from google.genai import types

import pathlib
import PIL.Image

image_path_1 = "path/to/your/image1.jpeg"  # Replace with the actual path to your first image
image_path_2 = "path/to/your/image2.jpeg" # Replace with the actual path to your second image

image_url_1 = "https://goo.gle/instrument-img" # Replace with the actual URL to your third image

pil_image = PIL.Image.open(image_path_1)

b64_image = types.Part.from_bytes(
    pathlib.Path(image_path_2).read_bytes(), "image/jpeg")

downloaded_image = requests.get(image_url_1)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What do these images have in common?",
              pil_image, b64_image, downloaded_image])

print(response.text)

يُرجى العِلم أنّ طلبات البيانات المضمّنة هذه لا تتضمّن العديد من الميزات المتاحة من خلال File API، مثل الحصول على البيانات الوصفية للملف أو إدراجه أو حذف الملفات.

حمولات الصور الكبيرة

عندما يكون حجم مجموعة الملفات وتعليمات النظام التي تريد إرسالها أكبر من 20 ميغابايت، استخدِم File API لتحميل هذه الملفات.

استخدِم طريقة media.upload في File API لتحميل صورة من أي حجم.

بعد تحميل الملف، يمكنك إرسال طلبات GenerateContent تشير إلى عنوان URL الخاص بـ File API. اختَر النموذج التوليدي وقدِّم له طلبًا نصيًا والصورة المحمَّلة.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

img_path = "/path/to/Cajun_instruments.jpg"
file_ref = client.files.upload(path=img_path)
print(f'{file_ref=}')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What can you tell me about these instruments?",
              file_ref])

print(response.text)

التوافق مع OpenAI

يمكنك الاستفادة من إمكانات Gemini في فهم الصور باستخدام مكتبات OpenAI. يتيح لك ذلك دمج Gemini في سير العمل الحالي في OpenAI من خلال تعديل ثلاثة أسطر من الرمز البرمجي واستخدام مفتاح Gemini API. اطّلِع على مثال على فهم الصور للحصول على رمز يوضّح كيفية إرسال صور مُشفَّرة كحمولات Base64.

طلب المساعدة باستخدام الصور

في هذا الدليل التعليمي، ستحمّل الصور باستخدام File API أو كبيانات مضمّنة وتنشئ محتوى استنادًا إلى هذه الصور.

التفاصيل الفنية (الصور)

يتيح Gemini 1.5 Pro و1.5 Flash استخدام 3,600 ملف صورة كحد أقصى.

يجب أن تكون الصور بأحد أنواع MIME التالية لبيانات الصور:

  • ‫PNG - image/png
  • ‫JPEG - image/jpeg
  • ‫WEBP ‏- image/webp
  • ‫HEIC - image/heic
  • ‫HEIF - image/heif

الرموز المميزة

في ما يلي كيفية احتساب الرموز المميّزة للصور:

  • Gemini 1.0 Pro Vision: تُمثّل كل صورة 258 رمزًا مميّزًا.
  • Gemini 1.5 Flash وGemini 1.5 Pro: إذا كانت سمتا الصورة تتعدان عن 384 بكسل أو كانتا متساويتين، يتم استخدام 258 رمزًا. إذا كان أحد سمات الصورة أكبر من 384 بكسل، يتم اقتصاص الصورة إلى مربّعات. يكون حجم كل قطعة مربّعة تلقائيًا هو أصغر سمة (العرض أو الارتفاع) مقسومًا على 1.5. إذا لزم الأمر، يتم تعديل كل مربّع لكي لا يكون أصغر من 256 بكسل ولا يزيد عن 768 بكسل. وبعد ذلك، يتم تغيير حجم كل مربّع إلى 768×768 ويستخدم 258 رمزًا مميزًا.
  • Gemini 2.0 Flash: يتم احتساب مدخلات الصور التي تقلّ أبعادها عن 384 بكسل على أنّها 258 رمزًا مميّزًا. يتم اقتصاص الصور الأكبر حجمًا في أحد البعدين أو كليهما و تصغيرها حسب الحاجة إلى مربّعات بحجم 768 × 768 بكسل، ويتم احتساب كل منها على أنّه 258 رمزًا.

للحصول على أفضل النتائج

  • يجب تدوير الصور إلى الاتجاه الصحيح قبل تحميلها.
  • تجنَّب استخدام الصور المموّهة.
  • إذا كنت تستخدم صورة واحدة، ضَع الطلب النصي بعد الصورة.

الإمكانات

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

الحصول على مربّع حدود لعنصر

يتم تدريب نماذج Gemini لعرض إحداثيات مربّع الحدود كنسبة عرض أو ارتفاع في النطاق [0, 1]. وبعد ذلك، يتم تكبير هذه القيم بمقدار 1,000 ومقلوبها إلى أعداد صحيحة. تمثل الإحداثيات بشكلٍ فعال مربّع الحدود في نسخة من الصورة بحجم 1,000 × 1,000 بكسل. لذلك، عليك تحويل هذه الإحداثيات مرة أخرى إلى سمات الصورة الأصلية لربط المربّعات الحدودية بدقة.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

prompt = (
  "Return a bounding box for each of the objects in this image "
  "in [ymin, xmin, ymax, xmax] format.")

response = client.models.generate_content(
  model="gemini-1.5-pro",
  contents=[sample_file_1, prompt])

print(response.text)

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

المزايا الأساسية

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

التفاصيل الفنية

  • الإدخال: الطلب والصور أو لقطات الفيديو المرتبطة به
  • الإخراج: مربّعات الحدود بتنسيق [y_min, x_min, y_max, x_max] الزاوية العليا اليسرى هي نقطة الأصل. يمتد محورا x وy أفقيًا وعموديًا على التوالي. يتم تسويتها بين 0 و1000 لكل صورة.
  • العرض المرئي: سيرى مستخدمو AI Studio مربّعات حدودية مرسومة ضمن واجهة المستخدِم.

بالنسبة إلى مطوّري Python، جرِّب دفتر ملاحظات الفهم المكاني ثنائي الأبعاد أو دفتر ملاحظات التوجيه التجريبي الثلاثي الأبعاد.

توحيد الإحداثيات

يعرض النموذج إحداثيات المربّع الحدودي بالتنسيق [y_min, x_min, y_max, x_max]. لتحويل هذه الإحداثيات المُعدَّلة إلى إحداثيات البكسل لصورتك الأصلية، اتّبِع الخطوات التالية:

  1. اقسم كل إحداثي ناتج على 1000.
  2. اضرب إحداثيات x في عرض الصورة الأصلية.
  3. اضرب إحداثيات y في ارتفاع الصورة الأصلية.

لاستكشاف أمثلة أكثر تفصيلاً على إنشاء إحداثيات مربّع الحدود و عرضها على الصور، ننصحك بمراجعة مثال على دليل إعداد الوجبات الخاص بميزة "اكتشاف الأجسام".

طلب الإجراء باستخدام الفيديو

في هذا الدليل التعليمي، ستحمِّل فيديو باستخدام File API وتنشئ محتوًى استنادًا إلى هذه الصور.

التفاصيل الفنية (فيديو)

يتيح Gemini 1.5 Pro وFlash ما يصل إلى ساعة تقريبًا من بيانات الفيديو.

يجب أن يكون الفيديو بأحد أنواع MIME التالية لتنسيق الفيديو:

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

تُستخرج خدمة File API لقطات الصور من الفيديوهات بمعدّل لقطة واحدة في الثانية (FPS) والصوت بمعدّل 1 كيلوبت في الثانية، في قناة واحدة، مع إضافة الطوابع الزمنية كل ثانية. هذه المعدّلات خاضعة للتغيير في المستقبل بسبب التحسينات في الاستنتاج.

تبلغ كمية الرموز المميّزة للّقطات الفردية 258 رمزًا، وكمية الرموز المميّزة للصوت 32 رمزًا في الثانية. باستخدام metadata، تصبح كل ثانية من الفيديو 300 رمز مميّز تقريبًا، ما يعني أنّه يمكن أن تتضمن نافذة سياق تبلغ سعتها مليون رمز مميّز ما يقلّ قليلاً عن ساعة من الفيديو.

لطرح أسئلة عن المواقع الجغرافية التي تحمل الطوابع الزمنية، استخدِم التنسيق MM:SS، حيث يمثّل الرقمان الأولان الدقائق ويمثّل الرقمان الأخيران الثواني.

للحصول على أفضل النتائج:

  • استخدِم فيديو واحدًا لكل طلب.
  • إذا كنت تستخدم فيديو واحدًا، ضَع الطلب النصي بعد الفيديو.

تحميل ملف فيديو باستخدام File API

تقبل واجهة برمجة التطبيقات File API تنسيقات ملفات الفيديو مباشرةً. يستخدِم هذا المثال الفيلم القصير الذي أنشأته وكالة ناسا بعنوان "تقلص البقعة الحمراء الكبيرة على كوكب المشتري ونموها". مصدر الصورة: مركز Goddard لرحلات الفضاء (GSFC)/ديفيد لاد (2018).

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

ابدأ باسترداد الفيديو القصير باتّباع الخطوات التالية:

wget https://storage.googleapis.com/generativeai-downloads/images/GreatRedSpot.mp4

حمِّل الفيديو باستخدام واجهة برمجة التطبيقات File API واطبع عنوان URL.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print("Uploading file...")
video_file = client.files.upload(path="GreatRedSpot.mp4")
print(f"Completed upload: {video_file.uri}")

التحقّق من تحميل الملف والاطّلاع على حالته

تأكَّد من أنّ واجهة برمجة التطبيقات قد تلقّت الملفات بنجاح من خلال استدعاء الأسلوب files.get.

import time

# Check whether the file is ready to be used.
while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(1)
    video_file = client.files.get(name=video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

print('Done')

طلب الإجراء باستخدام فيديو ونص

بعد أن يصبح الفيديو المحمَّل في الحالة ACTIVE، يمكنك إرسال GenerateContent طلبات تحدّد عنوان URL لواجهة برمجة التطبيقات File API لهذا الفيديو. اختَر النموذج التوليدي وقدِّم له الفيديو المحمَّل وطلبًا نصيًا.

from IPython.display import Markdown

# Pass the video file reference like any other media part.
response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[
        video_file,
        "Summarize this video. Then create a quiz with answer key "
        "based on the information in the video."])

# Print the response, rendering any Markdown
Markdown(response.text)

الإشارة إلى الطوابع الزمنية في المحتوى

يمكنك استخدام طوابع زمنية من النوع HH:MM:SS للإشارة إلى لحظات معيّنة في الفيديو.

prompt = "What are the examples given at 01:05 and 01:19 supposed to show us?"

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

تحويل الصوت إلى نص وتقديم أوصاف مرئية

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

prompt = (
    "Transcribe the audio from this video, giving timestamps for "
    "salient events in the video. Also provide visual descriptions.")

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

إدراج الملفات

يمكنك إدراج جميع الملفات التي تم تحميلها باستخدام File API ومعرّفات الموارد المنتظمة (URI) الخاصة بها باستخدام files.list.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print('My files:')
for f in client.files.list():
  print(" ", f'{f.name}: {f.uri}')

حذف الملفات

يتم حذف الملفات التي تم تحميلها باستخدام File API تلقائيًا بعد يومَين. يمكنك أيضًا حذفها يدويًا باستخدام files.delete.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

# Upload a file
poem_file = client.files.upload(path="poem.txt")

# Files will auto-delete after a period.
print(poem_file.expiration_time)

# Or they can be deleted explicitly.
dr = client.files.delete(name=poem_file.name)

try:
  client.models.generate_content(
      model="gemini-2.0-flash-exp",
      contents=['Finish this poem:', poem_file])
except genai.errors.ClientError as e:
  print(e.code)  # 403
  print(e.status)  # PERMISSION_DENIED
  print(e.message)  # You do not have permission to access the File .. or it may not exist.

الخطوات التالية

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

  • استراتيجيات طلب الملفات: تتيح واجهة برمجة التطبيقات Gemini API طلب البيانات النصية والمرئية والصوتية والفيديوية، ويُعرف ذلك أيضًا باسم الطلبات المتعدّدة الوسائط.
  • تعليمات النظام: تتيح لك تعليمات النظام توجيه سلوك النموذج استنادًا إلى احتياجاتك وحالات الاستخدام المحدّدة.
  • إرشادات السلامة: في بعض الأحيان، تُنتج نماذج الذكاء الاصطناعي التوليدي نتائج غير متوقّعة، مثل النتائج غير الدقيقة أو المجحِّفة أو المسيئة. إنّ المعالجة اللاحقة والتقييم البشري ضروريان لمحاولة الحد من خطر الضرر الناتج عن هذه النتائج.