教學課程:開始使用 Gemini API


本教學課程示範如何使用 Google AI Dart SDK,為 Dart 或 Flutter 應用程式存取 Gemini API。如果不想直接使用 REST API 在應用程式中存取 Gemini 模型,您可以使用這個 SDK。

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

此外,本教學課程包含進階用途相關章節 (例如嵌入計算符記),以及控制內容產生的選項。

先備知識

本教學課程假設您已熟悉如何使用 Dart 建構應用程式。

如要完成本教學課程,請確認您的開發環境符合下列規定:

  • Dart 3.2.0 以上版本

設定專案

呼叫 Gemini API 之前,您需要設定專案,包括設定 API 金鑰、將 SDK 加入發布商依附元件,以及初始化模型。

設定 API 金鑰

如要使用 Gemini API,您必須具備 API 金鑰。如果您沒有金鑰 請在 Google AI Studio 中建立金鑰

取得 API 金鑰

確保 API 金鑰安全

妥善保護 API 金鑰。強烈建議您「不要」直接在程式碼中納入 API 金鑰,或將包含金鑰的檔案檢查到版本管控系統中。您應該改用密鑰儲存庫做為 API 金鑰。

本教學課程的所有程式碼片段均假設您存取 API 金鑰做為程序環境變數。如果您開發的是 Flutter 應用程式,可以使用 String.fromEnvironment,並將 --dart-define=API_KEY=$API_KEY 傳遞至 flutter buildflutter run 以使用 API 金鑰進行編譯,因為執行應用程式時的程序環境會有所不同。

安裝 SDK 套件

如要在自己的應用程式使用 Gemini API,您必須將 google_generative_ai 套件 add 至 Dart 或 Flutter 應用程式:

飛鏢

dart pub add google_generative_ai

飄逸袖

flutter pub add google_generative_ai

初始化生成式模型

您必須先匯入並初始化生成式模型,才能發出 API 呼叫。

import 'dart:io';
import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {

  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }

  // The Gemini 1.5 models are versatile and work with most use cases
  final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
}

指定模型時,請注意下列事項:

  • 使用您用途專屬的模型 (例如,gemini-1.5-flash 適用於多模態輸入)。在本指南中,各實作方法的操作說明會列出每種用途的建議模型。

實作常見用途

專案設定完成後,您就可以瞭解如何使用 Gemini API 實作不同的用途:

在進階用途部分中,您可以找到 Gemini API 和嵌入的相關資訊。

從純文字輸入來生成文字

如果提示內容只包含文字,請使用 Gemini 1.5 模型或搭載 generateContent 的 Gemini 1.0 Pro 模型,生成文字輸出:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
  final content = [Content.text('Write a story about a magic backpack.')];
  final response = await model.generateContent(content);
  print(response.text);
}

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

Gemini 提供多種可處理多模態輸入的模型 (Gemini 1.5 模型),方便您輸入文字和圖片。請務必查看提示的圖片規定

如果提示輸入內容包含文字和圖片,請使用 Gemini 1.5 模型和 generateContent 方法生成文字輸出:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
  final (firstImage, secondImage) = await (
    File('image0.jpg').readAsBytes(),
    File('image1.jpg').readAsBytes()
  ).wait;
  final prompt = TextPart("What's different between these pictures?");
  final imageParts = [
    DataPart('image/jpeg', firstImage),
    DataPart('image/jpeg', secondImage),
  ];
  final response = await model.generateContent([
    Content.multi([prompt, ...imageParts])
  ]);
  print(response.text);
}

打造多輪對話 (聊天)

使用 Gemini 即可多回合,建立任意形式的對話。SDK 會透過管理對話狀態來簡化程序,因此與 generateContent 不同,您不需要自行儲存對話記錄。

如要建構多輪對話 (例如對話),請使用 Gemini 1.5 模型或 Gemini 1.0 Pro 模型,然後呼叫 startChat() 初始化對話。接著使用 sendMessage() 傳送新的使用者訊息,這個訊息也會將訊息和回應附加到即時通訊記錄中。

與對話中的內容相關的 role 有兩種可能的選項:

  • user:提供提示的角色。這個值是 sendMessage 呼叫的預設值,且如果傳遞其他角色,該函式將擲回例外狀況。

  • model:提供回應的角色。透過現有的 history 呼叫 startChat() 時,您可以使用這個角色。

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

Future<void> main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
  final model = GenerativeModel(
      model: 'gemini-1.5-flash',
      apiKey: apiKey,
      generationConfig: GenerationConfig(maxOutputTokens: 100));
  // Initialize the chat
  final chat = model.startChat(history: [
    Content.text('Hello, I have 2 dogs in my house.'),
    Content.model([TextPart('Great to meet you. What would you like to know?')])
  ]);
  var content = Content.text('How many paws are in my house?');
  var response = await chat.sendMessage(content);
  print(response.text);
}

使用串流加快互動速度

根據預設,模型會在完成整個產生程序後傳回回應。您不必等待整個結果,就能實現更快速的互動,並改用串流處理部分結果。

以下範例說明如何使用 generateContentStream 方法實作串流,根據文字和圖片輸入提示產生文字。

// ...

final response = model.generateContentStream([
  Content.multi([prompt, ...imageParts])
]);
await for (final chunk in response) {
  print(chunk.text);
}

// ...

在純文字輸入和聊天使用情境中,您也可以採取類似的做法。

// Use streaming with text-only input
final response = model.generateContentStream(content);
// Use streaming with multi-turn conversations (like chat)
final response = chat.sendMessageStream(content);

實作進階用途

本教學課程前一節所述的常見用途,可協助您熟悉 Gemini API 的使用方式。本節說明一些較進階的用途。

函式呼叫

函式呼叫可讓您輕鬆從生成式模型取得結構化資料輸出內容。接著,您可以使用這些輸出內容呼叫其他 API,並將相關的回應資料傳回模型。換句話說,函式呼叫可協助您將生成式模型連結至外部系統,讓產生的內容包含最新且準確的資訊。詳情請參閱函式呼叫教學課程

使用嵌入

嵌入是一種技術,用於將資訊顯示為陣列中的浮點數清單。您可以透過 Gemini 以向量形式表示文字 (字詞、句子和文字區塊),比較嵌入和對比。舉例來說,具有相同主題或情緒的兩段文字應有類似的嵌入,並且可透過數學相似度等數學比較技巧來識別。

搭配 embedContent 方法 (或 batchEmbedContent 方法) 使用 embedding-001 模型產生嵌入。以下範例會產生單一字串的嵌入:

final model = GenerativeModel(model: 'embedding-001', apiKey: apiKey);
final content = Content.text('The quick brown fox jumps over the lazy dog.');
final result = await model.embedContent(content);
print(result.embedding.values);

計算符記數量

使用長提示時,建議先計算符記再傳送任何內容至模型。下列範例說明如何將 countTokens() 用於各種用途:

// For text-only input
final tokenCount = await model.countTokens(Content.text(prompt));
print('Token count: ${tokenCount.totalTokens}');
// For text-and-image input (multimodal)
final tokenCount = await model.countTokens([
  Content.multi([prompt, ...imageParts])
]);
print('Token count: ${tokenCount.totalTokens}');
// For multi-turn conversations (like chat)
final prompt = Content.text(message);
final allContent = [...chat.history, prompt];
final tokenCount = await model.countTokens(allContent);
print('Token count: ${tokenCount.totalTokens}');

控管內容生成功能的選項

您可以設定模型參數及使用安全設定,控管內容產生作業。

請注意,將 generationConfigsafetySettings 傳遞至模型要求方法 (例如 generateContent) 會完全覆寫 getGenerativeModel 中傳遞的相同名稱設定物件。

設定模型參數

您傳送至模型的每個提示都含有參數值,用來控制模型生成回覆的方式。模型可能會針對不同的參數值產生不同的結果。進一步瞭解模型參數。系統會在模型執行個體的生命週期內保留設定。

final generationConfig = GenerationConfig(
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
);
final model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  model: 'gemini-1.5-flash',
  apiKey: apiKey,
  generationConfig: generationConfig,
);

使用安全性設定

您可以使用安全性設定,調整收到可能視為有害回應的機率。根據預設,安全性設定會封鎖中等和/或很有可能為不安全的內容。進一步瞭解安全性設定

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

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  model: 'gemini-1.5-flash',
  apiKey: apiKey,
  safetySettings: safetySettings,
);

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

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
  SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.high),
];

後續步驟

  • 「提示設計」是指建立提示的程序,會從語言模型中取得所需回應。想確保語言模型提供準確且高品質的回覆,就必須撰寫條理分明的提示。瞭解撰寫提示的最佳做法

  • Gemini 提供多種不同模型版本,可滿足不同用途的需求,例如輸入類型和複雜度、對話或其他對話方塊語言工作的實作方式,以及大小限制。瞭解可用的 Gemini 模型