A Groq anunciou, através do seu próprio blog corporativo, um financiamento adicional de 350 milhões de dólares em agosto de 2026, depois de já ter angariado 650 milhões em junho do mesmo ano, o que eleva o total captado nesses dois meses a mil milhões de dólares segundo a própria empresa. O motivo do interesse é simples: o chip LPU da empresa corre o modelo openai/gpt-oss-20b a 1.000 tokens por segundo, segundo a própria tabela de modelos publicada pela Groq. Este tutorial mostra, passo a passo, como criar conta, instalar o SDK e construir um chatbot completo em Python que aproveita essa velocidade, com fallback automático, streaming e um pipeline RAG simples.

Vais precisar de cerca de 60 a 90 minutos e de conhecimentos básicos de Python. No final, terás uma aplicação FastAPI funcional, pronta para receber pedidos reais e a correr sobre um dos motores de inferência mais rápidos disponíveis publicamente em 2026. O guia cobre 12 passos práticos, mais transcrição de áudio, modelos multimodais, limites do plano gratuito e uma lista de erros e soluções para os problemas mais comuns que vais encontrar pelo caminho.

O Que é a API Groq e Porque Está a Crescer em 2026

A Groq (não confundir com o Grok da xAI) é uma empresa de hardware e cloud que desenha os seus próprios chips, chamados LPU (Language Processing Unit), em vez de depender de GPUs da Nvidia. A GroqCloud é a plataforma onde esses chips ficam disponíveis por API, com uma interface compatível com a da OpenAI. Isso significa que, se já usaste a biblioteca openai em Python, a curva de aprendizagem aqui é quase zero.

O motivo prático para escolher a Groq em 2026 é a velocidade. Segundo a página oficial de modelos suportados da Groq, o openai/gpt-oss-20b atinge 1.000 tokens/s, o qwen/qwen3-32b chega a 662 tokens/s e até o modelo maior, openai/gpt-oss-120b, mantém 500 tokens/s. Para comparação, um modelo mais denso como o llama-3.3-70b-versatile corre a 276 tokens/s na mesma infraestrutura. Estes números não são estimativas de terceiros: vêm diretamente da tabela de modelos da documentação oficial da Groq.

Há também um fator de manutenção que torna este tutorial mais útil do que um simples “olá mundo”. Em setembro de 2026, a Groq descontinuou os modelos groq/compound e groq/compound-mini (a 21 de setembro) e recomenda a migração de qwen/qwen3.6-27b para qwen/qwen3.8-27b. Quem construiu uma aplicação sem lidar com estas mudanças viu pedidos a falhar de um dia para o outro. Por isso, o passo 8 deste guia ensina a criar um sistema de fallback entre modelos, para que a tua aplicação não dependa de um único nome de modelo fixo no código.

Vale ainda perceber a diferença entre a Groq e outros nomes parecidos que aparecem nas mesmas pesquisas. A Groq foi fundada em 2016 e vende inferência sobre modelos de terceiros (OpenAI, Meta, Alibaba, Moonshot AI) através do seu próprio hardware. Não fabrica modelos de fundação, fabrica o chip que os corre mais depressa. Esta distinção importa porque, ao longo deste tutorial, vais ver nomes como “openai/gpt-oss” e “meta-llama” a aparecer como parâmetro model nas chamadas à API: são os modelos de outras empresas, disponibilizados através da infraestrutura da Groq.

Groq vs GPU Tradicional: o Chip LPU Explicado em Termos Simples

Uma GPU foi desenhada para processar gráficos em paralelo, e depois foi adaptada para treinar e correr modelos de IA. Uma LPU nasceu com um único objetivo: executar a inferência de modelos de linguagem o mais rápido possível, com latência previsível. A arquitetura da Groq evita alguns dos gargalos de memória que afetam GPUs em cargas de inferência sequencial, o que explica porque um modelo pequeno como o gpt-oss-20b consegue gerar texto tão depressa.

Na prática, isto importa para quem constrói produtos. Um chatbot de apoio ao cliente que responde em 300 milissegundos parece vivo. O mesmo chatbot a demorar 4 segundos por resposta perde utilizadores a meio da conversa. É essa diferença que justifica escolher a Groq para casos de uso interativos, mesmo sabendo que, para tarefas em lote sem pressão de tempo, outras opções podem ser mais baratas por token.

Esta troca entre velocidade e custo por token não é absoluta. Como viste na tabela do passo 6, o modelo mais rápido do catálogo (gpt-oss-20b) é também um dos mais baratos, o que quebra a suposição comum de que “mais rápido custa sempre mais”. Isto acontece porque a Groq otimiza o custo operacional do próprio hardware LPU para modelos mais pequenos, e não apenas o preço de venda ao cliente final.

Pré-Requisitos: Contas, Versões e Ferramentas Necessárias

Antes de avançar, confirma que tens tudo isto preparado:

  • Python 3.9 ou superior instalado (testa com python3 --version)
  • Uma conta gratuita na GroqCloud
  • O pacote oficial groq, versão 1.7.0 ou posterior (lançado a 26 de agosto de 2026, disponível no PyPI)
  • Opcionalmente, o pacote openai, para o passo de compatibilidade
  • O pacote fastapi e uvicorn para o passo de publicação em produção
  • Um editor de texto ou IDE (VS Code, PyCharm ou equivalente)
  • Ligação à internet estável, já que todos os pedidos são feitos à API da GroqCloud

Não precisas de nenhum GPU local. Toda a computação pesada acontece na infraestrutura da Groq, o teu computador só envia e recebe texto por HTTP.

Passo 1: Criar Conta na GroqCloud e Gerar a Chave de API

Acede à consola da GroqCloud, cria uma conta com o teu email ou uma conta Google, e vai à secção de chaves de API. Cria uma nova chave e guarda-a de imediato, porque a plataforma só a mostra uma vez. O plano gratuito da Groq inclui limites de 30 pedidos por minuto e 8.000 tokens por minuto para os modelos principais, segundo a página oficial de limites de taxa. É suficiente para testar e para muitos projetos pequenos, mas vais notar esses limites no passo 12, quando falamos de retries.

Nunca cries a chave e a coloques diretamente num ficheiro que vais publicar num repositório público. Isso é o erro mais comum entre principiantes e está detalhado na secção de erros comuns mais abaixo.

Passo 2: Instalar o SDK Oficial em Python

Com Python já instalado, cria uma pasta para o projeto, ativa um ambiente virtual e instala o pacote oficial. Este comando também instala o cliente HTTP e as dependências necessárias:

python3 -m venv venv
source venv/bin/activate
pip install -U groq fastapi uvicorn openai

O sinalizador -U garante que instalas sempre a versão mais recente disponível, algo relevante numa API que muda modelos com frequência. No momento de escrita, isto instala a versão 1.7.0 do pacote groq, confirmada diretamente no registo do PyPI.

Passo 3: Guardar a Chave de API em Segurança

Define a chave como variável de ambiente, nunca como texto fixo no código. No Linux ou macOS, no terminal:

export GROQ_API_KEY="a_tua_chave_aqui"

No Windows, usa setx GROQ_API_KEY "a_tua_chave_aqui" numa nova janela do PowerShell. Para projetos mais permanentes, cria um ficheiro .env na raiz do projeto e adiciona-o imediatamente ao .gitignore, antes de escrever qualquer outra linha de código. Assim evitas que a chave acabe num histórico de commits do Git, que é praticamente impossível de limpar depois de um push.

Passo 4: Fazer o Primeiro Pedido de Chat Completion

Cria um ficheiro chat_basico.py com o código abaixo. Este exemplo usa o openai/gpt-oss-20b, o modelo mais rápido do catálogo atual da Groq:

import os
from groq import Groq

client = Groq(api_key=os.environ.get("GROQ_API_KEY"))

completion = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[
        {"role": "user", "content": "Explica o que é uma LPU em duas frases simples."}
    ],
    temperature=0.7,
    max_tokens=200,
)

print(completion.choices[0].message.content)

Corre com python3 chat_basico.py. A resposta deve chegar em bem menos de um segundo, mesmo num portátil comum, porque o trabalho pesado corre nos servidores da Groq e não na tua máquina. Se receberes um erro 401, salta já para a secção de resolução de problemas, quase sempre é a variável de ambiente que não foi carregada na sessão atual do terminal.

Passo 5: Ativar Streaming de Tokens em Tempo Real

Para uma aplicação de chat real, esperar pela resposta completa antes de mostrar qualquer texto é uma má experiência. O streaming resolve isso, mostrando cada token à medida que é gerado:

stream = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[
        {"role": "user", "content": "Escreve três frases curtas sobre velocidade de inferência."}
    ],
    stream=True,
)

for chunk in stream:
    pedaco = chunk.choices[0].delta.content
    if pedaco:
        print(pedaco, end="", flush=True)

print()

Nota o if pedaco:. Alguns fragmentos do stream chegam sem conteúdo (por exemplo, o último, que só traz metadados de finalização), e tentar concatenar texto vazio ou nulo é a causa mais comum de streaming que “para a meio” sem lançar erro nenhum.

Passo 6: GPT-OSS 20B vs 120B — Como Escolher o Modelo Certo

A Groq disponibiliza os dois tamanhos do modelo aberto da OpenAI, o gpt-oss-20b e o gpt-oss-120b, além de modelos da família Llama, Qwen e Kimi K2. Escolher mal aqui custa dinheiro e velocidade sem necessidade. A tabela seguinte junta os números oficiais publicados na documentação da Groq:

ModeloPreço entrada (por 1M tokens)Preço saída (por 1M tokens)Janela de contextoVelocidade oficial
openai/gpt-oss-20b$0,075$0,30131.072 tokens1.000 tokens/s
openai/gpt-oss-120b$0,15$0,60131.072 tokens500 tokens/s
qwen/qwen3-32b$0,29$0,59131.072 tokens662 tokens/s
meta-llama/llama-4-scout-17b-16e-instruct$0,11$0,34131.072 tokens594 tokens/s
meta-llama/llama-4-maverick-17b-128e-instruct$0,20$0,60131.072 tokens562 tokens/s
llama-3.3-70b-versatile$0,59$0,79131.072 tokens276 tokens/s
moonshotai/kimi-k2-instruct$1,00$3,00131.072 tokens200 tokens/s

A regra prática: usa o gpt-oss-20b para chat geral, resumos e classificação, onde a qualidade já costuma bastar e o custo é o mais baixo da tabela. Reserva o gpt-oss-120b ou o kimi-k2-instruct para tarefas de raciocínio mais denso, onde a qualidade extra compensa pagar mais e esperar um pouco mais por token.

Passo 7: Aproveitar a Compatibilidade com a API da OpenAI

A Groq expõe um endpoint compatível com a API da OpenAI em https://api.groq.com/openai/v1. Isto quer dizer que podes usar a biblioteca openai oficial, mudando apenas o base_url e a chave:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("GROQ_API_KEY"),
    base_url="https://api.groq.com/openai/v1",
)

resposta = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[
        {"role": "user", "content": "Resume este texto em três pontos: a Groq usa chips LPU."}
    ],
)

print(resposta.choices[0].message.content)

Isto é útil se já tens uma base de código escrita para a API da OpenAI e queres testar a Groq sem reescrever nada, ou se usas uma ferramenta como um gateway de LLMs que já suporta o formato OpenAI. Já cobrimos essa abordagem de gateway único para múltiplos fornecedores no tutorial sobre o LiteLLM, que funciona bem em conjunto com a Groq como um dos fornecedores configurados.

Passo 8: Criar Fallback Automático Entre Modelos

Como a Groq descontinuou modelos em setembro de 2026 sem grande aviso prévio, qualquer aplicação séria precisa de um plano B. A ideia é simples: define uma lista de modelos por ordem de preferência e tenta o próximo se o primeiro falhar:

MODELOS_FALLBACK = [
    "openai/gpt-oss-120b",
    "openai/gpt-oss-20b",
    "llama-3.3-70b-versatile",
]

def gerar_resposta(mensagens):
    for modelo in MODELOS_FALLBACK:
        try:
            return client.chat.completions.create(
                model=modelo,
                messages=mensagens,
            )
        except Exception as erro:
            print(f"Modelo {modelo} falhou: {erro}. A tentar o próximo modelo...")
    raise RuntimeError("Todos os modelos da lista de fallback falharam.")

Guarda esta lista num ficheiro de configuração separado do código principal. Assim, quando a Groq anunciar a próxima descontinuação, basta atualizar uma linha em vez de andar à procura de nomes de modelos espalhados pela aplicação.

Passo 9: Medir Latência, Tokens Por Segundo e Custo Real

Os números da tabela do passo 6 são medições oficiais da Groq, mas o que interessa ao teu produto é o que acontece na tua própria aplicação, com a tua rede e os teus prompts. Este pequeno bloco de código mede latência e tokens gerados por segundo em cada pedido:

import time

inicio = time.time()
resposta = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[{"role": "user", "content": "Conta de 1 a 30, um número por linha."}],
)
duracao = time.time() - inicio

tokens_gerados = resposta.usage.completion_tokens
tokens_por_segundo = tokens_gerados / duracao

print(f"Tokens gerados: {tokens_gerados}")
print(f"Duração: {duracao:.2f}s")
print(f"Velocidade real: {tokens_por_segundo:.1f} tokens/s")

Corre este script várias vezes e regista os valores. Se estiveres muito abaixo dos números oficiais de forma consistente, o problema está quase sempre na tua ligação de rede ou num prompt muito curto, onde o tempo de arranque do pedido pesa mais do que a geração em si.

Passo 10: Construir um Pipeline RAG Simples com Groq

Um chatbot só com o conhecimento geral do modelo tem limites óbvios. Um pipeline RAG (geração aumentada por recuperação) junta os teus próprios documentos à pergunta antes de enviar tudo ao modelo. Este exemplo usa uma recuperação simples por palavras-chave, suficiente para entender o conceito antes de avançar para uma base vetorial:

import numpy as np

documentos = [
    "A Groq foi fundada em 2016 e desenha o chip LPU.",
    "O modelo openai/gpt-oss-20b tem uma janela de 131.072 tokens.",
    "A GroqCloud oferece um plano gratuito com limites de 30 pedidos por minuto.",
]

def recuperar_contexto(pergunta, documentos, top_k=2):
    termos_pergunta = set(pergunta.lower().split())
    pontuacoes = []
    for doc in documentos:
        termos_doc = set(doc.lower().split())
        pontuacoes.append(len(termos_pergunta & termos_doc))
    indices = np.argsort(pontuacoes)[::-1][:top_k]
    return [documentos[i] for i in indices]

pergunta = "Quando foi fundada a Groq e qual chip usa?"
contexto = recuperar_contexto(pergunta, documentos)
contexto_texto = "\n".join(contexto)

prompt = f"""Contexto:
{contexto_texto}

Pergunta: {pergunta}
Responde apenas com base no contexto acima."""

resposta = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": prompt}],
)
print(resposta.choices[0].message.content)

Para projetos reais com centenas ou milhares de documentos, troca esta recuperação por palavras-chave por embeddings e uma base vetorial. Se já exploraste esse caminho com outro fornecedor, os mesmos princípios aplicam-se aqui, como vimos no tutorial de sistema RAG com a API da OpenAI; só muda o cliente e o modelo usado na fase final de geração.

Nota que a Groq não fornece, ela própria, um serviço de embeddings ou de base vetorial: a plataforma foca-se na fase final de geração. Isto significa que precisas de outra ferramenta para a fase de recuperação, seja uma base vetorial dedicada, seja uma biblioteca local. A vantagem de separar as duas fases é que podes trocar a base de recuperação sem tocar no código que fala com a Groq, e vice-versa. É esta separação de responsabilidades que torna o pipeline mais fácil de depurar quando uma resposta sai errada: primeiro confirmas se o contexto recuperado estava correto, só depois suspeitas da geração.

Passo 11: Publicar a Aplicação com FastAPI

Para transformar isto num serviço real que outras aplicações ou um frontend possam chamar, envolve o cliente Groq num endpoint FastAPI:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class PedidoChat(BaseModel):
    mensagem: str
    modelo: str = "openai/gpt-oss-20b"

@app.post("/chat")
def chat(pedido: PedidoChat):
    resposta = client.chat.completions.create(
        model=pedido.modelo,
        messages=[{"role": "user", "content": pedido.mensagem}],
    )
    return {"resposta": resposta.choices[0].message.content}

Guarda como servidor.py e corre com uvicorn servidor:app --reload --port 8000. Testa com um pedido POST para http://localhost:8000/chat com um corpo JSON como {"mensagem": "Olá, o que consegues fazer?"}. A partir daqui, o próximo passo natural é colocar isto detrás de um proxy HTTPS e adicionar autenticação própria antes de expor a qualquer utilizador externo.

Segurança: o Que Verificar Antes de Expor o Endpoint

Um endpoint FastAPI como o do passo 11 não deve, por padrão, ficar acessível à internet sem camadas extra de proteção. Antes de apontar um domínio público para este servidor, confirma três coisas. Primeiro, adiciona autenticação própria ao endpoint, por exemplo através de uma chave de API interna que o teu frontend envia num cabeçalho, separada da chave da Groq, para que um utilizador malicioso não consiga gastar a tua quota gratuita ou paga só por adivinhar o endereço do servidor.

Segundo, valida sempre o tamanho e o conteúdo da mensagem recebida antes de a enviares à Groq. Um campo de texto sem limite de tamanho permite que um utilizador envie milhares de caracteres numa única mensagem, esgotando o teu limite de tokens por minuto com um único pedido malicioso. Terceiro, ativa CORS de forma restritiva, permitindo apenas os domínios do teu próprio frontend, e nunca uses allow_origins=["*"] num endpoint que aceita pedidos autenticados. Estas três verificações resolvem a maioria dos incidentes reportados por quem publica protótipos de IA sem pensar na camada de exposição pública.

Passo 12: Gerir Limites de Taxa e Repetições Automáticas

O plano gratuito da Groq limita os modelos principais a 30 pedidos por minuto e 8.000 tokens por minuto, segundo a página oficial de limites de taxa. Uma aplicação com vários utilizadores em simultâneo vai bater neste limite mais rápido do que parece. A solução é um retry com espera exponencial:

import time
from groq import RateLimitError

def pedido_com_retry(mensagens, tentativas=3):
    for tentativa in range(tentativas):
        try:
            return client.chat.completions.create(
                model="openai/gpt-oss-20b",
                messages=mensagens,
            )
        except RateLimitError:
            espera = 2 ** tentativa
            print(f"Limite de taxa atingido. A esperar {espera}s antes de repetir...")
            time.sleep(espera)
    raise RuntimeError("Limite de taxa excedido após várias tentativas.")

Se o teu produto vai crescer além do plano gratuito, vale a pena rever também como monitorizar estes limites ao longo do tempo, o mesmo princípio que já detalhámos no tutorial sobre avaliação e benchmark de LLMs, adaptando as métricas para incluir contagem de pedidos por minuto por modelo.

Limites do Plano Gratuito: Quanto Podes Usar Sem Pagar

Antes de escalar qualquer projeto, vale a pena conhecer os números exatos do plano gratuito. A tabela seguinte junta os valores publicados na página oficial de limites de taxa da Groq, atualizada a 22 de setembro de 2026:

ModeloPedidos por minutoTokens por minuto
openai/gpt-oss-20b30 RPM8.000 TPM
openai/gpt-oss-120b30 RPM8.000 TPM
openai/gpt-oss-safeguard-20b30 RPM8.000 TPM
qwen/qwen3.8-27b30 RPM8.000 TPM
meta-llama/llama-prompt-guard-2-22m30 RPM15.000 TPM
whisper-large-v320 RPM2.000 pedidos/dia*

*Para os modelos de áudio, a Groq mede o limite diário em pedidos e em segundos de áudio por hora (7.200 segundos/hora no caso do Whisper), não em tokens por minuto como os modelos de texto. Se o teu caso de uso vai além destes números com regularidade, a Groq disponibiliza planos pagos com limites mais altos, geridos diretamente na consola.

Transcrição de Áudio com Whisper na Groq

Além de texto, a GroqCloud também disponibiliza modelos de transcrição de áudio da família Whisper, com a mesma vantagem de velocidade que já viste nos modelos de chat. Isto é útil para transcrever chamadas de apoio ao cliente, reuniões ou notas de voz dentro da mesma aplicação que já estás a construir.

whisper-large-v3: Precisão Máxima

O whisper-large-v3 é o modelo de transcrição mais preciso da Groq, cobrado a $0,111 por hora de áudio processado, segundo o tarifário oficial. É a escolha certa quando a exatidão da transcrição pesa mais do que a velocidade, por exemplo em contexto legal ou médico.

whisper-large-v3-turbo: Mais Barato e Mais Rápido

O whisper-large-v3-turbo custa $0,04 por hora de áudio, quase um terço do preço do modelo completo, com uma perda de precisão pequena para a maioria dos casos de uso. Para transcrição em tempo real de chamadas ou legendas automáticas, é normalmente a escolha mais equilibrada.

with open("chamada_cliente.mp3", "rb") as ficheiro_audio:
    transcricao = client.audio.transcriptions.create(
        model="whisper-large-v3-turbo",
        file=ficheiro_audio,
        language="pt",
    )

print(transcricao.text)

O parâmetro language="pt" ajuda o modelo a fixar-se no português desde o primeiro segundo de áudio, reduzindo erros de transcrição nas primeiras palavras da gravação.

Modelos de Visão e Multimodais na GroqCloud

A Groq também expandiu o catálogo para além de texto e áudio. Segundo anúncios recentes da empresa, o Qwen3-VL 32B Instruct, capaz de interpretar imagens além de texto, e o MiniMax M2.5 passaram a estar disponíveis na GroqCloud para clientes empresariais. Isto abre a porta a aplicações que combinam leitura de documentos digitalizados, análise de fotografias de produtos ou apoio visual a equipas de suporte, tudo com a mesma latência baixa dos modelos de texto.

Para já, a disponibilidade destes modelos multimodais está associada a contas empresariais, pelo que vale a pena confirmar o acesso na consola antes de planear uma aplicação que dependa deles em produção.

Casos de Uso Reais para a API Groq

A combinação de baixa latência e preço reduzido por token torna a Groq particularmente adequada para três tipos de aplicação. O primeiro é o apoio ao cliente em tempo real, onde cada segundo de espera reduz a satisfação do utilizador. O segundo são agentes de IA que fazem várias chamadas encadeadas ao modelo antes de dar uma resposta final. Nestes casos, a diferença entre um modelo a 200 tokens/s e outro a 1.000 tokens/s multiplica-se a cada passo do agente, e pode significar a diferença entre um agente que responde em 2 segundos e outro que responde em 10.

O terceiro caso de uso são assistentes de voz, onde o áudio do utilizador precisa de ser transcrito, processado por um modelo de linguagem e devolvido como resposta falada, tudo dentro de uma janela de tempo que ainda pareça uma conversa natural. Juntando o Whisper para transcrição e o gpt-oss-20b para gerar a resposta, é possível construir este tipo de pipeline com a latência total a manter-se abaixo de um segundo na maioria dos pedidos, um valor difícil de alcançar com infraestrutura de GPU tradicional gerida internamente.

5 Erros Comuns ao Usar a API Groq

  • Fixar um único nome de modelo no código. Quando a Groq descontinua um modelo, como aconteceu ao groq/compound a 21 de setembro de 2026, toda a aplicação para. Usa sempre a lista de fallback do passo 8.
  • Colocar a chave de API no código-fonte. Mesmo em protótipos, usa variáveis de ambiente desde o primeiro minuto. Uma chave exposta num repositório público costuma ser detetada e usada por terceiros em minutos.
  • Ignorar os limites do plano gratuito. Sem retries, uma aplicação com poucos utilizadores simultâneos já começa a devolver erros 429 em produção.
  • Escolher sempre o modelo maior. Usar o gpt-oss-120b para tarefas simples custa o dobro por token e corre a metade da velocidade do gpt-oss-20b, sem ganho real de qualidade percetível na maioria dos casos.
  • Tratar mal os fragmentos de streaming. Assumir que todo o delta.content vem preenchido causa exceções ou texto cortado a meio de frases.
  • Não fixar a versão do SDK no requirements.txt. Como a Groq atualiza o pacote com frequência, uma instalação sem versão fixa pode trazer mudanças de comportamento inesperadas entre o ambiente de desenvolvimento e o de produção.

Resolução de Problemas: 8 Situações Frequentes

Esta lista cobre os problemas mais reportados por quem está a começar com a API Groq:

  • Erro 401 Unauthorized: a variável GROQ_API_KEY não está definida na sessão atual do terminal, ou a chave foi revogada na consola.
  • Erro 429 Too Many Requests: excedeste o limite de pedidos ou tokens por minuto. Implementa o retry com espera exponencial do passo 12.
  • Erro relacionado com modelo descontinuado: o nome do modelo já não existe. Consulta a lista atualizada em console.groq.com/docs/models e atualiza a lista de fallback.
  • Streaming que para a meio sem erro: confirma se estás a verificar if pedaco: antes de imprimir ou concatenar o conteúdo de cada fragmento.
  • Latência maior que os números oficiais: testa a partir de outra rede ou região. A tabela do passo 6 reflete a infraestrutura da Groq, não a tua ligação à internet.
  • O SDK não encontra a chave mesmo depois de a exportares: abriste um novo terminal ou ficheiro que não recarregou as variáveis de ambiente. Reexporta a chave na sessão atual.
  • Resposta vazia ou cortada: o parâmetro max_tokens está demasiado baixo para a resposta pedida. Aumenta o valor gradualmente.
  • Custo mais alto do que esperado na fatura: confirma se não estás a confundir o preço de entrada com o de saída, e se o modelo grande (120b) não está a ser chamado para tarefas simples que o 20b resolveria mais barato.
  • Erro de CORS no browser ao chamar o endpoint FastAPI a partir do frontend: falta configurar o middleware CORS do FastAPI com o domínio correto do teu frontend, e não apenas testar sempre a partir do mesmo localhost onde o servidor corre.

Dicas Avançadas Para Reduzir Custo e Latência

Depois de teres o básico a funcionar, estas práticas fazem diferença real num produto em produção:

  • Cascata de modelos: usa o gpt-oss-20b para triagem rápida e só chama o gpt-oss-120b ou o kimi-k2-instruct quando a primeira resposta indicar baixa confiança ou complexidade extra.
  • Cache de prompts repetidos: se muitos utilizadores fazem perguntas semelhantes, guarda respostas recentes localmente antes de gastar tokens novos.
  • Streaming sempre em produção: reduz a latência percebida pelo utilizador, mesmo quando a duração total do pedido é igual.
  • Logging estruturado por pedido: regista modelo, tokens de entrada, tokens de saída, duração e custo estimado de cada chamada, para conseguires justificar decisões de modelo com dados reais e não com intuição.
  • Revê a lista de modelos com regularidade: como a Groq atualiza o catálogo com frequência (a migração de qwen3.6 para qwen3.8 é um exemplo recente), agenda uma verificação mensal da documentação oficial.
  • Agrupa pedidos pequenos sempre que possível: várias perguntas curtas e independentes custam mais, em overhead de rede, do que uma única chamada com várias tarefas pedidas ao mesmo tempo no mesmo prompt.
  • Define um limite de tokens de saída realista: um max_tokens generoso a mais não custa nada se o modelo parar sozinho, mas protege-te de respostas anormalmente longas em casos raros de o modelo entrar em repetição.

Projeto Completo: o Chatbot de Ponta a Ponta

Juntando os passos 1 a 11, tens uma aplicação com: chave de API guardada em variável de ambiente, cliente Groq configurado, streaming para a interface, fallback automático entre modelos, medição de tokens por segundo, um pipeline RAG simples com contexto próprio, e um endpoint FastAPI que expõe tudo isto por HTTP. É uma base pequena mas completa, com menos de 100 linhas de código, que já resolve os problemas reais de quem publica uma aplicação de IA sem depender de infraestrutura própria de GPU.

Para fixar as versões exatas usadas neste tutorial e evitar que uma atualização futura do SDK mude o comportamento sem aviso, cria um ficheiro requirements.txt na raiz do projeto:

groq>=1.7.0
fastapi>=0.115
uvicorn>=0.32
openai>=1.50
numpy>=1.26

Com este ficheiro, qualquer colega (ou o teu próprio eu dentro de seis meses) consegue recriar o ambiente com pip install -r requirements.txt. Para colocar o servidor FastAPI a correr fora da tua máquina, plataformas como Render, Railway ou Fly.io aceitam este tipo de aplicação Python praticamente sem alterações, desde que a variável GROQ_API_KEY seja definida nas configurações de ambiente da própria plataforma, nunca dentro do código submetido ao repositório.

ComponenteFicheiro sugeridoModelo recomendado
Chat básicochat_basico.pyopenai/gpt-oss-20b
Streamingchat_stream.pyopenai/gpt-oss-20b
Fallback entre modelosfallback.pyopenai/gpt-oss-120b → 20b → llama-3.3-70b
Pipeline RAGrag_simples.pyopenai/gpt-oss-120b
Servidor de produçãoservidor.pyconfigurável por pedido

Perguntas Frequentes

A Groq é o mesmo que o Grok da xAI?
Não. A Groq é uma empresa de hardware e cloud de inferência fundada em 2016, com chips próprios chamados LPU. O Grok é o modelo de linguagem da xAI, empresa de Elon Musk. São produtos de empresas diferentes com nomes parecidos, o que causa confusão frequente nas pesquisas.

A API Groq é gratuita?
Existe um plano gratuito com limites de 30 pedidos por minuto e 8.000 tokens por minuto para os modelos principais, segundo a documentação oficial de limites de taxa. Para uso em produção com mais tráfego, é preciso um plano pago com limites mais altos.

Qual é a diferença entre gpt-oss-20b e gpt-oss-120b?
O gpt-oss-20b é mais rápido (1.000 tokens/s) e mais barato ($0,075 por milhão de tokens de entrada). O gpt-oss-120b é maior, mais lento (500 tokens/s) e mais caro ($0,15 por milhão), mas costuma dar respostas mais consistentes em tarefas de raciocínio complexo.

Preciso de GPU própria para usar a Groq?
Não. Toda a inferência corre nos servidores da Groq. O teu computador só precisa de fazer pedidos HTTP através do SDK ou de uma chamada REST direta.

A biblioteca da OpenAI funciona diretamente com a Groq?
Sim. Basta apontar o parâmetro base_url do cliente OpenAI para https://api.groq.com/openai/v1 e usar a tua chave da Groq no lugar da chave da OpenAI, como mostrado no passo 7.

Porque é que um modelo que eu estava a usar deixou de funcionar de um dia para o outro?
A Groq descontinua modelos com regularidade, como aconteceu ao groq/compound e ao groq/compound-mini a 21 de setembro de 2026. A solução é sempre manter uma lista de fallback, como no passo 8, e consultar a lista atualizada de modelos antes de assumir que um nome vai continuar disponível para sempre.

Consigo usar a API Groq em Node.js, ou só em Python?
A Groq também publica um SDK oficial para JavaScript/Node.js, com a mesma estrutura compatível com a API da OpenAI usada neste tutorial. A lógica de fallback, streaming e limites de taxa descrita aqui aplica-se da mesma forma, só a sintaxe do cliente muda.

Vale mais a pena usar a Groq ou correr um modelo localmente com o Ollama?
Depende do hardware disponível e do volume de pedidos. Correr um modelo localmente, como descrito no tutorial do Ollama, evita custos por token e mantém os dados na tua máquina, mas fica limitado à potência do teu próprio hardware. A Groq elimina essa limitação de hardware ao custo de pagar por token e enviar os dados para fora da tua rede.

A Groq guarda os dados enviados nos pedidos à API?
As políticas de retenção de dados variam por plano e devem ser confirmadas diretamente na documentação oficial e nos termos de serviço da Groq antes de enviar informação sensível ou dados pessoais de clientes através da API.