يمكن لواجهة برمجة التطبيقات Gemini API إنشاء إخراج نصي استجابةً لمدخلات مختلفة، بما في ذلك النصوص والصور والفيديوهات والمحتوى الصوتي. يوضّح لك هذا الدليل كيفية إنشاء نص باستخدام مدخلات النص والصور. ويشمل أيضًا تعليمات حول البث المباشر والمحادثة والنظام.
إدخال نصي
إنّ أبسط طريقة لإنشاء نص باستخدام Gemini API هي تزويد النموذج بإدخال نصي واحد فقط، كما هو موضّح في هذا المثال:
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=["How does AI work?"]
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: "How does AI work?",
});
console.log(response.text);
}
await main();
// import packages here
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
if err != nil {
log.Fatal(err)
}
defer client.Close()
model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx, genai.Text("How does AI work?"))
if err != nil {
log.Fatal(err)
}
printResponse(resp) // helper function for printing content parts
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "How does AI work?"
}
]
}
]
}'
إدخال صورة
تتيح Gemini API إدخالات متعددة الوسائط التي تجمع بين النصوص وملفات الوسائط. يوضّح المثال التالي كيفية إنشاء نص من إدخال نص وصورة:
from PIL import Image
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
image = Image.open("/path/to/organ.png")
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=[image, "Tell me about this instrument"]
)
print(response.text)
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const image = await ai.files.upload({
file: "/path/to/organ.png",
});
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: [
createUserContent([
"Tell me about this instrument",
createPartFromUri(image.uri, image.mimeType),
]),
],
});
console.log(response.text);
}
await main();
model := client.GenerativeModel("gemini-2.0-flash")
imgData, err := os.ReadFile(filepath.Join(testDataDir, "organ.jpg"))
if err != nil {
log.Fatal(err)
}
resp, err := model.GenerateContent(ctx,
genai.Text("Tell me about this instrument"),
genai.ImageData("jpeg", imgData))
if err != nil {
log.Fatal(err)
}
printResponse(resp)
# 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-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON"
إخراج البث
يعرض النموذج تلقائيًا استجابةً بعد إكمال عملية إنشاء النص بالكامل. يمكنك تحقيق تفاعلات أسرع باستخدام البث لمحاولة
عرض نُسخ من
GenerateContentResponse
أثناء إنشائها.
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content_stream(
model="gemini-2.0-flash",
contents=["Explain how AI works"]
)
for chunk in response:
print(chunk.text, end="")
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const response = await ai.models.generateContentStream({
model: "gemini-2.0-flash",
contents: "Explain how AI works",
});
for await (const chunk of response) {
console.log(chunk.text);
}
}
await main();
model := client.GenerativeModel("gemini-1.5-flash")
iter := model.GenerateContentStream(ctx, genai.Text("Write a story about a magic backpack."))
for {
resp, err := iter.Next()
if err == iterator.Done {
break
}
if err != nil {
log.Fatal(err)
}
printResponse(resp)
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=${GEMINI_API_KEY}" \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{
"contents": [
{
"parts": [
{
"text": "Explain how AI works"
}
]
}
]
}'
المحادثات التي تتضمّن عدّة أدوار
تتيح لك حزمة تطوير البرامج (SDK) في Gemini جمع جولات متعدّدة من الأسئلة والردود في
محادثة. يتيح تنسيق المحادثة للمستخدمين التقدّم تدريجيًا نحو الإجابات،
والحصول على مساعدة بشأن المشاكل المتعدّدة الأجزاء. يقدّم تطبيق حزمة تطوير البرامج هذا للمحادثة
واجهة لتتبُّع سجلّ المحادثات، ولكنّه يستخدم
بطريقةٍ غير مرئية
generateContent
الطريقة نفسها
لإنشاء الردّ.
يعرض مثال الرمز البرمجي التالي عملية تنفيذ محادثة أساسية:
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
chat = client.chats.create(model="gemini-2.0-flash")
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)
for message in chat.get_history():
print(f'role - {message.role}',end=": ")
print(message.parts[0].text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const chat = ai.chats.create({
model: "gemini-2.0-flash",
history: [
{
role: "user",
parts: [{ text: "Hello" }],
},
{
role: "model",
parts: [{ text: "Great to meet you. What would you like to know?" }],
},
],
});
const response1 = await chat.sendMessage({
message: "I have 2 dogs in my house.",
});
console.log("Chat response 1:", response1.text);
const response2 = await chat.sendMessage({
message: "How many paws are in my house?",
});
console.log("Chat response 2:", response2.text);
}
await main();
model := client.GenerativeModel("gemini-1.5-flash")
cs := model.StartChat()
cs.History = []*genai.Content{
{
Parts: []genai.Part{
genai.Text("Hello, I have 2 dogs in my house."),
},
Role: "user",
},
{
Parts: []genai.Part{
genai.Text("Great to meet you. What would you like to know?"),
},
Role: "model",
},
}
res, err := cs.SendMessage(ctx, genai.Text("How many paws are in my house?"))
if err != nil {
log.Fatal(err)
}
printResponse(res)
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_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?"
}
]
}
]
}'
يمكنك أيضًا استخدام ميزة البث مع المحادثة، كما هو موضّح في المثال التالي:
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
chat = client.chats.create(model="gemini-2.0-flash")
response = chat.send_message_stream("I have 2 dogs in my house.")
for chunk in response:
print(chunk.text, end="")
response = chat.send_message_stream("How many paws are in my house?")
for chunk in response:
print(chunk.text, end="")
for message in chat.get_history():
print(f'role - {message.role}', end=": ")
print(message.parts[0].text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const chat = ai.chats.create({
model: "gemini-2.0-flash",
history: [
{
role: "user",
parts: [{ text: "Hello" }],
},
{
role: "model",
parts: [{ text: "Great to meet you. What would you like to know?" }],
},
],
});
const stream1 = await chat.sendMessageStream({
message: "I have 2 dogs in my house.",
});
for await (const chunk of stream1) {
console.log(chunk.text);
console.log("_".repeat(80));
}
const stream2 = await chat.sendMessageStream({
message: "How many paws are in my house?",
});
for await (const chunk of stream2) {
console.log(chunk.text);
console.log("_".repeat(80));
}
}
await main();
model := client.GenerativeModel("gemini-1.5-flash")
cs := model.StartChat()
cs.History = []*genai.Content{
{
Parts: []genai.Part{
genai.Text("Hello, I have 2 dogs in my house."),
},
Role: "user",
},
{
Parts: []genai.Part{
genai.Text("Great to meet you. What would you like to know?"),
},
Role: "model",
},
}
iter := cs.SendMessageStream(ctx, genai.Text("How many paws are in my house?"))
for {
resp, err := iter.Next()
if err == iterator.Done {
break
}
if err != nil {
log.Fatal(err)
}
printResponse(resp)
}
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=$GEMINI_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?"
}
]
}
]
}'
مَعلمات الإعدادات
تتضمّن كلّ مطالبة ترسلها إلى النموذج مَعلمات تتحكّم في كيفية توليد النموذج للردود. يمكنك ضبط هذه المَعلمات أو السماح للنموذج باستخدام الخيارات التلقائية.
يوضّح المثال التالي كيفية ضبط مَعلمات النموذج:
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=["Explain how AI works"],
config=types.GenerateContentConfig(
max_output_tokens=500,
temperature=0.1
)
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: "Explain how AI works",
config: {
maxOutputTokens: 500,
temperature: 0.1,
},
});
console.log(response.text);
}
await main();
model := client.GenerativeModel("gemini-1.5-pro-latest")
model.SetTemperature(0.9)
model.SetTopP(0.5)
model.SetTopK(20)
model.SetMaxOutputTokens(100)
model.SystemInstruction = genai.NewUserContent(genai.Text("You are Yoda from Star Wars."))
model.ResponseMIMEType = "application/json"
resp, err := model.GenerateContent(ctx, genai.Text("What is the average size of a swallow?"))
if err != nil {
log.Fatal(err)
}
printResponse(resp)
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Explain how AI works"
}
]
}
],
"generationConfig": {
"stopSequences": [
"Title"
],
"temperature": 1.0,
"maxOutputTokens": 800,
"topP": 0.8,
"topK": 10
}
}'
في ما يلي بعض مَعلمات النماذج التي يمكنك ضبطها. (تختلف اصطلاحات التسمية حسب لغة البرمجة).
stopSequences
: لتحديد مجموعة تسلسلات الأحرف (5 تسلسلات كحد أقصى) التي ستؤدي إلى إيقاف إنشاء الإخراج. في حال تحديد هذا الحقل، ستتوقف واجهة برمجة التطبيقات عند أول ظهور لرمزstop_sequence
. لن يتم تضمين تسلسل الإيقاف كجزء من الاستجابة.-
temperature
: تتحكّم هذه السمة في العشوائية الناتجة. استخدِم قيمًا أعلى للحصول على ردود أكثر إبداعًا، وقيمًا أقل للحصول على ردود أكثر تحديدًا. يمكن أن تتراوح القيم بين [0.0, 2.0]. maxOutputTokens
: لضبط الحد الأقصى لعدد الرموز المميّزة المطلوب تضمينها في مرشّح.topP
: لتغيير طريقة اختيار النموذج للرموز لإخراجها يتم اختيار الرموز من الأكثر إلى الأقل احتمالية إلى أن يساوي مجموع احتمالاتها قيمةtopP
. القيمة التلقائيةtopP
هي 0.95.-
topK
: لتغيير طريقة اختيار النموذج للرموز لإخراجها إذا كانت قيمةtopK
هي 1، يعني ذلك أنّ الرمز المميّز المحدّد هو الأكثر احتمالًا من بين جميع الرموز المميّزة في قاموس النموذج، في حين أنّ قيمةtopK
هي 3 تعني أنّ الرمز المميّز التالي يتم اختياره من بين 3 رموز مميّزة الأكثر احتمالًا باستخدام درجة الحرارة. تتم فلترة الرموز المميّزة بشكلٍ أكبر استنادًا إلىtopP
مع اختيار الرمز المميّز النهائي باستخدام تحليل عيّنات درجة الحرارة.
تعليمات النظام
تتيح لك تعليمات النظام توجيه سلوك النموذج استنادًا إلى حالة الاستخدام الخاصة بك. عند تقديم تعليمات النظام، تمنح النموذج سياقًا إضافيًا لمساعدته في فهم المهمة وإنشاء ردود أكثر تخصيصًا. يجب أن يلتزم النموذج بتعليمات النظام خلال التفاعل الكامل مع المستخدم، ما يتيح لك تحديد السلوك على مستوى المنتج بشكل منفصل عن الطلبات التي يقدّمها المستخدمون النهائيون.
يمكنك ضبط تعليمات النظام عند بدء تشغيل النموذج:
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
model="gemini-2.0-flash",
config=types.GenerateContentConfig(
system_instruction="You are a cat. Your name is Neko."),
contents="Hello there"
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: "Hello there",
config: {
systemInstruction: "You are a cat. Your name is Neko.",
},
});
console.log(response.text);
}
await main();
// import packages here
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
if err != nil {
log.Fatal(err)
}
defer client.Close()
model := client.GenerativeModel("gemini-2.0-flash")
model.SystemInstruction = &genai.Content{
Parts: []genai.Part{genai.Text(`
You are a cat. Your name is Neko.
`)},
}
resp, err := model.GenerateContent(ctx, genai.Text("Hello there"))
if err != nil {
log.Fatal(err)
}
printResponse(resp) // helper function for printing content parts
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_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"
}
]
}
]
}'
بعد ذلك، يمكنك إرسال الطلبات إلى النموذج كالمعتاد.
النماذج المتوافقة
تتيح مجموعة نماذج Gemini بأكملها إنشاء النصوص. لمزيد من المعلومات عن النماذج وإمكاناتها، اطّلِع على النماذج.
نصائح حول صياغة الطلبات
في حالات استخدام إنشاء النصوص الأساسية، قد لا تحتاج إلى تضمين أي مثال على الإخراج أو تعليمات النظام أو معلومات التنسيق في الطلب. هذا أسلوب بدون تدريب مسبق. في بعض حالات الاستخدام، قد يؤدي استخدام طلب لمرة واحدة أو لعدة مرات إلى تقديم نتيجة أكثر توافقًا مع توقعات المستخدم. في بعض الحالات، قد تحتاج أيضًا إلى تقديم تعليمات النظام لمساعدة النموذج في فهم المهمة أو اتّباع إرشادات معيّنة.
الخطوات التالية
- جرِّب البدء باستخدام Gemini API في Colab.
- تعرَّف على كيفية استخدام ميزة فهم الرؤية في Gemini لمعالجة الصور والفيديوهات.
- تعرَّف على كيفية استخدام ميزة فهم الصوت في Gemini لمعالجة الملفات الصوتية.
- اطّلِع على معلومات عن استراتيجيات طلب الملفات باستخدام الوسائط المتعددة.