Bắt đầu sử dụng mẫu câu lệnh trên máy chủ


Trong mỗi yêu cầu gửi đến một mô hình, bạn sẽ gửi một câu lệnh và có thể gửi thêm lược đồ cũng như cấu hình để kiểm soát phản hồi của mô hình. Khi sử dụng Firebase AI Logic, bạn có thể gửi tất cả thông tin này trực tiếp từ mã ứng dụng của mình hoặc có thể chỉ định thông tin này phía máy chủ bằng cách sử dụng mẫu câu lệnh của máy chủ.

Khi sử dụng mẫu lời nhắc trên máy chủ, bạn sẽ lưu trữ lời nhắc, giản đồ và cấu hình phía máy chủ, đồng thời ứng dụng của bạn chỉ truyền khoá (mã nhận dạng mẫu) tham chiếu đến một mẫu cụ thể cũng như các dữ liệu đầu vào bắt buộc cho mẫu đó từ máy khách đến máy chủ.

Khi sử dụng mẫu lời nhắc trên máy chủ, bạn sẽ lưu trữ lời nhắc và cấu hình phía máy chủ, đồng thời chỉ cung cấp một khoá (mã nhận dạng mẫu) trong cơ sở mã của ứng dụng. Sau đây là một số lợi ích của phương pháp này:

  • Ngăn chặn việc để lộ câu lệnh phía máy khách

  • Cập nhật lời nhắc và cấu hình mà không cần phát hành phiên bản ứng dụng mới

Hướng dẫn này mô tả cách bắt đầu sử dụng mẫu câu lệnh trên máy chủ.

Chuyển đến phần tổng quan cấp cao Chuyển đến phần hướng dẫn chi tiết

Các mô hình và chức năng được hỗ trợ


Thông tin tổng quan

Sau đây là quy trình cơ bản để sử dụng mẫu câu lệnh trên máy chủ:

  1. Tạo mẫu bằng giao diện người dùng có hướng dẫn trong bảng điều khiển Firebase.

  2. Kiểm thử mẫu trong một yêu cầu thực bằng cách sử dụng trải nghiệm kiểm thử của bảng điều khiển Firebase.

  3. Truy cập vào mẫu trong ứng dụng của bạn.

Định dạng cơ bản của mẫu câu lệnh trên máy chủ

Đối với Firebase AI Logic, bảng điều khiển Firebase cung cấp một giao diện người dùng có hướng dẫn để bạn chỉ định nội dung của một mẫu.

Mẫu câu lệnh trên máy chủ sử dụng cú pháp và định dạng dựa trên Dotprompt. Để biết thêm thông tin chi tiết, hãy xem phần Định dạng, cú pháp và ví dụ về mẫu.

Sau đây là những thành phần quan trọng nhất cho một yêu cầu mẫu đối với mô hình Gemini:

---
model: 'gemini-2.5-flash'
---

{{role "system"}}
All output must be a clearly structured invoice document.
Use a tabular or clearly delineated list format for line items.

{{role "user"}}
Create an example customer invoice for a customer named {{customerName}}.

  • Phần trên cùng trong dấu gạch ngang ba lần chứa tên mô hình cũng như mọi cấu hình mô hình, xác thực đầu vào hoặc giản đồ mà bạn muốn gửi trong yêu cầu (không bắt buộc). Thông số này được viết dưới dạng cặp khoá-giá trị và thường được gọi là frontmatter YAML.

  • Nội dung của mẫu chứa câu lệnh. Bạn cũng có thể tuỳ ý thêm hướng dẫn hệ thống và giá trị đầu vào (bằng cú pháp Handlebars).

Sử dụng mẫu trong mã

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 đây là cách sử dụng mẫu trong mã của bạn:

Swift 


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
let model = FirebaseAI.firebaseAI(backend: .googleAI()).templateGenerativeModel()

let customerName = "Jane"

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "my-first-template-v1-0-0",
        // Provide the values for any input variables required by your template.
        inputs: [
            "customerName": customerName
        ]
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin 


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.googleAI.templateGenerativeModel()

val customerName = "Jane"

val response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf(
        "customerName" to customerName
    )
)

val text = response.text
println(text)

Java 


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

String customerName = "Jane";

Future response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf("customerName", customerName)
);
addCallback(response,
       new FutureCallback() {
           public void onSuccess(GenerateContentResponse result) {
             System.out.println(result.getText());
           }
           public void onFailure(Throwable t) {
             reportError(t);
           }
    }
executor);

Web 


// ...

// Initialize the Gemini Developer API backend service
const ai = getAI(app, { backend: new GoogleAIBackend() });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const customerName = 'Jane';

const result = await model.generateContent(
  // Specify your template ID
  'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template
  {
    customerName: customerName,
  }
);

const response = response.result;
const text = response.text();

Dart

Trình bổ trợ Flutter sẽ sớm hỗ trợ các mẫu câu lệnh trên máy chủ!

Unity

Gói Unity sẽ sớm hỗ trợ các mẫu câu lệnh trên máy chủ!


Hướng dẫn chi tiết

Phần này cung cấp hướng dẫn chi tiết về cách tạo, kiểm thử và sử dụng các mẫu câu lệnh trên máy chủ.

Trước khi bắt đầu

  • Nếu bạn chưa thực hiện, hãy hoàn tất hướng dẫn bắt đầu sử dụng. Hướng dẫn này mô tả cách thiết lập dự án Firebase, kết nối ứng dụng với Firebase, thêm SDK, khởi chạy dịch vụ phụ trợ cho nhà cung cấp Gemini API mà bạn chọn và tạo một phiên bản GenerativeModel.

  • Đảm bảo bạn có các quyền bắt buộc để tạo và quản lý mẫu câu lệnh trên máy chủ. Theo mặc định, tất cả các quyền này đều có trong vai trò Chủ sở hữu.

  • Nếu bạn sử dụng Vertex AI Gemini API và nếu trường hợp sử dụng của bạn yêu cầu các hạn chế dựa trên vị trí, chúng tôi sẽ hỗ trợ quy trình làm việc nâng cao cho các mẫu.

Bước 1: Tạo mẫu câu lệnh trên máy chủ

Đối với hầu hết các trường hợp sử dụng, bạn sẽ tạo và quản lý các mẫu câu lệnh trên máy chủ trong bảng điều khiển Firebase.

  1. Trong bảng điều khiển Firebase, hãy chuyển đến thẻ Firebase AI Logic Mẫu câu lệnh.

  2. Nhấp vào Tạo mẫu mới rồi chọn một mẫu cơ bản.

    • Các mẫu khởi đầu này cung cấp định dạng và cú pháp cho một số trường hợp sử dụng phổ biến. Tuy nhiên, bất kể bạn chọn lựa chọn nào, bạn đều có thể thay đổi hoàn toàn mẫu để đáp ứng nhu cầu của mình.

    • Hướng dẫn bắt đầu sử dụng này giả định rằng bạn đã chọn lựa chọn Input + System Instructions.

  3. Nhập giá trị nhận dạng của mẫu:

    • Tên mẫu: Đây là tên hiển thị của mẫu (ví dụ: My First Template). Tên này chỉ xuất hiện trong các giao diện Firebase, chẳng hạn như bảng điều khiển Firebase.

    • Mã nhận dạng mẫu: Đây phải là mã nhận dạng duy nhất cho mẫu trong dự án Firebase của bạn (ví dụ: my-first-template-v1-0-0). Bạn sẽ tham chiếu mã nhận dạng này trong yêu cầu từ ứng dụng của mình.

  4. Sửa đổi phần Cấu hình (frontmatter) của mẫu nếu cần.

    • Phần này phải có ít nhất một tên mẫu, chẳng hạn như:

      ---
model: 'gemini-2.5-flash'
---

    • Bạn cũng có thể chỉ định cấu hình của mô hình và mọi chế độ kiểm soát đầu vào và đầu ra, v.v. (không bắt buộc). Để biết thêm thông tin chi tiết và các lựa chọn, hãy xem bài viết Định dạng, cú pháp và ví dụ về mẫu.

  5. Sửa đổi phần Câu lệnh và (nếu có) hướng dẫn của hệ thống trong mẫu nếu cần.

    • Phần này phải có ít nhất một câu lệnh văn bản để gửi đến mô hình.

      Write a story about a magic backpack.

    • Bạn cũng có thể tạo câu lệnh phức tạp hơn, chẳng hạn như các lựa chọn sau. Để biết thêm thông tin chi tiết và các lựa chọn, hãy xem Định dạng, cú pháp và ví dụ về mẫu.

      • (Không bắt buộc và tuỳ trường hợp) Chỉ định hướng dẫn hệ thống bằng cú pháp {{role "system"}} và câu lệnh văn bản bằng cú pháp {{role "user"}}.

      • (Không bắt buộc) Chỉ định các biến đầu vào bằng cú pháp Handlebars (chẳng hạn như {{customerName}}). Bạn có thể cung cấp giá trị mặc định trong mẫu, nhưng giá trị của biến đầu vào này thường được truyền trong yêu cầu.

      {{role "system"}}
All output must be a clearly structured invoice document.
Use a tabular or clearly delineated list format for line items.

{{role "user"}}
Create an example customer invoice for a customer named {{customerName}}.

Bước 2: Kiểm thử mẫu trong bảng điều khiển Firebase

Bảng điều khiển Firebase cung cấp trải nghiệm kiểm thử cho mẫu của bạn. Trải nghiệm này cho phép bạn xem điều gì sẽ xảy ra khi mẫu của bạn được sử dụng – cả định dạng của yêu cầu cũng như đầu ra của một yêu cầu thực tế.

  1. Nhấp vào Lưu mẫu để bạn có thể kiểm tra mẫu.

    Bạn luôn có thể chỉnh sửa hoặc thậm chí xoá mẫu sau này. Giá trị duy nhất mà bạn không thể thay đổi sau này là mã nhận dạng mẫu.

  2. Nếu câu lệnh của bạn sử dụng các biến đầu vào, hãy thêm các giá trị kiểm thử vào trường Đầu vào kiểm thử. Trong ví dụ này:

      {
    "customerName": "Jane"
  }

  3. Nếu đã bật nhiều nhà cung cấp Gemini API trong dự án Firebase, bạn có thể chọn nhà cung cấp muốn dùng cho yêu cầu kiểm thử. Nếu lựa chọn này xuất hiện trong bảng điều khiển, hãy chọn Gemini Developer API hoặc Vertex AI Gemini API.

    Xin lưu ý rằng lựa chọn này chỉ áp dụng cho các yêu cầu được gửi thông qua trải nghiệm kiểm thử trên bảng điều khiển Firebase. Trong yêu cầu thực tế từ ứng dụng của bạn, hãy chỉ định nhà cung cấp Gemini API mà bạn đã chọn giống như cách bạn làm đối với mọi yêu cầu.

  4. Nhấp vào nút Tạo yêu cầu kiểm thử có định dạng.

    Xem xét Yêu cầu kiểm thử được định dạng trong kết quả ở bên phải màn hình và lặp lại trên bất kỳ trường nào trong mẫu của bạn.

  5. Khi bạn hài lòng với yêu cầu kiểm thử đã định dạng, hãy nhấp vào nút Chạy kiểm thử câu lệnh.

    Xem Phản hồi kiểm thử thu được ở bên phải màn hình và lặp lại trên bất kỳ trường nào trong mẫu của bạn.

  6. Nếu bạn đã sẵn sàng truy cập vào mẫu từ mã của ứng dụng, hãy khoá mẫu bằng cách nhấp vào biểu tượng khoá ở góc trên cùng bên phải của mẫu.

  7. Nhấp vào Đóng để thoát khỏi chế độ chỉnh sửa.

Bước 3: Truy cập vào mẫu từ mã 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.

Yêu cầu sử dụng mẫu câu lệnh của máy chủ trông tương tự như các yêu cầu khác, với những điều chỉnh sau:

  • Sử dụng templateGenerativeModel (hoặc templateImagenModel nếu cần).
  • Cung cấp mã mẫu.
  • Cung cấp giá trị của mọi đầu vào biến mà mẫu của bạn yêu cầu.

Xin lưu ý rằng sau khi tạo hoặc cập nhật mẫu, bạn có thể phải đợi vài phút để mẫu được truyền tải trên các máy chủ Firebase trước khi truy cập vào mẫu đó từ mã của bạn.

Swift

Tạo một thực thể templateGenerativeModel (hoặc templateImagenModel) để sử dụng một mẫu trong yêu cầu của bạn.


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
let model = FirebaseAI.firebaseAI(backend: .googleAI()).templateGenerativeModel()

let customerName = "Jane"

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "my-first-template-v1-0-0",
        // Provide the values for any input variables required by your template.
        inputs: [
            "customerName": customerName
        ]
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin

Tạo một thực thể templateGenerativeModel (hoặc templateImagenModel) để sử dụng một mẫu trong yêu cầu của bạn.


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.googleAI.templateGenerativeModel()

val customerName = "Jane"

val response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf(
        "customerName" to customerName
    )
)

val text = response.text
println(text)

Java

Tạo một thực thể templateGenerativeModel (hoặc templateImagenModel) để sử dụng một mẫu trong yêu cầu của bạn.


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

String customerName = "Jane";

Future response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf("customerName", customerName)
);
addCallback(response,
       new FutureCallback() {
           public void onSuccess(GenerateContentResponse result) {
             System.out.println(result.getText());
           }
           public void onFailure(Throwable t) {
             reportError(t);
           }
    }
executor);

Web

Tạo một thực thể templateGenerativeModel (hoặc templateImagenModel) để sử dụng một mẫu trong yêu cầu của bạn.


// ...

// Initialize the Gemini Developer API backend service
const ai = getAI(app, { backend: new GoogleAIBackend() });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const customerName = 'Jane';

const result = await model.generateContent(
  // Specify your template ID
  'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template
  {
    customerName: customerName,
  }
);

const response = response.result;
const text = response.text();

Dart

Trình bổ trợ Flutter sẽ sớm hỗ trợ các mẫu câu lệnh trên máy chủ!

Unity

Gói Unity sẽ sớm hỗ trợ các mẫu câu lệnh trên máy chủ!


Tiếp theo là gì?