Hướng dẫn: Làm quen với API Gemini

Python Node.js Web Kiến trúc chuyển trạng thái đại diện (REST) Bắt đầu Dart (Flutter) Android Swift

Hướng dẫn này minh hoạ cách truy cập Gemini API ngay từ Ứng dụng Swift dùng SDK Google AI Swift. Bạn có thể sử dụng SDK này nếu không muốn để làm việc trực tiếp với API REST hoặc mã phía máy chủ (như Python) nhằm truy cập vào Các mô hình Gemini trong ứng dụng Swift.

Trong hướng dẫn này, bạn sẽ tìm hiểu cách thực hiện những việc sau:

• Thiết lập dự án, bao gồm cả khoá API
• Tạo văn bản từ dữ liệu nhập chỉ có văn bản
• Tạo văn bản bằng cách nhập văn bản và hình ảnh (đa phương thức)
• Tạo cuộc trò chuyện nhiều lượt (trò chuyện)
• Sử dụng tính năng truyền trực tuyến để tương tác nhanh hơn

Ngoài ra, hướng dẫn này bao gồm các phần về các trường hợp sử dụng nâng cao (như đếm mã thông báo) cũng như các tuỳ chọn cho kiểm soát việc tạo nội dung.

Điều kiện tiên quyết

Hướng dẫn này giả định rằng bạn đã quen thuộc với việc sử dụng Xcode để phát triển Swift của chúng tôi.

Để hoàn thành hướng dẫn này, hãy đảm bảo rằng môi trường phát triển và Ứng dụng Swift đáp ứng các yêu cầu sau:

• Xcode 15.0 trở lên
• Ứng dụng Swift phải nhắm đến iOS 15 trở lên hoặc macOS 12 trở lên.

Thiết lập dự án

Trước khi gọi Gemini API, bạn cần thiết lập dự án Xcode của mình bao gồm thiết lập khoá API, thêm gói SDK vào dự án Xcode của bạn, và khởi tạo mô hình.

Thiết lập khoá API

Để sử dụng Gemini API, bạn sẽ cần có khoá API. Nếu chưa có tài khoản, tạo một khoá trong Google AI Studio.

Tải khoá API

Bảo mật khoá API của bạn

Bạn không nên kiểm tra khoá API trong phiên bản của mình hệ thống kiểm soát. Một cách khác là lưu trữ mã đó trong một GenerativeAI-Info.plist, sau đó đọc khoá API từ .plist . Hãy nhớ đặt tệp .plist này vào thư mục gốc của ứng dụng và hãy loại trừ ứng dụng đó khỏi hệ thống quản lý phiên bản.

enum APIKey {
  // Fetch the API key from `GenerativeAI-Info.plist`
  static var `default`: String {
    guard let filePath = Bundle.main.path(forResource: "GenerativeAI-Info", ofType: "plist")
    else {
      fatalError("Couldn't find file 'GenerativeAI-Info.plist'.")
    }
    let plist = NSDictionary(contentsOfFile: filePath)
    guard let value = plist?.object(forKey: "API_KEY") as? String else {
      fatalError("Couldn't find key 'API_KEY' in 'GenerativeAI-Info.plist'.")
    }
    if value.starts(with: "_") {
      fatalError(
        "Follow the instructions at https://ai.google.dev/tutorials/setup to get an API key."
      )
    }
    return value
  }
}

Bạn cũng có thể tham khảo ứng dụng mẫu để tìm hiểu cách lưu trữ khoá API trong tệp .plist.

Tất cả đoạn mã trong hướng dẫn này đều giả định rằng bạn đang truy cập khoá API của mình từ tệp .plist tài nguyên theo yêu cầu này.

Thêm gói SDK vào dự án

Để sử dụng Gemini API trong ứng dụng Swift của riêng bạn, hãy thêm GoogleGenerativeAI cho ứng dụng của bạn:

1. Trong Xcode, hãy nhấp chuột phải vào dự án của bạn trong trình điều hướng dự án.

2. Chọn Add Packages (Thêm gói) trong trình đơn theo bối cảnh.

3. Trong hộp thoại Add Packages (Thêm gói), hãy dán URL của gói vào thanh tìm kiếm:

   https://github.com/google/generative-ai-swift
   

4. Nhấp vào Add Package (Thêm gói). Xcode sẽ thêm gói GoogleGenerativeAI cho dự án của bạn.

Khởi chạy mô hình tạo sinh

Để có thể thực hiện lệnh gọi API, bạn cần khởi chạy mô hình tạo sinh.

1. Nhập mô-đun GoogleGenerativeAI:

   import GoogleGenerativeAI
   

2. Khởi chạy mô hình tạo sinh:

   // Access your API key from your on-demand resource .plist file
   // (see "Set up your API key" above)
   // The Gemini 1.5 models are versatile and work with most use cases
   let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)
   

Khi chỉ định một mô hình, hãy lưu ý những điều sau:

• Sử dụng một mô hình cụ thể cho trường hợp sử dụng của bạn (ví dụ: gemini-1.5-flash dành cho phương thức nhập đa phương thức). Trong hướng dẫn này, hướng dẫn cho từng liệt kê mô hình triển khai được đề xuất cho từng trường hợp sử dụng.

Triển khai các trường hợp sử dụng phổ biến

Bây giờ, dự án của bạn đã được thiết lập, bạn có thể khám phá việc sử dụng Gemini API để triển khai các trường hợp sử dụng khác nhau:

• Tạo văn bản từ dữ liệu nhập chỉ có văn bản
• Tạo văn bản bằng cách nhập văn bản và hình ảnh (đa phương thức)
• Tạo cuộc trò chuyện nhiều lượt (trò chuyện)
• Sử dụng tính năng truyền trực tuyến để tương tác nhanh hơn

Tạo văn bản từ dữ liệu đầu vào chỉ có văn bản

Khi câu lệnh chỉ bao gồm văn bản, hãy sử dụng mô hình Gemini 1.5 hoặc Mô hình Gemini 1.0 Pro có generateContent để tạo đầu ra văn bản:

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let prompt = "Write a story about a magic backpack."
let response = try await model.generateContent(prompt)
if let text = response.text {
  print(text)
}

Tạo văn bản bằng cách nhập văn bản và hình ảnh (đa phương thức)

Gemini cung cấp nhiều mô hình có thể xử lý dữ liệu nhập đa phương thức (Các mô hình Gemini 1.5) để bạn có thể nhập cả hai văn bản và hình ảnh. Hãy nhớ xem lại các yêu cầu về hình ảnh đối với câu lệnh.

Khi câu lệnh nhập bao gồm cả văn bản và hình ảnh, hãy sử dụng mô hình Gemini 1.5 bằng phương thức generateContent để tạo đầu ra văn bản:

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let image1 = UIImage(...)
let image2 = UIImage(...)

let prompt = "What's different between these pictures?"

let response = try await model.generateContent(prompt, image1, image2)
if let text = response.text {
  print(text)
}

Xây dựng cuộc trò chuyện nhiều lượt

Khi sử dụng Gemini, bạn có thể tạo các cuộc trò chuyện dạng tự do ở nhiều chặng. Chiến lược phát hành đĩa đơn SDK đơn giản hoá quy trình bằng cách quản lý trạng thái của cuộc trò chuyện, vì vậy, không giống như với generateContent, bạn không cần lưu trữ nhật ký trò chuyện chính bạn.

Để tạo một cuộc trò chuyện nhiều lượt (chẳng hạn như trò chuyện), hãy sử dụng mô hình Gemini 1.5 hoặc Mô hình Gemini 1.0 Pro và bắt đầu cuộc trò chuyện bằng cách gọi startChat(). Sau đó, sử dụng sendMessage() để gửi thông báo cho người dùng mới. Việc này cũng sẽ thêm thông báo tin nhắn và câu trả lời trong nhật ký trò chuyện.

Có hai lựa chọn cho role được liên kết với nội dung trong một cuộc trò chuyện:

• user: vai trò đưa ra lời nhắc. Đây là giá trị mặc định cho sendMessage cuộc gọi.

• model: vai trò đưa ra câu trả lời. Vai trò này có thể được dùng khi gọi startChat() bằng history hiện có.

import GoogleGenerativeAI

let config = GenerationConfig(
  maxOutputTokens: 100
)

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  generationConfig: config
)

let history = [
  ModelContent(role: "user", parts: "Hello, I have 2 dogs in my house."),
  ModelContent(role: "model", parts: "Great to meet you. What would you like to know?"),
]

// Initialize the chat
let chat = model.startChat(history: history)
let response = try await chat.sendMessage("How many paws are in my house?")
if let text = response.text {
  print(text)
}

Sử dụng tính năng phát trực tuyến để tương tác nhanh hơn

Theo mặc định, mô hình này trả về một phản hồi sau khi hoàn tất toàn bộ quá trình tạo của chúng tôi. Bạn có thể đạt được các tương tác nhanh hơn bằng cách không phải đợi toàn bộ kết quả và thay vào đó hãy sử dụng luồng để xử lý một phần kết quả.

Ví dụ sau đây trình bày cách triển khai tính năng truyền trực tuyến bằng Phương thức generateContentStream để tạo văn bản qua phương thức nhập văn bản và hình ảnh .

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let image1 = UIImage(named: "")!
let image2 = UIImage(named: "")!

let prompt = "What's different between these pictures?"
var fullResponse = ""
let contentStream = model.generateContentStream(prompt, image1, image2)
for try await chunk in contentStream {
  if let text = chunk.text {
    print(text)
    fullResponse += text
  }
}
print(fullResponse)

Bạn có thể sử dụng phương pháp tương tự cho các trường hợp sử dụng chỉ nhập văn bản và trò chuyện.

// Use streaming with text-only input
let contentStream = model.generateContentStream(prompt)

// Use streaming with multi-turn conversations (like chat)
let responseStream = chat.sendMessageStream(message)

Triển khai các trường hợp sử dụng nâng cao

Các trường hợp sử dụng phổ biến được mô tả trong phần trước của trợ giúp hướng dẫn này bạn cảm thấy thoải mái khi sử dụng Gemini API. Phần này mô tả một số các trường hợp sử dụng có thể được xem là nâng cao hơn.

Gọi hàm

Lệnh gọi hàm giúp bạn dễ dàng nhận kết quả đầu ra dữ liệu có cấu trúc các mô hình tạo sinh. Sau đó, bạn có thể sử dụng những dữ liệu đầu ra này để gọi các API khác và trả về dữ liệu phản hồi phù hợp cho mô hình. Nói cách khác, lệnh gọi hàm giúp bạn kết nối các mô hình tạo sinh với hệ thống bên ngoài để nội dung được tạo bao gồm thông tin chính xác và mới nhất. Tìm hiểu thêm trong hướng dẫn gọi hàm.

Đếm mã

Khi sử dụng các câu lệnh dài, có thể bạn nên đếm mã thông báo trước khi gửi bất cứ mã nào vào mô hình. Các ví dụ sau đây minh hoạ cách sử dụng countTokens() cho nhiều trường hợp sử dụng:

// For text-only input
let response = try await model.countTokens("Why is the sky blue?")
print(response.totalTokens)

// For text-and-image input (multi-modal)
let response = try await model.countTokens(prompt, image1, image2)
print(response.totalTokens)

// For multi-turn conversations (like chat)
let chat = model.startChat()
let history = chat.history
let message = try ModelContent(role: "user", "Why is the sky blue?")
let contents = history + [message]
let response = try await model.countTokens(contents)
print(response.totalTokens)

Các tuỳ chọn kiểm soát việc tạo nội dung

Bạn có thể kiểm soát việc tạo nội dung bằng cách định cấu hình các thông số của mô hình và bằng cách sử dụng cài đặt an toàn.

Định cấu hình tham số của mô hình

Mỗi câu lệnh bạn gửi đến mô hình đều có các giá trị thông số kiểm soát cách mô hình sẽ tạo một phản hồi. Mô hình đó có thể tạo ra các kết quả khác nhau cho các giá trị thông số khác nhau. Tìm hiểu thêm về Thông số mô hình. Cấu hình này được duy trì trong suốt thời gian hoạt động của phiên bản mô hình.

let config = GenerationConfig(
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
  maxOutputTokens: 200,
  stopSequences: ["red"]
)

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  generationConfig: config
)

Sử dụng chế độ cài đặt an toàn

Bạn có thể sử dụng chế độ cài đặt an toàn để điều chỉnh khả năng nhận được câu trả lời có thể bị coi là gây hại. Theo mặc định, chế độ cài đặt an toàn sẽ chặn nội dung có mức trung bình và/hoặc có khả năng cao là nội dung không an toàn trên tất cả phương diện. Học tập tìm hiểu thêm về Cài đặt an toàn.

Dưới đây là cách đặt một chế độ cài đặt an toàn:

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  safetySettings: [
    SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
  ]
)

Bạn cũng có thể đặt nhiều chế độ cài đặt an toàn:

let harassmentSafety = SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
let hateSpeechSafety = SafetySetting(harmCategory: .hateSpeech, threshold: .blockMediumAndAbove)

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
    safetySettings: [harassmentSafety, hateSpeechSafety]
)

Các bước tiếp theo

• Thiết kế câu lệnh là quá trình tạo câu lệnh đáp ứng yêu cầu phản hồi từ các mô hình ngôn ngữ. Viết câu lệnh có cấu trúc hợp lý là điều thiết yếu để đảm bảo các câu trả lời chính xác, có chất lượng cao từ một mô hình ngôn ngữ. Tìm hiểu các phương pháp hay nhất để viết câu lệnh.

• Gemini cung cấp một số biến thể mô hình để đáp ứng nhu cầu sử dụng khác nhau trường hợp, chẳng hạn như loại dữ liệu đầu vào và độ phức tạp, các cách triển khai cho cuộc trò chuyện hoặc các tác vụ ngôn ngữ của hộp thoại và giới hạn kích thước. Tìm hiểu về các mô hình Gemini hiện có.