이 튜토리얼에서는 Google AI Swift SDK를 사용하여 Swift 앱에서 직접 Gemini API에 액세스하는 방법을 보여줍니다. Swift 앱에서 Gemini 모델에 액세스하기 위해 REST API 또는 서버 측 코드 (예: Python)로 직접 작업하지 않으려는 경우 이 SDK를 사용할 수 있습니다.
이 튜토리얼에서는 다음 작업을 수행하는 방법을 알아봅니다.
- API 키를 포함하여 프로젝트 설정
- 텍스트 전용 입력에서 텍스트 생성
- 텍스트 및 이미지 입력에서 텍스트 생성 (멀티모달)
- 멀티턴 대화 만들기 (채팅)
- 스트리밍을 통한 빠른 상호작용
또한 이 가이드에는 고급 사용 사례 (예: 토큰 계산)와 콘텐츠 생성 제어 옵션에 대한 섹션이 포함되어 있습니다.
기본 요건
이 가이드에서는 Xcode를 사용하여 Swift 앱을 개발하는 데 익숙하다고 가정합니다.
이 튜토리얼을 완료하려면 개발 환경과 Swift 앱이 다음 요구사항을 충족하는지 확인하세요.
- Xcode 15.0 이상
- Swift 앱이 iOS 15 이상 또는 macOS 12 이상을 타겟팅해야 합니다.
프로젝트 설정
Gemini API를 호출하기 전에 Xcode 프로젝트를 설정해야 합니다. 여기에는 API 키 설정, Xcode 프로젝트에 SDK 패키지 추가, 모델 초기화가 포함됩니다.
API 키 설정
Gemini API를 사용하려면 API 키가 필요합니다. 아직 키가 없으면 Google AI Studio에서 키를 만듭니다
API 키 보호
API 키를 버전 제어 시스템에 체크인하지 않는 것이 좋습니다. 한 가지 대체 옵션은 GenerativeAI-Info.plist 파일에 저장한 후 .plist 파일에서 API 키를 읽는 것입니다. 이 .plist 파일을 앱의 루트 폴더에 저장하고 버전 제어에서 제외해야 합니다.
샘플 앱을 검토하여 API 키를 .plist 파일에 저장하는 방법을 알아볼 수도 있습니다.
이 튜토리얼의 모든 스니펫은 사용자가 이 주문형 리소스 .plist 파일에서 API 키에 액세스한다고 가정합니다.
프로젝트에 SDK 패키지 추가
자체 Swift 앱에서 Gemini API를 사용하려면 GoogleGenerativeAI 패키지를 앱에 추가합니다.
Xcode의 프로젝트 탐색기에서 프로젝트를 마우스 오른쪽 버튼으로 클릭합니다.
컨텍스트 메뉴에서 Add Packages를 선택합니다.
Add Packages 대화상자에서 검색창에 패키지 URL을 붙여넣습니다.
https://github.com/google/generative-ai-swift패키지 추가를 클릭합니다. 이제 Xcode가
GoogleGenerativeAI패키지를 프로젝트에 추가합니다.
생성 모델 초기화
API를 호출하려면 먼저 생성 모델을 초기화해야 합니다.
GoogleGenerativeAI모듈을 가져옵니다.import GoogleGenerativeAI생성 모델을 초기화합니다.
// Access your API key from your on-demand resource .plist file // (see "Set up your API key" above) let model = GenerativeModel(name: "MODEL_NAME", apiKey: APIKey.default)
모델을 지정할 때는 다음 사항에 유의하세요.
사용 사례에 맞는 모델을 사용하세요 (예:
gemini-pro-vision은 멀티모달 입력용). 이 가이드 내에서 각 구현의 안내에는 사용 사례별 권장 모델이 나열되어 있습니다.
일반적인 사용 사례 구현
이제 프로젝트가 설정되었으므로 Gemini API를 사용하여 다양한 사용 사례를 구현할 수 있습니다.
텍스트 전용 입력에서 텍스트 생성
프롬프트 입력에 텍스트만 포함된 경우 gemini-pro 모델을 generateContent 메서드와 함께 사용하여 텍스트 출력을 생성합니다.
import GoogleGenerativeAI
// For text-only input, use the gemini-pro model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro", apiKey: APIKey.default)
let prompt = "Write a story about a magic backpack."
let response = try await model.generateContent(prompt)
if let text = response.text {
print(text)
}
텍스트 및 이미지 입력에서 텍스트 생성 (멀티모달)
Gemini는 멀티모달 모델 (gemini-pro-vision)을 제공하므로 텍스트와 이미지를 모두 입력할 수 있습니다. 프롬프트의 이미지 요구사항을 검토하세요.
프롬프트 입력에 텍스트와 이미지가 모두 포함되면 gemini-pro-vision 모델을 generateContent 메서드와 함께 사용하여 텍스트 출력을 생성합니다.
import GoogleGenerativeAI
// For text-and-image input (multimodal), use the gemini-pro-vision model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro-vision", apiKey: APIKey.default)
let image1 = UIImage(...)
let image2 = UIImage(...)
let prompt = "What's different between these pictures?"
let response = try await model.generateContent(prompt, image1, image2)
if let text = response.text {
print(text)
}
멀티턴 대화 만들기 (채팅)
Gemini를 사용하면 여러 차례에 걸쳐 자유 형식으로 대화를 만들 수 있습니다. SDK는 대화 상태를 관리하여 프로세스를 간소화하므로 generateContent와 달리 대화 기록을 직접 저장할 필요가 없습니다.
멀티턴 대화 (예: 채팅)를 빌드하려면 gemini-pro 모델을 사용하고 startChat()를 호출하여 채팅을 초기화합니다. 그런 다음 sendMessage()를 사용하여 새 사용자 메시지를 보내면 메시지와 응답이 채팅 기록에 추가됩니다.
대화의 콘텐츠와 연결된 role에는 두 가지 가능한 옵션이 있습니다.
user: 프롬프트를 제공하는 역할입니다. 이 값은sendMessage호출의 기본값입니다.model: 응답을 제공하는 역할입니다. 이 역할은 기존history로startChat()를 호출할 때 사용할 수 있습니다.
import GoogleGenerativeAI
let config = GenerationConfig(
maxOutputTokens: 100
)
// For text-only input, use the gemini-pro model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
name: "gemini-pro",
apiKey: APIKey.default,
generationConfig: config
)
let history = [
ModelContent(role: "user", parts: "Hello, I have 2 dogs in my house."),
ModelContent(role: "model", parts: "Great to meet you. What would you like to know?"),
]
// Initialize the chat
let chat = model.startChat(history: history)
let response = try await chat.sendMessage("How many paws are in my house?")
if let text = response.text {
print(text)
}
스트리밍으로 더 빠른 상호작용
기본적으로 모델은 전체 생성 프로세스를 완료한 후 응답을 반환합니다. 전체 결과를 기다리지 않고 스트리밍을 사용하여 부분 결과를 처리하면 상호작용을 더 빠르게 달성할 수 있습니다.
다음 예는 텍스트 및 이미지 입력 프롬프트에서 텍스트를 생성하는 generateContentStream 메서드로 스트리밍을 구현하는 방법을 보여줍니다.
import GoogleGenerativeAI
// For text-and-image input (multimodal), use the gemini-pro-vision model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro-vision", apiKey: APIKey.default)
let image1 = UIImage(named: "")!
let image2 = UIImage(named: "")!
let prompt = "What's different between these pictures?"
var fullResponse = ""
let contentStream = model.generateContentStream(prompt, image1, image2)
for try await chunk in contentStream {
if let text = chunk.text {
print(text)
fullResponse += text
}
}
print(fullResponse)
텍스트 전용 입력 및 채팅 사용 사례에도 비슷한 접근 방식을 사용할 수 있습니다.
// Use streaming with text-only input
let contentStream = model.generateContentStream(prompt)
// Use streaming with multi-turn conversations (like chat)
let responseStream = chat.sendMessageStream(message)
고급 사용 사례 구현
이 튜토리얼의 이전 섹션에 설명된 일반적인 사용 사례를 참고하면 Gemini API 사용에 익숙해질 수 있습니다. 이 섹션에서는 더 고급화된 것으로 간주될 수 있는 몇 가지 사용 사례를 설명합니다.
토큰 개수
긴 프롬프트를 사용할 때는 모델에 콘텐츠를 보내기 전에 토큰을 세는 것이 유용할 수 있습니다. 다음 예는 다양한 사용 사례에 countTokens()를 사용하는 방법을 보여줍니다.
// For text-only input
let response = try await model.countTokens("Why is the sky blue?")
print(response.totalTokens)
// For text-and-image input (multi-modal)
let response = try await model.countTokens(prompt, image1, image2)
print(response.totalTokens)
// For multi-turn conversations (like chat)
let chat = model.startChat()
let history = chat.history
let message = ModelContent(role: "user", "Why is the sky blue?")
let contents = history + [message]
let response = try await model.countTokens(contents)
print(response.totalTokens)
콘텐츠 생성을 제어하는 옵션
모델 매개변수를 구성하고 안전 설정을 사용하여 콘텐츠 생성을 제어할 수 있습니다.
모델 매개변수 구성
모델에 전송하는 모든 프롬프트에는 모델의 응답 생성 방식을 제어하는 매개변수 값이 포함됩니다. 모델은 서로 다른 매개변수 값에 대해 서로 다른 결과를 생성할 수 있습니다. 모델 매개변수에 대해 자세히 알아보세요. 구성은 모델 인스턴스의 수명 동안 유지됩니다.
let config = GenerationConfig(
temperature: 0.9,
topP: 0.1,
topK: 16,
maxOutputTokens: 200,
stopSequences: ["red"]
)
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
name: "MODEL_NAME",
apiKey: APIKey.default,
generationConfig: config
)
안전 설정 사용
안전 설정을 사용하여 유해한 것으로 간주될 수 있는 응답을 받을 가능성을 조정할 수 있습니다. 기본적으로 안전 설정은 모든 측정기준에서 보통 또는 높은 가능성이 있는 콘텐츠를 차단합니다. 안전 설정에 관해 자세히 알아보세요.
하나의 안전 설정을 지정하는 방법은 다음과 같습니다.
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
name: "MODEL_NAME",
apiKey: APIKey.default,
safetySettings: [
SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
]
)
다음과 같이 두 개 이상의 안전 설정을 지정할 수도 있습니다.
let harassmentSafety = SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
let hateSpeechSafety = SafetySetting(harmCategory: .hateSpeech, threshold: .blockMediumAndAbove)
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
name: "MODEL_NAME",
apiKey: APIKey.default,
safetySettings: [harassmentSafety, hateSpeechSafety]
)
다음 단계
프롬프트 설계는 언어 모델에서 원하는 응답을 유도하는 프롬프트를 만드는 프로세스입니다. 체계적인 메시지 작성은 언어 모델의 정확하고 고품질 응답을 보장하는 필수 부분입니다. 프롬프트 작성 권장사항에 대해 알아보기
Gemini는 입력 유형 및 복잡성, 채팅 또는 기타 대화상자 언어 작업의 구현, 크기 제약 조건과 같은 다양한 사용 사례의 요구사항을 충족하기 위해 여러 모델 변형을 제공합니다. 사용 가능한 Gemini 모델을 알아보세요.
Gemini는 비율 한도 증가를 요청하는 옵션을 제공합니다. Gemini Pro 모델의 비율 한도는 분당 요청 수 (RPM) 60개입니다.