Neste tutorial, demonstramos como acessar a API Gemini diretamente do app Swift usando o SDK do Google AI para Swift. Você pode usar esse SDK se não quiser trabalhar diretamente com APIs REST ou código do lado do servidor (como Python) para acessar modelos do Genmini no seu app Swift.
Neste tutorial, você aprenderá a fazer o seguinte:
- Configurar seu projeto, incluindo a chave de API
- Gerar texto com base apenas em uma entrada de texto
- Gerar texto com base na entrada de texto e imagem (multimodal)
- Criar conversas com vários turnos (chat)
- Usar o streaming para interações mais rápidas
Além disso, este tutorial contém seções sobre casos de uso avançados (como contagem de tokens), bem como opções para controlar a geração de conteúdo.
Pré-requisitos
Neste tutorial, presumimos que você esteja familiarizado com o uso do Xcode para desenvolver apps Swift.
Para concluir este tutorial, verifique se o ambiente de desenvolvimento e o app Swift atendem aos seguintes requisitos:
- Xcode 15.0 ou mais recente
- O app Swift precisa ser direcionado ao iOS 15 ou mais recente ou ao macOS 12 ou mais recente.
Configurar seu projeto
Antes de chamar a API Gemini, você precisa configurar seu projeto do Xcode, o que inclui a configuração da chave de API, a adição do pacote do SDK ao projeto do Xcode e a inicialização do modelo.
Configurar sua chave de API
Para usar a API Gemini, você precisa de uma chave de API. Se você ainda não tiver uma, crie uma chave no Google AI Studio.
Proteger sua chave de API
É altamente recomendável não verificar uma chave de API no sistema de controle de versões. Uma alternativa é armazená-la em um arquivo GenerativeAI-Info.plist
e, em seguida, ler a chave de API do arquivo .plist
. Coloque esse arquivo .plist
na pasta raiz do app e
o exclua do controle de versões.
Consulte também o app de exemplo para saber como armazenar sua chave de API em um arquivo .plist
.
Em todos os snippets deste tutorial, presumimos que você esteja acessando sua chave de API a partir deste arquivo .plist
de recurso sob demanda.
Adicionar o pacote do SDK ao projeto
Para usar a API Gemini no seu próprio app Swift, adicione o pacote GoogleGenerativeAI
ao app:
No Xcode, clique com o botão direito do mouse no seu projeto no navegador do projeto.
Selecione Add Packages no menu de contexto.
Na caixa de diálogo Add Packages, cole o URL do pacote na barra de pesquisa:
https://github.com/google/generative-ai-swift
Clique em Add Package. O Xcode adicionará o pacote
GoogleGenerativeAI
ao projeto.
Inicializar o modelo generativo
Antes de fazer qualquer chamada de API, você precisa inicializar o modelo generativo.
Importe o módulo
GoogleGenerativeAI
:import GoogleGenerativeAI
Inicialize o modelo generativo:
// Access your API key from your on-demand resource .plist file // (see "Set up your API key" above) // The Gemini 1.5 models are versatile and work with most use cases let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)
Ao especificar um modelo, observe o seguinte:
Use um modelo específico para seu caso de uso (por exemplo,
gemini-pro-vision
é para entrada multimodal). Neste guia, as instruções para cada implementação listam o modelo recomendado para cada caso de uso.
Implemente casos de uso comuns
Agora que o projeto está configurado, é possível explorar o uso da API Gemini para implementar diferentes casos de uso:
- Gerar texto com base apenas em uma entrada de texto
- Gerar texto com base na entrada de texto e imagem (multimodal)
- Criar conversas com vários turnos (chat)
- Usar o streaming para interações mais rápidas
Gerar texto com base apenas em entradas de texto
Quando a entrada do comando incluir apenas texto, use um modelo Gemini 1.5 ou
Gemini 1.0 Pro com generateContent
para gerar uma saída de texto:
import GoogleGenerativeAI
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", 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)
}
Gerar texto com base em entradas de texto e imagem (multimodal)
O Gemini fornece vários modelos que podem lidar com entradas multimodais (modelos Genmini 1.5 e Gemini 1.0 Pro Vision) para que você possa inserir texto e imagens. Leia os requisitos de imagem para solicitações.
Quando a entrada da solicitação incluir texto e imagens, use um modelo Gemini 1.5 ou
o modelo Gemini 1.0 Pro Vision com o método generateContent
para gerar
a saída de texto:
import GoogleGenerativeAI
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", 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)
}
Criar conversas com vários turnos (chat)
Com o Gemini, é possível criar conversas livres em vários turnos. O
SDK simplifica o processo gerenciando o estado da conversa. Portanto, ao contrário de
generateContent
, você não precisa armazenar o histórico
da conversa.
Para criar uma conversa de várias interações (como um chat), use um modelo Gemini 1.5 ou
Gemini 1.0 Pro e inicialize o chat chamando startChat()
.
Em seguida, use sendMessage()
para enviar uma mensagem de novo usuário, que também vai anexar a mensagem e a resposta ao histórico de chat.
Há duas opções possíveis de role
associadas ao conteúdo em uma
conversa:
user
: o papel que fornece as solicitações. Esse valor é o padrão para chamadassendMessage
.model
: o papel que fornece as respostas. Esse papel pode ser usado ao chamarstartChat()
comhistory
.
import GoogleGenerativeAI
let config = GenerationConfig(
maxOutputTokens: 100
)
// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
name: "gemini-1.5-flash",
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)
}
Use o streaming para interações mais rápidas
Por padrão, o modelo retorna uma resposta depois de concluir todo o processo de geração. Consiga interações mais rápidas não esperando todo o resultado e, em vez disso, use o streaming para lidar com resultados parciais.
O exemplo a seguir mostra como implementar o streaming com o método generateContentStream
para gerar texto a partir de um prompt de entrada de texto e imagem.
import GoogleGenerativeAI
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", 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)
Você pode usar uma abordagem semelhante para casos de uso de chat e entrada somente de texto.
// Use streaming with text-only input
let contentStream = model.generateContentStream(prompt)
// Use streaming with multi-turn conversations (like chat)
let responseStream = chat.sendMessageStream(message)
Implemente casos de uso avançados
Os casos de uso comuns descritos na seção anterior deste tutorial ajudam você a se familiarizar com o uso da API Gemini. Esta seção descreve alguns casos de uso que podem ser considerados mais avançados.
Chamadas de função
A chamada de função facilita a geração de saídas de dados estruturados de modelos generativos. Assim, é possível usar essas saídas para chamar outras APIs e retornar os dados de resposta relevantes para o modelo. Em outras palavras, a chamada de função ajuda a conectar modelos generativos a sistemas externos para que o conteúdo gerado inclua as informações mais atualizadas e precisas. Saiba mais no tutorial de chamada de função.
Tokens de contagem
Ao usar prompts longos, pode ser útil contar os tokens antes de enviar qualquer conteúdo ao modelo. Os exemplos abaixo mostram como usar countTokens()
para vários casos de uso:
// 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 = try ModelContent(role: "user", "Why is the sky blue?")
let contents = history + [message]
let response = try await model.countTokens(contents)
print(response.totalTokens)
Opções para controlar a geração de conteúdo
É possível controlar a geração de conteúdo definindo parâmetros de modelo e usando as configurações de segurança.
Configurar parâmetros do modelo
Cada comando enviado ao modelo inclui valores de parâmetros que controlam como o modelo gera uma resposta. O modelo pode gerar diferentes resultados para diferentes valores de parâmetros. Saiba mais sobre os parâmetros de modelo. A configuração é mantida durante todo o ciclo de vida da instância de modelo.
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(
// The Gemini 1.5 models are versatile and work with most use cases
name: "gemini-1.5-flash",
apiKey: APIKey.default,
generationConfig: config
)
Usar configurações de segurança
Você pode usar as configurações de segurança para ajustar a probabilidade de receber respostas que podem ser consideradas prejudiciais. Por padrão, as configurações de segurança bloqueiam conteúdo com probabilidade média e/ou alta de não ser seguro em todas as dimensões. Saiba mais sobre as Configurações de segurança.
Veja como definir uma configuração de segurança:
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
// The Gemini 1.5 models are versatile and work with most use cases
name: "gemini-1.5-flash",
apiKey: APIKey.default,
safetySettings: [
SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
]
)
Também é possível definir mais de uma configuração de segurança:
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(
// The Gemini 1.5 models are versatile and work with most use cases
name: "gemini-1.5-flash",
apiKey: APIKey.default,
safetySettings: [harassmentSafety, hateSpeechSafety]
)
A seguir
Design de prompt é o processo de criação de prompts que extraem a resposta desejada dos modelos de linguagem. Escrever solicitações bem estruturadas é uma parte essencial para garantir respostas precisas e de alta qualidade de um modelo de linguagem. Saiba mais sobre as práticas recomendadas para escrita de comandos.
O Gemini oferece diversas variações de modelo para atender às necessidades de diferentes casos de uso, como tipos de entrada e complexidade, implementações para chat ou outras tarefas de linguagem de diálogo e restrições de tamanho. Saiba mais sobre os modelos disponíveis do Gemini.
Gemini oferece opções para solicitar aumentos no limite de taxa. O limite de taxa para os modelos Genmini Pro é de 60 solicitações por minuto (RPM).