Bắt đầu: Truy cập Gemini API thông qua khung Mô hình cơ bản của Apple


Tại WWDC 2026, Apple đã mở khung Mô hình cơ sở cho các bộ điều hợp mô hình của bên thứ ba. Điều này có nghĩa là bạn có thể truy cập vào các mô hình được lưu trữ trên đám mây (chẳng hạn như Gemini) thông qua khung Mô hình cơ sở bằng cách sử dụng cùng một API như khi bạn truy cập vào các mô hình trên thiết bị.

Trong ứng dụng, bạn có thể hoán đổi phiên bản mô hình để định tuyến các yêu cầu đến suy luận trên thiết bị hoặc suy luận trên đám mây cho phù hợp với trường hợp sử dụng của mình:

  • Các mô hình trên thiết bị mang đến quyền riêng tư tối đa, hoàn toàn miễn phí và hỗ trợ ngoại tuyến.
  • Các mô hình Gemini được lưu trữ trên đám mây cung cấp cửa sổ ngữ cảnh lớn, các chức năng nâng cao và khả năng suy luận mạnh mẽ hơn.

Bạn có thể truy cập vào các mô hình Gemini được lưu trữ trên đám mây thông qua khung Mô hình cơ bản của Apple bằng cách sử dụng SDK Firebase cho các nền tảng Apple – cụ thể là thư viện Firebase AI Logic. Hướng dẫn này sẽ cho bạn biết cách bắt đầu.

Để bảo vệ quyền truy cập vào các mô hình Gemini, hướng dẫn này cũng cho bạn biết cách thiết lập Firebase App Check. Đây là một bước quan trọng ngay cả trong quá trình phát triển.

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

  • Cài đặt Xcode 27 beta mới nhất.

  • Một trình mô phỏng nền tảng Apple hoặc một thiết bị thực, cả hai đều chạy phiên bản hệ điều hành beta tương ứng (ví dụ: iOS 27 beta).

  • Một dự án Xcode mới của ứng dụng nền tảng Apple sử dụng giao diện SwiftUI.

Các mẫu Gemini được hỗ trợ

Việc tích hợp với khung Mô hình nền tảng của Apple hỗ trợ các mô hình Gemini sau đây.

  • Mô hình đa năng

    • gemini-3.1-pro-preview
    • gemini-3.6-flash (và gemini-3.5-flash cũ hơn)
    • gemini-3.5-flash-lite (và gemini-3.1-flash-lite cũ hơn)

  • Mô hình tạo hình ảnh

    • gemini-3-pro-image (còn gọi là "Nano Banana Pro")
    • gemini-3.1-flash-image (còn gọi là "Nano Banana 2")
    • gemini-3.1-flash-lite-image (còn gọi là "Nano Banana 2 Lite")

Các mô hình Gemini Live API và Imagen không được hỗ trợ. Xin lưu ý rằng các mô hình Gemini 2.5 được hỗ trợ về mặt kỹ thuật, nhưng không được khuyến nghị cho các dự án mới và yêu cầu cấu hình đặc biệt không có trong các hướng dẫn này.

Bước 1: Tạo dự án Firebase

Bạn nên bắt đầu bằng một dự án Firebase mới để khám phá tính năng tích hợp này.

  1. Đăng nhập vào bảng điều khiển Firebase.

  2. Nhấp vào Tạo dự án Firebase mới.

  3. Làm theo hướng dẫn trên màn hình. Bạn không cần bật Google Analytics.

Bước 2: Kết nối ứng dụng của bạn với Firebase

Để kết nối ứng dụng với Firebase, bạn phải đăng ký ứng dụng đó với dự án Firebase và thêm một tệp cấu hình vào toàn bộ mã nguồn của mình.

  1. Ở giữa trang tổng quan về dự án, hãy nhấp vào biểu tượng iOS+ để chạy quy trình thiết lập.

  2. Đăng ký ứng dụng:

    1. Nhập mã nhận dạng gói của ứng dụng. Đảm bảo rằng mã này khớp với mã nhận dạng gói của dự án mà bạn đang tạo trong Xcode.

    2. Nhấp vào Đăng ký ứng dụng.

  3. Thêm tệp cấu hình Firebase. Tệp này chứa các chế độ cài đặt để Firebase SDK kết nối với dự án Firebase của bạn.

    1. Nhấp vào Tải xuống GoogleService-Info.plist để tải tệp cấu hình xuống.

    2. Di chuyển GoogleService-Info.plist vào thư mục gốc của dự án Xcode rồi thêm tệp này vào tất cả các đích.

    3. Nhấp vào Tiếp theo trong bảng điều khiển Firebase.

  4. Quy trình trong bảng điều khiển cung cấp hướng dẫn chung để thêm Firebase SDK vào ứng dụng của bạn, vì vậy, hãy chuyển sang bước tiếp theo trong hướng dẫn này để xem hướng dẫn cụ thể cho Firebase AI Logic.

Bước 3: Thêm các thư viện Firebase và khởi động Firebase trong ứng dụng của bạn

  1. Sử dụng Swift Package Manager để thêm các thư viện Firebase cần thiết:

    1. Trong Xcode, khi dự án ứng dụng của bạn đang mở, hãy chọn File (Tệp) > Add Packages (Thêm gói).

    2. Nhập URL kho lưu trữ Firebase Apple SDK:

      https://github.com/firebase/firebase-ios-sdk

    3. Chọn Quy tắc phụ thuộc là Branch (Nhánh) rồi nhập wwdc26-preview.

    4. Nhấp vào Thêm gói. Xcode sẽ phân giải và tải các phần phụ thuộc xuống.

    5. Khi được nhắc, hãy thêm các thư viện FirebaseAILogic và FirebaseAppCheck vào mục tiêu ứng dụng của bạn.

  2. Khởi động Firebase khi ứng dụng của bạn khởi động bằng cách thêm mã sau vào điểm truy cập chính của ứng dụng:

    import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  init() {
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

Bước 4: Bật và bảo mật các dịch vụ của Firebase

Giờ đây, khi ứng dụng của bạn được định cấu hình để sử dụng Firebase, bạn cần bật dịch vụ Firebase AI Logic và bảo vệ quyền truy cập vào các API được liên kết bằng Firebase App Check.

Bước 4a: Thiết lập Firebase AI Logic trong dự án Firebase

  1. Trong bảng điều khiển Firebase, hãy chuyển đến Dịch vụ AI > Logic AI.

  2. Nhấp vào Bắt đầu để khởi chạy quy trình thiết lập có hướng dẫn.

  3. Khi được yêu cầu chọn "nhà cung cấp Gemini API", bạn nên chọn Gemini Developer API để bắt đầu nhanh chóng mà không mất phí.

    Bất cứ lúc nào sau này, bạn đều có thể thiết lập Vertex AI Gemini API (và yêu cầu về việc thanh toán).

  4. Tiếp tục quy trình thiết lập các API bắt buộc và các dịch vụ liên kết cho Firebase AI Logic.

    Kể từ đầu tháng 7 năm 2026, giai đoạn này của quy trình làm việc sẽ tự động thực thi Firebase App Check cho AI Logic. Đây là một dịch vụ quan trọng giúp bảo vệ Gemini API khi được truy cập trực tiếp từ ứng dụng của bạn. Trong quá trình bắt đầu (xem các bước sau trong hướng dẫn này), bạn sẽ cần định cấu hình App Check nhà cung cấp dịch vụ gỡ lỗi để phát triển cục bộ khi App Check được thực thi.

Bước 4b: Định cấu hình nhà cung cấp dịch vụ gỡ lỗi App Check để phát triển cục bộ

Đối với quá trình phát triển cục bộ, bạn cần định cấu hình nhà cung cấp dịch vụ gỡ lỗi App Check để bỏ qua chứng thực trong khi vẫn duy trì việc thực thi App Check.

  1. Trong dự án Xcode, hãy nhập FirebaseAppCheck và khởi chạy App Check bằng nhà máy nhà cung cấp dịch vụ gỡ lỗi trước khi bạn định cấu hình Firebase.

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. Lấy mã thông báo gỡ lỗi:

    1. Chạy ứng dụng trong trình mô phỏng hoặc trên thiết bị thử nghiệm.

    2. Mở bảng điều khiển Xcode rồi tìm mã gỡ lỗi App Check. Ví dụ:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. Sao chép mã thông báo (ví dụ: 123a4567-b89c-12d3-e456-789012345678).

  3. Đăng ký mã thông báo gỡ lỗi bằng App Check:

    1. Trong bảng điều khiển Firebase, hãy chuyển đến Bảo mật > Kiểm tra ứng dụng > thẻ Ứng dụng.

    2. Tìm ứng dụng của bạn, nhấp vào trình đơn mục bổ sung (), rồi chọn Quản lý mã gỡ lỗi.

    3. Làm theo hướng dẫn trên màn hình để đăng ký mã gỡ lỗi.

Để biết thông tin chi tiết về nhà cung cấp dịch vụ gỡ lỗi (bao gồm cả cách lấy mã thông báo gỡ lỗi mới), hãy xem tài liệu App Check chính thức.

Bước 5: Khởi chạy dịch vụ AI Logic trong ứng dụng của bạn

Nhấp vào nhà cung cấp Gemini API để xem nội dung và mã dành riêng cho nhà cung cấp trên trang này.

Sau khi định cấu hình Firebase và App Check, giờ đây, bạn có thể khởi động dịch vụ Firebase AI Logic trong ứng dụng của mình.

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")

Bước 6: Gửi yêu cầu đến một mô hình Gemini

Sau khi thiết lập, bảo vệ và khởi tạo Firebase AI Logic trong ứng dụng, bạn đã sẵn sàng gửi yêu cầu đến một mô hình Gemini.

Ví dụ sau đây minh hoạ loại yêu cầu cơ bản nhất – tạo văn bản từ một câu lệnh chỉ có văn bản:

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a text response to a prompt.
let response = try await session.respond(to: "Write a story about a magic backpack.")
print(response.content)

Các mô hình Gemini cũng hỗ trợ các loại yêu cầu khác, chẳng hạn như phân tích hình ảnh và tệp PDF, tạo đầu ra JSON có cấu trúc và tạo hình ảnh (bằng các mô hình "Nano Banana"). Hãy xem ví dụ về các loại yêu cầu này trong tài liệu hoặc trong ứng dụng mẫu.

Hiện câu trả lời theo thời gian thực

Bạn có thể đạt được các lượt tương tác nhanh hơn bằng cách không đợi toàn bộ kết quả từ quá trình tạo mô hình mà thay vào đó, hãy sử dụng tính năng truyền phát trực tiếp để xử lý kết quả một phần. Để truyền trực tuyến phản hồi, hãy sử dụng streamResponse(to:) thay vì respond(to:).

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a streamed text response to a prompt.
// To stream the response, use `streamResponse(to:)` instead of `respond(to:)`
let stream = session.streamResponse(to: "Write a story about a magic backpack.")
var response = ""
for try await snapshot in stream {
  // The snapshot contains *all* content generated so far.
  response = snapshot.content
}

Các bước tiếp theo


Gửi ý kiến phản hồi về việc truy cập vào Gemini API thông qua khung Mô hình cơ bản của Apple