웹 앱에서 Gemini API 시작하기

이 튜토리얼에서는 Google AI JavaScript SDK를 사용하여 웹 앱에서 직접 Gemini API에 액세스하는 방법을 보여줍니다. 웹 앱에서 Gemini 모델에 액세스하기 위해 REST API 또는 서버 측 코드 (예: Node.js)를 직접 사용하지 않으려는 경우 이 SDK를 사용할 수 있습니다.

이 튜토리얼에서는 다음 작업을 수행하는 방법을 알아봅니다.

또한 이 가이드에는 고급 사용 사례 (예: 토큰 계산)와 콘텐츠 생성 제어 옵션에 대한 섹션이 포함되어 있습니다.

기본 요건

이 가이드에서는 개발자가 JavaScript를 사용하여 웹 앱을 개발하는 데 익숙하다고 가정합니다. 이 가이드는 프레임워크와 무관합니다.

이 가이드를 완료하려면 개발 환경이 다음 요구사항을 충족하는지 확인하세요.

  • (선택사항) Node.js
  • 최신 웹브라우저

프로젝트 설정

Gemini API를 호출하기 전에 API 키를 가져오고 모델을 초기화하는 프로젝트를 설정해야 합니다.

API 키 설정

Gemini API를 사용하려면 API 키가 필요합니다. 아직 키가 없으면 Google AI Studio에서 키를 만듭니다

API 키 가져오기

API 키 보호

API 키를 버전 제어 시스템에 체크인하지 않는 것이 좋습니다. 대신 모델을 초기화하기 직전에 API 키를 앱에 전달해야 합니다.

이 튜토리얼의 모든 스니펫은 API 키에 전역 상수로 액세스한다고 가정합니다.

생성 모델 초기화

API를 호출하려면 먼저 생성 모델을 가져오고 초기화해야 합니다.

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

      const model = genAI.getGenerativeModel({ model: "MODEL_NAME"});

      // ...
    </script>
  </body>
</html>

모델을 지정할 때는 다음 사항에 유의하세요.

  • 사용 사례에 맞는 모델을 사용하세요 (예: gemini-pro-vision은 멀티모달 입력용). 이 가이드 내에서 각 구현의 안내에는 사용 사례별 권장 모델이 나열되어 있습니다.

일반적인 사용 사례 구현

이제 프로젝트가 설정되었으므로 Gemini API를 사용하여 다양한 사용 사례를 구현할 수 있습니다.

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

프롬프트 입력에 텍스트만 포함된 경우 gemini-pro 모델을 generateContent 메서드와 함께 사용하여 텍스트 출력을 생성합니다.

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

async function run() {
  // For text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

  const prompt = "Write a story about a magic backpack."

  const result = await model.generateContent(prompt);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

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

Gemini는 멀티모달 모델 (gemini-pro-vision)을 제공하므로 텍스트와 이미지를 모두 입력할 수 있습니다. 입력 이미지 요구사항을 검토하세요.

프롬프트 입력에 텍스트와 이미지가 모두 포함되면 gemini-pro-vision 모델을 generateContent 메서드와 함께 사용하여 텍스트 출력을 생성합니다.

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

// Converts a File object to a GoogleGenerativeAI.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() {
  // For text-and-images input (multimodal), use the gemini-pro-vision model
  const model = genAI.getGenerativeModel({ model: "gemini-pro-vision" });

  const prompt = "What's different between these pictures?";

  const fileInputEl = document.querySelector("input[type=file]");
  const imageParts = await Promise.all(
    [...fileInputEl.files].map(fileToGenerativePart)
  );

  const result = await model.generateContent([prompt, ...imageParts]);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

멀티턴 대화 만들기 (채팅)

Gemini를 사용하면 여러 차례에 걸쳐 자유 형식으로 대화를 만들 수 있습니다. SDK는 대화 상태를 관리하여 프로세스를 간소화하므로 generateContent와 달리 대화 기록을 직접 저장할 필요가 없습니다.

멀티턴 대화 (예: 채팅)를 빌드하려면 gemini-pro 모델을 사용하고 startChat()를 호출하여 채팅을 초기화합니다. 그런 다음 sendMessage()를 사용하여 새 사용자 메시지를 보내면 메시지와 응답이 채팅 기록에 추가됩니다.

대화의 콘텐츠와 연결된 role에는 두 가지 가능한 옵션이 있습니다.

  • user: 프롬프트를 제공하는 역할입니다. 이 값은 sendMessage 호출의 기본값이며 다른 역할이 전달되면 함수에서 예외가 발생합니다.

  • model: 응답을 제공하는 역할입니다. 이 역할은 기존 history로 startChat()를 호출할 때 사용할 수 있습니다.

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

async function run() {
  // For text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

  const chat = model.startChat({
    history: [
      {
        role: "user",
        parts: [{ text: "Hello, I have 2 dogs in my house." }],
      },
      {
        role: "model",
        parts: [{ text: "Great to meet you. What would you like to know?" }],
      },
    ],
    generationConfig: {
      maxOutputTokens: 100,
    },
  });

  const msg = "How many paws are in my house?";

  const result = await chat.sendMessage(msg);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

스트리밍으로 더 빠른 상호작용

기본적으로 모델은 전체 생성 프로세스를 완료한 후 응답을 반환합니다. 전체 결과를 기다리지 않고 스트리밍을 사용하여 부분 결과를 처리하면 상호작용을 더 빠르게 달성할 수 있습니다.

다음 예는 텍스트 및 이미지 입력 프롬프트에서 텍스트를 생성하는 generateContentStream 메서드로 스트리밍을 구현하는 방법을 보여줍니다.

// ...

const result = await model.generateContentStream([prompt, ...imageParts]);

let text = '';
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
  text += chunkText;
}

// ...

텍스트 전용 입력 및 채팅 사용 사례에도 비슷한 접근 방식을 사용할 수 있습니다.

// Use streaming with text-only input
const result = await model.generateContentStream(prompt);

chat를 인스턴스화하는 방법은 위의 채팅 예를 참고하세요.

// Use streaming with multi-turn conversations (like chat)
const result = await chat.sendMessageStream(msg);

고급 사용 사례 구현

이 튜토리얼의 이전 섹션에 설명된 일반적인 사용 사례를 참고하면 Gemini API 사용에 익숙해질 수 있습니다. 이 섹션에서는 더 고급화된 것으로 간주될 수 있는 몇 가지 사용 사례를 설명합니다.

토큰 개수

긴 프롬프트를 사용할 때는 모델에 콘텐츠를 보내기 전에 토큰을 세는 것이 유용할 수 있습니다. 다음 예는 다양한 사용 사례에 countTokens()를 사용하는 방법을 보여줍니다.

// For text-only input
const { totalTokens } = await model.countTokens(prompt);

// For text-and-image input (multimodal)
const { totalTokens } = await model.countTokens([prompt, ...imageParts]);

// For multi-turn conversations (like chat)
const history = await chat.getHistory();
const msgContent = { role: "user", parts: [{ text: msg }] };
const contents = [...history, msgContent];
const { totalTokens } = await model.countTokens({ contents });

콘텐츠 생성을 제어하는 옵션

모델 매개변수를 구성하고 안전 설정을 사용하여 콘텐츠 생성을 제어할 수 있습니다.

모델 매개변수 구성

모델에 전송하는 모든 프롬프트에는 모델의 응답 생성 방식을 제어하는 매개변수 값이 포함됩니다. 모델은 서로 다른 매개변수 값에 대해 서로 다른 결과를 생성할 수 있습니다. 모델 매개변수에 대해 자세히 알아보세요. 구성은 모델 인스턴스의 수명 동안 유지됩니다.

const generationConfig = {
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
};

const model = genAI.getGenerativeModel({ model: "MODEL_NAME",  generationConfig });

안전 설정 사용

안전 설정을 사용하여 유해한 것으로 간주될 수 있는 응답을 받을 가능성을 조정할 수 있습니다. 기본적으로 안전 설정은 모든 측정기준에서 보통 또는 높은 가능성이 있는 콘텐츠를 차단합니다. 안전 설정에 관해 자세히 알아보세요.

하나의 안전 설정을 지정하는 방법은 다음과 같습니다.

import { HarmBlockThreshold, HarmCategory } from "@google/generative-ai";

// ...

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
];

const model = genAI.getGenerativeModel({ model: "MODEL_NAME", safetySettings });

다음과 같이 두 개 이상의 안전 설정을 지정할 수도 있습니다.

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
  {
    category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
    threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
  },
];

다음 단계

  • 프롬프트 설계는 언어 모델에서 원하는 응답을 유도하는 프롬프트를 만드는 프로세스입니다. 체계적인 메시지 작성은 언어 모델의 정확하고 고품질 응답을 보장하는 필수 부분입니다. 프롬프트 작성 권장사항에 대해 알아보기

  • Gemini는 입력 유형 및 복잡성, 채팅 또는 기타 대화상자 언어 작업의 구현, 크기 제약 조건과 같은 다양한 사용 사례의 요구사항을 충족하기 위해 여러 모델 변형을 제공합니다. 사용 가능한 Gemini 모델을 알아보세요.

  • Gemini는 비율 한도 증가를 요청하는 옵션을 제공합니다. Gemini Pro 모델의 비율 한도는 분당 요청 수 (RPM) 60개입니다.