إنشاء نص باستخدام Gemini API

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

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

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

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

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

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

import google.generativeai as genai

model = genai.GenerativeModel("gemini-1.5-flash")
response = model.generate_content("Write a story about a magic backpack.")
print(response.text)

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

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

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

import google.generativeai as genai

import PIL.Image

model = genai.GenerativeModel("gemini-1.5-flash")
organ = PIL.Image.open(media / "organ.jpg")
response = model.generate_content(["Tell me about this instrument", organ])
print(response.text)

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

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

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

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

import google.generativeai as genai

model = genai.GenerativeModel("gemini-1.5-flash")
response = model.generate_content("Write a story about a magic backpack.", stream=True)
for chunk in response:
    print(chunk.text)
    print("_" * 80)

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

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

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

import google.generativeai as genai

model = genai.GenerativeModel("gemini-1.5-flash")
chat = model.start_chat(
    history=[
        {"role": "user", "parts": "Hello"},
        {"role": "model", "parts": "Great to meet you. What would you like to know?"},
    ]
)
response = chat.send_message("I have 2 dogs in my house.")
print(response.text)
response = chat.send_message("How many paws are in my house?")
print(response.text)

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

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

import google.generativeai as genai

model = genai.GenerativeModel("gemini-1.5-flash")
chat = model.start_chat(
    history=[
        {"role": "user", "parts": "Hello"},
        {"role": "model", "parts": "Great to meet you. What would you like to know?"},
    ]
)
response = chat.send_message("I have 2 dogs in my house.", stream=True)
for chunk in response:
    print(chunk.text)
    print("_" * 80)
response = chat.send_message("How many paws are in my house?", stream=True)
for chunk in response:
    print(chunk.text)
    print("_" * 80)

print(chat.history)

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

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

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

import google.generativeai as genai

model = genai.GenerativeModel("gemini-1.5-flash")
response = model.generate_content(
    "Tell me a story about a magic backpack.",
    generation_config=genai.types.GenerationConfig(
        # Only one candidate for now.
        candidate_count=1,
        stop_sequences=["x"],
        max_output_tokens=20,
        temperature=1.0,
    ),
)

print(response.text)

candidateCount يحدّد عدد الردود التي تم إنشاؤها المطلوب عرضها. لا يمكن حاليًا ضبط هذه القيمة إلا على 1. في حال عدم ضبط هذا الخيار، سيتم ضبطه تلقائيًا على 1.

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

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

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

يمكنك أيضًا ضبط مكالمات فردية إلى generateContent:

response = model.generate_content(
    'Write a story about a magic backpack.',
    generation_config = genai.GenerationConfig(
        max_output_tokens=1000,
        temperature=0.1,
    )
)

وتتجاهل أي قيم تم ضبطها في الطلب الفردي القيم في دالة إنشاء النموذج.

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

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

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