فهم المستندات

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

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

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

إدخال ملف PDF

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

As inline_data

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

DOC_URL="https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
PROMPT="Summarize this document"
DISPLAY_NAME="base64_pdf"

# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

# Check for FreeBSD base64 and set flags accordingly
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

# Base64 encode the PDF
ENCODED_PDF=$(base64 $B64FLAGS "${DISPLAY_NAME}.pdf")

# Generate content using the base64 encoded PDF
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"inline_data": {"mime_type": "application/pdf", "data": "'"$ENCODED_PDF"'"}},
          {"text": "'$PROMPT'"}
        ]
      }]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"

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

يتيح 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 كبيرة

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

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

ملفات PDF كبيرة من عناوين URL

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

PDF_PATH="https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
PROMPT="Summarize this document"

# Download the PDF from the provided URL
wget -O "${DISPLAY_NAME}.pdf" "${PDF_PATH}"

MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")

echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "'$PROMPT'"},
          {"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"

ملفات PDF كبيرة يتم تخزينها على الجهاز

NUM_BYTES=$(wc -c < "${PDF_PATH}")
DISPLAY_NAME=TEXT
tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: application/pdf" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${PDF_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Can you add a few more lines to this poem?"},
          {"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

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

name=$(jq ".file.name" file_info.json)
# Get the file of interest to check state
curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
# Print some information about the file you got
name=$(jq ".file.name" file_info.json)
echo name=$name
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

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

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

DOC_URL_1="https://arxiv.org/pdf/2312.11805"
DOC_URL_2="https://arxiv.org/pdf/2403.05530"
DISPLAY_NAME_1="Gemini_paper"
DISPLAY_NAME_2="Gemini_1.5_paper"
PROMPT="What is the difference between each of the main benchmarks between these two papers? Output these in a table."

# Function to download and upload a PDF
upload_pdf() {
  local doc_url="$1"
  local display_name="$2"

  # Download the PDF
  wget -O "${display_name}.pdf" "${doc_url}"

  local MIME_TYPE=$(file -b --mime-type "${display_name}.pdf")
  local NUM_BYTES=$(wc -c < "${display_name}.pdf")

  echo "MIME_TYPE: ${MIME_TYPE}"
  echo "NUM_BYTES: ${NUM_BYTES}"

  local tmp_header_file=upload-header.tmp

  # Initial resumable request
  curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
    -D "${tmp_header_file}" \
    -H "X-Goog-Upload-Protocol: resumable" \
    -H "X-Goog-Upload-Command: start" \
    -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
    -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
    -H "Content-Type: application/json" \
    -d "{'file': {'display_name': '${display_name}'}}" 2> /dev/null

  local upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
  rm "${tmp_header_file}"

  # Upload the PDF
  curl "${upload_url}" \
    -H "Content-Length: ${NUM_BYTES}" \
    -H "X-Goog-Upload-Offset: 0" \
    -H "X-Goog-Upload-Command: upload, finalize" \
    --data-binary "@${display_name}.pdf" 2> /dev/null > "file_info_${display_name}.json"

  local file_uri=$(jq ".file.uri" "file_info_${display_name}.json")
  echo "file_uri for ${display_name}: ${file_uri}"

  # Clean up the downloaded PDF
  rm "${display_name}.pdf"

  echo "${file_uri}"
}

# Upload the first PDF
file_uri_1=$(upload_pdf "${DOC_URL_1}" "${DISPLAY_NAME_1}")

# Upload the second PDF
file_uri_2=$(upload_pdf "${DOC_URL_2}" "${DISPLAY_NAME_2}")

# Now generate content using both files
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"mime_type": "application/pdf", "file_uri": '$file_uri_1'}},
          {"file_data": {"mime_type": "application/pdf", "file_uri": '$file_uri_2'}},
          {"text": "'$PROMPT'"}
        ]
      }]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

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

لمزيد من المعلومات، يمكنك الاطّلاع على المراجع التالية:

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