서버 프롬프트 템플릿 시작하기

모델에 대한 각 요청에서 프롬프트를 보내고 선택적으로 스키마와 구성을 보내 모델의 응답을 제어합니다. Firebase AI Logic를 사용하는 경우 클라이언트 코드에서 이 모든 정보를 직접 전송하거나 서버 프롬프트 템플릿을 사용하여 서버 측에서 이 정보를 지정할 수 있습니다.

서버 프롬프트 템플릿을 사용하면 프롬프트, 스키마, 구성을 서버 측에 저장하고 앱은 클라이언트에서 서버로 특정 템플릿을 참조하는 키 (템플릿 ID)와 해당 템플릿에 필요한 입력만 전달합니다.

서버 프롬프트 템플릿을 사용하면 프롬프트와 구성을 서버 측에 저장하고 앱의 코드베이스에 키 (템플릿 ID)만 제공합니다. 이 접근 방식의 이점은 다음과 같습니다.

• 프롬프트가 클라이언트 측에 노출되지 않도록 보호

• 새 앱 버전을 출시하지 않고도 프롬프트와 구성 업데이트

이 가이드에서는 서버 프롬프트 템플릿을 시작하는 방법을 설명합니다.

arrow_downward 높은 수준의 개요로 이동 arrow_downward 자세한 안내로 이동

지원되는 모델 및 기능

• Firebase AI Logic에서 지원하는 Gemini 및 Imagen 모델(Gemini Live 모델 제외)과 함께 서버 프롬프트 템플릿을 사용합니다.

• 아직 지원되지 않는 기능 목록을 검토합니다.

높은 수준의 개요

서버 프롬프트 템플릿을 사용하는 기본 워크플로는 다음과 같습니다.

1. Firebase 콘솔의 안내 UI를 사용하여 템플릿을 만듭니다.

2. Firebase 콘솔의 테스트 환경을 사용하여 실제 요청에서 템플릿을 테스트합니다.

3. 앱에서 템플릿에 액세스합니다.

서버 프롬프트 템플릿의 기본 형식

Firebase AI Logic의 경우 Firebase 콘솔은 템플릿의 콘텐츠를 지정할 수 있는 안내 UI를 제공합니다.

서버 프롬프트 템플릿은 Dotprompt 기반 문법과 형식을 사용합니다. 자세한 내용은 템플릿 형식, 구문, 예시를 참고하세요.

다음은 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}}.

• 세 개의 대시로 구분된 상단 섹션에는 모델 이름과 요청에 보낼 모델 구성, 입력 유효성 검사, 스키마가 선택적으로 포함됩니다. 키-값 쌍으로 작성되며 일반적으로 YAML 프런트매터라고 합니다.

• 템플릿의 본문에는 프롬프트가 포함됩니다. 선택적으로 시스템 안내와 입력 값 (Handlebars 문법 사용)을 포함할 수도 있습니다.

코드에서 템플릿 사용

코드에서 템플릿을 사용하는 방법은 다음과 같습니다.

// ...

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

자세한 안내

이 섹션에서는 서버 프롬프트 템플릿을 만들고 테스트하고 사용하는 방법을 자세히 설명합니다.

시작하기 전에

• 아직 진행하지 않았다면 Firebase 프로젝트를 설정하고, 앱을 Firebase에 연결하고, SDK를 추가하고, 선택한 Gemini API 제공업체의 백엔드 서비스를 초기화하고, GenerativeModel 인스턴스를 만드는 방법을 설명하는 시작 가이드를 완료합니다.

• 서버 프롬프트 템플릿을 만들고 관리하는 데 필요한 권한이 있는지 확인합니다. 기본적으로 이러한 모든 권한은 소유자 역할에 포함되어 있습니다.

  필수 권한 보기

  • 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

• Vertex AI Gemini API를 사용하고 사용 사례에 위치 기반 제한이 필요한 경우 템플릿의 고급 워크플로가 지원됩니다.

1단계: 서버 프롬프트 템플릿 만들기

대부분의 사용 사례에서 Firebase 콘솔에서 서버 프롬프트 템플릿을 만들고 관리합니다.

1. Firebase 콘솔에서 Firebase AI Logic 프롬프트 템플릿 탭으로 이동합니다.

2. 새 템플릿 만들기를 클릭하고 시작 템플릿 옵션을 선택합니다.

   • 이러한 시작 템플릿은 몇 가지 일반적인 사용 사례의 형식과 구문을 제공합니다. 어떤 옵션을 선택하든 필요에 맞게 템플릿을 완전히 변경할 수 있습니다.

   • 이 시작 가이드에서는 Input + System Instructions 옵션을 선택했다고 가정합니다.

3. 템플릿의 식별자를 입력합니다.

   • 템플릿 이름: 템플릿의 표시 이름입니다 (예: My First Template). Firebase 콘솔과 같은 Firebase 인터페이스 내에서만 볼 수 있습니다.

   • 템플릿 ID: Firebase 프로젝트 내에 있는 템플릿의 고유 ID여야 합니다 (예: my-first-template-v1-0-0). 앱의 요청에서 이 ID를 참조합니다.

     • 템플릿 ID에 버전 관리 시스템을 사용하는 것이 좋습니다.

     • 템플릿 ID는 최대 63자(영문 기준)이며 소문자, 숫자, 하이픈을 포함할 수 있습니다.

4. 필요에 따라 템플릿의 구성 (프런트매터) 섹션을 수정합니다.

   • 이 섹션에는 최소한 다음과 같은 모델 이름이 포함되어야 합니다.

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

   • 원하는 경우 모델의 구성과 입력 및 출력 제어 등을 지정할 수도 있습니다. 자세한 내용과 옵션은 템플릿 형식, 구문, 예시를 참고하세요.

5. 필요에 따라 템플릿의 프롬프트 및 (해당하는 경우) 시스템 요청 사항 섹션을 수정합니다.

   • 이 섹션에는 모델에 전송할 텍스트 프롬프트가 최소한 포함되어야 합니다.

     Write a story about a magic backpack.
     

   • 다음 옵션과 같이 더 복잡한 프롬프트를 만들 수도 있습니다. 자세한 내용과 옵션은 템플릿 형식, 구문, 예시를 참고하세요.

     • (선택사항 및 해당되는 경우) {{role "system"}} 구문을 사용하여 시스템 지침을 지정하고 {{role "user"}} 구문을 사용하여 텍스트 프롬프트를 지정합니다.

     • (선택사항) Handlebars 구문 (예: {{customerName}})을 사용하여 입력 변수를 지정합니다. 템플릿에서 기본값을 제공할 수 있지만 이 입력 변수의 값은 일반적으로 요청에 전달됩니다.

     {{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}}.
     

2단계: Firebase 콘솔에서 템플릿 테스트하기

Firebase 콘솔은 템플릿의 테스트 환경을 제공합니다. 이 환경을 사용하면 템플릿이 사용될 때 어떤 일이 일어나는지 확인할 수 있습니다. 요청 형식과 실제 요청의 출력을 모두 확인할 수 있습니다.

1. 템플릿 저장을 클릭하여 템플릿을 테스트할 수 있도록 합니다.

   나중에 언제든지 템플릿을 수정하거나 삭제할 수 있습니다. 나중에 변경할 수 없는 값은 템플릿 ID뿐입니다.

2. 프롬프트에서 입력 변수를 사용하는 경우 테스트 입력 필드에 테스트 값을 포함합니다. 이 예에서는 다음을 충족해야 합니다.

     {
       "customerName": "Jane"
     }
   

3. Firebase 프로젝트에서 여러 Gemini API 제공업체를 사용 설정한 경우 테스트 요청에 사용할 제공업체를 선택할 수 있습니다. 이 옵션이 콘솔에 표시되면 Gemini Developer API 또는 Vertex AI Gemini API를 선택합니다.

   이 선택사항은 Firebase 콘솔 테스트 환경을 통해 제출된 요청에만 적용됩니다. 앱의 실제 요청에서 선택한 Gemini API 제공자를 다른 요청과 마찬가지로 지정합니다.

4. 형식이 지정된 테스트 요청 만들기 버튼을 클릭합니다.

   화면 오른쪽에 표시된 형식이 지정된 테스트 요청을 검토하고 템플릿의 필드를 반복합니다.

   펼쳐서 형식이 지정된 테스트 요청 예시 보기

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-2.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. 형식이 지정된 테스트 요청이 만족스러우면 프롬프트 테스트 실행 버튼을 클릭합니다.

   화면 오른쪽에 표시되는 테스트 응답을 검토하고 템플릿의 필드를 반복합니다.

   펼쳐서 테스트 응답 예시 보기

   {
     "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-2.5-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

6. 앱의 코드에서 템플릿에 액세스할 준비가 되었다면 템플릿 오른쪽 상단에 있는 lock 잠금 아이콘을 클릭하여 템플릿을 잠급니다.

7. 닫기를 클릭하여 편집 환경을 종료합니다.

3단계: 코드에서 템플릿에 액세스

서버 프롬프트 템플릿을 사용하는 요청은 다음과 같은 조정 사항을 제외하고 다른 요청과 비슷합니다.

• templateGenerativeModel (또는 필요한 경우 templateImagenModel)을 사용합니다.
• 템플릿 ID를 제공합니다.
• 템플릿에 필요한 변수 입력 값을 제공합니다.

템플릿을 만들거나 업데이트한 후 코드에서 액세스하려면 템플릿이 Firebase 서버에 전파될 때까지 몇 분 정도 기다려야 할 수 있습니다.

// ...

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

다음 단계

• 서버 프롬프트 템플릿 사용에 관한 권장사항 및 고려사항을 알아보세요.

• 템플릿 형식 및 구문과 예시에 대해 자세히 알아보세요.

• 수정, 잠금, 버전 관리를 비롯한 템플릿 관리