SDK da API DeepSeek: use o SDK da OpenAI e altere endpoints

Por que o SDK da OpenAI é o SDK da API DeepSeek

Quando as pessoas pesquisam por um SDK da API DeepSeek, elas esperam um pacote com o nome do fornecedor. Na prática, a própria documentação da DeepSeek descreve chamar sua API por meio do SDK da OpenAI com uma URL base diferente, porque a API segue o formato de solicitação e resposta da OpenAI. Consulte a documentação atual deles para a URL base e os nomes dos modelos exatos; eles são a autoridade sobre o serviço deles.

A consequência é útil. Qualquer código escrito contra a biblioteca de cliente da OpenAI pode falar com qualquer servidor que implemente os mesmos endpoints, que aqui são POST /v1/chat/completions, POST /v1/responses e GET /v1/models. Mover-se entre provedores torna-se uma alteração de configuração em vez de uma reescrita. O restante deste artigo mostra o padrão em Python, Node e curl, em seguida, uma estrutura que torna a troca trivial.

Configuração em Python

Instale o pacote oficial e aponte-o para o endpoint:

Copypip install openai

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.deepseekapi.top/v1",
    api_key="YOUR_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain idempotency in two sentences."},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

Obtenha uma chave na página de chave de API. Usuários novos podem solicitar $0,50 de crédito de teste com um clique, sem cartão. O artigo API DeepSeek em Python aprofunda o assunto sobre esta linguagem, incluindo tratamento de erros.

Configuração em Node.js

Copynpm install openai

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseekapi.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "List four uses of a message queue." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

O padrão é idêntico: base URL, chave, modelo. O streaming retorna Server-Sent Events, e a biblioteca as transforma em um iterador assíncrono. A chamada de funções segue o mesmo esquema de outras APIs compatíveis com OpenAI: passe tools, leia tool_calls em streaming e retorne resultados como mensagens role: "tool".

Tornar o endpoint substituível

Não codifique os três valores. Leia-os do ambiente e envolva a criação do cliente em uma única função. Assim, mover-se de um endpoint para outro significa editar um arquivo .env, não o código-fonte.

Copyimport os
from openai import OpenAI

def make_client():
    return OpenAI(
        base_url=os.environ.get("LLM_BASE_URL", "https://api.deepseekapi.top/v1"),
        api_key=os.environ["LLM_API_KEY"],
    )

MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt: str) -> str:
    r = make_client().chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,
    )
    return r.choices[0].message.content

Agora, um provedor diferente precisa apenas de três variáveis de ambiente. Os SDKs oficiais também leem OPENAI_API_BASE e OPENAI_API_KEY em algumas versões, mas variáveis explícitas são mais claras e evitam surpresas quando você executa vários provedores ao mesmo tempo.

Se você usar TypeScript ou outra linguagem, a ideia é a mesma: uma função de fábrica, três variáveis, sem nomes de provedores espalhados pela base de código. Um erro comum é deixar o nome do fornecedor vazar para nomes de funções, mensagens de log e nomes de variáveis, o que torna uma troca posterior mais difícil do que o necessário. Nomeie as coisas pelo trabalho (ask, summarise) em vez do provedor.

Mantenha um teste pequeno que envie um prompt fixo por meio de ask() e verifique se há uma resposta não vazia. Execute-o após cada alteração de endpoint; ele captura URLs e chaves errados em segundos.

O que permanece igual e o que muda ao trocar

A última linha é a que pega as pessoas. Um endpoint é compatível no nível do protocolo, não no nível do comportamento. Dois provedores podem aceitar solicitações idênticas e dar respostas muito diferentes. O modelo aqui é um único modelo de pesos abertos de um provedor independente, ajustado para responder sem recusas de conteúdo para uso adulto legal, e não é a API oficial da DeepSeek ou de qualquer outro laboratório. Re-teste prompts que você ajustou para outro modelo.

Recursos que este endpoint possui e não possui

• Suportado: conclusões de chat, o formato de respostas, listagem de modelos, streaming, chamada de funções, modo JSON (response_format com json_object), e passagem de temperature, top_p, stop, seed e as penalidades.
• Não oferecido: geração de imagem, áudio ou vídeo, embeddings, ajuste fino.
• Limites: janela de 100.000 tokens, corpo máximo de 8 MB, 8 requisições simultâneas e 300 por minuto em uma chave completa (2 e 60 em uma chave de teste).
• Erros: HTTP 429 com o código rate_limited ou concurrency, e um cabeçalho Retry-After: 5 em sobrecarga temporária.

Se o seu código chamar um endpoint de embeddings, você precisará de outro provedor para essa parte e pode manter o chat aqui. Dividir por tarefa é um motivo comum para o padrão de variáveis de ambiente acima.

Uma lista de verificação de migração

Quando você troca um endpoint por outro em um projeto existente, percorra uma lista curta em vez de alterar tudo de uma vez.

1. Prove o endpoint. Envie uma solicitação com curl e confirme que você recebe texto de volta. Chame GET /v1/models e verifique se o ID do modelo uncensored está listado.
2. Altere os três valores. Base URL, chave, nome do modelo, nada mais. Não toque nos prompts ainda.
3. Execute seus testes existentes. Se você tiver testes de regressão de prompt, execute-os e anote quais falham. As falhas geralmente são comportamentais, como um formato de saída diferente, não erros de protocolo.
4. Verifique os parâmetros. Remova as opções que o endpoint não precisa. Mantenha temperature, top_p, stop e seed se você os usar.
5. Teste streaming e ferramentas separadamente. Bugs de streaming frequentemente se escondem no código do cliente que assume um layout específico de chunks. As chamadas de ferramentas precisam de um schema que o modelo siga bem, então teste com suas funções reais.
6. Meça custo e latência no tráfego real. Compare um dia de requisições, não um único prompt.

Faça isso em um branch ou com um feature flag que roteia uma pequena parte do tráfego para o novo endpoint. Como o código do cliente é compartilhado, reverter é alterar uma variável de ambiente.

Trate retries e leia o uso

Os SDKs fazem retry de algumas falhas por padrão, mas você ainda deve lidar com 429 manualmente, já que os limites de concurrency são reais em produção. Capture a exceção de rate-limit, aguarde o número de segundos em Retry-After (5 em overload) e faça retry algumas vezes. Requisições falhas não são cobradas, então retries são seguros para seu saldo.

Registre usage.prompt_tokens e usage.completion_tokens em toda chamada. O preço é $0,15 por 1M input tokens e $0,50 por 1M output tokens, então uma chamada com 2.000 input e 600 output tokens custa 2.000 × $0,15 / 1M + 600 × $0,50 / 1M = $0,0003 + $0,0003 = $0,0006. Os response headers também incluem X-Balance-USD para o crédito restante. Veja a página de preços para recargas e bônus, e a documentação para a lista completa de parâmetros.

Editores e outras ferramentas

Os três valores são transferidos para qualquer ferramenta com uma configuração de provedor compatível com OpenAI. O artigo sobre usar uma API estilo DeepSeek no Cursor mostra como configurar um editor assim. Em cada ferramenta, os campos são rotulados de forma ligeiramente diferente, mas você sempre insere a URL base terminando em /v1, a chave e o nome do modelo.

Mais guias

• Custo da API DeepSeek vs API OpenAI: Exemplos Práticos
• Chave de API DeepSeek: Acesso à API LLM sem censura