Provedores¶
Configure diferentes provedores de LLM via LangChain ou pelos SDKs oficiais de ferramentas locais.
Provedores Suportados¶
| Provider | Identificador | Modelos atuais | Modelo padrão |
|---|---|---|---|
| OpenAI | openai |
gpt-6-luna, gpt-6-sol, gpt-6-astra | gpt-6-luna |
google_genai |
gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite | gemini-3.8-flash |
|
| Anthropic | anthropic |
claude-sonnet-5, claude-opus-5-5, claude-haiku-4-5 | claude-sonnet-5 |
| Groq | groq |
openai/gpt-oss-120b, openai/gpt-oss-20b | openai/gpt-oss-120b |
| OpenAI Codex (experimental) | codex |
Modelos suportados pelo runtime empacotado | Escolhido pelo runtime |
| Claude Code | claude_code |
Modelos e aliases aceitos pelo Claude Code (sonnet, haiku, opus) |
Escolhido pelo runtime |
| Cohere | cohere |
Catálogo da Cohere | Informe model |
| Mistral | mistralai |
Catálogo da Mistral | Informe model |
Sem provider, o dataframeit usa openai com gpt-6-luna. Com provider e sem model, usa o modelo padrão do provider da tabela; para providers sem modelo padrão, model é obrigatório. Qualquer outro provider aceito pelo init_chat_model do LangChain também funciona, desde que o pacote langchain-<provider> esteja instalado.
Qual provedor escolher¶
| Situação | Provedor | Por quê |
|---|---|---|
| Começar, ou volume alto com custo baixo | openai (padrão) |
O gpt-6-luna tem o menor preço por token entre os modelos com preço listado abaixo |
| Free tier para testar | groq |
Limites gratuitos por minuto em cada modelo |
| Tarefa mais difícil que o modelo padrão resolve mal | modelo maior do mesmo provider (gpt-6-sol, claude-opus-5-5) |
Custa mais por token; compare numa amostra antes |
| Login do Codex ou do Claude Code, sem chave de API | codex ou claude_code |
Usam a autenticação local da ferramenta; não suportam busca web |
| Dados que precisam ficar no Brasil | Vertex AI, Bedrock ou Azure | Ver Servidor no Brasil |
| Busca web | qualquer provider via LangChain | codex e claude_code não suportam use_search=True |
Antes de processar o dataset inteiro, rode uma amostra de 20 a 50 linhas e confira o resultado e o custo no resumo de estatísticas.
OpenAI (Padrão)¶
# Padrão - não precisa especificar
resultado = dataframeit(df, Model, PROMPT)
# Com modelo mais avançado
resultado = dataframeit(
df, Model, PROMPT,
provider='openai',
model='gpt-6-sol',
model_kwargs={
'reasoning_effort': 'medium'
}
)
Modelos Recomendados¶
| Modelo | Uso | Preço (1M tokens, input / output) |
|---|---|---|
gpt-6-luna |
Alto volume, tarefas focadas | $0.10 / $0.50 |
gpt-6-sol |
Tarefas complexas e agênticas | $2.00 / $10.00 |
gpt-6-astra |
Máxima qualidade | $10.00 / $50.00 |
Google Gemini¶
resultado = dataframeit(
df, Model, PROMPT,
provider='google_genai' # usa gemini-3.8-flash
)
# Com parâmetros extras
resultado = dataframeit(
df, Model, PROMPT,
provider='google_genai',
model='gemini-3.5-flash-lite',
model_kwargs={
'thinking_level': 'low'
}
)
Modelos Recomendados¶
| Modelo | Uso | Preço (1M tokens, input / output) |
|---|---|---|
gemini-3.8-flash |
Uso geral, mais recente | $0.75 / $3.75 até 31/12/2026; $1.50 / $7.50 a partir de 2027 |
gemini-3.6-flash |
Uso geral | $0.75 / $3.75 até 31/12/2026; $1.50 / $7.50 a partir de 2027 |
gemini-3.5-flash-lite |
Alto volume, econômico | $0.30 / $2.50 |
OpenAI Codex (Experimental)¶
O provider codex usa o SDK Python oficial e permanece experimental. Para instalar o extra, entender qual runtime é executado e configurar a autenticação local em arquivo, consulte Instalação.
resultado = dataframeit(
df,
Model,
PROMPT,
provider='codex', # sem model: o runtime escolhe
model_kwargs={'effort': 'medium'},
parallel_requests=3,
)
Para esse provider, model_kwargs aceita somente effort e timeout. O effort recebe um dos valores que o SDK declara: none, minimal, low, medium, high, xhigh, max e ultra; cada modelo aceita só parte deles. O timeout é o prazo, em segundos, de cada tentativa, da abertura da thread ao fim do turno, com padrão de 600: o turno que não termina no prazo é interrompido, a tentativa falha com ProviderTransientError e a linha é repetida conforme max_retries. Se o prazo acaba antes de o app-server responder à abertura da thread ou do turno, o app-server é encerrado e a execução para com ProviderAbortError; as linhas sem status ficam para resume=True. Com timeout=None, não há prazo. Trocar o timeout não impede retomar um checkpoint. use_search=True não é suportado. O modelo Pydantic deve ter campos no nível raiz e usar o subconjunto de JSON Schema aceito por Structured Outputs; RootModel, Any, campos dict com chaves dinâmicas, keywords de validação fora do subconjunto, como as de tuplas fixas, set e min_length/max_length em texto, format fora da lista suportada, como os de bytes, Path, AnyUrl e UUID4, e pattern com lookahead, lookbehind ou referência a grupo, como o que o pydantic anterior à 2.14 gera para Decimal, são rejeitados no preflight. Chaves que não restringem o valor, como as anotações próprias em json_schema_extra e os metadados examples e deprecated, são descartadas do schema enviado, com um aviso que as lista; a resposta continua validada pelo modelo Pydantic. A autenticação configurada durante a instalação vem de auth.json, portanto não passe api_key ao dataframeit().
Com model, a biblioteca confere na abertura, por uma thread sem turno, que o runtime resolveu o modelo pedido, e falha antes da primeira linha se não resolveu; sem model, um aviso diz qual modelo será usado. Um turno que o runtime reroteia para outro modelo é interrompido, e a linha falha. O effort vai em cada turno e não volta na resposta do runtime, então não é conferido.
O erro de um turno que falha é classificado pelo código que o runtime envia: sobrecarga, limite de requisições, falta de capacidade no tier flex, HTTP 429 e 5xx são repetidos; a cota de uso esgotada e o runtime encerrado interrompem a execução, como descrito em Checkpoints. Quando uma tentativa seguinte dá certo, os tokens das que falharam entram no uso da linha.
O DataFrameIt mantém um codex app-server por execução do DataFrame e abre uma thread efêmera por tentativa de cada linha. Ao fim da tentativa, a thread recebe thread/unsubscribe, e o app-server a descarrega depois de cerca de um minuto sem assinante; a memória dele acompanha as threads do último minuto, e não o total de linhas. Cada execução usa CODEX_HOME e workspace isolados, e HOME aponta para o mesmo diretório, para que skills do usuário, como as de ~/.agents/skills, não entrem na execução (no Windows, onde a pasta do usuário não vem de HOME, esse isolamento não foi verificado); auth.json é o único arquivo do estado persistente do Codex vinculado ao runtime, que ainda herda as outras variáveis de ambiente do processo. Enquanto uma execução usa a credencial, outra execução do DataFrameIt com o mesmo auth.json falha antes de iniciar o runtime; isso impede refresh concorrente sem afetar parallel_requests dentro da execução ativa. Esse lock coordena somente instâncias do DataFrameIt, portanto não execute o Codex CLI com a mesma credencial até o processamento terminar. Busca web, shell, servidores MCP, sub-agentes, visualização de imagens, perguntas ao usuário e a ferramenta de pausa ficam desativados, assim como a repetição sem limite da conexão que falha, que deixaria o turno esperando para sempre; a linha sem conexão falha com erro transitório e é repetida conforme max_retries. Aprovações são negadas e o sandbox somente leitura bloqueia escrita. No início da execução, o DataFrameIt lê o catálogo de modelos da conta, ou o embutido no runtime quando o download falha, e o passa ao runtime sem os campos que ligam o code mode (exec e wait), as ferramentas experimentais e o apply_patch; assim o modelo recebe o request sem nenhuma ferramenta. O catálogo é lido uma vez por execução e não muda durante ela.
Claude Code¶
O provider claude_code usa o Claude Agent SDK, que executa o Claude Code CLI. A autenticação é a do próprio Claude Code: as credenciais de um login feito numa instalação do Claude Code na máquina (o CLI que o extra traz não fica no PATH), ou ANTHROPIC_API_KEY. O parâmetro api_key é ignorado.
resultado = dataframeit(
df,
Model,
PROMPT,
provider='claude_code',
model='haiku',
model_kwargs={'max_budget_usd': 0.25, 'effort': 'low'},
)
Em model_kwargs, o provider lê max_turns (padrão 1), max_budget_usd (padrão 0.50) e effort; outras chaves são ignoradas. max_budget_usd é o teto de gasto de cada tentativa: como uma resposta vazia ou fora do schema é tentada de novo, uma linha pode gastar até max_retries vezes esse valor. use_search=True não é suportado.
O texto das linhas é tratado como conteúdo não confiável. A execução roda sem ferramentas, sem os settings de usuário e de projeto e com --strict-mcp-config, de modo que servidores MCP e regras permissions.allow configurados no Claude Code não chegam a ela. Uma linha que estoura max_budget_usd ou max_turns termina em erro definitivo, sem nova tentativa.
Com track_tokens=True, o resumo ao fim da execução mostra o custo informado pelo SDK, somando as tentativas re-tentadas e as linhas que falharam.
Anthropic Claude¶
resultado = dataframeit(
df, Model, PROMPT,
provider='anthropic' # usa claude-sonnet-5
)
# Com max_tokens
resultado = dataframeit(
df, Model, PROMPT,
provider='anthropic',
model='claude-opus-5-5',
model_kwargs={
'max_tokens': 4096
}
)
Modelos Recomendados¶
| Modelo | Uso | Preço (1M tokens, input / output) |
|---|---|---|
claude-sonnet-5 |
Uso geral, velocidade e qualidade | $2.00 / $10.00 |
claude-opus-5-5 |
Máxima qualidade, agêntico | $4.00 / $20.00 |
claude-haiku-4-5 |
Rápido, econômico | $1.00 / $5.00 |
Groq¶
resultado = dataframeit(
df, Model, PROMPT,
provider='groq' # usa openai/gpt-oss-120b
)
# Modelo mais rápido/econômico
resultado = dataframeit(
df, Model, PROMPT,
provider='groq',
model='openai/gpt-oss-20b'
)
Modelos Recomendados¶
Produção:
| Modelo | Contexto | Throughput | Uso |
|---|---|---|---|
openai/gpt-oss-120b |
131K | ~500 t/s | Uso geral, raciocínio |
openai/gpt-oss-20b |
131K | ~1000 t/s | Mais rápido que o 120b, custo baixo |
Preview (podem mudar ou ser descontinuados):
| Modelo | Uso |
|---|---|
qwen/qwen3.8-27b |
Qwen 3.8, modos thinking e instruct |
Disponibilidade e free tier
O Groq oferece free tier com limites de requisições por minuto por modelo. A lista de modelos muda com frequência (especialmente os preview); verifique console.groq.com/docs/models para o catálogo atual e limites.
Cohere¶
Mistral¶
Servidor no Brasil (São Paulo)¶
Os providers acima usam endpoints públicos globais. Para servir do Brasil, por latência, residência de dados ou exigência regulatória, use um dos três caminhos abaixo. Em todos eles, o dataframeit repassa o que vier em model_kwargs direto para o LangChain.
Vertex AI (Gemini em southamerica-east1)¶
Duas variantes. A primeira não exige instalar pacote novo:
# Variante A: usa langchain-google-genai (já é dep do provider 'google_genai')
resultado = dataframeit(
df, Model, PROMPT,
provider='google_genai',
model='gemini-3.8-flash',
model_kwargs={
'vertexai': True,
'project': '<id-do-projeto-gcp>',
'location': 'southamerica-east1',
},
)
# Variante B: usa langchain-google-vertexai (provider dedicado)
# pip install langchain-google-vertexai
resultado = dataframeit(
df, Model, PROMPT,
provider='google_vertexai',
model='gemini-3.8-flash',
model_kwargs={
'project': '<id-do-projeto-gcp>',
'location': 'southamerica-east1',
},
)
Autenticação (qualquer variante):
gcloud auth application-default login
# OU
export GOOGLE_APPLICATION_CREDENTIALS=/caminho/service-account.json
AWS Bedrock (sa-east-1)¶
resultado = dataframeit(
df, Model, PROMPT,
provider='bedrock_converse',
model='global.anthropic.claude-sonnet-5',
model_kwargs={'region_name': 'sa-east-1'},
)
No Bedrock, a Converse API só aceita o Claude Sonnet 5 por perfil de inferência, e em sa-east-1 o único perfil oferecido é o global (global.), que pode processar a requisição fora do Brasil. Se residência de dados for exigência, confira no console Bedrock quais modelos a região oferece com perfil regional.
Para a API Bedrock legada (não-converse), troque por provider='bedrock' mantendo o mesmo model_kwargs. A nova API (bedrock_converse) é recomendada para novos projetos.
Azure OpenAI (Brazil South)¶
pip install langchain-openai
export AZURE_OPENAI_API_KEY="sua-chave"
export AZURE_OPENAI_ENDPOINT="https://<seu-recurso>.openai.azure.com/"
export OPENAI_API_VERSION="2025-03-01-preview"
resultado = dataframeit(
df, Model, PROMPT,
provider='azure_openai',
model='gpt-6-luna', # ou o nome do deployment
model_kwargs={'azure_deployment': '<nome-do-deployment>'},
)
A região é codificada no AZURE_OPENAI_ENDPOINT: provisione o recurso em "Brazil South" no portal Azure.
A versão da API (OPENAI_API_VERSION) muda com frequência. Confira a versão estável mais recente em aka.ms/azure-openai-api-versions.
Preços mudam
Os preços das tabelas acima são os de tabela padrão, por 1M tokens, com as mudanças já anunciadas indicadas na própria tabela. Verifique os valores atuais nos sites oficiais dos providers.
Passando API Key Diretamente¶
Se preferir não usar variáveis de ambiente:
resultado = dataframeit(
df, Model, PROMPT,
provider='openai',
api_key='sk-...' # Sua chave diretamente
)
Segurança
Evite colocar API keys diretamente no código. Prefira variáveis de ambiente.
Parâmetros Comuns (model_kwargs)¶
| Parâmetro | Descrição | Providers |
|---|---|---|
temperature |
Criatividade. O dataframeit não envia valor padrão | Depende do modelo: vários atuais rejeitam (ex.: Claude Sonnet 5, OpenAI GPT-6 com raciocínio e série o) |
top_p |
Nucleus sampling | Depende do modelo, como temperature |
max_tokens |
Limite de saída | Providers via LangChain |
Os providers codex e claude_code não usam esses parâmetros: o codex aceita só effort e timeout e recusa as outras chaves antes de começar; o claude_code lê só max_turns, max_budget_usd e effort e ignora o resto.