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 lời nhắc và có thể là lược đồ và 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, hoặc bạn có thể chỉ định thông tin này ở phía máy chủ bằng cách sử dụng mẫu lời nhắc trê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, lược đồ và cấu hình ở phía máy chủ. Ứng dụng của bạn sẽ chỉ truyền khoá (mã 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ừ ứng dụng đến máy chủ.

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

• Bảo vệ khỏi việc hiển thị lời nhắc ở 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 lời nhắc trên máy chủ.

arrow_downward Chuyển đến phần tổng quan arrow_downward Chuyển đến hướng dẫn chi tiết

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

• Sử dụng mẫu lời nhắc trên máy chủ với bất kỳ mô hình Gemini và Imagen nào mà Firebase AI Logic hỗ trợ, ngoại trừ các mô hình Gemini Live.

• Xem danh sách các tính năng chưa được hỗ trợ.

Tổng quan

Sau đây là quy trình làm việc cơ bản để sử dụng mẫu lời nhắc 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 trải nghiệm kiểm thử trong bảng điều khiển Firebase.

3. Truy cập mẫu từ mã của ứng dụng bằng templateGenerativeModel.

Định dạng cơ bản của mẫu lời nhắc 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 phần đầu và nội dung của mẫu.

Mẫu lời nhắc 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 bài viết Định dạng, cú pháp và ví dụ về mẫu.

Mẫu ví dụ bên dưới cho thấy các thành phần quan trọng nhất của một mẫu cho yêu cầu mẫu gửi đến mô hình Gemini:

---
model: 'gemini-3.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, quy trình xác thực dữ liệu đầu vào hoặc lược đồ mà bạn muốn gửi trong yêu cầu (không bắt buộc). Phần này được viết dưới dạng cặp khoá-giá trị và thường được gọi là phần đầu YAML.

• Nội dung của mẫu chứa lời nhắc. Bạn cũng có thể đưa vào hướng dẫn hệ thống và giá trị đầu vào (không bắt buộc) (sử dụng cú pháp Handlebars).

Sử dụng mẫu trong mã

Mã ứng dụng mẫu bên dưới cho thấy cách sử dụng mẫu trong mã 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")

// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.ai(backend = GenerativeBackend.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)

// ...

// 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);

// ...

// 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 = result.response;
const text = response.text();

// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
var _model = FirebaseAI.googleAI().templateGenerativeModel()

var customerName = 'Jane';

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

var text = response?.text;
print(text);

// ...

// Initialize the Gemini Developer API backend service
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();

var customerName = "Jane";

try
{
   var response = await model.GenerateContentAsync(
      // Specify your template ID
      "my-first-template-v1-0-0",
      // Provide the values for any input variables required by your template
      new Dictionary<string, object> {
         { "customerName", customerName },
      }
   );
   Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

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 mẫu lời nhắc 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. 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 thực thể GenerativeModel.

• Đảm bảo bạn có các quyền cần thiết để tạo và quản lý mẫu lời nhắc 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.

  Xem các quyền cần thiết

  • firebasevertexai.googleapis.com/promptTemplates.create
  • firebasevertexai.googleapis.com/promptTemplates.get
  • firebasevertexai.googleapis.com/promptTemplates.update
  • firebasevertexai.googleapis.com/promptTemplates.delete
  • firebasevertexai.googleapis.com/promptTemplates.list

• 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í, thì 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 lời nhắc 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ý mẫu lời nhắc 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ẻ AI Services > AI Logic > Prompt templates.

2. Nhấp vào Create new template (Tạo mẫu mới), rồi chọn một mẫu khởi đầu.

   • 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 mẫu 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 này giả định rằng bạn đã chọn tuỳ chọn Input + System Instructions (Hướng dẫn đầu vào + hệ thống).

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

   • Template name (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.

   • Template ID (Mã 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 đến mã nhận dạng này trong yêu cầu từ ứng dụng của mình.

     • Bạn nên sử dụng hệ thống kiểm soát phiên bản cho mã mẫu.

     • Mã mẫu có thể có tối đa 63 ký tự và có thể chứa các chữ cái viết thường, số và dấu gạch ngang.

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

   • Phần này phải có ít nhất tên mô hình, như sau:

     ---
     model: 'gemini-3.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 dữ liệu đầu vào & đầu ra, v.v. Để biết thêm thông tin chi tiết và các tuỳ chọn, hãy xem Định dạng, cú pháp và ví dụ về mẫu.

5. Sửa đổi phần Prompt and (as applicable) system instructions (Lời nhắc và hướng dẫn hệ thống (nếu có)) của mẫu nếu cần.

   • Phần này phải có ít nhất lời nhắc bằng 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ác lời nhắc phức tạp hơn, chẳng hạn như các tuỳ chọn sau. Để biết thêm thông tin chi tiết và các tuỳ chọn, hãy xem bài viết Định dạng, cú pháp và ví dụ về mẫu.

     • (Không bắt buộc và nếu có) Chỉ định hướng dẫn hệ thống bằng cú pháp {{role "system"}} và lời nhắc bằng 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 Handlebars cú pháp (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ư kết quả của một yêu cầu thực.

1. Nhấp vào Save template (Lưu mẫu) để bạn có thể kiểm thử 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ã mẫu.

2. Nếu lời nhắc 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 Test input (Kiểm thử dữ liệu đầu vào). Đối với 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 sử dụng cho yêu cầu kiểm thử. Nếu tuỳ 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ử trong bảng điều khiển Firebase. Trong yêu cầu thực từ ứng dụng của bạn, bạn sẽ chỉ định nhà cung cấp Gemini API mà bạn chọn giống như đối với mọi yêu cầu.

4. Nhấp vào nút Create formatted test request (Tạo yêu cầu kiểm thử được định dạng).

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

   Mở rộng để xem ví dụ về yêu cầu kiểm thử được định dạng

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-3.5-flash",
     "contents": [{
       "parts": [{
         "text": "Create an example customer invoice for a customer named Jane"
       }],
       "role": "user"
     }],
     "systemInstruction": {
       "parts": [{
         "text": "All output must be a clearly structured invoice document.\nUse a tabular or clearly delineated list format for line items."
       }]
     }
   }
   

5. Khi bạn hài lòng với yêu cầu kiểm thử được định dạng, hãy nhấp vào nút Run prompt test (Chạy kiểm thử lời nhắc).

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

   Mở rộng để xem ví dụ về phản hồi kiểm thử

   {
     "candidates": [{
       "content": {
         "parts": [{
           "text": "```\n--------------------------------------------------------------------------------\n                         **INVOICE**\n--------------------------------------------------------------------------------\n\n**Creative Solutions Inc.**\n123 Business Lane, Suite 100\nAnytown, USA 12345\nPhone: (555) 123-4567\nEmail: info@creativesolutions.com\n\n**INVOICE NO:** INV-2023-001\n**INVOICE DATE:** October 26, 2023\n**DUE DATE:** November 25, 2023\n\n**BILL TO:**\nJane\n456 Client Street, Apt 2B\nAnytown, USA 12346\nPhone: (555) 987-6543\nEmail: jane@example.com\n\n--------------------------------------------------------------------------------\n**ITEM DESCRIPTION**               **QTY**   **UNIT PRICE**   **AMOUNT**\n--------------------------------------------------------------------------------\nWebsite Design Services            1         $800.00          $800.00\nContent Creation (Blog Posts)      4         $120.00          $480.00\nMonthly Hosting \u0026 Maintenance      1         $50.00           $50.00\nConsultation Fee                   2         $75.00           $150.00\n--------------------------------------------------------------------------------\n\n**SUMMARY:**\nSubtotal:                                                     $1,480.00\nSales Tax (8%):                                               $118.40\n--------------------------------------------------------------------------------\n**TOTAL DUE:**                                                **$1,598.40**\n--------------------------------------------------------------------------------\n\n**PAYMENT TERMS:**\nPayment is due within 30 days of the invoice date. Please make checks payable to Creative Solutions Inc. For electronic payments, please contact us for details.\n\nThank you for your business!\n```"
         }],
         "role": "model"
       },
       "finishReason": "STOP",
       "index": 0
     }],
     "usageMetadata": {
       "promptTokenCount": 34,
       "candidatesTokenCount": 418,
       "totalTokenCount": 890,
       "promptTokensDetails": [{
         "modality": "TEXT",
         "tokenCount": 34
       }],
       "thoughtsTokenCount": 438
     },
     "modelVersion": "gemini-3.5-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

6. Nếu bạn đã sẵn sàng truy cập 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 lock khoá ở góc trên cùng bên phải của mẫu.

7. Nhấp vào Close (Đóng) để thoát khỏi trải nghiệm chỉnh sửa.

Bước 3: Truy cập mẫu từ mã

Yêu cầu sử dụng mẫu lời nhắc trên 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 dữ liệu đầ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ể cần đợi vài phút để mẫu được truyền trên các máy chủ Firebase trước khi truy cập mẫu đó từ mã 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")

// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.ai(backend = GenerativeBackend.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)

// ...

// 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);

// ...

// 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 = result.response;
const text = response.text();

// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
var _model = FirebaseAI.googleAI().templateGenerativeModel()

var customerName = 'Jane';

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

var text = response?.text;
print(text);

// ...

// Initialize the Gemini Developer API backend service
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();

var customerName = "Jane";

try
{
   var response = await model.GenerateContentAsync(
      // Specify your template ID
      "my-first-template-v1-0-0",
      // Provide the values for any input variables required by your template
      new Dictionary<string, object> {
         { "customerName", customerName },
      }
   );
   Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

Bước tiếp theo là gì?

• Tìm hiểu về các phương pháp hay nhất và những điều cần cân nhắc khi sử dụng mẫu lời nhắc trên máy chủ.

• Tìm hiểu thông tin chi tiết về định dạng và cú pháp của mẫu , cùng với các ví dụ.

• Tìm hiểu về cách quản lý mẫu, bao gồm cả việc chỉnh sửa, khoá và quản lý phiên bản.

• Tìm hiểu về các quy trình làm việc nâng cao, chẳng hạn như làm việc với các mẫu theo phương thức lập trình bằng API REST của chúng tôi hoặc triển khai các mẫu của bạn đến các vị trí cụ thể.