تولید متن

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"
          }
        ]
      }
    ]
  }'

مکالمات چند نوبتی

Gemini SDK به شما امکان می‌دهد چندین دور سؤال و پاسخ را در یک چت جمع‌آوری کنید. قالب چت به کاربران این امکان را می دهد که به تدریج به سمت پاسخ ها گام بردارند و برای مشکلات چند بخشی کمک بگیرند. این پیاده‌سازی SDK چت، رابطی را برای پیگیری تاریخچه مکالمه فراهم می‌کند، اما در پشت صحنه از همان روش 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) را مشخص می‌کند که تولید خروجی را متوقف می‌کند. اگر مشخص شود، API در اولین ظاهر یک 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"
          }
        ]
      }
    ]
  }'

سپس، می‌توانید طبق معمول درخواست‌ها را برای مدل ارسال کنید.

مدل های پشتیبانی شده

تمام مدل‌های خانواده جمینی از تولید متن پشتیبانی می‌کنند. برای کسب اطلاعات بیشتر در مورد مدل ها و قابلیت های آنها، به مدل ها مراجعه کنید.

راهنمایی های تشویقی

برای موارد استفاده اولیه از تولید متن، ممکن است درخواست شما نیازی به گنجاندن نمونه‌های خروجی، دستورالعمل‌های سیستم یا اطلاعات قالب‌بندی نداشته باشد. این یک رویکرد شات صفر است. برای برخی از موارد استفاده، یک اعلان یک شات یا چند شات ممکن است خروجی تولید کند که با انتظارات کاربر همسوتر باشد. در برخی موارد، ممکن است بخواهید دستورالعمل‌های سیستمی را برای کمک به مدل برای درک کار یا پیروی از دستورالعمل‌های خاص ارائه دهید.

بعدش چی