Como usar o DeepSeek por meio de uma API compatível com OpenAI

By TokuseTokuse
IAAPIDeepSeekTutorial

O DeepSeek já oferece um endpoint no estilo OpenAI. A questão prática é onde guardar a URL base, como lidar com nomes de modelo e o que testar antes de mover o tráfego de produção.

Experimente o Tokuse: crie uma conta gratuita e envie sua primeira requisição por um único endpoint compatível com OpenAI.

Este guia usa o Tokuse como exemplo de gateway porque seu catálogo público de modelos inclui deepseek-flash e deepseek-v4-pro e expõe uma API compatível com OpenAI em:

https://tokuse.com/v1

O conjunto de modelos, as cotas e o preço exibidos para sua conta podem mudar. Consulte o catálogo atual antes da implantação.

O que significa compatibilidade com OpenAI

Compatibilidade significa que os SDKs OpenAI existentes normalmente conseguem enviar requisições apenas alterando a URL base e o nome do modelo. Sua aplicação pode manter uma estrutura de cliente familiar:

SDK -> OpenAI-compatible base URL -> model alias -> provider

O gateway recebe a requisição, resolve o modelo, anexa a credencial do provedor e devolve uma resposta normalizada. Assim, mudanças de provedor ficam fora do código do produto.

Compatibilidade não significa que todo parâmetro específico de provedor funcione da mesma forma. Teste streaming, chamadas de ferramentas, saída JSON, códigos de erro e contabilização de tokens com o SDK e o modelo exatos que você pretende usar.

Configuração em Python

Instale o SDK OpenAI:

pip install openai

Defina a chave do Tokuse no servidor:

export TOKUSE_API_KEY="YOUR_KEY"

Depois use a interface normal de chat completions:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKUSE_API_KEY"],
    base_url="https://tokuse.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {
            "role": "system",
            "content": "Return a compact JSON object. Do not add commentary.",
        },
        {
            "role": "user",
            "content": "Extract the company name and plan from: Acme Pro, billed monthly.",
        },
    ],
    response_format={"type": "json_object"},
    max_tokens=200,
)

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

Use a URL base sem /chat/completions. O SDK adiciona o caminho do endpoint sozinho.

Configuração em Node.js

npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKUSE_API_KEY,
  baseURL: "https://tokuse.com/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-flash",
  messages: [
    {
      role: "user",
      content: "Summarize this support ticket in one sentence.",
    },
  ],
  max_tokens: 120,
});

console.log(response.choices[0].message.content);

Mantenha a chave em variáveis de ambiente do lado do servidor. Não a exponha em bundles de navegador, aplicativos móveis ou logs de build.

Escolha o modelo pela tarefa

Use o deepseek-flash primeiro para extração rotineira, classificação, resumos e etapas de fluxo de trabalho em alto volume. Teste o deepseek-v4-pro em tarefas de raciocínio complexo ou de longo horizonte em que a rota mais barata não passar na sua avaliação.

A decisão de roteamento deve se basear na conclusão bem-sucedida da tarefa, não no prestígio do modelo. Compare qualidade, tamanho da saída, latência, novas tentativas e custo por tarefa bem-sucedida.

O preço de cache hit do DeepSeek torna prompts estáveis especialmente importantes. A tarifa oficial fora do horário de pico é de $0.003/M em cache hit contra $0.15/M em cache miss; no Tokuse, as tarifas base atuais do deepseek-flash são $0.274/M de entrada e $1.096/M de saída, com cache hits em torno de $0.006/M. Consulte o modelo completo de preços e cache do DeepSeek antes de escolher um orçamento.

Teste estes modos de falha

401 ou token inválido

Confirme que a chave pertence à conta do gateway e não tem espaços acidentais. Gire a chave se ela já tiver sido commitada ou registrada em log.

404 em chat completions

Verifique tanto a URL base quanto o caminho do SDK. https://tokuse.com/v1 é a URL base. Não acrescente o caminho /chat/completions do SDK, a menos que seu cliente HTTP espere um endpoint completo.

Modelo não suportado

Consulte o catálogo de modelos atual ou o painel. Os aliases de modelo podem variar conforme a conta e a disponibilidade. Um modelo que funcionava durante o piloto pode ser desativado depois.

429 ou erros de cota

Adicione backoff exponencial limitado com jitter. Não tente novamente indefinidamente. Diferencie limites por minuto de erros de saldo ou cota da conta.

Saída truncada

Verifique finish_reason, o limite de tokens de saída e o esquema solicitado. Um limite maior pode aumentar o custo sem melhorar o resultado. Meça os dois.

Falhas de streaming

Registre a latência do primeiro token e o ponto de falha. Depois que os tokens chegam ao usuário, uma nova tentativa transparente pode duplicar texto. Prefira um erro visível ou uma continuação controlada.

Checklist de produção

  • Use chaves separadas para desenvolvimento e produção.
  • Nunca inclua chaves de provedor ou gateway no código cliente.
  • Registre IDs de requisição, modelo, status, latência, tokens de entrada, tokens de saída e número de tentativas.
  • Oculte prompts, respostas e cabeçalhos de autorização dos logs padrão.
  • Fixe os aliases de modelo e teste mudanças antes do rollout.
  • Adicione timeouts, orçamentos de nova tentativa e um kill switch.
  • Compare o custo por tarefa bem-sucedida, não o custo por requisição.
  • Comece com uma pequena porcentagem do tráfego e meça a qualidade com um conjunto de avaliação fixo.

Comece com um único endpoint

O Tokuse oferece um endpoint compatível com OpenAI, um catálogo de modelos, gestão de uso e um painel administrativo para equipes que avaliam vários modelos de IA. Comece com o catálogo atual e uma chave de teste e depois leve uma carga de trabalho de baixo risco pelo gateway antes de expandir.

Crie uma conta Tokuse e inspecione os modelos atuais

Guias relacionados de custos e migração

Fontes