يمكن لواجهة 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 لمعالجة الملفات الصوتية.