기기 내 및 클라우드 호스팅 모델로 하이브리드 환경 빌드

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

이번 출시를 통해 데스크톱의 Chrome용 온디바이스 추론을 지원하는 웹용 Firebase AI Logic 클라이언트 SDK를 사용하여 하이브리드 추론을 사용할 수 있습니다.

코드 예시로 이동

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

권장 사용 사례:

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

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

• 하이브리드 기능 혜택 사용:

  • 온디바이스 모델 사용 가능 여부와 관계없이 잠재고객의 100% 에 도달

온디바이스 추론을 위해 지원되는 기능:

• 단일 턴 콘텐츠 생성, 스트리밍 및 비스트리밍
• 텍스트 전용 입력에서 텍스트 생성
• 텍스트 및 이미지 입력에서 텍스트 생성(특히 JPEG 및 PNG 입력 이미지 유형)
• JSON 및 enum을 포함한 구조화된 출력 생성

시작하기

이 가이드에서는 Firebase AI Logic 웹용 SDK를 사용하여 하이브리드 추론을 시작하는 방법을 보여줍니다.

온디바이스 모델을 사용한 추론은 Chrome의 프롬프트 API를 사용하는 반면, 클라우드 호스팅 모델을 사용한 추론은 선택한 Gemini API 제공업체 (Gemini Developer API 또는 Vertex AI Gemini API)를 사용합니다.

1단계: 온디바이스 추론을 위해 Chrome 및 Prompt API 설정

1. 최신 Chrome 베타 빌드를 다운로드합니다.

   온디바이스 추론은 Chrome v138 이상에서 사용할 수 있습니다.

2. 다음 플래그를 설정하여 Chrome 인스턴스에 프롬프트 API를 사용 설정합니다.

   • chrome://flags/#optimization-guide-on-device-model: 사용으로 설정합니다.
   • chrome://flags/#prompt-api-for-gemini-nano: 사용으로 설정합니다.

   Chrome 문서에서 localhost에서 API 사용에 대해 자세히 알아보세요. 원하는 경우 Chrome의 사전 체험 프로그램 (EPP)에 참여하여 의견을 제공하세요.

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

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input: 사용으로 설정합니다.

4. 로컬에서 API를 확인합니다.

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

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

   3. 다음을 실행합니다.

      await LanguageModel.availability();
      

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

   5. 출력이 downloadable이면 await LanguageModel.create();를 실행하여 모델 다운로드를 시작할 수 있습니다. 그렇지 않으면 기기 내 추론을 위한 첫 번째 요청이 백그라운드에서 모델 다운로드를 시작하며 몇 분 정도 걸릴 수 있습니다.

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

1. Firebase 콘솔에 로그인한 다음 Firebase 프로젝트를 선택합니다.

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

   Firebase 프로젝트가 없으면 프로젝트 만들기를 클릭하고 다음 옵션 중 하나를 사용합니다.

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

   • 옵션 2: '프로젝트 만들기' 워크플로의 첫 번째 단계에서 드롭다운 메뉴에서 Google Cloud 프로젝트 이름을 선택하여 기존 Google Cloud 프로젝트에 'Firebase를 추가'합니다.

   메시지가 표시되면 Firebase AI Logic SDK를 사용하기 위해 Google Analytics를 설정하지 않아도 됩니다.

2. Firebase 콘솔에서 Firebase AI Logic 페이지로 이동합니다.

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

4. Firebase AI Logic SDK와 함께 사용할 'Gemini API' 제공업체를 선택합니다. 원하는 경우 나중에 언제든지 다른 API 제공업체를 설정하고 사용할 수 있습니다.

   • Gemini Developer API - 결제 선택사항 (무료 Spark 요금제에서 사용 가능하며 원하는 경우 나중에 업그레이드할 수 있음)
     콘솔에서 필수 API를 사용 설정하고 프로젝트에 Gemini API 키를 만듭니다.
     이 Gemini API 키를 앱의 코드베이스에 추가하지 마세요. 자세히 알아보기

   • Vertex AI Gemini API - 결제 필요 (사용량에 따라 지불하는 Blaze 요금제가 필요함)
     콘솔에서 결제를 설정하고 프로젝트에서 필요한 API를 사용 설정할 수 있습니다.

5. 콘솔의 워크플로에서 메시지가 표시되면 화면에 표시된 안내에 따라 앱을 등록하고 Firebase에 연결합니다.

6. 이 가이드의 다음 단계로 계속 진행하여 앱에 SDK를 추가합니다.

3단계: SDK 추가

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

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

   하이브리드 기능은 다른 npm 태그로 출시되므로 설치 명령어에 포함해야 합니다.

   npm install firebase@eap-ai-hybridinference
   

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

   import { initializeApp } from "firebase/app";
   
   // 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단계: 서비스 초기화 및 모델 인스턴스 생성

Gemini 모델에 프롬프트를 보내기 전에 선택한 API 제공업체의 서비스를 초기화하고 GenerativeModel 인스턴스를 만듭니다.

mode을 다음 중 하나로 설정합니다.

• prefer_on_device: 온디바이스 모델을 사용할 수 있는 경우 온디바이스 모델을 사용하도록 SDK를 구성하거나 클라우드 호스팅 모델로 대체합니다.

• only_on_device: 온디바이스 모델을 사용하거나 예외를 발생하도록 SDK를 구성합니다.

• only_in_cloud: 온디바이스 모델을 사용하지 않도록 SDK를 구성합니다.

prefer_on_device 또는 only_in_cloud를 사용하면 기본적으로 클라우드 호스팅 모델은 gemini-2.0-flash-lite이지만 기본값을 재정의할 수 있습니다.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } 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 to use on-device model when possible
const model = getGenerativeModel(ai, { mode: "prefer_on_device" });

모델에 프롬프트 요청 보내기

이 섹션에서는 다음과 같이 다양한 유형의 출력을 생성하기 위해 다양한 유형의 입력을 전송하는 방법을 보여주는 예시를 제공합니다.

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

구조화된 출력 (예: 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();

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

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

또 뭘 할 수 있어?

위의 예시 외에도 대체 추론 모드를 사용하고, 기본 대체 모델을 재정의하고, 모델 구성을 사용하여 응답을 제어할 수 있습니다.

대체 추론 모드 사용

위의 예에서는 prefer_on_device 모드를 사용하여 기기 내 모델이 있는 경우 이를 사용하고 클라우드 호스팅 모델로 대체하도록 SDK를 구성했습니다. SDK는 only_on_device 및 only_in_cloud의 두 가지 대체 추론 모드를 제공합니다.

• SDK가 온디바이스 모델만 사용할 수 있도록 only_on_device 모드를 사용합니다. 이 구성에서는 온디바이스 모델을 사용할 수 없는 경우 API에서 오류가 발생합니다.

  const model = getGenerativeModel(ai, { mode: "only_on_device" });
  

• SDK가 클라우드 호스팅 모델만 사용할 수 있도록 only_in_cloud 모드를 사용합니다.

  const model = getGenerativeModel(ai, { mode: "only_in_cloud" });
  

기본 대체 모델 재정의

prefer_on_device 모드를 사용하면 기기 내 모델을 사용할 수 없는 경우 SDK가 클라우드 호스팅 모델을 사용하도록 대체됩니다. 기본 대체 클라우드 호스팅 모델은 gemini-2.0-flash-lite입니다. 이 클라우드 호스팅 모델은 only_in_cloud 모드를 사용할 때도 기본값입니다.

inCloudParams 구성 옵션을 사용하여 대체 기본 클라우드 호스팅 모델을 지정할 수 있습니다.

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
  }
});

지원되는 모든 Gemini 모델의 모델 이름을 찾습니다.

모델 구성을 사용하여 대답 제어하기

모델에 대한 각 요청에서 모델이 응답을 생성하는 방식을 제어하는 모델 구성을 함께 보낼 수 있습니다. 클라우드 호스팅 모델과 온디바이스 모델은 서로 다른 구성 옵션을 제공합니다.

구성은 인스턴스의 수명 동안 유지됩니다. 다른 구성을 사용하려면 해당 구성으로 새 GenerativeModel 인스턴스를 만드세요.

클라우드 호스팅 모델의 구성 설정

inCloudParams 옵션을 사용하여 클라우드 호스팅 Gemini 모델을 구성합니다. 사용 가능한 매개변수에 대해 알아봅니다.

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
    temperature: 0.8,
    topK: 10
  }
});

온디바이스 모델의 구성 설정

온디바이스 모델을 사용한 추론은 Chrome의 프롬프트 API를 사용합니다.

onDeviceParams 옵션을 사용하여 기기 내 모델을 구성합니다. 사용 가능한 매개변수에 대해 알아봅니다.

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

구조화된 출력의 구성 설정

클라우드 호스팅 모델과 온디바이스 모델을 모두 사용하는 추론에 구조화된 출력 (예: JSON 및 enum) 생성이 지원됩니다.

하이브리드 추론의 경우 inCloudParams 및 onDeviceParams를 모두 사용하여 구조화된 출력으로 응답하도록 모델을 구성합니다. 다른 모드의 경우 적용 가능한 구성만 사용하세요.

• inCloudParams의 경우: 적절한 responseMimeType (이 예에서는 application/json)와 모델이 사용할 responseSchema을 지정합니다.

• onDeviceParams의 경우: 모델에서 사용할 responseConstraint을 지정합니다.

JSON 출력

다음 예에서는 하이브리드 추론을 위해 일반 JSON 출력 예를 적용합니다.

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

열거형 출력

위와 같지만 하이브리드 추론을 위해 열거형 출력에 관한 문서를 적용합니다.

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...

아직 온디바이스 추론에 사용할 수 없는 기능

실험적 출시이므로 Web SDK의 모든 기능을 온디바이스 추론에 사용할 수 있는 것은 아닙니다. 다음 기능은 아직 기기 내 추론에서 지원되지 않습니다 (하지만 일반적으로 클라우드 기반 추론에서는 사용할 수 있습니다).

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

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

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

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

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

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

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

• 멀티턴 채팅

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

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

  • 이 기능은 Firebase AI Logic 클라이언트 SDK for Web에서 클라우드 호스팅 모델의 경우에도 지원되지 않습니다.

• 함수 호출

  • 출시 예정

• 토큰 집계

  • 항상 오류를 발생시킵니다. 개수는 클라우드 호스팅 모델과 온디바이스 모델 간에 다르므로 직관적인 대체가 없습니다.

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

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

Firebase AI Logic 사용 경험에 관한 의견 보내기