آموزش: با Gemini API شروع کنید


این آموزش نحوه دسترسی به Gemini API برای برنامه Go خود را با استفاده از Google AI Go SDK نشان می دهد.

در این آموزش، نحوه انجام کارهای زیر را خواهید آموخت:

علاوه بر این، این آموزش شامل بخش هایی در مورد موارد استفاده پیشرفته (مانند جاسازی ها و شمارش نشانه ها ) و همچنین گزینه هایی برای کنترل تولید محتوا است .

پیش نیازها

در این آموزش فرض می شود که شما با ساخت اپلیکیشن با Go آشنا هستید.

برای تکمیل این آموزش، مطمئن شوید که محیط توسعه شما شرایط زیر را دارد:

  • برو 1.20+

پروژه خود را تنظیم کنید

قبل از فراخوانی Gemini API، باید پروژه خود را راه‌اندازی کنید که شامل تنظیم کلید API، نصب بسته SDK و مقداردهی اولیه مدل است.

کلید API خود را تنظیم کنید

برای استفاده از Gemini API، به یک کلید API نیاز دارید. اگر قبلاً یکی ندارید، یک کلید در Google AI Studio ایجاد کنید.

یک کلید API دریافت کنید

کلید API خود را ایمن کنید

اکیداً توصیه می شود که یک کلید API را در سیستم کنترل نسخه خود بررسی نکنید . درعوض، باید از یک فروشگاه مخفی برای کلید API خود استفاده کنید.

تمام قطعه های این آموزش فرض می کنند که شما به کلید API خود به عنوان یک متغیر محیطی دسترسی دارید.

بسته SDK را نصب کنید

برای استفاده از Gemini API در برنامه خود، باید بسته Go SDK را در پوشه ماژول خود get :

go get github.com/google/generative-ai-go

مدل مولد را راه اندازی کنید

قبل از اینکه بتوانید هر گونه تماس API را برقرار کنید، باید مدل تولیدی را وارد و مقداردهی اولیه کنید.

import "github.com/google/generative-ai-go/genai"
import "google.golang.org/api/option"

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("MODEL_NAME")

هنگام تعیین یک مدل به موارد زیر توجه کنید:

  • از مدلی استفاده کنید که مخصوص مورد استفاده شما باشد (مثلاً gemini-pro-vision برای ورودی چندوجهی است). در این راهنما، دستورالعمل‌های هر پیاده‌سازی، مدل پیشنهادی را برای هر مورد استفاده فهرست می‌کند.

موارد استفاده مشترک را اجرا کنید

اکنون که پروژه شما تنظیم شده است ، می توانید با استفاده از API Gemini برای اجرای موارد مختلف استفاده کنید:

در بخش موارد استفاده پیشرفته ، می توانید اطلاعات مربوط به API و تعبیه Gemini را پیدا کنید.

متن را از ورودی فقط متن ایجاد کنید

هنگامی که ورودی سریع فقط متن را شامل می شود ، از مدل gemini-pro با روش GenerateContent برای تولید خروجی متن استفاده کنید:

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// For text-only input, use the gemini-pro model
model := client.GenerativeModel("gemini-pro")
resp, err := model.GenerateContent(ctx, genai.Text("Write a story about a magic backpack."))
if err != nil {
  log.Fatal(err)
}

ایجاد متن از ورودی متن و تصویر (مولتی مدال)

Gemini یک مدل چند حالته ( gemini-pro-vision ) ارائه می دهد ، بنابراین می توانید متن و تصاویر را وارد کنید. حتماً مورد نیاز تصویر را برای ارسال ها بررسی کنید.

هنگامی که ورودی سریع شامل متن و تصویر است ، از مدل gemini-pro-vision با روش GenerateContent برای تولید خروجی متن استفاده کنید:

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// For text-and-image input (multimodal), use the gemini-pro-vision model
model := client.GenerativeModel("gemini-pro-vision")

imgData1, err := os.ReadFile(pathToImage1)
if err != nil {
  log.Fatal(err)
}

imgData2, err := os.ReadFile(pathToImage1)
if err != nil {
  log.Fatal(err)
}

prompt := []genai.Part{
  genai.ImageData("jpeg", imgData1),
  genai.ImageData("jpeg", imgData2),
  genai.Text("What's different between these two pictures?"),
}
resp, err := model.GenerateContent(ctx, prompt...)

if err != nil {
  log.Fatal(err)
}

ساخت مکالمات چند چرخش (گپ)

با استفاده از جمینی ، می توانید مکالمات Freeform را در چندین چرخش ایجاد کنید. SDK با مدیریت وضعیت گفتگو ، این روند را ساده می کند ، بنابراین برخلاف GenerateContent ، لازم نیست خودتان تاریخ گفتگو را ذخیره کنید.

برای ایجاد یک مکالمه چند چرخش (مانند گپ) ، از مدل gemini-pro استفاده کنید و با فراخوانی StartChat() چت را آغاز کنید. سپس از SendMessage() برای ارسال پیام کاربر جدید استفاده کنید ، که این پیام و پاسخ به تاریخچه گپ را نیز ضمیمه می کند.

دو گزینه ممکن برای role مرتبط با محتوا در یک مکالمه وجود دارد:

  • user : نقشی که ارائه می دهد. این مقدار پیش فرض تماس های SendMessage است.

  • model : نقشی که پاسخ ها را فراهم می کند. این نقش را می توان هنگام فراخوانی StartChat() با history موجود استفاده کرد.

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// For text-only input, use the gemini-pro model
model := client.GenerativeModel("gemini-pro")
// Initialize the chat
cs := model.StartChat()
cs.History = []*genai.Content{
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Hello, I have 2 dogs in my house."),
    },
    Role: "user",
  },
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Great to meet you. What would you like to know?"),
    },
    Role: "model",
  },
}

resp, err := cs.SendMessage(ctx, genai.Text("How many paws are in my house?"))
if err != nil {
  log.Fatal(err)
}

برای تعامل سریعتر از جریان استفاده کنید

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

مثال زیر نحوه اجرای جریان با روش GenerateContentStream را برای تولید متن از یک ارسال متن و تصویر نشان می دهد.

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// For text-and-image input (multimodal), use the gemini-pro-vision model
model := client.GenerativeModel("gemini-pro-vision")

imageBytes, err := os.ReadFile(pathToImage)

img := genai.ImageData("jpeg", imageBytes)
prompt := genai.Text("Tell me a story about this animal")
iter := model.GenerateContentStream(ctx, img, prompt)

for {
  resp, err := iter.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }

  // ... print resp
}

می توانید از یک روش مشابه برای موارد ورودی فقط متن و موارد استفاده از چت استفاده کنید.

prompt := genai.Text("Tell me a story about a lumberjack and his giant ox")
iter := model.GenerateContentStream(ctx, prompt)

prompt := genai.Text("And how do you feel about that?")
iter := cs.SendMessageStream(ctx, prompt)

موارد استفاده پیشرفته را اجرا کنید

موارد استفاده متداول که در بخش قبلی این آموزش شرح داده شده است به شما کمک می کند تا با استفاده از API Gemini راحت شوید. در این بخش مواردی از مواردی استفاده شده است که ممکن است پیشرفته تر تلقی شوند.

از تعبیهات استفاده کنید

تعبیه تکنیکی است که برای نشان دادن اطلاعات به عنوان لیستی از شماره های نقطه شناور در یک آرایه استفاده می شود. با استفاده از جمینی ، می توانید متن (کلمات ، جملات و بلوک های متن) را به صورت بردار نشان دهید ، و مقایسه و تضاد تعبیه ها را آسان تر می کند. به عنوان مثال ، دو متنی که یک موضوع یا احساسات مشابه را به اشتراک می گذارند ، باید تعبیه مشابهی داشته باشند ، که می توانند از طریق تکنیک های مقایسه ریاضی مانند شباهت کسین شناسایی شوند.

برای تولید تعبیه از مدل embedding-001 با روش EmbedContent (یا روش BatchEmbedContent ) استفاده کنید. مثال زیر تعبیه یک رشته واحد ایجاد می کند:

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()
em := client.EmbeddingModel("embedding-001")
res, err := em.EmbedContent(ctx, genai.Text("The quick brown fox jumps over the lazy dog."))

if err != nil {
  panic(err)
}
fmt.Println(res.Embedding.Values)

فراخوانی تابع

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

توکن ها را بشمارید

هنگام استفاده از اعلان های طولانی ، ممکن است قبل از ارسال هرگونه محتوا به مدل ، توکن ها را بشمارید. مثالهای زیر نحوه استفاده از CountTokens() برای موارد مختلف استفاده نشان می دهد:

// For text-only input
text := "Parrots can be green and live a long time."
resp, err := model.CountTokens(ctx, genai.Text(text))
if err != nil {
  log.Fatal(err)
}
fmt.Println(resp.TotalTokens)

// For text-and-image input (multimodal)
text := "Parrots can be green and live a long time."
imageBytes, err := os.ReadFile(pathToImage)
if err != nil {
  log.Fatal(err)
}

resp, err := model.CountTokens(
    ctx,
    genai.Text(text),
    genai.ImageData("png", imageBytes))
  if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.TotalTokens)

گزینه هایی برای کنترل تولید محتوا

می توانید با پیکربندی پارامترهای مدل و با استفاده از تنظیمات ایمنی ، تولید محتوا را کنترل کنید.

پارامترهای مدل را پیکربندی کنید

هر سریع که به مدل ارسال می کنید شامل مقادیر پارامتری است که نحوه تولید مدل پاسخ را کنترل می کند. این مدل می تواند برای مقادیر پارامتر مختلف نتایج مختلفی ایجاد کند. در مورد پارامترهای مدل بیشتر بدانید. پیکربندی برای طول عمر نمونه مدل شما حفظ می شود.

// ...

model := client.GenerativeModel("MODEL_NAME")

// Configure model parameters by invoking Set* methods on the model.
model.SetTemperature(0.9)
model.SetTopK(1)

// ...

از تنظیمات ایمنی استفاده کنید

شما می توانید از تنظیمات ایمنی برای تنظیم احتمال دریافت پاسخ هایی که ممکن است مضر تلقی شود ، استفاده کنید. به طور پیش فرض ، تنظیمات ایمنی محتوا را با احتمال متوسط ​​و/یا زیاد از عدم امنیت محتوای در همه ابعاد مسدود می کند. در مورد تنظیمات ایمنی بیشتر بدانید.

در اینجا نحوه تنظیم یک تنظیم ایمنی آورده شده است:

// ...

model := client.GenerativeModel("MODEL_NAME")

model.SafetySettings = []*genai.SafetySetting{
  {
    Category:  genai.HarmCategoryHarassment,
    Threshold: genai.HarmBlockOnlyHigh,
  },
}

// ...

همچنین می توانید بیش از یک تنظیم ایمنی تنظیم کنید:

// ...

model := client.GenerativeModel("MODEL_NAME")

model.SafetySettings = []*genai.SafetySetting{
  {
    Category:  genai.HarmCategoryHarassment,
    Threshold: genai.HarmBlockOnlyHigh,
  },
  {
    Category:  genai.HarmCategoryHateSpeech,
    Threshold: genai.HarmBlockMediumAndAbove,
  },
}

// ...

چه بعدی است

  • طراحی سریع فرایند ایجاد مطالب است که پاسخ مطلوب را از مدل های زبان استخراج می کند. نوشتن مطالب ساخت یافته به خوبی بخش مهمی در اطمینان از پاسخ های دقیق و با کیفیت بالا از یک مدل زبان است. در مورد بهترین شیوه ها برای نوشتن سریع بیاموزید.

  • Gemini برای پاسخگویی به نیازهای موارد مختلف استفاده ، مانند انواع ورودی و پیچیدگی ، پیاده سازی برای گپ یا سایر کارهای زبان گفتگو و محدودیت های اندازه ، چندین مدل مدل ارائه می دهد. در مورد مدل های جمینی موجود بیاموزید.

  • جمینی گزینه هایی را برای افزایش نرخ نرخ درخواست ارائه می دهد. حد نرخ برای مدل های Gemini Pro 60 درخواست در دقیقه (RPM) است.