The Google AI Swift SDK is in public preview, which means its behavior and features could change in backward-incompatible ways. Preview releases should not be used in production.

Trang này được dịch bởi Cloud Translation API.

Làm quen với API Gemini trong ứng dụng Swift

Hướng dẫn này minh hoạ cách truy cập vào API Gemini ngay từ ứng dụng Swift bằng cách sử dụng SDK Swift cho AI của Google. 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ủ (chẳng hạn như Python) để 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 bằng thông tin chỉ nhập bằng văn bản
Tạo văn bản từ dữ liệu nhập bằng văn bản và hình ảnh (đa phương thức)
Xây dựng cuộc trò chuyện nhiều lượt (trò chuyện)
Sử dụng tính năng phát trực tuyến để tương tác nhanh hơn

Ngoài ra, hướng dẫn này còn có các phần về các trường hợp sử dụng nâng cao (chẳng hạn như đếm mã thông báo) cũng như các tuỳ chọn để 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 ứng dụng Swift.

Để hoàn tất phần hướng dẫn này, hãy đảm bảo 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 của bạn 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 API Gemini, bạn cần thiết lập dự án Xcode, bao gồm cả việc thiết lập khoá API, thêm gói SDK vào dự án Xcode và khởi động mô hình.

Thiết lập khoá API

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

Lấy khoá API

Bảo mật khoá API

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

Mở rộng để xem cách lưu trữ và đọc khoá API trong tệp .plist

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ể xem ứng dụng mẫu để tìm hiểu cách lưu trữ khoá API trong tệp .plist.

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

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

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

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.
Chọn Add Packages (Thêm gói) trong trình đơn theo bối cảnh.
Trong hộp thoại Add Packages (Thêm gói), hãy dán URL gói vào thanh tìm kiếm:
```
https://github.com/google/generative-ai-swift
```
Nhấp vào Thêm gói. Giờ đây, Xcode sẽ thêm gói GoogleGenerativeAI vào dự án của bạn.

Khởi động mô hình tạo sinh

Trước khi có thể thực hiện bất kỳ lệnh gọi API nào, bạn cần khởi chạy mô hình tạo sinh.

Nhập mô-đun GoogleGenerativeAI:
```
import GoogleGenerativeAI
```

Khởi động mô hình tạo sinh:

// Access your API key from your on-demand resource .plist file
// (see "Set up your API key" above)
let model = GenerativeModel(name: "MODEL_NAME", apiKey: APIKey.default)

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

Sử dụng mô hình dành riêng cho trường hợp sử dụng của bạn (ví dụ: gemini-pro-vision 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 mỗi cách triển khai liệt kê mô hình được đề xuất cho từng trường hợp sử dụng.

Lưu ý: Để biết thông tin chi tiết về các mô hình hiện có, bao gồm cả tính năng và giới hạn số lượng yêu cầu, hãy xem bài viết Mô hình Gemini. Giới hạn số lượng yêu cầu cho các mô hình Gemini Pro là 60 yêu cầu mỗi phút (RPM) và chúng tôi cung cấp các lựa chọn để yêu cầu tăng giới hạn tốc độ.

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á cách sử dụng API Gemini để triển khai các trường hợp sử dụng khác nhau:

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

Tạo văn bản từ phương thức nhập chỉ bằng văn bản

Khi câu lệnh đầu vào chỉ bao gồm văn bản, hãy sử dụng mô hình gemini-pro với phương thức generateContent để tạo đầu ra văn bản:

import GoogleGenerativeAI

// For text-only input, use the gemini-pro model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro", 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 phương thức nhập văn bản và hình ảnh (đa phương thức)

Gemini cung cấp một mô hình đa phương thức (gemini-pro-vision) để bạn có thể nhập cả 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 đầu vào của lời nhắc bao gồm cả văn bản và hình ảnh, hãy sử dụng mô hình gemini-pro-vision với phương thức generateContent để tạo đầu ra văn bản:

import GoogleGenerativeAI

// For text-and-image input (multimodal), use the gemini-pro-vision model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro-vision", 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 (trò chuyện)

Khi dùng Gemini, bạn có thể tạo các cuộc trò chuyện dạng tự do qua nhiều lượt. 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ư generateContent, bạn không phải tự lưu trữ nhật ký cuộc trò chuyện.

Để tạo một cuộc trò chuyện nhiều lượt (như cuộc trò chuyện), hãy sử dụng mô hình gemini-pro và khởi động cuộc trò chuyện bằng cách gọi startChat(). Sau đó, sử dụng sendMessage() để gửi tin nhắn mới cho người dùng. Thao tác này cũng sẽ thêm tin nhắn và câu trả lời vào nhật ký trò chuyện.

Có 2 tuỳ chọn cho role liên kết với nội dung trong cuộc trò chuyện:

user: vai trò đưa ra lời nhắc. Giá trị này là giá trị mặc định cho các lệnh gọi sendMessage.
model: vai trò đưa ra câu trả lời. Bạn có thể dùng vai trò này khi gọi startChat() bằng history hiện có.

import GoogleGenerativeAI

let config = GenerationConfig(
  maxOutputTokens: 100
)

// For text-only input, use the gemini-pro model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  name: "gemini-pro",
  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 sẽ trả về một phản hồi sau khi hoàn tất toàn bộ quá trình tạo. Bạn có thể đạt được tương tác nhanh hơn bằng cách không đợi toàn bộ kết quả, mà thay vào đó sử dụng phương thức truyền trực tuyến để xử lý một phần kết quả.

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

import GoogleGenerativeAI

// For text-and-image input (multimodal), use the gemini-pro-vision model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro-vision", 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ể áp 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 hướng dẫn này giúp bạn làm quen với việc sử dụng API Gemini. Phần này mô tả một số trường hợp sử dụng có thể được coi là nâng cao hơn.

Gọi hàm

Tính năng gọi hàm giúp bạn dễ dàng nhận được kết quả dữ liệu có cấu trúc từ các mô hình tạo sinh. Sau đó, bạn có thể sử dụng các kết quả đầu ra này để gọi các API khác và trả về dữ liệu phản hồi liên quan cho mô hình. Nói cách khác, tính năng 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. Hãy tìm hiểu thêm trong hướng dẫn gọi hàm.

Số lượng mã thông báo

Khi sử dụng lời nhắc dài, bạn nên đếm mã thông báo trước khi gửi bất kỳ nội dung nào đến 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 = 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 tham số mô hình và sử dụng các chế độ cài đặt an toàn.

Định cấu hình thông số mô hình

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

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(
  name: "MODEL_NAME",
  apiKey: APIKey.default,
  generationConfig: config
)

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

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

Sau đâ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(
  name: "MODEL_NAME",
  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(
  name: "MODEL_NAME",
  apiKey: APIKey.default,
    safetySettings: [harassmentSafety, hateSpeechSafety]
)

Bước tiếp theo

Thiết kế lời nhắc là quá trình tạo các câu lệnh để khơi gợi phản hồi mong muốn từ các mô hình ngôn ngữ. Việc viết câu lệnh có cấu trúc hợp lý là một phần cần thiết để đảm bảo câu trả lời chính xác và chất lượng cao từ mô hình ngôn ngữ. Tìm hiểu các phương pháp hay nhất để viết gợi ý.
Gemini cung cấp một số biến thể mô hình để đáp ứng nhu cầu của nhiều trường hợp sử dụng, chẳng hạn như loại dữ liệu đầu vào và độ phức tạp, cách triển khai cho cuộc trò chuyện hoặc các tác vụ khác về ngôn ngữ hộp thoại cũng như các quy tắc ràng buộc về kích thước. Tìm hiểu về các mô hình Gemini hiện có.
Gemini đưa ra các tuỳ chọn để yêu cầu tăng giới hạn tốc độ. Giới hạn tốc độ cho các mô hình Genmini Pro là 60 yêu cầu mỗi phút (RPM).