온디바이스 및 클라우드 호스팅 모델로 웹 앱에서 하이브리드 환경 빌드

하이브리드 추론을 사용하여 AI 기반 웹 앱 및 기능을 빌드합니다. Firebase AI Logic 하이브리드 추론을 사용하면 기기 내 모델을 사용할 수 있는 경우 이를 사용하여 추론을 실행하고, 그렇지 않은 경우 클라우드 호스팅 모델로 원활하게 대체할 수 있습니다 (그 반대의 경우도 마찬가지).

이 페이지에서는 클라이언트 SDK를 사용하여 시작하는 방법을 설명합니다. 이 표준 설정을 완료한 후 추가 구성 옵션 및 기능 (예: 구조화된 출력)을 확인하세요.

기기 내 추론은 데스크톱의 Chrome에서 실행되는 웹 앱 에서 지원됩니다.

코드 예시로 이동

권장 사용 사례 및 지원되는 기능

권장 사용 사례:

• 추론에 기기 내 모델을 사용하면 다음과 같은 이점이 있습니다.

  • 더욱 강화된 개인 정보 보호
  • 로컬 컨텍스트
  • 무료 추론
  • 오프라인 기능

• 하이브리드 기능을 사용하면 다음과 같은 이점이 있습니다.

  • 기기 내 모델 사용 가능 여부 또는 인터넷 연결과 관계없이 잠재고객의 100% 에 도달

기기 내 추론을 위해 지원되는 기능:

기기 내 추론은 스트리밍 또는 비스트리밍 출력을 사용하여 단일 턴 텍스트 생성 (채팅 아님) 만 지원합니다. 다음과 같은 텍스트 생성 기능을 지원합니다.

• 텍스트 전용 입력에서 텍스트 생성

• 텍스트 및 이미지 입력, 특히 JPEG 및 PNG의 입력 이미지 유형에서 텍스트 생성

JSON 및 enum을 비롯한 구조화된 출력을 생성할 수도 있습니다.

시작하기 전에

다음 사항에 유의합니다.

• 기기 내 모델을 사용한 추론은 Chrome의 Prompt API를 사용합니다. 반면 클라우드 호스팅 모델을 사용한 추론은 선택한 Gemini API 제공업체 (Gemini Developer API 또는 Agent Platform Gemini API (formerly Vertex AI))를 사용합니다.

• 이 페이지에서는 localhost를 사용하여 개발을 시작하는 방법을 설명합니다 (Chrome 문서에서 localhost에서 API 사용에 대해 자세히 알아보세요).

  이 표준 설정을 완료한 후 추가 구성 옵션 및 기능 (예: 구조화된 출력)을 확인하세요.

localhost에서 시작하기

이 시작 단계에서는 전송하려는 지원되는 프롬프트 요청에 필요한 일반적인 설정을 설명합니다.

1단계: 기기 내 추론을 위한 Chrome 및 Prompt API 설정

1. 최신 버전의 Chrome을 사용 중인지 확인합니다. chrome://settings/help에서 업데이트합니다.
   기기 내 추론은 Chrome v139 이상에서 사용할 수 있습니다.

2. 다음 플래그를 사용 설정됨으로 설정하여 기기 내 멀티모달 모델을 사용 설정합니다.

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

3. Chrome을 다시 시작합니다.

4. (선택사항) 첫 번째 요청 전에 기기 내 모델을 다운로드합니다.

   Prompt API는 Chrome에 기본 제공되지만 기기 내 모델은 기본적으로 사용할 수 없습니다. 기기 내 추론을 위한 첫 번째 요청 전에 모델을 아직 다운로드하지 않은 경우 요청이 백그라운드에서 모델 다운로드를 자동으로 시작합니다.

   기기 내 모델을 다운로드하는 안내 보기

   1. 개발자 도구 > 콘솔 을 엽니다.

   2. 다음을 실행합니다.

      await LanguageModel.availability();
      

   3. 출력이 available, downloading 또는 downloadable인지 확인합니다.

   4. 출력이 downloadable이면 다음을 실행하여 모델 다운로드를 시작합니다.

      await LanguageModel.create();
      

   5. 다음 monitor 콜백을 사용하여 다운로드 진행률을 수신 대기하고 요청을 보내기 전에 모델이 available인지 확인할 수 있습니다.

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

2단계: Firebase 프로젝트 설정 및 앱을 Firebase에 연결

1. Firebase Console에 로그인한 후 Firebase 프로젝트를 선택합니다.

   아직 Firebase 프로젝트가 없으신가요?

   아직 Firebase 프로젝트가 없는 경우 버튼을 클릭하여 새 Firebase 프로젝트를 만든 후 다음 옵션 중 하나를 사용합니다.

   • 옵션 1: 워크플로의 첫 번째 단계에서 새 프로젝트 이름을 입력하여 완전히 새로운 Firebase 프로젝트 (및 기본 Google Cloud 프로젝트 자동 생성)를 만듭니다.

   • 옵션 2: 페이지 하단에 있는 Google Cloud 프로젝트에 Firebase 추가를 클릭하여 기존 Google Cloud 프로젝트에 'Firebase를 추가'합니다. 워크플로의 첫 번째 단계에서 기존 프로젝트의 프로젝트 이름 을 입력한 다음 표시되는 목록에서 프로젝트를 선택합니다.

   화면에 표시된 워크플로의 나머지 단계를 완료하여 Firebase 프로젝트를 만듭니다. 메시지가 표시되면 설정할 필요가 Google Analytics Firebase AI Logic SDK를 사용하기 위해 없습니다.

2. Firebase Console에서 AI 서비스 > AI Logic으로 이동합니다.

3. 시작하기 를 클릭하여 프로젝트에 필요한 API 와 리소스를 설정하는 데 도움이 되는 안내 워크플로를 실행합니다.

4. 메시지가 표시되면 화면에 표시된 안내에 따라 앱을 등록하고 Firebase 구성을 앱에 추가합니다.

5. "Gemini API 제공업체"를 선택하라는 메시지가 표시되면 Gemini Developer API를 선택하는 것이 좋습니다. 이 API를 사용하면 무료로 빠르게 시작할 수 있습니다.

   나중에 언제든지 설정할 수 있습니다Agent Platform Gemini API (formerly Vertex AI) (및 결제 요구사항).

6. 워크플로를 계속 진행하여 필요한 API와 연결된 서비스를 설정합니다. Firebase AI Logic

   2026년 7월 초부터 이 워크플로 단계에서는 앱에서 직접 액세스할 때 Gemini API를 보호하는 데 도움이 되는 중요한 서비스인 Firebase App Check용 AI Logic가 자동으로 적용됩니다. 시작하기의 일부로 (이 가이드의 뒷부분에 있는 단계 참고) App Check가 적용될 때 로컬 개발을 위해 App Check 디버그 제공자 를 구성해야 합니다.

   App Check

7. 이 가이드의 다음 단계로 이동하여 앱에 필요한 SDK를 추가합니다.

3단계: SDK 추가

Firebase 라이브러리는 생성형 모델과 상호작용하기 위한 API에 대한 액세스를 제공합니다. 이 라이브러리는 웹용 Firebase 자바스크립트 SDK의 일부로 포함되어 있습니다.

1. npm을 사용하여 웹용 Firebase JS SDK를 설치합니다.

   npm install firebase
   

2. 앱에서 Firebase를 초기화합니다.

   import { initializeApp } from "firebase/app";
   import { initializeAppCheck } from "firebase/app-check";
   
   // TODO(developer) Replace the following with your app's Firebase configuration
   // See: https://firebase.google.com/docs/web/learn-more#config-object
   const firebaseConfig = {
     // ...
   };
   
   // Initialize FirebaseApp
   const firebaseApp = initializeApp(firebaseConfig);
   

4단계: 로컬 개발을 위한 App Check 디버그 제공자 구성

2026년 7월 초부터 콘솔의 AI Logic 안내 설정 워크플로의 일부로 Firebase App Check이(가) Gemini API을(를) 보호하기 위해 자동으로 적용됩니다. 로컬 개발의 경우 App Check 디버그 제공자를 구성하여 앱 체크를 계속 적용App Check하면서 증명을 우회하도록 해야 합니다.

localhost에서 앱을 대화형으로 실행하는 동안 (예: 로컬 개발 중) 디버그 제공자를 사용하는 방법은 다음과 같습니다.

1. 디버그 빌드에서 self.FIREBASE_APPCHECK_DEBUG_TOKEN을 true로 설정하여 App Check를 초기화하기 전에 디버그 모드를 사용 설정합니다. 예를 들면 다음과 같습니다.

   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   initializeAppCheck(firebaseApp, { /* App Check options */ });
   

2. 로컬에서 웹 앱을 방문하여 브라우저의 개발자 도구를 엽니다. 디버그 콘솔에 디버그 토큰이 표시됩니다.

   AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
   You will need to safelist it in the Firebase console for it to work.
   

3. App Check에 디버그 토큰을 등록합니다.

   1. Firebase Console에서 보안 > 앱 체크 > 앱 탭으로 이동합니다.

   2. 앱을 찾고 더보기 메뉴 (more_vert)를 클릭한 후 디버그 토큰 관리를 선택합니다.

   3. 화면에 표시된 안내에 따라 디버그 토큰을 등록합니다.

새 디버그 토큰을 가져오는 방법을 비롯한 디버그 제공자에 관한 자세한 내용은 다음 공식 App Check 문서를 참고하세요.

5단계: 서비스 초기화 및 모델 인스턴스 만들기

모델에 프롬프트 요청을 보내기 전에 다음을 설정합니다.

1. 선택한 API 제공업체의 서비스를 초기화합니다.

2. GenerativeModel 인스턴스를 만듭니다. mode를 다음 중 하나로 설정해야 합니다.

   • PREFER_ON_DEVICE: 기기 내 모델을 사용할 수 있는 경우 이를 사용합니다. 그렇지 않은 경우 클라우드 호스팅 모델로 대체 합니다.

   • ONLY_ON_DEVICE: 기기 내 모델을 사용할 수 있는 경우 이를 사용합니다. 그렇지 않은 경우 예외를 발생 시킵니다.

   • PREFER_IN_CLOUD: 클라우드 호스팅 모델을 사용할 수 있는 경우 이를 사용합니다. 그렇지 않은 경우 기기 내 모델로 대체 합니다.

   • ONLY_IN_CLOUD: 클라우드 호스팅 모델을 사용할 수 있는 경우 이를 사용합니다. 그렇지 않은 경우 예외를 발생 시킵니다.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

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

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

6단계: 기기 내 모델 초기화

최종 사용자 페이지 상호작용 (예: 버튼 클릭) 후 또는 시 에 모델에 프롬프트 요청을 보내기 전에 initializeDeviceModel()을 호출해야 합니다. Chrome 문서에서 사용자 활성화 요구사항 에 대해 자세히 알아보세요.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

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

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

7단계: 모델에 프롬프트 요청 보내기

이 섹션에서는 다음과 같은 다양한 유형의 출력을 생성하기 위해 다양한 유형의 입력을 보내는 방법을 보여줍니다.

• 텍스트 전용 입력에서 텍스트 생성
• 텍스트 및 이미지 (멀티모달) 입력에서 텍스트 생성

구조화된 출력 (예: JSON 또는 enum)을 생성하려면 다음 '텍스트 생성' 예시 중 하나를 사용하고 추가로 제공된 스키마에 따라 응답하도록 모델을 구성합니다.

텍스트 전용 입력에서 텍스트 생성

generateContent() 를 사용하여 텍스트가 포함된 프롬프트에서 텍스트를 생성할 수 있습니다.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Firebase AI Logic은 generateContentStream (대신 generateContent)를 사용하여 텍스트 응답 스트리밍도 지원합니다.

텍스트 및 이미지 (멀티모달) 입력에서 텍스트 생성

generateContent() 를 사용하여 텍스트 및 이미지 파일이 포함된 프롬프트에서 텍스트를 생성할 수 있습니다. 각 입력 파일의 mimeType과 파일 자체를 제공합니다.

기기 내 추론을 위해 지원되는 입력 이미지 유형은 PNG 및 JPEG입니다.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Firebase AI Logic은 generateContentStream (대신 generateContent)를 사용하여 텍스트 응답 스트리밍도 지원합니다.

또 뭘 할 수 있니?

하이브리드 환경에 다양한 추가 구성 옵션과 기능을 사용할 수 있습니다.

• 추론 모드 설정

• 기본 클라우드 호스팅 대체 모델 재정의

• 모델 구성을 사용하여 응답 제어 (예: 온도)

• 구조화된 출력 생성 (예: JSON)

기기 내 추론에 아직 사용할 수 없는 기능

웹 SDK의 모든 기능을 기기 내 추론에 사용할 수 있는 것은 아닙니다. 다음 기능은 기기 내 추론에서 아직 지원되지 않지만 (일반적으로 클라우드 기반 추론에 사용할 수 있음)

• JPEG 및 PNG 이외의 이미지 파일 입력 유형에서 텍스트 생성

  • 클라우드 호스팅 모델로 대체할 수 있지만 ONLY_ON_DEVICE 모드에서는 오류가 발생합니다.

• 오디오, 동영상, 문서 (예: PDF) 입력에서 텍스트 생성

  • 클라우드 호스팅 모델로 대체할 수 있지만 ONLY_ON_DEVICE 모드에서는 오류가 발생합니다.

• Gemini 또는 Imagen 모델을 사용하여 이미지 생성

  • 클라우드 호스팅 모델로 대체할 수 있지만 ONLY_ON_DEVICE 모드에서는 오류가 발생합니다.

• 멀티모달 요청에서 URL을 사용하여 파일 제공 파일을 기기 내 모델에 인라인 데이터로 제공해야 합니다.

• 멀티턴 채팅

  • 클라우드 호스팅 모델로 대체할 수 있지만 ONLY_ON_DEVICE 모드에서는 오류가 발생합니다.

• Gemini Live API을 사용한 양방향 스트리밍

• 모델이 응답을 생성하는 데 도움이 되는 도구 제공 (예: 함수 호출, 코드 실행, URL 컨텍스트, Google Search를 사용한 그라운딩, Google Maps를 사용한 그라운딩)

• 토큰 집계

  • 항상 오류가 발생합니다. 집계는 클라우드 호스팅 모델과 기기 내 모델 간에 다르므로 직관적인 대체가 없습니다.

• 기기 내 추론을 위한 Firebase Console의 AI 모니터링

  • 클라우드 호스팅 모델을 사용한 추론은 웹용 Firebase AI Logic 클라이언트 SDK를 사용한 다른 추론과 마찬가지로 모니터링할 수 있습니다.

의견 제공 Firebase AI Logic 사용 경험에 관한