O custo de integração da GLM API é menor do que muitos imaginam: ela oferece interface compatível com OpenAI, e o SDK existente normalmente exige apenas três mudanças — API Key, URL base e nome do modelo. As armadilhas reais não estão em "conseguir chamar", mas em saber se o nome do modelo é válido, como tratar streaming, que formato a chamada de ferramenta retorna e quais parâmetros não podem ser copiados da OpenAI.

Este artigo faz a ponte funcionar com uma requisição mínima e depois cobre streaming, chamadas de ferramenta, diagnóstico de erros e checklist de migração. Todos os exemplos podem ser executados após substituir a chave.

Nota: Zhipu, GLM e BigModel são marcas de seus titulares. Este artigo é apenas uma explicação técnica e não tem vínculo de afiliação, representação ou endosso com a Zhipu. URL base, nomes de modelo, tamanho de contexto e critérios de cobrança podem mudar; valem a documentação oficial da plataforma Zhipu e a página de preços do site.

1. Preparação antes de integrar

Confirme três itens antes de começar:

  • Uma API Key válida e compatível com o tipo de interface a ser chamada.
  • A URL base correta; endereço oficial e endereço do gateway não podem ser misturados.
  • Um nome de modelo realmente disponível no momento; não copie exemplos de artigos antigos.

Para projetos novos, valide autenticação e rede com curl antes de conectar o SDK. Assim, em caso de erro, fica mais fácil distinguir chave, endereço e código.

2. Como preencher a URL base

A URL base da interface oficial compatível com OpenAI da Zhipu normalmente é:

https://open.bigmodel.cn/api/paas/v4

O endereço compatível com OpenAI do ZSQH AI Gateway é:

https://ai.zhongshangqihang.com/v1

Ambos são combinados com o caminho /chat/completions da OpenAI. Não repita o segmento de versão nem /chat/completions no código, e não misture variações com e sem barra final.

Modo Exemplo de URL base Cenário Atenção
Oficial Zhipu https://open.bigmodel.cn/api/paas/v4 Uso exclusivo de GLM com recursos mais recentes Requer conta e saldo oficiais
ZSQH AI Gateway https://ai.zhongshangqihang.com/v1 Entrada unificada e fatura única para vários modelos Requer chave criada no gateway

3. Como escolher o nome do modelo

A série GLM se divide por capacidade em texto, visão, voz e embeddings. Entre os modelos de texto há diferentes faixas: alguns voltados a conversa geral e agentes, outros a baixa latência e alta concorrência, e outros com contexto mais longo. Tomando como exemplo a série GLM-5 listada na documentação atual, são comuns nomes como glm-5.3, glm-5.3-flash e glm-5.2, mas os modelos são atualizados continuamente; os nomes realmente disponíveis seguem o console e a página de preços.

Não escolha apenas "o mais forte". Em atendimento, perguntas e respostas e classificação em lote, faixas de baixa latência costumam ser mais econômicas; análise de documentos longos e agentes complexos pedem configuração superior. Transforme o nome do modelo em item de configuração, não em valor fixo no código, para facilitar trocas futuras.

Se a tarefa envolve compreensão de imagens, escolha um modelo com entrada visual; se envolve busca vetorial, use a série de embeddings. Os caminhos e parâmetros de modelos de texto, visão e vetoriais não são iguais; não force o mesmo corpo de requisição. Antes do lançamento, coloque os modelos candidatos no mesmo conjunto de avaliação e compare acurácia, latência e consumo para decidir principal e reserva.

4. Primeira chamada com curl

Prepare primeiro a variável de ambiente, para evitar que a chave apareça no histórico de comandos:

export GLM_API_KEY="your_key_here"

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $GLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {"role": "system", "content": "Você é um assistente técnico conciso."},
      {"role": "user", "content": "Explique em três frases o que é um gateway de API."}
    ],
    "temperature": 0.6
  }'

Em uma resposta normal, observe três campos: choices[0].message.content é a resposta, usage é o consumo e finish_reason indica o motivo do encerramento. Se retornar 401, verifique a chave e o cabeçalho; se retornar 1211, verifique o nome do modelo.

5. Chamada com o SDK Python e streaming

O SDK da OpenAI precisa ser 1.0 ou superior. Apontando a URL base para a GLM, a chamada é basicamente igual à da OpenAI:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("GLM_API_KEY"),
    base_url="https://open.bigmodel.cn/api/paas/v4",
)

stream = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "Escreva uma apresentação de produto com no máximo cem palavras."}],
    stream=True,
)

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

No streaming, atenção: o primeiro chunk pode conter apenas informações de papel, com content vazio; não presuma que todo chunk tem texto. Com o modo de raciocínio ativado, o conteúdo de raciocínio pode aparecer em reasoning_content, enquanto a resposta final permanece em content; trate os dois separadamente para não exibir o raciocínio diretamente ao usuário final.

6. Chamadas de ferramenta e diferenças de parâmetros

As chamadas de ferramenta seguem o formato tools e tool_choice da OpenAI. Quando o modelo retorna message.tool_calls, é preciso interpretar function.arguments de cada chamada como JSON, executar a função local e devolver o resultado como mensagem de papel tool. Em produção, valide parâmetros e controle timeout; não confie diretamente nos parâmetros gerados pelo modelo.

Ao migrar da OpenAI, observe algumas diferenças: a faixa de temperature costuma ser de 0 a 1, e o valor 0 pode não ter efeito; o padrão é cerca de 0.6; alguns recursos novos exigem envio via extra_body. Parâmetros específicos seguem a documentação oficial de compatibilidade com OpenAI.

Em streaming, trate também a desconexão do cliente. Quando o usuário fecha a página, o servidor deve cancelar a requisição upstream o quanto antes para evitar geração e cobrança desnecessárias; se o negócio exige conclusão integral, mova a tarefa para uma fila em segundo plano em vez de depender da conexão do front-end.

7. Tabela de erros comuns

Sintoma Causa possível Tratamento
401 / 1000 Chave errada, tipo incompatível Verificar tipo de chave e cabeçalho
1211 Nome de modelo inexistente ou não ativado Consultar modelos disponíveis no console
1261 Entrada acima do limite de contexto Comprimir o prompt ou dividir em partes
1302 / 1305 Limite da conta ou plataforma ocupada Reduzir concorrência, retry com backoff
1113 Conta inadimplente Recarregar e tentar novamente
Timeout de conexão DNS, proxy ou caminho de rede Usar curl para isolar a camada de rede

Retry só funciona para 429, 5xx e timeout de rede. Erros como 401, 1211 e 1261 não melhoram com nova tentativa e apenas consomem tempo e cota.

8. Checklist de migração da OpenAI

  1. Faça backup dos prompts, parâmetros de modelo e conjunto de avaliação atuais.
  2. Crie uma chave exclusiva para a GLM; não reutilize chave de outro fornecedor.
  3. Transforme URL base e nome de modelo em itens de configuração.
  4. Compare qualidade, latência e consumo com o mesmo lote de amostras.
  5. Verifique compatibilidade de parsing de streaming, chamadas de ferramenta e saída JSON.
  6. Ajuste retry, timeout e concorrência e observe por uma semana antes de mudar tudo.

9. Perguntas frequentes (FAQ)

1. A GLM API é totalmente compatível com a OpenAI?

As interfaces mais usadas são compatíveis, mas ainda existem diferenças de faixa de parâmetros, campos de raciocínio e alguns recursos avançados. Valide item a item conforme a documentação oficial de compatibilidade e não presuma comportamento idêntico.

2. Devo colocar barra no final da URL base?

A documentação oficial já apresentou as duas formas. O SDK normalmente trata isso automaticamente. O importante é não repetir o caminho; escolha uma forma e padronize no projeto.

3. O streaming entrega o processo de raciocínio?

Alguns modelos no modo de raciocínio retornam reasoning_content. Exibir ou não depende do design do produto; para usuários finais, normalmente só a resposta final é mostrada.

4. A chamada de ferramenta usa o mesmo formato da OpenAI?

A definição de ferramentas e a estrutura de retorno seguem basicamente o formato da OpenAI, mas detalhes de parâmetros podem variar por modelo. Antes do lançamento, faça um teste de regressão com ferramentas reais.

5. Os nomes de modelo são iguais no oficial e no gateway?

Na maioria dos casos usa-se o mesmo conjunto de nomes, mas se o gateway libera um modelo específico e se suporta um parâmetro depende do console do gateway e da página de preços.

Leituras relacionadas