Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Instalar o SDK Python

Aula 4 de 22 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Instalar o SDK Python
  2. Pré-requisitos e Instalação
  3. Um Cliente, Todas as APIs
  4. Configurar o Cliente para o Seu Contexto
  5. Estruturar o Seu Projeto
  6. Três Falhas Comuns
  7. Pontos-chave

Instalar o SDK Python

O SDK Python openai é a biblioteca oficial para interagir com a API. Esta lição guia-o na instalação e configura uma estrutura de projeto limpa que utilizará ao longo do restante curso.

Pré-requisitos e Instalação

Precisa do Python 3.10 ou superior — o mínimo exigido pelo SDK openai (versão 3.42.1 em 2 de novembro de 2026, segundo o PyPI) —, de um gestor de pacotes (pip ou uv) e da chave de API que obteve na lição anterior. Comece por confirmar o seu interpretador, uma vez que as máquinas de desenvolvimento costumam alojar múltiplas versões:

python --version
# Python 3.12.4

A instalação requer apenas um comando: pip install openai, ou uv pip install openai se utilizar o uv, que é significativamente mais rápido. No entanto, crie o hábito de trabalhar dentro de um ambiente virtual. Isto evita o cenário comum em que, seis meses depois, descobre que dois projetos exigem versões incompatíveis da mesma biblioteca.

# Criar um ambiente virtual
python -m venv .venv

# Ativar (Linux/macOS)
source .venv/bin/activate

# Ativar (Windows)
.venv\Scripts\activate

# Instalar o SDK
pip install openai

Dois companheiros surgem em quase todos os projetos e merecem ser instalados juntamente com o SDK. O Pydantic ajuda a definir esquemas para Saída Estruturada, que verá mais tarde; o python-dotenv carrega o ficheiro .env para variáveis de ambiente.

# Instalar com suporte para dataclasses do Pydantic
pip install openai pydantic

# Instalar com python-dotenv para variáveis de ambiente
pip install openai python-dotenv

Por fim, verifique se a importação funciona e anote a versão instalada. Esta é a primeira informação a fornecer caso abra um ticket de suporte.

import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)

Um Cliente, Todas as APIs

O SDK gira em torno de um único objeto cliente que expõe toda a plataforma através de submódulos. Não precisa de instanciar nada de novo para alternar entre geração de texto, embeddings ou moderação.

from openai import OpenAI

client = OpenAI()

# Responses API (texto, chamada de funções, saída estruturada)
client.responses.create(...)

# Chat Completions API (legado)
client.chat.completions.create(...)

# Embeddings
client.embeddings.create(...)

# Imagens
client.images.generate(...)

# Áudio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)

# Moderação
client.moderations.create(...)

Configurar o Cliente para o Seu Contexto

As predefinições do SDK funcionam para experimentação, mas são insuficientes para aplicações web. O tempo limite predefinido é de dez minutos: numa API HTTP esperada responder em segundos, isto significa que um pedido bloqueado ocupa um trabalhador durante demasiado tempo. Reduza-o e aumente o número de novas tentativas automáticas, que por predefinição é duas.

from openai import OpenAI

client = OpenAI(
    timeout=60.0,  # 60 segundos (predefinição: 10 minutos)
    max_retries=3,  # 3 tentativas em caso de erro (predefinição: 2)
)

O parâmetro base_url responde a outra necessidade: encaminhar chamadas através de um proxy corporativo que regista o tráfego de saída, ou para um serviço que expõe uma API compatível.

# Útil para proxies corporativos ou APIs compatíveis
client = OpenAI(
    base_url="https://your-proxy.company.com/v1"
)

Por fim, se a sua aplicação depende de asyncio — FastAPI, aiohttp e semelhantes —, utilize AsyncOpenAI. O cliente síncrono bloquearia o ciclo de eventos durante a geração, anulando os benefícios do código assíncrono.

from openai import AsyncOpenAI

async_client = AsyncOpenAI()

# Utilização com await
import asyncio

async def main():
    response = await async_client.responses.create(
        model="gpt-5.6-terra",
        input="Hello!"
    )
    print(response.output_text)

asyncio.run(main())
# Output: Hello! How can I help you today?

Estruturar o Seu Projeto

Adote uma organização que isole a configuração do cliente do resto do seu código desde o início. Isto evita dispersar dezenas de chamadas OpenAI() por todo o projeto, cada uma com as suas próprias definições.

my-project/
├── .env                  # Chave de API (NUNCA fazer commit para git)
├── .gitignore            # Inclui .env
├── requirements.txt      # Dependências
├── src/
│   ├── __init__.py
│   ├── client.py         # Configuração do cliente OpenAI
│   └── main.py           # Ponto de entrada
└── tests/
    └── test_api.py

O ficheiro src/client.py centraliza a fábrica do cliente: no dia em que alterar o tempo limite ou adicionar um proxy, só precisa de modificar um local.

from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

def get_client() -> OpenAI:
    """Devolve um cliente OpenAI configurado."""
    return OpenAI(
        max_retries=3,
        timeout=30.0
    )

E o requirements.txt fixa as versões mínimas esperadas:

openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0

Três Falhas Comuns

Um ModuleNotFoundError em openai sinaliza quase sempre um ambiente virtual inativo ou diferente daquele onde instalou o pacote. Localize o interpretador realmente em uso com which python no Linux e macOS, ou where python no Windows, e reinstale com pip install --upgrade openai. Um AuthenticationError aponta para a variável de ambiente: imprima os.environ.get("OPENAI_API_KEY", "NOT DEFINED") para descartar problemas — o ficheiro .env não é carregado se load_dotenv() não tiver sido chamado antes de instanciar o cliente. Por fim, um erro relativo a um parâmetro desconhecido indica geralmente um SDK demasiado antigo para a funcionalidade que está a utilizar: pip install --upgrade openai resolve isto.

Pontos-chave

  • Instale o SDK com pip install openai dentro de um ambiente virtual
  • O cliente OpenAI() é o ponto de entrada para todas as APIs
  • Utilize AsyncOpenAI() para aplicações assíncronas
  • Configure o tempo limite e as novas tentativas conforme as suas necessidades
  • Estruture o seu projeto com um ficheiro .env e um cliente centralizado