Endpoint nativo da Zhipu vs LiteLLM: qual usar

O problema

Ao longo da série sobre Claude Code + Zhipu, eu fiz questão de usar o LiteLLM como intermediário (o que no mundo da tecnologia chamamos de proxy — pense nele como um “tradutor” que roda direto no seu computador). Por ser um programa em Python, ele exige configuração e ocupa uma “porta” específica da sua máquina (a porta 4001, que funciona como uma porta de entrada para conexões locais).

Parece um trabalho desnecessário quando você descobre que a própria Zhipu lançou um endpoint nativo (/api/anthropic) — ou seja, um endereço direto na internet que “simula” a API da Anthropic (o sistema que permite que programas conversem com a IA). Em tese, bastaria apontar o Claude Code direto para esse endereço, sem precisar do tradutor intermediário, sem Python e sem ocupar a porta 4001.

Então eu resolvi testar. E descobri que a escolha não é “o método nativo é mais moderno e o proxy é ultrapassado”. A verdade é: “o nativo serve para um caso, e o proxy serve para outro”. Eu errei na primeira vez que achei que podia simplesmente jogar o LiteLLM fora.

O que é o endpoint nativo

A Zhipu percebeu que muita gente no Ocidente usava o Claude Code e queria pagar mais barato. Por isso, eles criaram uma camada de tradução dentro dos próprios servidores deles: você aponta a variável de ambiente ANTHROPIC_BASE_URL (uma espécie de atalho de configuração no seu sistema) direto para https://open.bigmodel.cn/api/anthropic, usa sua chave de acesso ZHIPU_API_KEY, e a Zhipu cuida do resto. Ela recebe os dados no formato da Anthropic, converte internamente para o modelo dela (o GLM), processa tudo e devolve a resposta convertida. É como ter o “LiteLLM rodando direto nos servidores da Zhipu”.

A vantagem é bem clara: uma configuração super simples de 5 minutos, sem precisar instalar outros programas ou depender do Python. Você só precisa salvar duas variáveis no .bashrc (um arquivo que guarda suas configurações do terminal), rodar o comando claude e pronto, já está no ar.

Onde o nativo brilha

Setup imediato. Sem precisar instalar dependências no seu computador. Adicionou duas variáveis de ambiente e está tudo pronto.
Zero latência de proxy. Como a tradução é feita direto no servidor deles, você elimina o tempo de espera (latência) que o LiteLLM leva para processar os dados localmente (que é pequeno, mas existe).
Menos peças pra quebrar. Sem precisar manter um programa em Python rodando, sem ocupar portas no computador e sem precisar atualizar versões do LiteLLM.

Se o seu caso é “quero usar o Claude Code com a Zhipu no menor tempo possível”, o endpoint nativo é o vencedor.

O problema fatal — pra quem tem Developer Plan

Aqui é onde eu quase joguei o LiteLLM fora sem motivo. O endpoint nativo foi desenhado para um público-alvo específico: desenvolvedores no plano Pay-As-You-Go (aquele modelo em que você coloca saldo no cartão e paga centavos por token — os pedacinhos de texto processados pela IA).

Se você paga por token consumido, o endpoint nativo é perfeito. Agora, se você assina o Developer (Coding) Plan (uma assinatura mensal pré-paga, com uma cota fixa de uso), o endpoint nativo tem um defeito grave, pelo menos no momento em que escrevo: ele não suporta o roteamento (redirecionamento) para /api/coding/paas/v4 — que é o endereço exclusivo para os assinantes desse plano.

Suas requisições (os pedidos enviados à IA) precisam bater em /api/coding/paas/v4 para consumir a cota da sua assinatura. Mas o endpoint nativo /api/anthropic não consegue ser forçado a mandar os dados para o caminho interno do Coding Plan. O resultado: o sistema tenta descontar do seu saldo avulso. Se o seu saldo avulso for zero (o que é normal para quem paga a assinatura), você recebe mensagens de erro como RateLimit Exceeded (limite excedido) ou Payment Required (pagamento necessário) — mesmo tendo milhões de tokens disponíveis no seu plano.

É o mesmo bug que descrevi no artigo sobre RateLimit, só que dessa vez não é um erro de configuração do LiteLLM — é uma limitação do próprio endpoint nativo da Zhipu.

O segundo problema: granularidade de mapeamento

Mesmo que o endpoint nativo resolvesse o problema do plano de assinatura, existe uma segunda diferença. O LiteLLM te dá um controle granular (ou seja, detalhado item por item): você pode mapear o modelo principal claude-sonnet para usar o poderoso GLM-4-Plus e os modelos secundários claude-haiku para usar o GLM-Turbo, poupando sua cota nas tarefas mais simples e mecânicas.

O endpoint nativo não permite isso. Ele faz um mapeamento fixo e automático — você não consegue dizer de forma transparente “quero que este apelido vá para determinado modelo GLM”. Você fica preso à escolha que a Zhipu decidiu internamente.

Para quem usa Claude Code com subagentes (assistentes secundários) trabalhando em paralelo, isso importa: sem esse controle detalhado, os subagentes invisíveis acabam usando o modelo que a Zhipu escolheu, e não o que você gostaria de ter definido.

O veredito, na prática

Use o endpoint nativo (/api/anthropic) se:

Você é um usuário casual.
Você usa a Zhipu na modalidade Pay-As-You-Go (paga exatamente o que consome, sem assinatura).
Você quer a configuração mais rápida e não se importa em pagar centavos por token.

Use o LiteLLM (proxy local) se:

Você assina o Developer / Coding Plan (precisa forçar o caminho /api/coding/paas/v4).
Você quer controle detalhado para mandar o modelo principal para um tipo de GLM e os subagentes para outro.
Você quer interceptar e registrar (logar) as requisições para analisar e corrigir problemas (debug).

O LiteLLM dá um pouco de trabalho para configurar na primeira vez. Mas o controle que ele te dá sobre custos e rotas vale cada minuto — especialmente quando o endpoint nativo simplesmente não atende ao seu caso de uso.

O que aprendi

A lição que fica além deste caso técnico é: “oficial” e “adequado” não são sinônimos. O endpoint nativo é a solução oficial da Zhipu — mais moderna, mais limpa e melhor documentada. Mas ela é oficial para um caso específico (pay-as-you-go), não para o meu (Developer Plan). Assumir que “oficial = melhor para mim” teria me feito jogar fora o proxy que realmente funciona para a minha necessidade.

E o segundo aprendizado, mais geral: antes de migrar de abordagem, entenda qual caso de uso cada uma atende. Eu ia migrar para o nativo achando que era uma “atualização”. Mas migrar para uma solução que não atende ao seu caso é um retrocesso disfarçado de avanço. A pergunta certa não é “qual é mais moderno?”, mas sim “qual atende às minhas limitações?”.