Migrar do SDK da OpenAI para o SDK da IA generativa

Nesta página, explicamos como migrar o código projetado para o SDK da OpenAI para o SDK da IA generativa do Google e usar os modelos do Gemini na Vertex AI.

Visão geral da migração

O notebook a seguir demonstra uma migração prática da biblioteca openai para a biblioteca google-genai:

Mapeamento de API e sintaxe

A tabela a seguir compara os principais componentes, métodos e parâmetros do SDK da OpenAI com o SDK de IA generativa.

Recurso SDK da OpenAI (openai) SDK de IA generativa (google-genai)
Inicialização do cliente client = OpenAI(api_key=...) client = genai.Client(vertexai=True, ...)
Método de geração client.chat.completions.create client.models.generate_content
Método de streaming stream=True (parâmetro) client.models.generate_content_stream (método)
Entrada do usuário messages=[{"role": "user", "content": "..."}] contents="..." (str) ou contents=[...] (list)
Instruções do sistema messages=[{"role": "system", "content": "..."}] config=types.GenerateContentConfig(system_instruction=...)
Acesso à resposta response.choices[0].message.content response.text
Histórico de chat Gerenciamento manual de listas (messages.append) client.chats.create() (objeto com estado)
Máximo de tokens max_tokens max_output_tokens (em config)
Temperatura temperature temperature (em config)
Modo JSON response_format={"type": "json_object"} response_mime_type="application/json" (em config)

Instalação e configuração

Desinstale a biblioteca OpenAI e instale o SDK da IA generativa.

pip install google-genai

2. Autenticação e inicialização

Enquanto a OpenAI usa uma chave de API, a Vertex AI usa credenciais do Identity and Access Management (IAM) (Application Default Credentials). É necessário definir explicitamente o ID do projeto e o local.

SDK da OpenAI SDK do Google Gen AI 
from openai import OpenAI
import os

# Relies on OPENAI_API_KEY environment variable
client = OpenAI()
        
from google import genai

# Use vertexai=True to use the Vertex AI platform
client = genai.Client(
    vertexai=True,
    project='your-project-id',
    location='us-central1'
)
Dica:também é possível definir variáveis de ambiente para inicializar o cliente sem argumentos, semelhante a como o cliente da OpenAI lê a chave de API do ambiente.

Defina GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT e GOOGLE_CLOUD_LOCATION, conforme mostrado:

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='global'

Depois de configurado, é possível inicializar o cliente sem transmitir parâmetros:

from google import genai

client = genai.Client()

Exemplos de código

Os exemplos de código a seguir mostram as diferenças entre o SDK da OpenAI e o SDK da IA generativa do Google para tarefas comuns.

Geração de texto em um único turno

Os exemplos de código a seguir mostram como gerar texto. No SDK da IA generativa do Google, as instruções do sistema são processadas como um parâmetro de configuração, e não como uma função de mensagem na lista de entrada.

SDK da OpenAI SDK do Google Gen AI 
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum physics."}
    ]
)
print(response.choices[0].message.content)
        
from google.genai import types

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Explain quantum physics.",
    config=types.GenerateContentConfig(
        system_instruction="You are a helpful assistant."
    )
)
print(response.text)

Geração de texto com parâmetros

Os exemplos de código a seguir mostram as diferenças na definição de parâmetros de configuração. No SDK da IA generativa do Google, parâmetros como temperature, max_output_tokens (antes max_tokens) e formatação JSON são agrupados em um objeto GenerateContentConfig.

SDK da OpenAI SDK do Google Gen AI 
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "List 3 types of apples in JSON."}
    ],
    temperature=0.7,
    max_tokens=1000,
    response_format={"type": "json_object"}
)

print(response.choices[0].message.content)
        
from google.genai import types

config = types.GenerateContentConfig(
    temperature=0.7,
    max_output_tokens=1000,
    response_mime_type="application/json"
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="List 3 types of apples in JSON.",
    config=config
)

print(response.text)

Chat (vários turnos)

Os exemplos de código a seguir mostram as diferenças no gerenciamento do histórico de conversas. O SDK da IA generativa do Google simplifica isso ao fornecer um objeto chat com estado, enquanto a OpenAI exige a anexação manual de mensagens a uma lista.

SDK da OpenAI SDK do Google Gen AI 
# You must manually manage the list state
messages = [{"role": "user", "content": "Hi"}]

response = client.chat.completions.create(
    model="gpt-4",
    messages=messages
)

# Append the response to history manually
messages.append(response.choices[0].message)
messages.append({"role": "user", "content": "Next question"})

response2 = client.chat.completions.create(
    model="gpt-4",
    messages=messages
)
print(response2.choices[0].message.content)
        
# The SDK manages history for you
chat = client.chats.create(
    model="gemini-2.5-flash",
    config=types.GenerateContentConfig(
        system_instruction="You are a helpful assistant."
    )
)

response1 = chat.send_message("Hi")
print(response1.text)

# History is retained automatically in the chat object
response2 = chat.send_message("Next question")
print(response2.text)

Streaming

Os exemplos de código a seguir mostram as diferenças nas respostas de streaming. O SDK da IA generativa do Google usa um método específico (generate_content_stream) em vez de uma flag booleana.

SDK da OpenAI SDK do Google Gen AI 
stream = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Write a story."}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
        
stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="Write a story."
)

for chunk in stream:
    print(chunk.text, end="")

A seguir