Como implantar o deepseek-v3.1 localmente via ollama: The Eastest Guide

O DeepSeek-V3.1 é um modelo de linguagem MoE híbrido, "pensante/não pensante" (671 bilhões no total, aproximadamente 37 bilhões ativados por token) que pode ser executado localmente se você usar o provedor/quantização e as ferramentas corretos. Abaixo, explico o que é o DeepSeek-V3.1, os requisitos de hardware/software, tutoriais passo a passo para execução local (exemplos de Ollama + llama.cpp) e como implantar e usar o Modo de Pensamento (O <think>/</think> modelo de bate-papo) com exemplos de código que você pode copiar/colar.

O que é DeepSeek-V3.1?

DeepSeek-V3.1 é a versão v3.1 da família MoE (Mixture-of-Experts) do DeepSeek. Foi projetado como um modelo de inferência híbrido que suporta dois modelos/modos de conversação — Pensando e Não-pensamento — do mesmo ponto de verificação, alterando o modelo de bate-papo. A arquitetura do modelo remonta ao design do DeepSeek-V3 MoE (671 bilhões de parâmetros no total; aproximadamente 37 bilhões de parâmetros ativados por token para inferência) e adiciona melhorias pós-treinamento para uso de ferramentas, habilidades de agentes e tratamento de contexto longo.

Destaques rápidos de recursos

Híbrido Pensando / Não pensando modos (alternados pela tokenização do modelo de bate-papo).
Arquitetura MoE: grande contagem total de parâmetros, mas parâmetros ativados limitados por token (permite eficiência).
Aumentos pós-treinamento para chamadas de ferramentas e fluxos de trabalho de agentes (formato de chamada de ferramenta e modelos de agentes documentados nos ativos do modelo).

O que preciso para executar o DeepSeek-V3.1 localmente?

Executando o completa O DeepSeek-V3.1 (pontos de verificação brutos) é pesado — o treinamento/armazenamento de pontos de verificação e orquestração de inferências não são triviais. Mas existem caminhos práticos:

Hardware

Inferência distribuída completa (pesquisa/cluster): várias GPUs de alta memória (classe A100/H800) ou um cluster de GPU com serviço paralelo de modelo (típico para mais de 600B pontos de verificação). Use somente se estiver executando clusters de pesquisa de produção.
Opções locais práticas: use o parâmetros ativados perspectiva (≈37B ativado) ou uma compilação dinâmica GGUF/1 bit quantizada. Quantizações da comunidade (dinâmica de 1 bit/GGUF) reduzem significativamente os requisitos de disco+RAM — por exemplo, publicações da comunidade relatam a compactação de um ponto de verificação de 720 GB para ~170 GB de GGUF para uma variante quantizada. Isso torna a inferência de GPU local de servidor único viável para desktops/servidores com bons recursos.

Bottom line: espere um fluxo de trabalho de modelo grande (dezenas a centenas de GB de disco para artefatos quantizados); para VRAM de GPU, use variantes quantizadas e tenha como meta ≥24–48 GB de VRAM para uma taxa de transferência razoável; caso contrário, use CPU+swap com compensações de desempenho.

Software e ferramentas

Python 3.10+ (para ferramentas de transformador/tokenizador e scripts personalizados).

transformers (para funções de tokenizador e auxiliar) — o cartão de modelo mostra exemplos usando transformers.AutoTokenizer.

Um ou mais tempos de execução de inferência local:

Ollama (fácil: ollama pull / ollama run integração; algumas compilações do DeepSeek no Ollama exigem versões de pré-lançamento (consulte a nota sobre o modelo/ollama). O Ollama se tornou um executor local padrão para modelos da comunidade.
llama.cpp / ggml pilhas ou llama-server para arquivos GGUF quantizados — ótimo para execução direta de GGUF.
pilhas de geração de texto / Triton / FlashAttention para inferência de GPU de alto desempenho (configurações avançadas).

Disco: grande espaço livre para arquivos de modelo (dezenas → centenas de GB, dependendo da quantização).

Artefatos do modelo (qual arquivo obter)

Safetensors oficiais / variantes BF16 / FP8 / GGUF: O Hugging Face hospeda artefatos do modelo V3.1 e múltiplas quantizações. Se você precisar de um arquivo GGUF/quantizado para llama.cpp, procure por uma versão de quantização da comunidade (ou um script de conversão de safetensors → GGUF) — o cartão do modelo lista variantes quantizadas.

Como preparo o modelo para inferência local?

Abaixo estão as etapas de preparação recomendadas, organizadas do simples ao avançado.

Etapa 1 — Escolha um tempo de execução (recomendação)

Teste rápido/iniciante: Ollama — configuração mínima: baixar, executar o modelo, chamar a API. Observação: algumas compilações do DeepSeek V3.1 mencionam o Ollama v0.11.7 como necessário para recursos específicos.
Controle avançado/de baixo nível: llama.cpp + GGUF quant (se uma quantização GGUF estiver disponível). Isso lhe dá controle de inferência direta e integração com llama-server.

Etapa 2 — Baixe o modelo

Se você usa Ollama:

# install ollama (see https://ollama.com/docs)

# Pull the model (this downloads the model to your machine)
ollama pull deepseek-ai/DeepSeek-V3.1
# or a specific tag: ollama pull deepseek-ai/DeepSeek-V3.1:quant-q4_0

(Ollama's run será puxado automaticamente se não estiver presente; pull permite que você controle o tempo.)

Se você usar Hugging Face + llama.cpp:

# Example: download via huggingface-cli or hf_transfer

pip install huggingface_hub
hf_hub_download(repo_id="deepseek-ai/DeepSeek-V3.1", filename="DeepSeek-V3.1.gguf")
# or use a community quant file (gguf) referenced on the Hugging Face model page

Hugging Face lista artefatos do modelo, modelos e quantizações no cartão do modelo.

Etapa 3 — Converter / quantizar (opcional)

Se você encontrar apenas tensores de segurança ou artefatos BF16, mas precisar de GGUF para llama.cpp, use os scripts de conversão em llama.cpp (ou ferramentas da comunidade) para converter → quantizar. Existem ferramentas da comunidade para quantização dinâmica de 1 bit que preservam a precisão enquanto reduzem o tamanho; veja as postagens da comunidade que relatam até ~170 GB.

Como executar o DeepSeek-V3.1 localmente? (Tutoriais práticos de execução)

Eu vou mostrar Ollama (fácil, recomendado) e lhama.cpp Exemplos (GGUF) mais um pequeno exemplo em Python usando os auxiliares do tokenizador de cartão modelo.

A — Correndo com Ollama (início rápido)

Instale o Ollama (siga as instruções oficiais).
Puxe e execute o modelo:

# pull model to disk (optional; run will pull automatically)

ollama pull deepseek-ai/DeepSeek-V3.1

# start an interactive session (runs model and exposes local API)

ollama run deepseek-ai/DeepSeek-V3.1

Faça uma solicitação HTTP ao servidor Ollama local:

# curl usage example (local Ollama server usually listens on port 11434)

curl -sS -X POST 'http://localhost:11434/api/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"deepseek-ai/DeepSeek-V3.1",
    "prompt":"Explain the difference between thinking and non-thinking mode in DeepSeek.",
    "max_tokens":256
  }'

Os padrões de CLI e API do Ollama são projetados para serem simples: ollama run puxará se necessário e iniciará um servidor de modelo. Consulte a documentação e as páginas de modelo do Ollama para dicas de memória e nomes/tags exatos de modelo.

B — Executando um GGUF quantizado via llama.cpp

Construção llama.cpp com CUDA (opcional) ou CPU:

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
# for CUDA:

make clean && make LLAMA_CUBLAS=1
# or CPU only:

make

Coloque o arquivo do modelo GGUF em um caminho e execute:

./main -m /path/to/DeepSeek-V3.1.q4_K_M.gguf \
  -p "Explain how to enable thinking mode." \
  --temp 0.2 --n_predict 512

Para uso do servidor, llama-server (projeto comunitário) pode expor um ponto de extremidade HTTP:

llama-server -m /path/to/DeepSeek-V3.1.q4_K_M.gguf
# then POST to the server like:

curl -X POST "http://localhost:8080/api/v1/generate" -d '{"prompt":"Hello","max_tokens":200}'

Use quantizações GGUF da comunidade (q4/q8/1 bit dinâmico) para se adequar aos orçamentos de GPU/CPU; llama.cpp O repositório fornece ferramentas de conversão e orientação.

C — Exemplo em Python usando o tokenizer + modelo de bate-papo

O cartão modelo Hugging Face fornece um tokenizer.apply_chat_template ajudante e mostra como codificar uma conversa com thinking=True. Aqui está um exemplo mínimo de Python adaptado do cartão de modelo:

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("deepseek-ai/DeepSeek-V3.1")

messages = [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Who are you?"},
    {"role": "assistant", "content": "<think>Hmm</think>I am DeepSeek"},
    {"role": "user", "content": "1+1=?"}
]

# apply thinking chat template

s = tokenizer.apply_chat_template(messages, tokenize=False, thinking=True, add_generation_prompt=True)
print(s)  # the template includes the special <think> token placement

Você pode então alimentar o prompt tokenizado em seu tempo de execução de inferência (Ollama/llama.cpp/TGI), dependendo da sua pilha.

Como o Thinking Mode funciona e como implantá-lo localmente?

Usos do DeepSeek-V3.1 modelos de bate-papo que contêm um token de pensamento especial (por exemplo, <think> e </think>). O modelo determina se o modelo está no modo Pensante ou Não Pensante:

Não-pensamento lugares de modelo </think> no prefixo assistente, que instrui o modelo a produzir respostas diretas (o formato de chamada de ferramenta é suportado em não-pensamento).
Pensando lugares de modelo <think> no prefixo assistente que faz com que o modelo emita sinais intermediários no estilo de cadeia de pensamento interna (o modelo é treinado para usar essa sequência de tokens para raciocinar internamente e produzir respostas multietapas de maior qualidade). O cartão do modelo Rosto Abraçado documenta esses tokens exatos e o tokenizer.apply_chat_template(..., thinking=True) API.

Alternância programática (exemplos)

A — Com o tokenizador (Python):

# thinking=True or thinking=False changes how the prompt is formatted

prompt_thinking = tokenizer.apply_chat_template(messages, thinking=True, add_generation_prompt=True)
prompt_non_thinking = tokenizer.apply_chat_template(messages, thinking=False, add_generation_prompt=True)

alimentação prompt_thinking ao seu tempo de execução de inferência para obter o comportamento de pensamento.

B — Com prompt bruto (llama.cpp / manual):

inserção <think> antes que o assistente vire quando você solicitar:

<｜begin_of_sentence｜>You are a helpful assistant<｜User｜>How to optimize this code?<｜Assistant｜><think>

(O enquadramento exato do token está no cartão modelo — você deve respeitar o espaçamento e os marcadores especiais se usar o modelo bruto.)

C — Com Ollama (alternância de interface do usuário):
A demonstração web oficial do DeepSeek e as notas de lançamento mencionam um botão de alternância "DeepThink" para alternar os modos na interface de usuário hospedada. Localmente, o Ollama ou seu aplicativo devem replicar esse comportamento alternando o modelo de bate-papo (ou seja, alterando o prompt que você envia para o tempo de execução entre os dois formulários tokenizados). Se você executar o DeepSeek via Ollama, poderá implementar isso em seu aplicativo mantendo dois modelos de prompt (pensante vs. não pensante) e alternando qual você passa pela API do Ollama.

Como implantar o Modo de Pensamento como um agente (chamadas de ferramentas, agentes de código)?

Documentos do DeepSeek-V3.1 chamada de ferramenta e agente modelos nos ativos do modelo. O modelo espera que as ferramentas sejam apresentadas em um formato JSON/instrução específico e suporta o encadeamento de múltiplas chamadas de ferramentas em um único turno, se você seguir os tokens de wrapper exatos descritos no cartão do modelo.

Exemplo: wrapper de chamada de ferramenta simples (pseudo)

O modelo especifica um bloco descritor de ferramenta e um estrito tool_calls_begin / tool_call_begin formato. Um exemplo mínimo (conceitual):

## Tools

You have access to the following tools:

### web_search

Description: Query the web
Parameters: {"q": "string"}

<｜begin_of_sentence｜>{system prompt}

## Tools

...tool descriptions...

<｜User｜>Find the population of Tokyo<｜Assistant｜></think>
<｜tool_calls_begin｜><｜tool_call_begin｜>web_search<｜tool_sep｜>{"q":"population of Tokyo 2025"}<｜tool_call_end｜><｜tool_calls_end｜>

A saída da ferramenta deve então ser realimentada ao modelo na próxima volta, seguindo o formato prescrito do modelo (consulte assets/search_tool_trajectory.html na página do modelo para o fluxo exato). A implementação de agentes requer orquestração programática: chamar a ferramenta → capturar o resultado → injetar o resultado de volta no contexto do chat exatamente como o modelo prescreve → chamar o modelo novamente.

Dicas práticas, solução de problemas e notas de segurança (O que devo observar?)

Os modelos de token são rigorosos. Use o modelo tokenizer.apply_chat_template ou reproduzir o exato <think>/</think> tokens conforme mostrado. Espaçamento incorreto ou marcadores ausentes alterarão o comportamento do modelo.
O formato da ferramenta deve ser JSON válido. O modelo analisará os argumentos da ferramenta como JSON — JSON inválido interromperá as chamadas da ferramenta.
Compensações de quantização. Quantizações dinâmicas/agressivas de 1 bit reduzem o armazenamento e a RAM, mas podem alterar ligeiramente a fidelidade numérica. Teste em suas cargas de trabalho. Existem quantizações comunitárias que reduzem 80% do uso do disco (exemplo de relatório: 720 GB → ~170 GB), mas sempre valide com seus prompts.
Compatibilidade com Ollama. Algumas variantes do DeepSeek mencionam o Ollama v0.11.7 como necessário para recursos de pré-lançamento — verifique a página do modelo do Ollama e atualize conforme necessário.

Exemplo de ponta a ponta: execute o DeepSeek-V3.1 localmente com o Modo de Pensamento (mini passo a passo)

Instale o Ollama e puxe o modelo:

# install ollama per docs, then:

ollama pull deepseek-ai/DeepSeek-V3.1
ollama run deepseek-ai/DeepSeek-V3.1 &

Use o tokenizador Python para compor um prompt de pensamento:

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("deepseek-ai/DeepSeek-V3.1")

msgs = [
  {"role":"system","content":"You are a helpful assistant."},
  {"role":"user","content":"Plan a multi-step strategy to prototype a mobile app in 2 weeks."}
]
prompt = tokenizer.apply_chat_template(msgs, thinking=True, add_generation_prompt=True)

import requests
resp = requests.post("http://localhost:11434/api/generate", json={
    "model": "deepseek-ai/DeepSeek-V3.1",
    "prompt": prompt,
    "max_tokens": 400
})
print(resp.json())

Se o modelo retornar uma chamada de ferramenta no formato toolcall, analise o JSON e execute a ferramenta, depois injete os resultados na próxima mensagem de acordo com os modelos de cartão do modelo.

Como você deve escolher seu caminho de implantação?

Se você quer o caminho mais rápido para experimentar: usar Ollama e os exemplos do modelo de cartão "Hugging Face". Ollama oculta muitos detalhes de infraestrutura e fornece uma API HTTP local.
Se você precisa de menor custo / mais portabilidade: usar uma comunidade GGUF quantizado artefato e correr com llama.cpp or llama-serverA quantização economiza disco e memória, mas testa a precisão da sua carga de trabalho.
Se você estiver criando agentes ou ferramentas: siga o modelo do cartão chamada de ferramenta e agente modelos exatamente; orquestrar saídas de ferramentas de volta ao contexto do modelo.

Começando a jornada

A CometAPI é uma plataforma de API unificada que agrega mais de 500 modelos de IA de provedores líderes — como a série GPT da OpenAI, a Gemini do Google, a Claude da Anthropic, a Midjourney e a Suno, entre outros — em uma interface única e amigável ao desenvolvedor. Ao oferecer autenticação, formatação de solicitações e tratamento de respostas consistentes, a CometAPI simplifica drasticamente a integração de recursos de IA em seus aplicativos. Seja para criar chatbots, geradores de imagens, compositores musicais ou pipelines de análise baseados em dados, a CometAPI permite iterar mais rapidamente, controlar custos e permanecer independente de fornecedores — tudo isso enquanto aproveita os avanços mais recentes em todo o ecossistema de IA.

Os desenvolvedores podem acessar DeepSeekV3.1 Por meio do CometAPI, as versões mais recentes dos modelos listados são as da data de publicação do artigo. Para começar, explore os recursos do modelo no Playground e consulte o Guia de API para obter instruções detalhadas. Antes de acessar, certifique-se de ter feito login no CometAPI e obtido a chave da API. CometAPI oferecem um preço muito mais baixo que o preço oficial para ajudar você a se integrar.

Conclusão

O DeepSeek-V3.1 traz uma filosofia prática de inferência híbrida (um ponto de verificação + comportamento de pensamento modelado) que simplifica a experimentação com raciocínio em cadeia de pensamento e o uso de ferramentas de agente, desde que você respeite os modelos de bate-papo e os requisitos de ferramentas. Use o cartão de modelo "Hugging Face" e as notas de lançamento do DeepSeek como sua primeira parada. Escolha um tempo de execução local (Ollama para simplificar, llama.cpp para controle) e testar compilações quantizadas para implantações locais práticas.