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

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

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

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

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

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

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

const prompt = "Write a story about a magic backpack.";

const result = await model.generateContent(prompt);
console.log(result.response.text());

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

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

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

function fileToGenerativePart(path, mimeType) {
  return {
    inlineData: {
      data: Buffer.from(fs.readFileSync(path)).toString("base64"),
      mimeType,
    },
  };
}

const prompt = "Describe how this product might be manufactured.";
// Note: The only accepted mime types are some image types, image/*.
const imagePart = fileToGenerativePart(
  `${mediaPath}/jetpack.jpg`,
  "image/jpeg",
);

const result = await model.generateContent([prompt, imagePart]);
console.log(result.response.text());

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

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

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

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

const prompt = "Write a story about a magic backpack.";

const result = await model.generateContentStream(prompt);

// Print text as it comes in.
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  process.stdout.write(chunkText);
}

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

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

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const chat = model.startChat({
  history: [
    {
      role: "user",
      parts: [{ text: "Hello" }],
    },
    {
      role: "model",
      parts: [{ text: "Great to meet you. What would you like to know?" }],
    },
  ],
});
let result = await chat.sendMessage("I have 2 dogs in my house.");
console.log(result.response.text());
result = await chat.sendMessage("How many paws are in my house?");
console.log(result.response.text());

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

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const chat = model.startChat({
  history: [
    {
      role: "user",
      parts: [{ text: "Hello" }],
    },
    {
      role: "model",
      parts: [{ text: "Great to meet you. What would you like to know?" }],
    },
  ],
});
let result = await chat.sendMessageStream("I have 2 dogs in my house.");
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  process.stdout.write(chunkText);
}
result = await chat.sendMessageStream("How many paws are in my house?");
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  process.stdout.write(chunkText);
}

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

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

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({
  model: "gemini-1.5-flash",
  generationConfig: {
    candidateCount: 1,
    stopSequences: ["x"],
    maxOutputTokens: 20,
    temperature: 1.0,
  },
});

const result = await model.generateContent(
  "Tell me a story about a magic backpack.",
);
console.log(result.response.text());

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

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

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

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

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

const result = await model.generateContent({
  contents: [
    {
      role: 'user',
      parts: [
        {
          text: prompt,
        }
      ],
    }
  ],
  generationConfig: {
    maxOutputTokens: 1000,
    temperature: 0.1,
  },
});
console.log(result.response.text());

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

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

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

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