튜토리얼: Gemini API 시작하기

Python Node.js 웹 REST Go Dart (Flutter) Android Swift

이 튜토리얼에서는 Google AI Go SDK를 사용하여 Go 애플리케이션용 Gemini API에 액세스하는 방법을 보여줍니다.

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

• API 키를 포함하여 프로젝트 설정
• 텍스트 전용 입력에서 텍스트 생성
• 텍스트 및 이미지 입력에서 텍스트 생성 (멀티모달)
• 멀티턴 대화 빌드 (채팅)
• 스트리밍을 사용하여 상호작용 속도 향상

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

기본 요건

이 가이드에서는 Go를 사용한 애플리케이션 빌드에 익숙하다고 가정합니다.

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

• Go 1.20 이상

프로젝트 설정

Gemini API를 호출하기 전에 프로젝트를 설정해야 합니다. 여기에는 API 키 설정, SDK 패키지 설치, 모델 초기화가 포함됩니다.

API 키 설정

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

API 키 가져오기

API 키 보호

버전 제어 시스템에 API 키를 체크인하지 않는 것이 좋습니다. 대신 API 키에 보안 비밀 저장소를 사용해야 합니다.

이 가이드의 모든 스니펫은 API 키를 환경 변수로 액세스한다고 가정합니다.

SDK 패키지 설치

자체 애플리케이션에서 Gemini API를 사용하려면 모듈 디렉터리에서 Go SDK 패키지를 get해야 합니다.

go get github.com/google/generative-ai-go

생성 모델 초기화

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

import "github.com/google/generative-ai-go/genai"
import "google.golang.org/api/option"

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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

• 사용 사례에 맞는 모델을 사용합니다 (예: gemini-1.5-flash는 멀티모달 입력에 사용됨). 이 가이드 내 각 구현 안내에는 각 사용 사례에 대한 권장 모델이 나와 있습니다.

일반적인 사용 사례 구현

이제 프로젝트가 설정되었으므로 Gemini API를 사용하여 다양한 사용 사례를 구현하는 방법을 알아볼 수 있습니다.

• 텍스트 전용 입력에서 텍스트 생성
• 텍스트 및 이미지 입력에서 텍스트 생성 (멀티모달)
• 멀티턴 대화 빌드 (채팅)
• 스트리밍을 사용하여 상호작용 속도 향상

고급 사용 사례 섹션에서 Gemini API 및 임베딩에 관한 정보를 확인할 수 있습니다.

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

프롬프트 입력에 텍스트만 포함된 경우 다음과 같이 Gemini 1.5 모델 또는 generateContent가 포함된 Gemini 1.0 Pro 모델을 사용하여 텍스트 출력을 생성합니다.

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")
resp, err := model.GenerateContent(ctx, genai.Text("Write a story about a magic backpack."))
if err != nil {
  log.Fatal(err)
}

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

Gemini는 멀티모달 입력을 처리할 수 있는 다양한 모델(Gemini 1.5 모델)을 제공하므로 텍스트와 이미지를 모두 입력할 수 있습니다. 프롬프트의 이미지 요구사항을 검토하세요.

프롬프트 입력에 텍스트와 이미지가 모두 포함된 경우 generateContent 메서드와 함께 Gemini 1.5 모델을 사용하여 텍스트 출력을 생성합니다.

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")

imgData1, err := os.ReadFile(pathToImage1)
if err != nil {
  log.Fatal(err)
}

imgData2, err := os.ReadFile(pathToImage1)
if err != nil {
  log.Fatal(err)
}

prompt := []genai.Part{
  genai.ImageData("jpeg", imgData1),
  genai.ImageData("jpeg", imgData2),
  genai.Text("What's different between these two pictures?"),
}
resp, err := model.GenerateContent(ctx, prompt...)

if err != nil {
  log.Fatal(err)
}

멀티턴 대화 빌드 (채팅)

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

채팅과 같은 멀티턴 대화를 빌드하려면 Gemini 1.5 모델 또는 Gemini 1.0 Pro 모델을 사용하고 startChat()를 호출하여 채팅을 초기화합니다. 그런 다음 sendMessage()를 사용하여 새 사용자 메시지를 전송합니다. 이 메시지도 채팅 기록에 메시지와 응답이 추가됩니다.

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

• user: 프롬프트를 제공하는 역할입니다. 이 값은 SendMessage 호출의 기본값입니다.

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

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
model := client.GenerativeModel("gemini-1.5-flash")
// Initialize the chat
cs := model.StartChat()
cs.History = []*genai.Content{
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Hello, I have 2 dogs in my house."),
    },
    Role: "user",
  },
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Great to meet you. What would you like to know?"),
    },
    Role: "model",
  },
}

resp, err := cs.SendMessage(ctx, genai.Text("How many paws are in my house?"))
if err != nil {
  log.Fatal(err)
}

스트리밍을 사용하여 상호작용 속도 향상

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

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

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")

imageBytes, err := os.ReadFile(pathToImage)

img := genai.ImageData("jpeg", imageBytes)
prompt := genai.Text("Tell me a story about this animal")
iter := model.GenerateContentStream(ctx, img, prompt)

for {
  resp, err := iter.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }

  // ... print resp
}

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

prompt := genai.Text("Tell me a story about a lumberjack and his giant ox")
iter := model.GenerateContentStream(ctx, prompt)

prompt := genai.Text("And how do you feel about that?")
iter := cs.SendMessageStream(ctx, prompt)

고급 사용 사례 구현

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

임베딩 사용

임베딩은 정보를 배열에서 부동 소수점 숫자 목록으로 표현하는 데 사용되는 기법입니다. Gemini를 사용하면 텍스트 (단어, 문장, 텍스트 블록)를 벡터화된 형식으로 표현할 수 있으므로 임베딩을 더 쉽게 비교하고 대조할 수 있습니다. 예를 들어 주제나 감정이 비슷한 두 텍스트는 임베딩이 유사해야 하며, 이는 코사인 유사성과 같은 수학적 비교 기법을 통해 식별할 수 있습니다.

embedding-001 모델을 EmbedContent 메서드 (또는 BatchEmbedContent 메서드)와 함께 사용하여 임베딩을 생성합니다. 다음 예는 단일 문자열의 임베딩을 생성합니다.

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()
// For embeddings, use the embedding-001 model
em := client.EmbeddingModel("embedding-001")
res, err := em.EmbedContent(ctx, genai.Text("The quick brown fox jumps over the lazy dog."))

if err != nil {
  panic(err)
}
fmt.Println(res.Embedding.Values)

함수 호출

함수 호출을 통해 생성 모델에서 구조화된 데이터 출력을 더 쉽게 가져올 수 있습니다. 그런 다음 이러한 출력을 사용하여 다른 API를 호출하고 관련 응답 데이터를 모델에 반환할 수 있습니다. 즉, 함수 호출은 생성 모델을 외부 시스템에 연결하여 생성된 콘텐츠에 가장 정확한 최신 정보가 포함되도록 하는 데 도움이 됩니다. 자세한 내용은 함수 호출 튜토리얼을 참조하세요.

토큰 수 계산

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

// For text-only input
text := "Parrots can be green and live a long time."
resp, err := model.CountTokens(ctx, genai.Text(text))
if err != nil {
  log.Fatal(err)
}
fmt.Println(resp.TotalTokens)

// For text-and-image input (multimodal)
text := "Parrots can be green and live a long time."
imageBytes, err := os.ReadFile(pathToImage)
if err != nil {
  log.Fatal(err)
}

resp, err := model.CountTokens(
    ctx,
    genai.Text(text),
    genai.ImageData("png", imageBytes))
  if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.TotalTokens)

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

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

모델 매개변수 구성

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

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

// Configure model parameters by invoking Set* methods on the model.
model.SetTemperature(0.9)
model.SetTopK(1)

// ...

안전 설정 사용

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

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

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

model.SafetySettings = []*genai.SafetySetting{
  {
    Category:  genai.HarmCategoryHarassment,
    Threshold: genai.HarmBlockOnlyHigh,
  },
}

// ...

둘 이상의 안전 설정을 지정할 수도 있습니다.

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

model.SafetySettings = []*genai.SafetySetting{
  {
    Category:  genai.HarmCategoryHarassment,
    Threshold: genai.HarmBlockOnlyHigh,
  },
  {
    Category:  genai.HarmCategoryHateSpeech,
    Threshold: genai.HarmBlockMediumAndAbove,
  },
}

// ...

다음 단계

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

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