이 튜토리얼에서는 Google AI JavaScript SDK를 사용하여 웹 앱에서 직접 Gemini API에 액세스하는 방법을 보여줍니다. 웹 앱에서 Gemini 모델에 액세스하기 위해 REST API 또는 서버 측 코드 (예: Node.js)로 직접 작업하지 않으려면 이 SDK를 사용할 수 있습니다.
이 튜토리얼에서는 다음 작업을 수행하는 방법을 알아봅니다.
- API 키를 포함하여 프로젝트 설정
- 텍스트 전용 입력에서 텍스트 생성
- 텍스트 및 이미지 입력에서 텍스트 생성 (멀티모달)
- 멀티턴 대화 빌드 (채팅)
- 스트리밍을 사용하여 상호작용 속도 향상
또한 이 가이드에는 토큰 계산과 같은 고급 사용 사례와 콘텐츠 생성 제어 옵션에 대한 섹션이 포함되어 있습니다.
기본 요건
이 가이드에서는 사용자가 JavaScript를 사용한 웹 앱 개발에 익숙하다고 가정합니다. 이 가이드는 프레임워크와 독립적입니다.
이 가이드를 완료하려면 개발 환경이 다음 요구사항을 충족하는지 확인하세요.
- (선택사항) Node.js
- 최신 웹브라우저
프로젝트 설정
Gemini API를 호출하기 전에 프로젝트를 설정해야 합니다. 여기에는 API 키 가져오기, SDK 가져오기, 모델 초기화가 포함됩니다.
API 키 설정
Gemini API를 사용하려면 API 키가 필요합니다. 아직 키가 없다면 Google AI Studio에서 키를 만듭니다
API 키 보호
버전 제어 시스템에 API 키를 체크인하지 않는 것이 좋습니다. 대신 모델을 초기화하기 직전에 API 키를 앱에 전달해야 합니다.
이 가이드의 모든 스니펫은 API 키에 전역 상수로 액세스한다고 가정합니다.
SDK 가져오기 및 생성 모델 초기화
API 호출을 하려면 먼저 SDK를 가져오고 생성 모델을 초기화해야 합니다.
<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 = "...";
// Reminder: This should only be for local testing
// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);
// ...
// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});
// ...
</script>
</body>
</html>
모델을 지정할 때는 다음 사항에 유의하세요.
사용 사례에 맞는 모델을 사용합니다 (예:
gemini-1.5-flash
는 멀티모달 입력에 사용됨). 이 가이드 내 각 구현 안내에는 각 사용 사례에 대한 권장 모델이 나와 있습니다.
일반적인 사용 사례 구현
이제 프로젝트가 설정되었으므로 Gemini API를 사용하여 다양한 사용 사례를 구현하는 방법을 알아볼 수 있습니다.
텍스트 전용 입력에서 텍스트 생성
프롬프트 입력에 텍스트만 포함된 경우 다음과 같이 Gemini 1.5 모델 또는 generateContent
가 포함된 Gemini 1.0 Pro 모델을 사용하여 텍스트 출력을 생성합니다.
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() {
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});
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 1.5 모델)을 제공합니다. 프롬프트의 이미지 요구사항을 검토하세요.
프롬프트 입력에 텍스트와 이미지가 모두 포함된 경우 Gemini 1.5 모델과 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() {
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
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 1.5 모델 또는 Gemini 1.0 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() {
// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});
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 사용에 익숙해질 수 있습니다. 이 섹션에서는 고급 사용 사례로 간주될 수 있는 몇 가지 사용 사례를 설명합니다.
함수 호출
함수 호출을 통해 생성 모델에서 구조화된 데이터 출력을 더 쉽게 가져올 수 있습니다. 그런 다음 이러한 출력을 사용하여 다른 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,
};
// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash", generationConfig });
안전 설정 사용
안전 설정을 사용하여 유해한 것으로 간주될 수 있는 응답을 받을 가능성을 조정할 수 있습니다. 기본적으로 안전 설정은 모든 측정기준에서 중간 또는 높은 수준의 안전하지 않은 콘텐츠를 차단합니다. 안전 설정에 관해 자세히 알아보세요.
하나의 안전 설정을 지정하는 방법은 다음과 같습니다.
import { HarmBlockThreshold, HarmCategory } from "@google/generative-ai";
// ...
const safetySettings = [
{
category: HarmCategory.HARM_CATEGORY_HARASSMENT,
threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
},
];
// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash", 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 모델에 대해 알아보세요.