إنشاء النص

يمكن لواجهة برمجة التطبيقات Gemini API إنشاء إخراج نصي عند تقديم نص وصور وفيديو وصوت كإدخال.

يوضّح لك هذا الدليل كيفية إنشاء نص باستخدام الطريقتَين generateContent و streamGenerateContent. للتعرّف على كيفية استخدام ميزات الرؤية والصوت في Gemini، يُرجى الرجوع إلى دليلَي Vision والصوت.

إنشاء نص من إدخال نصي فقط

أبسط طريقة لإنشاء نص باستخدام Gemini API هي تزويد النموذج بإدخال نصي واحد فقط، كما هو موضّح في هذا المثال:

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": "Write a story about a magic backpack."}]
        }]
       }' 2> /dev/null
text_generation.sh

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

إنشاء نص من إدخال نص وصورة

تتوافق Gemini API مع الإدخالات المتعدّدة الوسائط التي تجمع النص مع ملفات الوسائط. يوضّح المثال التالي كيفية إنشاء نص من إدخال نص وصورة:

# Use a temporary file to hold the base64 encoded image data
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"

# Use a temporary file to hold the JSON payload
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT

cat > "$TEMP_JSON" << EOF
{
  "contents": [{
    "parts":[
      {"text": "Tell me about this instrument"},
      {
        "inline_data": {
          "mime_type":"image/jpeg",
          "data": "$(cat "$TEMP_B64")"
        }
      }
    ]
  }]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON" 2> /dev/null
text_generation.sh

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

إنشاء مصدر نصي

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

يوضّح المثال التالي كيفية تنفيذ البث باستخدام أسلوب streamGenerateContent ل إنشاء نص من طلب إدخال نصي فقط.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:streamGenerateContent?alt=sse&key=${GOOGLE_API_KEY}" \
        -H 'Content-Type: application/json' \
        --no-buffer \
        -d '{ "contents":[{"parts":[{"text": "Write a story about a magic backpack."}]}]}'
text_generation.sh

إنشاء محادثة تفاعلية

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

يعرض مثال الرمز البرمجي التالي عملية تنفيذ محادثة أساسية:

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": [
        {"role":"user",
         "parts":[{
           "text": "Hello"}]},
        {"role": "model",
         "parts":[{
           "text": "Great to meet you. What would you like to know?"}]},
        {"role":"user",
         "parts":[{
           "text": "I have two dogs in my house. How many paws are in my house?"}]},
      ]
    }' 2> /dev/null | grep "text"
chat.sh

تفعيل بث المحادثات

يمكنك أيضًا استخدام ميزة البث مع المحادثة، كما هو موضّح في المثال التالي:

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:streamGenerateContent?alt=sse&key=$GOOGLE_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {"role":"user",
         "parts":[{
           "text": "Hello"}]},
        {"role": "model",
         "parts":[{
           "text": "Great to meet you. What would you like to know?"}]},
        {"role":"user",
         "parts":[{
           "text": "I have two dogs in my house. How many paws are in my house?"}]},
      ]
    }' 2> /dev/null | grep "text"
chat.sh

ضبط إعدادات إنشاء النصوص

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

يوضّح المثال التالي كيفية ضبط العديد من الخيارات المتاحة.

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": "Write a story about a magic backpack."}
            ]
        }],
        "safetySettings": [
            {
                "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
                "threshold": "BLOCK_ONLY_HIGH"
            }
        ],
        "generationConfig": {
            "stopSequences": [
                "Title"
            ],
            "temperature": 1.0,
            "maxOutputTokens": 800,
            "topP": 0.8,
            "topK": 10
        }
    }'  2> /dev/null | grep "text"
configure_model_parameters.sh

stopSequences تحدِّد مجموعة تسلسلات الأحرف (ما يصل إلى 5) التي ستؤدي إلى إيقاف إنشاء الإخراج. في حال تحديد هذا الحقل، ستتوقف واجهة برمجة التطبيقات عند أول ظهور لعنصر stop_sequence. لن يتم تضمين تسلسل التوقف كجزء من الاستجابة.

تتحكّم مَعلمة temperature في العشوائية الناتجة. استخدِم قيمًا أعلى للحصول على ردود أكثر إبداعًا، وقيمًا أقل للحصول على ردود أكثر تحديدًا. يمكن أن تتراوح القيم بين [0.0, 2.0].

يحدِّد maxOutputTokens الحد الأقصى لعدد الرموز المميّزة المطلوب تضمينها في المرشّح.

topP يغيّر طريقة اختيار النموذج للرموز لعرضها. يتم اختيار الرموز من الأكثر إلى الأقل احتمالية إلى أن يصبح مجموع احتمالاتها مساويًا لقيمة topP. القيمة التلقائية topP هي 0.95.

topK يغيّر طريقة اختيار النموذج للرموز لعرضها. إذا كانت قيمة topK هي 1، يعني ذلك أنّه تم اختيار الرمز المميّز الأكثر احتمالًا من بين كل الرموز المميّزة في المفردات للنموذج، في حين أنّ قيمة topK هي 3 تعني أنّه يتم اختيار الرمز المميّز التالي من بين الرموز المميّزة الثلاثة الأكثر احتمالًا باستخدام درجة الحرارة. تتم فلترة الرموز المميّزة بشكلٍ إضافي استنادًا إلى topP مع اختيار الرمز المميّز النهائي باستخدام تحليل درجة الحرارة.

إضافة تعليمات النظام

تتيح لك تعليمات النظام توجيه سلوك النموذج استنادًا إلى احتياجاتك وحالات الاستخدام المحدّدة.

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

يمكنك ضبط تعليمات النظام عند بدء تشغيل النموذج:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
    "parts":
      { "text": "You are a cat. Your name is Neko."}},
    "contents": {
      "parts": {
        "text": "Hello there"}}}'
system_instruction.sh

للحصول على مثال تفاعلي شامل لاستخدام تعليمات النظام، يُرجى الاطّلاع على تعليمات النظام Colab.

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

بعد أن استكشافت أساسيات Gemini API، ننصحك بالمحاولة التالية:

  • فهم الرؤية: تعرَّف على كيفية استخدام ميزة فهم الرؤية المضمّنة في Gemini لمعالجة الصور والفيديوهات.
  • فهم الصوت: تعرَّف على كيفية استخدام ميزة فهم الصوت المضمّنة في Gemini لمعالجة الملفات الصوتية.