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


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

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

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

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

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

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

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

지원되는 모델 및 기능


높은 수준의 개요

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

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

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

  3. templateGenerativeModel을 사용하여 앱의 코드에서 템플릿에 액세스합니다.

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

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

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

아래 예시 템플릿은 Gemini 모델에 대한 예시 요청의 템플릿에서 가장 중요한 구성요소를 보여줍니다. 

---
model: 'gemini-3-flash-preview'
---

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

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

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

코드에서 템플릿 사용

Gemini API 제공업체를 클릭하여 이 페이지에서 제공업체별 콘텐츠 및 코드를 확인합니다.

아래 예시 클라이언트 코드는 코드에서 템플릿을 사용하는 방법을 보여줍니다.

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.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)

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

Dart 


// ...

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

Unity 


// ...

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


자세한 안내

이 섹션에서는 서버 프롬프트 템플릿을 만들고 테스트하고 사용하는 방법에 관한 자세한 안내를 제공합니다.

시작하기 전에

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      ---
model: 'gemini-3-flash-preview'
---

    • 모델의 구성과 입력 & 출력 제어 등을 선택적으로 지정할 수도 있습니다. 자세한 내용과 옵션은 템플릿 형식, 문법, 예시를 참고하세요.

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

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

Firebase 콘솔은 템플릿의 테스트 환경을 제공합니다. 이 환경을 사용하면 템플릿이 사용될 때 발생하는 상황(요청 형식과 실제 요청의 출력)을 확인할 수 있습니다.

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

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

  2. 프롬프트에서 입력 변수를 사용하는 경우 테스트 입력 필드에 테스트 값을 포함합니다. 이 예시의 경우:

      {
    "customerName": "Jane"
  }

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

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

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

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

  5. 형식이 지정된 테스트 요청이 만족스러우면 프롬프트 테스트 실행 버튼을 클릭합니다.

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

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

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

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

Gemini API 제공업체를 클릭하여 이 페이지에서 제공업체별 콘텐츠 및 코드를 확인합니다.

서버 프롬프트 템플릿을 사용하는 요청은 다음과 같은 조정이 적용된 다른 요청과 유사합니다.

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

템플릿을 만들거나 업데이트한 후 코드에서 템플릿에 액세스하기 전에 템플릿이 Firebase 서버 전체에 전파되는 데 몇 분 정도 걸릴 수 있습니다.

Swift

요청에서 템플릿을 사용하려면 templateGenerativeModel 인스턴스 (또는 templateImagenModel)를 만듭니다.


// ...

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

요청에서 템플릿을 사용하려면 templateGenerativeModel 인스턴스 (또는 templateImagenModel)를 만듭니다.


// ...

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

Java

요청에서 템플릿을 사용하려면 templateGenerativeModel 인스턴스 (또는 templateImagenModel)를 만듭니다.


// ...

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

요청에서 템플릿을 사용하려면 templateGenerativeModel 인스턴스 (또는 templateImagenModel)를 만듭니다.


// ...

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

Dart

Flutter 플러그인은 곧 서버 프롬프트 템플릿을 지원할 예정입니다.

요청에서 템플릿을 사용하려면 templateGenerativeModel 인스턴스 (또는 templateImagenModel)를 만듭니다.


// ...

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

Unity

요청에서 템플릿을 사용하려면 templateGenerativeModel 인스턴스 (또는 templateImagenModel)를 만듭니다.


// ...

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


다음 단계