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 de IA Generativa do Google para usar modelos 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 da IA generativa.

Recurso SDK da OpenAI (openai) SDK da 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=[...] (lista)
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)
Tokens máximos max_tokens max_output_tokens (dentro de config)
Temperatura temperature temperature (dentro de config)
Modo JSON response_format={"type": "json_object"} response_mime_type="application/json" (dentro de config)

Instalação e configuração

Desinstale a biblioteca da 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 e o local do projeto.

SDK da OpenAI SDK de IA Generativa do Google 
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 Agent Platform 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, de maneira 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 de IA Generativa do Google para tarefas comuns.

Geração de texto de turno único

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

SDK da OpenAI SDK de IA Generativa do Google 
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 de IA Generativa do Google, parâmetros como temperature, max_output_tokens (anteriormente max_tokens) e formatação JSON são agrupados em um objeto GenerateContentConfig.

SDK da OpenAI SDK de IA Generativa do Google 
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 (multiturno)

Os exemplos de código a seguir mostram as diferenças no gerenciamento do histórico de chat. O SDK de IA Generativa do Google simplifica isso fornecendo um objeto chat com estado, enquanto a OpenAI exige que as mensagens sejam anexadas manualmente a uma lista.

SDK da OpenAI SDK de IA Generativa do Google 
# 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 de IA Generativa do Google usa um método específico (generate_content_stream), em vez de uma flag booleana.

SDK da OpenAI SDK de IA Generativa do Google 
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