Como construir uma base de conhecimento com DeepSeek: RAG, embeddings externos e V3.2

Este artigo foi atualizado em 18 de abril de 2026 para alinhar o conteúdo à documentação oficial pública da DeepSeek e ao restante do site. A versão antiga, centrada em “embeddings do DeepSeek”, já não refletia da melhor forma o ecossistema público atual. Hoje, a DeepSeek API pública aparece organizada sobretudo em torno de Chat, Completions, Models e Others, enquanto a listagem pública de modelos destaca deepseek-chat e deepseek-reasoner. Para bases de conhecimento, isso muda o enquadramento editorial: o DeepSeek deve ser tratado principalmente como camada de geração, raciocínio, saída estruturada, uso de ferramentas e composição final de respostas em pipelines de RAG.

Em termos práticos, construir uma base de conhecimento com DeepSeek em 2026 não significa assumir que a API pública atual tenha como eixo principal um endpoint oficial de embeddings exposto ao público. Significa desenhar ingestão, recuperação, governança e contexto de forma explícita, usando o DeepSeek onde a documentação pública hoje está mais clara: geração final, thinking mode, JSON Output, Function Calling, multi-turn stateless e context caching. Quando a aplicação exigir embeddings, a camada vetorial deve ser tratada como uma decisão de arquitetura independente — externa, híbrida ou self-hosted — em vez de ser atribuída automaticamente à DeepSeek API pública atual.

Se você está começando agora, vale ler em paralelo DeepSeek API, Preços do DeepSeek, FAQ e DeepSeek V3.2, porque essas páginas concentram o estado atual da API, dos preços e dos modos de uso.

O que mudou no ecossistema DeepSeek desde 2025

O primeiro ponto importante é histórico. Em 26/12/2024, a DeepSeek apresentou o DeepSeek-V3 como uma geração com “fully open-source models & papers”. Em 20/01/2025, veio o DeepSeek-R1, lançado como referência para raciocínio, matemática e código. Depois, em 01/12/2025, a DeepSeek lançou o DeepSeek-V3.2 como sucessor oficial do V3.2-Exp e o posicionou como um modelo reasoning-first, com foco em agentes e suporte a thinking in tool-use.

Essa evolução importa porque muda a forma correta de escrever sobre a plataforma. Em 2025, era comum enxergar o DeepSeek sobretudo pelo ângulo do “modelo open-source que rivaliza com sistemas fechados”. Em abril de 2026, a documentação pública revisada mostra um ecossistema mais operacional: API compatível com OpenAI, modelos públicos identificados com clareza, guias específicos para conversas multi-turn, context caching, JSON Output, Function Calling e Thinking Mode.

Outro detalhe decisivo é que a página Your First API Call e a página de Models & Pricing informam que, na API pública atual, deepseek-chat e deepseek-reasoner correspondem à versão DeepSeek-V3.2 com contexto de 128K, e a própria documentação ressalta que isso diferencia a API da versão App/Web. Para uma base de conhecimento séria, esse tipo de nuance vale mais do que repetir slogans genéricos sobre “IA aberta”.

O que a documentação oficial atual realmente mostra

Nas fontes oficiais públicas revisadas em 18/04/2026, a DeepSeek documenta com clareza a camada de geração e raciocínio da stack. A referência principal da API está em DeepSeek API, e a listagem de modelos disponíveis em /models apresenta deepseek-chat e deepseek-reasoner como modelos públicos atuais. A página Your First API Call também deixa explícito que a API é compatível com o formato OpenAI e pode ser acessada pelo SDK da OpenAI apenas ajustando base_url.

Já a camada de memória e composição de contexto é descrita de forma direta. O guia de Multi-round Conversation informa que a API é stateless: o servidor não grava o contexto da conversa e, por isso, todo o histórico relevante precisa ser reenviado a cada chamada. Para knowledge bases, isso significa que o seu pipeline continua responsável por recuperar documentos, montar contexto, inserir instruções, enviar tudo ao modelo e controlar o histórico útil da sessão.

Ao mesmo tempo, a documentação oficial oferece recursos que fazem muito sentido em RAG moderno. O guia de Context Caching afirma que o cache em disco está habilitado por padrão para todos os usuários, e que prefixos repetidos podem gerar cache hit. O guia de JSON Output documenta saída estruturada em JSON. O guia de Function Calling mostra como o modelo pode chamar ferramentas externas. E o guia de Thinking Mode explica como ativar o raciocínio explícito com model="deepseek-reasoner" ou via parâmetro thinking; no OpenAI SDK, esse parâmetro é enviado em extra_body.

Nota editorial sobre documentação legada
Em 18 de abril de 2026, a leitura mais segura para decisões de produção é priorizar Your First API Call, Models & Pricing, DeepSeek-V3.2 Release, Thinking Mode, Multi-round Conversation, JSON Output, Function Calling e Context Caching. Algumas páginas antigas, como Reasoning Model (deepseek-reasoner), preservam limitações anteriores e não refletem completamente o comportamento atual do DeepSeek-V3.2 na API.

Esse cuidado é importante porque a própria documentação oficial mostra a transição. A página legada de deepseek-reasoner ainda preserva uma fase em que Function Calling aparecia como não suportado. Já as páginas atuais de Models & Pricing, Thinking Mode e DeepSeek-V3.2 Release documentam tool-use também em thinking mode. Para evitar contradição interna dentro do site, este artigo segue a leitura mais nova e operacional da API pública atual.

Na documentação pública revisada em 18/04/2026, não há uma seção pública central de embeddings nem modelos de embeddings na listagem pública de modelos. O material público atual se concentra em Chat, Completions, Models e Others, com destaque para deepseek-chat e deepseek-reasoner. Por isso, este guia usa “embeddings” no sentido arquitetural de RAG — não como promessa de um endpoint público central da DeepSeek API atual.

Embeddings ainda fazem sentido em knowledge bases?

Sim. Em RAG, embeddings continuam úteis para busca semântica, clusterização, recuperação por similaridade, reranking híbrido e organização de acervo. O ponto corrigido aqui não é técnico, e sim editorial: o fato de embeddings continuarem importantes em arquitetura não significa que a DeepSeek API pública atual os documente como eixo principal da oferta pública.

Por isso, o desenho mais honesto em 2026 é separar responsabilidades. A camada vetorial pode ser externa, híbrida ou self-hosted; o DeepSeek entra na geração final, no raciocínio, na resposta estruturada, nas ferramentas e na síntese de evidências. Essa formulação combina melhor com a documentação oficial atual e com a forma como o restante deste site organiza páginas de API, preços, FAQ e modelos.

Como fica uma arquitetura de base de conhecimento com DeepSeek hoje

Uma arquitetura prática de base de conhecimento com DeepSeek em 2026 costuma seguir sete etapas: ingestão de documentos, chunking, embeddings por camada externa ou self-hosted quando necessário, armazenamento vetorial, recuperação, montagem de contexto e geração final da resposta com DeepSeek. Essa decomposição é uma recomendação técnica de arquitetura para RAG; não é uma promessa de que a DeepSeek forneça sozinha todas essas camadas na documentação pública atual.

Ingestão de documentos

A primeira etapa é trazer o conteúdo que será consultado: políticas internas, PDFs, páginas de help center, manuais, contratos, artigos técnicos, tickets, changelogs e FAQs. O ponto importante aqui é normalizar os documentos e preservar origem, data, versão, idioma e permissões de acesso. Em bases corporativas, vale tratar a ingestão como um pipeline de atualização contínua, não como uma importação única.

Em um projeto sério, a base de conhecimento precisa saber de onde veio cada trecho. Isso será útil depois para citações, auditoria e atualização de conteúdo. Em outras palavras: antes de pensar em “IA”, pense em governança documental.

Chunking e metadados

Depois da ingestão, o conteúdo precisa ser dividido em trechos menores. Esse processo de chunking é decisivo para o recall do sistema. Trechos longos demais misturam assuntos; trechos curtos demais perdem contexto. Como regra editorial/técnica, o ideal é preservar títulos, subtítulos, listas e hierarquia documental, sempre anexando metadados como fonte, seção, data, idioma, classificação de acesso e identificador do documento.

Se a sua aplicação exigir rastreabilidade forte, cada chunk deve carregar pelo menos: document_id, source_title, section_title, updated_at e access_scope. Isso simplifica filtragem por permissão e melhora a explicabilidade da resposta final.

Embeddings (externos, híbridos ou self-hosted)

Aqui está a correção mais importante em relação ao artigo antigo. Em um fluxo de RAG, embeddings continuam sendo úteis para busca semântica. Mas, nas fontes oficiais públicas revisadas em 18/04/2026, isso não aparece documentado como o foco central da API pública atual da DeepSeek. Portanto, a recomendação correta é tratar a camada de embeddings como uma decisão de arquitetura independente: você pode usar um modelo de embeddings externo, um modelo self-hosted ou uma recuperação híbrida que combine busca lexical, vetorial e reranking.

Essa distinção evita prometer um recurso oficial que o material público atual não coloca no centro. Se o seu stack já tem um sistema vetorial maduro, o DeepSeek pode entrar diretamente na etapa de geração e raciocínio. Se você ainda vai montar a camada semântica, escolha embeddings com base em recall, custo, idioma, governança, observabilidade e latência — sem atribuir automaticamente essa responsabilidade à DeepSeek API pública atual.

Armazenamento vetorial

Com embeddings gerados, os vetores e metadados precisam ser indexados em um armazenamento adequado. Em alguns projetos isso significa um banco vetorial dedicado; em outros, um índice híbrido com filtros por metadados, busca lexical e ranqueamento semântico. O ponto-chave é que a busca não deve retornar apenas similaridade, mas também contexto verificável e documentos autorizados para aquele usuário.

Em cenários com muita governança, o armazenamento vetorial precisa conviver com filtros por permissão, área, cliente, país, data de vigência e classificação do documento. Isso evita que um bom sistema de recuperação se transforme em um risco de compliance.

Recuperação e montagem de contexto

Na hora da pergunta, o pipeline precisa recuperar os trechos mais relevantes, montar o contexto e enviá-lo ao modelo. Como a API é stateless, esse contexto precisa ser reenviado a cada chamada. Na prática, isso significa que o sistema de retrieval faz parte da aplicação, não do servidor da DeepSeek.

Uma boa montagem de contexto separa claramente: instruções do sistema, política de resposta, pergunta do usuário, trechos recuperados e formato esperado da saída. Se você quer respostas auditáveis, também vale pedir que o modelo devolva IDs de trechos, títulos de fonte, evidências faltantes e nível de confiança. Nessa parte, JSON Output ajuda muito.

Geração da resposta com deepseek-chat vs deepseek-reasoner

Na geração final, entram os dois modelos públicos centrais da API atual: deepseek-chat e deepseek-reasoner. A própria DeepSeek informa na documentação que ambos correspondem hoje à versão DeepSeek-V3.2 na API, sendo o primeiro o modo non-thinking e o segundo o modo thinking da mesma geração.

Comparação entre deepseek-chat e deepseek-reasoner na API pública atual (DeepSeek-V3.2)

Critério	deepseek-chat	deepseek-reasoner
Posicionamento na documentação atual	Modo não pensante do DeepSeek-V3.2 na API	Modo pensante do DeepSeek-V3.2 na API
Quando usar em knowledge base	FAQ, help center, respostas rápidas, alto volume, menor complexidade de raciocínio	Perguntas ambíguas, síntese de políticas, análise de múltiplas evidências e tarefas com raciocínio mais longo
Contexto	128K	128K
Orçamento de saída (max_tokens) padrão / máximo	4K / 8K	32K / 64K
JSON Output	Sim	Sim
Tool Calls / Function Calling	Sim	Sim, conforme a documentação atual de V3.2 e Thinking Mode
Chat Prefix Completion (Beta)	Sim	Sim
FIM Completion (Beta)	Sim	Não
Referência operacional	Models & Pricing, Your First API Call e Thinking Mode

Nota editorial: a página legada Reasoning Model (deepseek-reasoner) ainda preserva limitações anteriores. Para DeepSeek-V3.2 atual na API, a leitura operacional mais segura é seguir Models & Pricing, Thinking Mode e DeepSeek-V3.2 Release.

No deepseek-reasoner, o orçamento de saída (max_tokens) inclui também o conteúdo de raciocínio (reasoning_content), não apenas a resposta final. Em fluxos simples isso pode ser excesso; em bases de conhecimento com comparação de regras, reconciliação de evidências ou síntese mais analítica, pode valer a pena.

Na prática, deepseek-chat tende a ser a escolha natural para assistentes de base de conhecimento com alto volume, SLA previsível e respostas curtas a médias. Já deepseek-reasoner faz mais sentido quando a resposta exige comparar normas, inferir implicações, reconciliar trechos potencialmente conflitantes ou justificar um resultado com maior cuidado analítico.

Recursos oficiais do DeepSeek úteis para RAG e knowledge bases

API stateless

O guia de Multi-round Conversation é explícito: a API não grava automaticamente o contexto da conversa. Para uma base de conhecimento, isso é bom e ruim ao mesmo tempo. É bom porque deixa o controle da sessão na sua aplicação. É ruim se você presumir memória implícita e esquecer de reenviar instruções, histórico útil e trechos recuperados.

Operacionalmente, isso significa que o seu backend deve decidir o que entra no prompt em cada rodada. Em um assistente interno, por exemplo, você pode reenviar apenas os fatos relevantes, o histórico mínimo da conversa e as regras de resposta. Não há atalho aqui: se o contexto não foi enviado, a API não o “lembrará”.

Context caching

A documentação de Context Caching informa que o recurso está habilitado por padrão e que apenas a parte repetida do prefixo entre chamadas gera cache hit. Para knowledge bases, isso abre uma oportunidade clara de otimização: manter instruções estáveis, políticas fixas e partes permanentes do prompt sempre na mesma ordem.

Como recomendação editorial/técnica, vale organizar o prompt com um prefixo bem estável no topo — por exemplo: identidade do assistente, política de citação, formato JSON e regras de recusa — deixando a pergunta e os chunks recuperados mais abaixo. Isso não substitui retrieval nem vetor; apenas reduz custo e latência quando o prefixo se repete.

JSON Output

O JSON Output é uma das features mais úteis para bases de conhecimento. A DeepSeek documenta que, para ativá-lo, o request deve usar response_format={"type":"json_object"} e o prompt precisa incluir a palavra “json”, além de um exemplo de estrutura desejada. Em aplicações reais, isso facilita pós-processamento, auditoria, integração com front-end e armazenamento do resultado.

Em vez de pedir uma resposta livre, você pode exigir um objeto com answer, citations, confidence, missing_evidence e next_action. Isso melhora muito a rastreabilidade da resposta final.

Function Calling

O guia de Function Calling explica que o modelo pode chamar ferramentas externas para ampliar suas capacidades. Em um stack de knowledge base, isso permite modelar o retriever, o verificador de permissões, o resolvedor de IDs de documentos ou até um serviço de atualização de fonte como ferramentas chamáveis pelo modelo. Essa é uma estratégia arquitetural recomendada; não é um produto de retrieval pronto da DeepSeek.

Na prática, o ganho aqui é separar duas responsabilidades: a aplicação sabe buscar e validar dados; o modelo sabe decidir quando pedir a ferramenta e como usar o resultado para compor a resposta. Para assistentes corporativos, isso costuma ser mais seguro do que despejar tudo no prompt de uma vez.

Se você precisar de schema mais rígido em chamadas de ferramenta, a documentação oficial também descreve um strict mode em beta, ativado via base_url="https://api.deepseek.com/beta" e strict: true na definição das funções.

Thinking Mode

O Thinking Mode documenta duas formas de ativação: usar deepseek-reasoner diretamente ou habilitar thinking no request. No SDK compatível com OpenAI, a documentação atual mostra esse parâmetro em extra_body={"thinking": {"type": "enabled"}}. A release do DeepSeek-V3.2 também afirma que esta foi a primeira geração da DeepSeek a integrar raciocínio diretamente em tool-use.

Isso é especialmente relevante em bases de conhecimento que precisam decidir entre fontes concorrentes, detectar lacunas de evidência, sintetizar múltiplos trechos ou executar um fluxo em mais de uma etapa. Para FAQ simples, isso pode ser excesso. Para decisões internas e consultas analíticas, pode ser a diferença entre uma resposta apenas plausível e uma resposta realmente bem justificada.

Exemplo simples em Python: recuperação externa + resposta final com DeepSeek

O exemplo abaixo mostra o papel correto da API em um fluxo de knowledge base: a recuperação vem de fora, o contexto é montado pela aplicação e o DeepSeek gera a resposta final em JSON. Esse padrão está alinhado à documentação pública atual, que descreve a API como stateless e fornece JSON Output e formato compatível com OpenAI SDK.

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

def retrieve_context(user_query: str):
    return [
        {
            "source_id": "pol-logs-2026",
            "title": "Política de retenção de logs",
            "excerpt": "Os logs operacionais devem ser mantidos por 180 dias, salvo obrigação regulatória superior.",
        },
        {
            "source_id": "runbook-incidentes",
            "title": "Runbook de incidentes",
            "excerpt": "Em incidente crítico, logs de segurança podem ter retenção ampliada para investigação.",
        },
    ]

def main():
    query = "Qual é a política de retenção de logs?"
    chunks = retrieve_context(query)

    context_text = "\n\n".join(
        f"[{c['source_id']}] {c['title']}: {c['excerpt']}"
        for c in chunks
    )

    messages = [
        {
            "role": "system",
            "content": (
                "Você é um assistente de base de conhecimento. "
                "Responda apenas com base no contexto fornecido. "
                "Se a evidência for insuficiente, diga isso explicitamente. "
                "Retorne um json com os campos: answer, citations, confidence, missing_evidence."
            ),
        },
        {
            "role": "user",
            "content": (
                f"Pergunta do usuário: {query}\n\n"
                f"Contexto recuperado:\n{context_text}\n\n"
                "Retorne json válido."
            ),
        },
    ]

    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=messages,
        response_format={"type": "json_object"},
    )

    content = response.choices[0].message.content
    data = json.loads(content)
    print(json.dumps(data, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

Se você quiser migrar esse mesmo fluxo para raciocínio mais profundo, pode trocar deepseek-chat por deepseek-reasoner em perguntas mais complexas. O importante é não esquecer o princípio básico: como a API é stateless, o histórico útil e o contexto recuperado precisam ser reenviados na próxima rodada.

Custos e quando cada modelo faz sentido

A página oficial de Models & Pricing, consultada em 18/04/2026, informa no snapshot público atual US$ 0,028 para input com cache hit, US$ 0,28 para input com cache miss e US$ 0,42 para output por 1 milhão de tokens. A mesma página ressalta que os preços podem mudar e que ela deve ser consultada regularmente. Em produção, essa página é a referência correta para custos atuais — não anúncios históricos de lançamento.

Na prática, o custo real do sistema não depende só do preço por token. Ele também depende da quantidade de contexto enviada, da repetição de prefixos, da frequência de cache hit, do tamanho das respostas e do uso de raciocínio mais longo. Por isso, a escolha entre deepseek-chat e deepseek-reasoner deve levar em conta não apenas preço unitário, mas também latência, profundidade analítica e tamanho típico de saída.

• Use deepseek-chat quando o objetivo for responder rápido, em grande volume, com contexto bem recuperado e baixa necessidade de raciocínio longo.
• Use deepseek-reasoner quando o problema exigir comparação de múltiplas regras, interpretação de ambiguidades, síntese de evidências dispersas ou justificativas mais cuidadosas.
• Use caching de prefixo com disciplina quando seu assistente tiver muitas instruções fixas ou conversas repetitivas.
• Reduza contexto inútil antes de culpar o modelo por custo ou latência altos.

Operação em produção: filas, retentativas e comportamento sob carga

A página oficial de Rate Limit afirma que a DeepSeek API não publica um limite fixo por usuário e que tenta atender todas as requisições. Isso não significa throughput infinito. Em períodos de alta carga, a conexão pode permanecer aberta com linhas vazias em requisições non-streaming ou com comentários : keep-alive em streaming. Se a inferência não começar em até 10 minutos, o servidor pode encerrar a conexão.

Ao mesmo tempo, a página oficial de Error Codes continua documentando erros 429 e 503. Em aplicações de knowledge base, a leitura correta dessas duas páginas juntas é: não conte com um número fixo de RPS, mas implemente fila, timeout razoável, retry com backoff, observabilidade e uma política clara para requests longas.

Erros comuns e limites do que a DeepSeek documenta hoje

O primeiro erro é assumir que “DeepSeek = solução completa de banco vetorial + embeddings + retrieval + resposta”. As fontes oficiais públicas revisadas em 18/04/2026 não documentam isso dessa forma. O que elas documentam com clareza é a camada de API para geração, raciocínio, JSON, ferramentas, thinking mode e caching.

O segundo erro é confundir App/Web com API. A própria DeepSeek avisa na página Your First API Call que deepseek-chat e deepseek-reasoner na API correspondem ao DeepSeek-V3.2 com 128K, e que isso difere da versão App/Web. Em conteúdo editorial, ignorar essa diferença gera explicações erradas sobre modelos, recursos e comportamento.

O terceiro erro é esquecer que a API é stateless. Sem reenviar o contexto, o modelo não “lembrará” do que foi conversado nem do que foi recuperado do seu acervo. O quarto erro é usar JSON Output sem especificar claramente o esquema. O quinto é desperdiçar a oportunidade do context caching montando prompts com prefixos instáveis. O sexto é assumir que “sem rate limit fixo” significa ausência de filas, backoff ou observabilidade. E o sétimo é prometer um endpoint público central de embeddings sem uma fonte oficial pública atual e explícita para isso.

Há ainda um limite editorial importante: DeepSeek é muito forte hoje como motor de geração, raciocínio, estruturação e orquestração da resposta, mas o sistema ao redor continua importando. Ingestão, versionamento documental, chunking, permissões, retrieval, reranking, auditoria, fallback e revisão humana continuam fazendo parte do resultado final. Em knowledge bases corporativas, o erro mais caro costuma acontecer fora do modelo, não dentro dele.

Conclusão

Se você já tem uma camada de recuperação madura — com documentos bem versionados, chunking competente e busca confiável — o DeepSeek faz muito sentido como camada principal de geração, raciocínio, estruturação e orquestração da resposta. Nesse cenário, ele entra onde a documentação oficial atual está mais forte: deepseek-chat, deepseek-reasoner, API compatível com OpenAI, JSON, Function Calling, Thinking Mode e Context Caching.

Se você ainda está montando a stack inteira, a decisão mais honesta é separar as camadas: retrieval e embeddings de um lado; DeepSeek como motor de resposta e raciocínio do outro. Essa arquitetura é mais fiel às fontes oficiais revisadas em 18/04/2026 e produz um conteúdo melhor para o leitor técnico. Em vez de vender uma “plataforma total” sem base documental suficiente, ela explica exatamente onde o DeepSeek brilha hoje em um fluxo moderno de base de conhecimento.

Para começar sem ruído, combine este guia com DeepSeek API, Preços do DeepSeek, FAQ e DeepSeek V3.2. Essas páginas ajudam a manter a navegação interna apontando para os hubs principais do site e, ao mesmo tempo, reduzem o risco de contradição editorial com versões antigas do ecossistema.

Transparência: deepseek-portugues.chat é um projeto independente, sem afiliação oficial com a DeepSeek ou seus desenvolvedores. Esta página foi revisada em 18 de abril de 2026. Para decisões de produção, confirme sempre a documentação oficial, a página atual de preços e o painel da sua conta.

FAQ:

Fontes oficiais verificadas

• DeepSeek API Docs — Your First API Call
• DeepSeek API — API Reference
• Lists Models
• Models & Pricing
• Rate Limit
• Error Codes
• Multi-round Conversation
• Context Caching
• Function Calling
• JSON Output
• Thinking Mode
• Reasoning Model (deepseek-reasoner)
• DeepSeek-V3.2 Release — 01/12/2025
• DeepSeek-R1 Release — 20/01/2025
• Introducing DeepSeek-V3 — 26/12/2024