I/O is live! Tune in for livestreamed keynotes and sessions May 20-21 starting at 10 AM PT. Watch now.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

기기 내 및 클라우드 호스팅 모델로 하이브리드 환경 빌드
컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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 설정

최신 Chrome 개발자 빌드를 다운로드합니다.

기기 내 추론은 Chrome v138 이상에서 사용할 수 있습니다.
다음 플래그를 설정하여 Chrome 인스턴스에 Prompt API를 사용 설정합니다.
- chrome://flags/#optimization-guide-on-device-model: 사용 설정됨으로 설정합니다.
- chrome://flags/#prompt-api-for-gemini-nano: 사용 설정됨으로 설정합니다.
Chrome 문서에서 localhost에서 API 사용에 대해 자세히 알아보세요. 원하는 경우 Chrome의 사전 미리보기 프로그램 (EPP)에 참여하여 의견을 제공할 수 있습니다.
다음 플래그를 설정하여 기기 내 멀티모달 모델을 사용 설정합니다.
- chrome://flags/#prompt-api-for-gemini-nano-multimodal-input: 사용 설정됨으로 설정합니다.
로컬에서 API를 확인합니다.
1. Chrome을 다시 시작합니다.
2. 개발자 도구 > 콘솔을 엽니다.
3. 다음을 실행합니다.
```
await LanguageModel.availability();
```
4. 출력이 available, downloading 또는 downloadable인지 확인합니다. .
5. 출력이 downloadable이면 await LanguageModel.create();를 실행하여 모델 다운로드를 시작할 수 있습니다. 그러지 않으면 기기 내 추론을 위한 첫 번째 요청이 백그라운드에서 모델 다운로드를 시작하며 이 작업은 몇 분 정도 걸릴 수 있습니다.

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

Firebase 콘솔에 로그인한 후 Firebase 프로젝트를 선택합니다.
아직 Firebase 프로젝트가 없나요?

Firebase 프로젝트가 없는 경우 프로젝트 만들기를 클릭한 다음 다음 옵션 중 하나를 사용합니다.
- 옵션 1: '프로젝트 만들기' 워크플로의 첫 번째 단계에서 새 프로젝트 이름을 입력하여 완전히 새로운 Firebase 프로젝트 (및 기본 Google Cloud 프로젝트 자동 생성)를 만듭니다.
- 옵션 2: '프로젝트 만들기' 워크플로의 첫 번째 단계에서 드롭다운 메뉴에서 Google Cloud 프로젝트 이름을 선택하여 기존 Google Cloud 프로젝트에 'Firebase를 추가'합니다.
메시지가 표시되면 Firebase AI Logic SDK를 사용하기 위해 Google Analytics를 설정하지 않아도 됩니다.
Firebase 콘솔에서 Firebase AI Logic 페이지로 이동합니다.
시작하기를 클릭하여 프로젝트에 필요한 API 및 리소스를 설정하는 데 도움이 되는 안내 워크플로를 시작합니다.
Firebase AI Logic SDK와 함께 사용할 'Gemini API' 제공업체를 선택합니다. 원하는 경우 나중에 언제든지 다른 API 제공업체를 설정하고 사용할 수 있습니다.
- Gemini Developer API — 결제 선택사항(무료 Spark 요금제에서 사용 가능)
  Console에서 필요한 API를 사용 설정하고 프로젝트에 Gemini API 키를 만듭니다.
  이 Gemini API 키를 앱의 코드베이스에 추가하지 마세요. 자세히 알아보기
  
  요금제를 업그레이드하려면 나중에 결제를 설정할 수 있습니다.
- Vertex AI Gemini API — 결제 필요(사용한 만큼 지불 Blaze 요금제 필요)
  콘솔을 사용하면 결제를 설정하고 프로젝트에서 필요한 API를 사용 설정할 수 있습니다.
Console의 워크플로에서 메시지가 표시되면 화면에 표시된 안내에 따라 앱을 등록하고 Firebase에 연결합니다.
이 가이드의 다음 단계로 진행하여 앱에 SDK를 추가합니다.

3단계: SDK 추가

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

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

하이브리드 기능은 다른 npm 태그로 출시되므로 설치 명령어에 포함해야 합니다.
```
npm install firebase@eap-ai-hybridinference
```

앱에서 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.0-flash"
  }
});

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

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

모델에 대한 각 요청에서 모델 구성을 함께 전송하여 모델의 응답 생성 방식을 제어할 수 있습니다. 클라우드 호스팅 모델과 기기 내 모델은 서로 다른 구성 옵션을 제공합니다.

구성은 인스턴스 전체 기간 동안 유지됩니다. 다른 구성을 사용하려면 해당 구성으로 새 GenerativeModel 인스턴스를 만듭니다.

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

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

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.0-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.0-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 사용 경험에 관한 의견 보내기