Guia de Integração da API Mistral
Mover uma integração estilo Mistral para uma nova URL base exige menos trabalho do que a maioria das equipes espera. Este guia cobre a alteração da URL base, o ID do modelo, streaming, ferramentas, limites de tokens, tentativas de novo e os erros que você mais provavelmente encontrará, com código que você pode executar conforme está.
Última atualização
Resumo
- A mudança é uma URL base e uma chave; o formato da solicitação e da resposta permanece o mesmo.
- Use o id do modelo uncensored e verifique-o com uma única requisição de teste antes de alterar qualquer outra coisa.
- O streaming e a chamada de funções funcionam por meio do mesmo endpoint de conclusões de chat, portanto, os analisadores existentes continuam funcionando.
- Os custos são $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída, cobrados do crédito pré-pago.
Compreendendo a alteração da URL base
Seu código envia solicitações para uma URL base e anexa uma chave. Para mudar para outro endpoint compatível com OpenAI, você altera apenas esses dois valores. O caminho /v1/chat/completions permanece o mesmo, então o corpo da solicitação e o corpo da resposta mantêm sua forma.
Mantenha a URL base antiga em um valor de configuração, em vez de no código. Dessa forma, você pode voltar atrás em um passo, se um problema aparecer em produção.
Compatibilidade com SDK: Clientes OpenAI vs Mistral
A maioria das bibliotecas de clientes aceita uma URL base personalizada. O SDK oficial da OpenAI, LangChain e LlamaIndex todos fazem, e um cliente HTTP simples também funciona. Defina a URL base para https://mistralapibaseurl.com/v1 e passe a nova chave.
- Verifique a versão do SDK, pois versões muito antigas ignoram a configuração da URL base.
- Verifique se o cliente envia a chave no
Authorizationcabeçalho como um token bearer.
Configurando o ID do Modelo
Envie o ID do modelo uncensored. É o único modelo que o serviço oferece, então o id não muda entre solicitações e você não precisa de lógica de seleção de modelo.
Execute uma única solicitação com um prompt curto. Uma resposta e um bloco de uso significam que a URL base, a chave e o id do modelo estão todos corretos.
Implementando Respostas em Streaming
Definir stream: true para receber a resposta como eventos enviados pelo servidor. Cada evento carrega um pequeno trecho de texto, e o evento final carrega os números de uso.
Exiba os chunks conforme chegam e mantenha o texto completo em um buffer, para que a mensagem seja armazenada quando o stream terminar. Meça o tempo até o primeiro token; esse valor mostra o quão responsivo o chat parece para o usuário.
Habilitando Chamada de Funções e Ferramentas
Envie a matriz tools no mesmo formato que você já usa. O modelo retorna uma chamada de ferramenta com um nome de função e argumentos JSON. Execute a função no seu código, envie o resultado de volta como uma mensagem de ferramenta e leia a resposta final.
- Defina uma ferramenta com dois argumentos obrigatórios e teste-a isoladamente.
- Teste um caso onde duas chamadas de ferramentas são necessárias em sequência.
- Valide os argumentos antes de executar qualquer coisa que altere dados.
Gerenciamento de Janelas de Contexto e Tokens
A janela de contexto é de 100.000 tokens. Conversas longas preenchem a janela, então remova turnos antigos ou resuma-os antes que o limite seja atingido. Cada solicitação pode retornar até 16.000 tokens de saída, e o padrão é 2.048, então defina max_tokens para as respostas que você espera.
Conte os tokens a partir do campo de uso de cada resposta. Estimativas baseadas em contagem de palavras frequentemente erram por uma grande margem para código e texto não inglês.
Lidando com Limites de Taxa e Retentativas
Cada chave permite 300 solicitações por minuto e 8 solicitações simultâneas. Quando você ultrapassa o limite, recebe uma resposta 429. Retente apenas as respostas 429 e 5xx, com backoff exponencial e um limite para o tempo total de espera.
Nunca tente novamente um 400 ou um 401, porque a mesma solicitação falhará da mesma maneira novamente. Corrija a solicitação ou a chave primeiro.
Depuração de erros comuns de API
| Status | Causa habitual | O que fazer |
|---|---|---|
| 400 | JSON malformado ou campo desconhecido | Verifique o corpo da solicitação contra o formato que você envia |
| 401 | Chave ausente ou incorreta | Copie a chave novamente e verifique o cabeçalho Authorization |
| 402 | Crédito esgotado | Recarregue o saldo; as recargas começam em $20 |
| 429 | Limite de taxa atingido | Aguarde e tente novamente mais tarde |
Registre o código de status e o ID da solicitação para cada falha, para rastrear um problema rapidamente.
Migrando de APIs de Concorrentes
Planeje a migração em três etapas: um ambiente de teste, uma pequena parte do tráfego ao vivo e, em seguida, a mudança completa. Mantenha ambas as URLs base na configuração durante a etapa intermediária e compare as respostas e a latência nos mesmos prompts.
Compare o custo com base no seu uso real, não nos preços de lista. Multiplique os tokens de entrada e saída do campo de uso por $0.15 e $0.50 por 1M de tokens e compare com sua conta atual.
Perguntas frequentes
Preciso alterar o formato da solicitação?
Não. O endpoint segue o formato de conclusões de chat, portanto as mesmas estruturas de mensagem e ferramentas funcionam. Apenas a URL base e a chave mudam.
Qual model id devo usar?
Use uncensored. É o único modelo no serviço, então o id permanece o mesmo em todas as requisições.
Como obtenho uma chave para testar?
Cadastre-se com Google ou com um e-mail e uma senha. A chave aparece na tela, e a conta começa com $0.50 de crédito de teste válido por 7 dias. Não é necessário cartão.
Como faço para pagar pelo uso?
Recarregue com USDT na TRC20 ou USDC na Base, começando em $20. Crédito bônus aplica-se a partir de $50, e o crédito não expira.
Acesse sua chave
Cadastre-se, recupere sua chave e atualize a URL base. Esse é todo o processo.
