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


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

이 버전에서는 데스크톱용 Chrome의 기기 내 추론을 지원하는 웹용 Firebase AI Logic 클라이언트 SDK를 사용하여 하이브리드 추론을 사용할 수 있습니다.

코드 예시로 이동

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

권장 사용 사례:

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

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

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

    • 기기 내 모델 사용 가능 여부와 관계없이 잠재고객 100% 에게 도달

기기 내 추론에 지원되는 기능:

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

시작하기

이 가이드에서는 웹용 Firebase AI Logic SDK를 사용하여 하이브리드 추론을 실행하는 방법을 설명합니다.

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

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

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

    기기 내 추론은 Chrome v138 이상에서 사용할 수 있습니다.

  2. 다음 플래그를 설정하여 Chrome 인스턴스에 Prompt 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 프로젝트를 선택합니다.

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

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

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

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

    • Vertex AI Gemini API — 결제 필요(사용한 만큼 지불 Blaze 요금제 필요)
      콘솔을 사용하면 결제를 설정하고 프로젝트에서 필요한 API를 사용 설정할 수 있습니다.

  5. Console의 워크플로에서 메시지가 표시되면 화면에 표시된 안내에 따라 앱을 등록하고 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 제공업체를 클릭하여 이 페이지에서 제공업체별 콘텐츠와 코드를 확인합니다.

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의 Prompt 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
    }
  }
});
enum 출력

위와 동일하지만 하이브리드 추론을 위해 enum 출력에 관한 문서를 조정합니다.

// ...

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

const model = getGenerativeModel(ai, {

// ...

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

// ...

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

실험용 출시이므로 웹 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에서는 이 기능을 지원하지 않습니다.

  • 함수 호출

    • 출시 예정

  • 토큰 집계

    • 항상 오류를 발생시킵니다. 클라우드 호스팅 모델과 기기 내 모델의 개수는 다르므로 직관적인 대체 방법은 없습니다.

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

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


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