教學課程：開始使用 Gemini API


本教學課程示範如何使用 Go 適用的 Gemini API 開發應用程式

在本教學課程中，您將瞭解如何執行下列操作：

此外，本教學課程還包含進階用途的相關章節 (例如 嵌入和 計算符記) 以及 控管內容生成作業。

必要條件

本教學課程假設您熟悉如何使用 開始

如要完成本教學課程，請確認您的開發環境符合 下列要求：

  • Go 1.20 以上版本

設定專案

呼叫 Gemini API 前，您必須先設定專案，包括 設定 API 金鑰、安裝 SDK 套件以及初始化模型。

設定 API 金鑰

如要使用 Gemini API，您必須具備 API 金鑰。如果您沒有帳戶 建立金鑰

取得 API 金鑰

確保 API 金鑰安全

強烈建議您「不要」在版本中檢查 API 金鑰 控制系統您應該改用密鑰儲存庫做為 API 金鑰。

本教學課程的所有程式碼片段均假設您透過 環境變數

安裝 SDK 套件

如要在自己的應用程式中使用 Gemini API，請get Go SDK 安裝於模組目錄中：

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()

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

指定模型時，請注意下列事項：

  • 請使用符合自身用途的模型，例如 gemini-1.5-flash 多模態輸入)。本指南中將說明 實作會列出每種用途的建議模型。

實作常見用途

專案設定完成後，您就可以使用 Gemini API 進行以下操作： 用途包括

您可以在「進階用途」一節中找到 Gemini API 的相關資訊 和嵌入。

從純文字輸入來生成文字

如果提示內容只包含文字，請使用 Gemini 1.5 模型或 使用 generateContent 的 Gemini 1.0 Pro 模型生成文字：

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()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")
resp, err := model.GenerateContent(ctx, genai.Text("Write a story about a magic backpack."))
if err != nil {
  log.Fatal(err)
}

根據文字和圖片輸入內容產生文字 (多模態)

Gemini 提供各種模型，可處理多模態輸入 (Gemini 1.5 模型)，就能輸入文字和圖片。請務必 查看 提示的圖片相關規定。

如果提示輸入內容包含文字和圖片，請使用 Gemini 1.5 模型 並使用 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()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")

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)
}

打造多輪對話 (聊天)

使用 Gemini 即可多回合，建立任意形式的對話。 SDK 會管理對話狀態，藉此簡化程序，因此 使用「GenerateContent」時，您不必儲存對話記錄 你自己。

如要建立多輪對話 (例如對話)，請使用 Gemini 1.5 模型或 接著，您就能呼叫 startChat() 來初始化 Gemini 1.0 Pro 模型。 接著，使用 sendMessage() 傳送新的使用者訊息，此訊息也會附加 訊息和對即時通訊記錄的回應。

role 有兩種可能的選項， 對話：

  • user：提供提示的角色。這是 SendMessage 次通話。

  • model：提供回應的角色。這個角色可用於 使用現有的 history 呼叫 StartChat()。

，瞭解如何調查及移除這項存取權。 
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()

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
model := client.GenerativeModel("gemini-1.5-flash")
// 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)
}

使用串流加快互動速度

根據預設，模型會在完成整個生成程序後傳回回應 上傳資料集之後，您可以運用 AutoML 自動完成部分資料準備工作您不必等待整個 並改用串流處理部分結果

以下範例顯示如何使用 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()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")

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)

實作進階用途

本教學課程前一節所述的常見用途 您越來越習慣使用 Gemini 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()
// For embeddings, use the embedding-001 model
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)

控管內容生成功能的選項

您可以設定模型參數和 安全性設定

設定模型參數

您傳送至模型的每個提示都含有參數值，用來控制 模型會產生回應模型可能會針對 不同的參數值進一步瞭解 模型參數：設定是 並在模型執行個體的生命週期內持續維護

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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

// ...

使用安全性設定

您可以運用安全性設定，調整收到回應 可能會被視為有害內容根據預設，安全性設定會封鎖中性內容 和/或所有維度中都很有可能出現不安全的內容學習新知 進一步瞭解安全性設定。

以下說明如何進行各項安全性設定：

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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

// ...

你也可以設置多項安全性設定：

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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

// ...

後續步驟

  • 「提示設計」是指建立提示來促成所需流程的程序 語言模型的回應撰寫條理分明的提示相當重要 能確保語言模型提供準確且高品質的回覆。 瞭解撰寫提示的最佳做法。

  • Gemini 提供多種模型版本，可滿足不同用途的需求 例如輸入類型和複雜度、即時通訊等實作 對話語言工作和大小限制 瞭解可用的 Gemini 模型。

，瞭解如何調查及移除這項存取權。