استكشاف إمكانات معالجة المستندات باستخدام Gemini API

تتيح Gemini API إدخال ملفات PDF، بما في ذلك المستندات الطويلة (حتى 3600 صفحة). تعالج نماذج Gemini ملفات PDF باستخدام ميزة الرؤية الأصلية، وبالتالي يمكنها فهم محتويات النصوص والصور داخل المستندات. من خلال ميزة الرؤية المضمّنة لملفات PDF، يمكن لنماذج Gemini تنفيذ ما يلي:

  • تحليل المخططات البيانية والرسومات البيانية والجداول داخل المستندات
  • استخراج المعلومات إلى تنسيقات إخراج منظَّمة
  • الإجابة عن أسئلة حول المحتوى المرئي والنصي في المستندات
  • تلخيص المستندات
  • تحويل محتوى المستندات إلى نص (مثلاً إلى HTML) مع الحفاظ على التنسيقات والتنسيقات، لاستخدامها في التطبيقات النهائية (مثل قنوات RAG).

يوضّح هذا البرنامج التعليمي بعض الطرق المحتمَلة لاستخدام Gemini API مع مستندات PDF. تكون جميع النتائج نصية فقط.

قبل البدء: إعداد مشروعك ومفتاح واجهة برمجة التطبيقات

قبل طلب Gemini API، عليك إعداد مشروعك وضبط مفتاح واجهة برمجة التطبيقات.

طلب التوقيع باستخدام ملفات PDF

يوضّح هذا الدليل كيفية تحميل ملفات PDF ومعالجتها باستخدام File API أو من خلال تضمينها كبيانات مضمّنة.

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

يتيح Gemini 1.5 Pro و1.5 Flash ما يصل إلى 3,600 صفحة مستند كحد أقصى. يجب أن تكون صفحات المستند بأحد أنواع MIME التالية للبيانات النصية:

  • ملف PDF‏ - application/pdf
  • JavaScript - application/x-javascript، text/javascript
  • Python - ‏application/x-python، text/x-python
  • TXT - text/plain
  • HTML - text/html
  • CSS - text/css
  • Markdown - text/md
  • ملف CSV‏ - text/csv
  • XML - text/xml
  • RTF - text/rtf

تعادل كل صفحة من صفحات المستند 258 رمزًا.

على الرغم من عدم وجود حدود محددة لعدد البكسل في المستند بجانب نافذة سياق النموذج، يتم تصغير الصفحات الأكبر حجمًا إلى الحد الأقصى من الدقة الذي يبلغ 3072×3072 مع الحفاظ على نسبة العرض إلى الارتفاع الأصلية، في حين يتم تكبير الصفحات الأصغر حجمًا إلى 768×768 بكسل. لا يتمّ تخفيض التكلفة للصفحات ذات الحجم المنخفض، باستثناء عرض النطاق، ولا يتمّ تحسين الأداء للصفحات ذات الدقة العالية.

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

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

إدخال ملف PDF

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

المستندات المشفَّرة باستخدام Base64

يمكنك معالجة ملفات PDF مباشرةً من عناوين URL. في ما يلي مقتطف رمز برمجي يوضّح كيفية إجراء ذلك:

import httpx
import base64

model = genai.GenerativeModel("gemini-1.5-flash")
doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"  # Replace with the actual URL of your PDF

# Retrieve and encode the PDF
doc_data = base64.standard_b64encode(httpx.get(doc_url).content).decode("utf-8")

prompt = "Summarize this document"

response = model.generate_content([{'mime_type':'application/pdf', 'data': doc_data}, prompt])
print(response.text)

ملفات PDF المخزّنة على الجهاز

بالنسبة إلى ملفات PDF المخزّنة على الجهاز، يمكنك اتّباع الخطوات التالية:

import base64

model = genai.GenerativeModel("gemini-1.5-flash")
doc_path = "/path/to/file.pdf" # Replace with the actual path to your local PDF

# Read and encode the local file
with open(doc_path, "rb") as doc_file:
    doc_data = base64.standard_b64encode(doc_file.read()).decode("utf-8")

prompt = "Summarize this document"

response = model.generate_content([{'mime_type': 'application/pdf', 'data': doc_data}, prompt])

print(response.text)

ملفات PDF كبيرة

يمكنك استخدام واجهة برمجة التطبيقات File API لتحميل مستند من أي حجم. استخدِم دائمًا واجهة برمجة التطبيقات File API عندما يكون إجمالي حجم الطلب (بما في ذلك الملفات والطلبات النصية وتعليمات النظام وغيرها) أكبر من 20 ميغابايت.

اتصل بـ media.upload لتحميل ملف باستخدام File API. تحمِّل التعليمة البرمجية التالية ملف مستند، ثم تستخدم الملف في طلب موجَّه إلى models.generateContent.

ملفات PDF كبيرة من عناوين URL ("‎#large-pdfs-urls")

استخدِم واجهة برمجة التطبيقات File API لملفات PDF الكبيرة الحجم المتوفّرة من عناوين URL، لتبسيط عملية تحميل هذه المستندات ومعالجتها مباشرةً من خلال عناوين URL الخاصة بها:

import io
import httpx

model = genai.GenerativeModel("gemini-1.5-flash")
long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf" # Replace with the actual URL of your large PDF

# Retrieve and upload the PDF using the File API
doc_data = io.BytesIO(httpx.get(long_context_pdf_path).content)
sample_doc = genai.upload_file(data=doc_data, mime_type='application/pdf')

prompt = "Summarize this document"

response = model.generate_content([sample_doc, prompt])
print(response.text)

ملفات PDF كبيرة يتم تخزينها على الجهاز (‎#large-pdfs-local)

import google.generativeai as genai

model = genai.GenerativeModel("gemini-1.5-flash")
sample_pdf = genai.upload_file(media / "test.pdf")
response = model.generate_content(["Give me a summary of this pdf file.", sample_pdf])
print(response.text)
files.py

يمكنك التحقّق من أنّ واجهة برمجة التطبيقات قد نجحت في تخزين الملف المحمَّل والحصول على ملفه الوصفي من خلال استدعاء files.get. إنّ name (وuri) فقط هما فريدان.

import google.generativeai as genai

myfile = genai.upload_file(media / "poem.txt")
file_name = myfile.name
print(file_name)  # "files/*"

myfile = genai.get_file(file_name)
print(myfile)
files.py

ملفات PDF متعددة

يمكن لواجهة برمجة التطبيقات Gemini API معالجة عدّة ملفات PDF في طلب واحد، ما دام حجم المستندات والطلب النصي مجتمعَين ضمن نطاق قدرة استيعاب النموذج.

import io
import httpx

model = genai.GenerativeModel("gemini-1.5-flash")

doc_url_1 = "https://arxiv.org/pdf/2312.11805" # Replace with the URL to your first PDF
doc_url_2 = "https://arxiv.org/pdf/2403.05530" # Replace with the URL to your second PDF

# Retrieve and upload both PDFs using the File API
doc_data_1 = io.BytesIO(httpx.get(doc_url_1).content)
doc_data_2 = io.BytesIO(httpx.get(doc_url_2).content)

sample_pdf_1 = genai.upload_file(data=doc_data_1, mime_type='application/pdf')
sample_pdf_2 = genai.upload_file(data=doc_data_2, mime_type='application/pdf')

prompt = "What is the difference between each of the main benchmarks between these two papers? Output these in a table."

response = model.generate_content([sample_pdf_1, sample_pdf_2, prompt])
print(response.text)

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

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

import google.generativeai as genai

print("My files:")
for f in genai.list_files():
    print("  ", f.name)
files.py

حذف الملفات

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

import google.generativeai as genai

myfile = genai.upload_file(media / "poem.txt")

myfile.delete()

try:
    # Error.
    model = genai.GenerativeModel("gemini-1.5-flash")
    result = model.generate_content([myfile, "Describe this file."])
except google.api_core.exceptions.PermissionDenied:
    pass
files.py

ذاكرة التخزين المؤقت للسياق باستخدام ملفات PDF

import os
from google.generativeai import caching
import io
import httpx

# Define the path to the PDF document (or use a URL)
long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf" # Replace with the URL of your large PDF
doc_data = io.BytesIO(httpx.get(long_context_pdf_path).content)

# Upload the PDF document using the File API
document = genai.upload_file(data=doc_data, mime_type='application/pdf')

# Specify the model name and system instruction for caching
model_name = "gemini-1.5-flash-002" # Ensure this matches the model you intend to use
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = caching.CachedContent.create(
    model=model_name,
    system_instruction=system_instruction,
    contents=[document], # The document(s) and other content you wish to cache
)

# Display the cache details
print(cache)

# Initialize a generative model from the cached content
model = genai.GenerativeModel.from_cached_content(cache)

# Generate content using the cached prompt and document
response = model.generate_content("Please summarize this transcript")

# (Optional) Print usage metadata for insights into the API call
print(response.usage_metadata)

# Print the generated text
print(response.text)

ذاكرات التخزين المؤقت

لا يمكن استرداد المحتوى المخزّن مؤقتًا أو عرضه، ولكن يمكنك استرداد البيانات الوصفية المخزّنة مؤقتًا (name وmodel وdisplay_name وusage_metadata وcreate_time وupdate_time وexpire_time).

لعرض البيانات الوصفية لجميع ذاكرات التخزين المؤقت التي تم تحميلها، استخدِم CachedContent.list():

for c in caching.CachedContent.list():
  print(c)

تعديل ذاكرة تخزين مؤقت

يمكنك ضبط ttl أو expire_time جديدَين لمخزن مؤقت. لا يمكن تغيير أي شيء آخر بشأن ذاكرة التخزين المؤقت.

يوضّح المثال التالي كيفية تعديل ttl لمخزن مؤقت باستخدام CachedContent.update().

import datetime

cache.update(ttl=datetime.timedelta(hours=2))

حذف ذاكرة تخزين مؤقت

توفّر خدمة التخزين المؤقت عملية حذف لإزالة المحتوى يدويًا من ذاكرة التخزين المؤقت. يوضّح المثال التالي كيفية حذف ذاكرة التخزين المؤقت باستخدام CachedContent.delete().

cache.delete()

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

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

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