OpenAI e Outros SDKs

O SDK Python da OpenAI é o padrão de referência para chat completions, embeddings e tool calling. LiteLLM e bibliotecas similares abstraem múltiplos provedores quando você precisa de flexibilidade de fornecedor.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from openai import OpenAI
 
client = OpenAI()  # lê OPENAI_API_KEY
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Olá"}],
)
print(response.choices[0].message.content)

Quando usar isso:

Construindo sobre modelos GPT-4o, GPT-4o-mini ou de embedding.
Migrando do SDK OpenAI v0 (openai.ChatCompletion) para o v1.
Abstraindo entre modelos OpenAI, Anthropic e locais com LiteLLM.
Chamando a API de Respostas ou endpoints de lote para economia de custos.

Exemplo de Trabalho

"""openai_sdks.py - chat, embeddings, ferramentas e fallback LiteLLM."""
from __future__ import annotations
 
import json
import os
from openai import OpenAI, AsyncOpenAI
 
client = OpenAI()
 
# Chat completion
chat = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Você é um assistente útil."},
        {"role": "user", "content": "O que é FastAPI?"},
    ],
    temperature=0.2,
)
print(chat.choices[0].message.content)
 
# Embeddings
emb = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Python data pipelines", "Machine learning basics"],
)
print("dimensão do embedding:", len(emb.data[0].embedding))
 
# Chamada de função
tools = [{
    "type": "function",
    "function": {
        "name": "search_docs",
        "description": "Pesquisar documentação interna",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]
tool_resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Encontre documentos sobre validadores pydantic"}],
    tools=tools,
)
msg = tool_resp.choices[0].message
if msg.tool_calls:
    call = msg.tool_calls[0]
    print(f"ferramenta: {call.function.name}({call.function.arguments})")
 
# LiteLLM multi-provedor
try:
    import litellm
    response = litellm.completion(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Oi"}],
    )
    print("litellm:", response.choices[0].message.content[:50])
except ImportError:
    print("litellm não instalado - pulando")

O que isso demonstra:

Padrão de cliente do SDK OpenAI v1 para chat e embeddings.
Chamada de ferramentas/funções com parâmetros de esquema JSON.
Vetores de embedding para pipelines de busca semântica.
LiteLLM como um wrapper drop-in multi-provedor.

Aprofundamento

Como Funciona

Instância de cliente contém a chave de API, URL base e configuração HTTP.
Chat completions enviam mensagens; o modelo retorna uma escolha de completude.
Embeddings mapeiam texto para vetores densos para busca de similaridade.
Tool calls permitem que o modelo solicite a execução de funções com argumentos analisados.
AsyncOpenAI espelha a API síncrona para servidores web assíncronos.

Comparação de Provedores

Provedor	SDK	Pontos Fortes
OpenAI	`openai`	Modelos GPT, embeddings, ampla gama de ferramentas
Anthropic	`anthropic`	Claude, contexto longo, uso de ferramentas
Google	`google-genai`	Gemini, multimodal
LiteLLM	`litellm`	API unificada para mais de 100 modelos

Notas Python

# URL base personalizada (Azure OpenAI, proxy local)
client = OpenAI(base_url=os.environ["OPENAI_BASE_URL"], api_key=os.environ["OPENAI_API_KEY"])
 
# Uso assíncrono em FastAPI
async def ask(question: str) -> str:
    client = AsyncOpenAI()
    resp = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
    )
    return resp.choices[0].message.content or ""

Armadilhas

Usando API v0 depreciada - openai.ChatCompletion.create foi removido. Correção: migre para o cliente OpenAI().
Chaves de API codificadas - chaves no código-fonte são commitadas no git. Correção: variáveis de ambiente e gerenciadores de segredos.
Não tratando tool_calls - o modelo solicita uma função, mas o código a ignora. Correção: verifique message.tool_calls e itere.
Ignorando limites de taxa - erros 429 sob carga. Correção: backoff exponencial; respeite os cabeçalhos retry-after.
Dimensões incorretas do modelo de embedding - misturar modelos quebra a busca de vetores. Correção: fixe um modelo de embedding por índice.
Assumindo conteúdo não nulo - recusas ou chamadas de ferramentas deixam content como None. Correção: verifique antes de usar .content.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
OpenAI SDK	Modelos GPT diretamente	Precisa de Claude ou Gemini
LiteLLM	Aplicativos multi-provedor	Provedor único, sem necessidade de abstração
Wrappers LLM LangChain	Chains e agentes	Chamadas de API simples e únicas
HTTP Bruto (httpx)	Controle total, sem dependência de SDK	Recursos de SDK padrão são suficientes

FAQs

Como migro do openai v0 para o v1?

# v0 (depreciado)
# openai.ChatCompletion.create(model="gpt-3.5-turbo", messages=[...])
# v1
client = OpenAI()
client.chat.completions.create(model="gpt-4o-mini", messages=[...])

O que é a API de Respostas?

API mais recente da OpenAI para fluxos de trabalho de agentes com tratamento de ferramentas integrado.
Verifique a documentação atual para migração de chat completions.

Como uso o Azure OpenAI?

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT']}/openai/v1/",
)

Como faço para agrupar requisições para economizar custos?

A API Batch da OpenAI processa requisições de forma assíncrona com menor custo.
Bom para geração de embeddings offline ou avaliação em lote.

O que é LiteLLM?

Wrapper drop-in: litellm.completion(model="claude-sonnet-4-20250514", ...).
Roteia para o SDK do provedor correto com base no prefixo do nome do modelo.

Como listar modelos disponíveis?

models = client.models.list()
for m in models.data:
    print(m.id)

Como definir timeouts?

client = OpenAI(timeout=30.0, max_retries=3)

Posso usar embeddings da OpenAI com pgvector?

Sim - armazene vetores text-embedding-3-small (1536 dims) no PostgreSQL.
Veja Bancos de Dados Vetoriais.

Como registrar requisições?

O painel da OpenAI mostra uso e custos.
Registre hashes de prompt e contagens de tokens em sua aplicação.

E quanto a modelos de código aberto via API compatível com OpenAI?

vLLM e Ollama expõem endpoints compatíveis com /v1/chat/completions.
Aponte base_url para o servidor local.

Como lidar com recusas de política de conteúdo?

Verifique finish_reason == "content_filter".
Forneça mensagens de fallback para os usuários.

Como testar sem chamadas de API?

Simule o cliente em testes unitários.
Use fixtures gravadas (estilo VCR) para testes de integração.

Relacionados

SDK Anthropic Claude - Padrões específicos do Claude
Embeddings e Similaridade - modelos de embedding
Saída Estruturada - modo JSON
Modelos Locais e Abertos - Ollama e vLLM
Uso de Ferramentas e Chamada de Funções - loops de ferramentas

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

OpenAI e Outros SDKs

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from openai import OpenAI
 
client = OpenAI()  # lê OPENAI_API_KEY
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Olá"}],
)
print(response.choices[0].message.content)

Quando usar isso:

Construindo sobre modelos GPT-4o, GPT-4o-mini ou de embedding.
Migrando do SDK OpenAI v0 (openai.ChatCompletion) para o v1.
Abstraindo entre modelos OpenAI, Anthropic e locais com LiteLLM.
Chamando a API de Respostas ou endpoints de lote para economia de custos.

Exemplo de Trabalho

"""openai_sdks.py - chat, embeddings, ferramentas e fallback LiteLLM."""
from __future__ import annotations
 
import json
import os
from openai import OpenAI, AsyncOpenAI
 
client = OpenAI()
 
# Chat completion
chat = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Você é um assistente útil."},
        {"role": "user", "content": "O que é FastAPI?"},
    ],
    temperature=0.2,
)
print(chat.choices[0].message.content)
 
# Embeddings
emb = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Python data pipelines", "Machine learning basics"],
)
print("dimensão do embedding:", len(emb.data[0].embedding))
 
# Chamada de função
tools = [{
    "type": "function",
    "function": {
        "name": "search_docs",
        "description": "Pesquisar documentação interna",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]
tool_resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Encontre documentos sobre validadores pydantic"}],
    tools=tools,
)
msg = tool_resp.choices[0].message
if msg.tool_calls:
    call = msg.tool_calls[0]
    print(f"ferramenta: {call.function.name}({call.function.arguments})")
 
# LiteLLM multi-provedor
try:
    import litellm
    response = litellm.completion(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Oi"}],
    )
    print("litellm:", response.choices[0].message.content[:50])
except ImportError:
    print("litellm não instalado - pulando")

O que isso demonstra:

Padrão de cliente do SDK OpenAI v1 para chat e embeddings.
Chamada de ferramentas/funções com parâmetros de esquema JSON.
Vetores de embedding para pipelines de busca semântica.
LiteLLM como um wrapper drop-in multi-provedor.

Aprofundamento

Como Funciona

Instância de cliente contém a chave de API, URL base e configuração HTTP.
Chat completions enviam mensagens; o modelo retorna uma escolha de completude.
Embeddings mapeiam texto para vetores densos para busca de similaridade.
Tool calls permitem que o modelo solicite a execução de funções com argumentos analisados.
AsyncOpenAI espelha a API síncrona para servidores web assíncronos.

Comparação de Provedores

Provedor	SDK	Pontos Fortes
OpenAI	`openai`	Modelos GPT, embeddings, ampla gama de ferramentas
Anthropic	`anthropic`	Claude, contexto longo, uso de ferramentas
Google	`google-genai`	Gemini, multimodal
LiteLLM	`litellm`	API unificada para mais de 100 modelos

Notas Python

# URL base personalizada (Azure OpenAI, proxy local)
client = OpenAI(base_url=os.environ["OPENAI_BASE_URL"], api_key=os.environ["OPENAI_API_KEY"])
 
# Uso assíncrono em FastAPI
async def ask(question: str) -> str:
    client = AsyncOpenAI()
    resp = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
    )
    return resp.choices[0].message.content or ""

Armadilhas

Usando API v0 depreciada - openai.ChatCompletion.create foi removido. Correção: migre para o cliente OpenAI().
Chaves de API codificadas - chaves no código-fonte são commitadas no git. Correção: variáveis de ambiente e gerenciadores de segredos.
Não tratando tool_calls - o modelo solicita uma função, mas o código a ignora. Correção: verifique message.tool_calls e itere.
Ignorando limites de taxa - erros 429 sob carga. Correção: backoff exponencial; respeite os cabeçalhos retry-after.
Dimensões incorretas do modelo de embedding - misturar modelos quebra a busca de vetores. Correção: fixe um modelo de embedding por índice.
Assumindo conteúdo não nulo - recusas ou chamadas de ferramentas deixam content como None. Correção: verifique antes de usar .content.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
OpenAI SDK	Modelos GPT diretamente	Precisa de Claude ou Gemini
LiteLLM	Aplicativos multi-provedor	Provedor único, sem necessidade de abstração
Wrappers LLM LangChain	Chains e agentes	Chamadas de API simples e únicas
HTTP Bruto (httpx)	Controle total, sem dependência de SDK	Recursos de SDK padrão são suficientes

FAQs

Como migro do openai v0 para o v1?

# v0 (depreciado)
# openai.ChatCompletion.create(model="gpt-3.5-turbo", messages=[...])
# v1
client = OpenAI()
client.chat.completions.create(model="gpt-4o-mini", messages=[...])

O que é a API de Respostas?

API mais recente da OpenAI para fluxos de trabalho de agentes com tratamento de ferramentas integrado.
Verifique a documentação atual para migração de chat completions.

Como uso o Azure OpenAI?

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT']}/openai/v1/",
)

Como faço para agrupar requisições para economizar custos?

A API Batch da OpenAI processa requisições de forma assíncrona com menor custo.
Bom para geração de embeddings offline ou avaliação em lote.

O que é LiteLLM?

Wrapper drop-in: litellm.completion(model="claude-sonnet-4-20250514", ...).
Roteia para o SDK do provedor correto com base no prefixo do nome do modelo.

Como listar modelos disponíveis?

models = client.models.list()
for m in models.data:
    print(m.id)

Como definir timeouts?

client = OpenAI(timeout=30.0, max_retries=3)

Posso usar embeddings da OpenAI com pgvector?

Sim - armazene vetores text-embedding-3-small (1536 dims) no PostgreSQL.
Veja Bancos de Dados Vetoriais.

Como registrar requisições?

O painel da OpenAI mostra uso e custos.
Registre hashes de prompt e contagens de tokens em sua aplicação.

E quanto a modelos de código aberto via API compatível com OpenAI?

vLLM e Ollama expõem endpoints compatíveis com /v1/chat/completions.
Aponte base_url para o servidor local.

Como lidar com recusas de política de conteúdo?

Verifique finish_reason == "content_filter".
Forneça mensagens de fallback para os usuários.

Como testar sem chamadas de API?

Simule o cliente em testes unitários.
Use fixtures gravadas (estilo VCR) para testes de integração.

Relacionados

SDK Anthropic Claude - Padrões específicos do Claude
Embeddings e Similaridade - modelos de embedding
Saída Estruturada - modo JSON
Modelos Locais e Abertos - Ollama e vLLM
Uso de Ferramentas e Chamada de Funções - loops de ferramentas

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

OpenAI e Outros SDKs

Buscar na documentação

OpenAI e Outros SDKs