DeepSeek V3.2 to V4 Migration Playbook: Open-Weight Stack

The DeepSeek V3.2 to V4 migration is the first open-weight upgrade in this generation that genuinely moves the cost needle — V4-Pro runs at roughly 27% of V3.2's single-token inference FLOPs and 10% of the KV cache at 1M context — but it is not a drop-in swap. Four breaking-change axes need careful sequencing or quality will regress before the cost win lands.

What's at stake: teams that treat V4 as a version bump tend to ship the new model behind a tokenizer that quietly invalidates every prompt-prefix cache, on an inference stack that wasn't built for HCA/CSA attention, with one default reasoning mode used for every workload class. The result is a regression in both quality and latency, which then gets blamed on the model rather than the migration. The win is real; the path matters.

This playbook covers seven stages: the four axes V4 actually breaks on, when to use each of the three reasoning modes, the tokenizer change and its impact on prompt caching, what the HCA + CSA attention stack means for vLLM / TensorRT-LLM / SGLang, the KV-cache reduction and what new workload archetypes it unlocks, a phased rollout that earns the cost win without staking production quality on it, and the four pitfalls that trip teams the most.

The honest way to scope a V3.2 to V4 migration is to enumerate the axes that broke. The model is a bigger MoE (1.6T total / 49B active for V4-Pro versus 671B / 37B for V3.2), but raw size is not what makes the upgrade a migration project. Four axes do.

Reasoning modes. V3.2 had a single inference path; V4 exposes three (Non-Think, Think High, Think Max) selected via the <think>token and a Max-only prepended system prompt. Every workload now needs a routing decision.

Attention stack. V3.2 used DeepSeek Sparse Attention uniformly. V4 interleaves Compressed Sparse Attention (CSA, the V3.2 generalization) with Heavily Compressed Attention (HCA, much more aggressive folding) across layers. That hybrid is what unlocks the cost numbers — and it required code changes in every major open-weight inference stack.

Tokenizer. V4 ships a new tokenizer. Any prompt-prefix cache, KV-cache prefix index, or evaluation suite built against V3.2 token IDs is invalidated on the first V4 request. This is the silent breakage that catches the most teams.

KV cache.At 1M-token context, V4-Pro's KV cache is roughly 10% of V3.2's. That opens new workload archetypes (full-codebase agents, multi-document corpus reasoning) that previously could not clear the inference cost bar — and changes the right memory configuration for an inference replica.

Two things did notbreak, and the migration benefits from calling them out. DeepSeekMoE's fine-grained routed-expert FFN framework carries over from V3 to V4 with a small affinity-scoring tweak; Multi-Token Prediction (MTP) is retained unchanged. If your V3.2 stack already integrated with MTP for inference acceleration, the integration surface stays compatible.

The three reasoning modes are the most visible change at the application layer. They map roughly onto the latency / cost / quality tradeoff every team already makes — but the tradeoff is now explicit in the protocol rather than buried in prompt engineering.

The migration-time decision is a per-workload routing policy, not a single global default. Map your existing V3.2 traffic into three buckets — routine, default, frontier — then route each bucket to the matching V4 mode. Treating every request as Think Max wastes tokens and raises tail latency; treating every request as Non-Think regresses quality on the workloads V4 was actually tuned around.

One operational detail worth knowing: V4 retains complete reasoning history across tool calls within a conversation (Interleaved Thinking), whereas V3.2 discarded reasoning traces at each new user turn. For agent workloads this is a quality win and a token-budget hit at the same time — coherent long-horizon chains of thought are preserved, but context consumption per turn rises. Re-tune your max-output-tokens budget during migration.

V4 ships a different tokenizer than V3.2. That single sentence hides the most reliably underestimated risk in this migration. Any system, anywhere in the request path, that caches tokenized content keyed by V3.2 token IDs is dead on first contact with V4.

What breaks the moment V4 traffic starts

• Provider-side prefix caches.DeepSeek's own API prompt cache, and any third-party gateway you sit behind, indexes cache hits by the tokenized prefix of the request. Different tokenizer means zero overlap — every V4 request is a cache miss until the cache re-warms.
• Self-hosted KV-cache prefix indexes. If you run vLLM or TensorRT-LLM with prefix caching enabled, the radix tree indexed by V3.2 tokens does not interoperate with V4 tokens. Hot-swap the model and the cache is functionally empty.
• Evaluation suites with stored token counts. Any test that asserts on a specific token count or compares token IDs against a golden output needs regeneration.
• Cost dashboards keyed on tokens-per-request. The same prompt will tokenize to a different count under V4. Year-over-year comparisons need a tokenizer-version dimension.

The cache-rebuild window

Plan it. A production system that runs at 60% cache-hit on V3.2 will start the V4 migration at 0% hits. Cost spikes by the amount of context you previously got for free, until your most common prompt prefixes re-warm. Two patterns work: (a) run a scripted warmup pass on your top-N system prompts and tool descriptions immediately after cutover, or (b) cut over a single workload at a time and let cache warmth rebuild naturally before adding the next workload.

Operationally, the migration recipe that holds up: tokenize a representative sample of your production traffic with both the V3.2 and V4 tokenizers before cutover, measure the average and P95 token-count delta, and re-tune your max-tokens budgets, timeout windows, and cost dashboards accordingly. The delta is usually modest in either direction, but per-workload variance can be significant on technical content with heavy code or domain-specific vocabulary.

V4's attention stack interleaves Compressed Sparse Attention (CSA) with Heavily Compressed Attention (HCA) across layers. The architectural rationale is in the V4 launch coverage — for the migration playbook, what matters is that every open-weight inference stack needed code changes to support the hybrid. The wrong version of vLLM, TensorRT-LLM, or SGLang will either fail to load V4 weights or run them with degraded quality.

Pin to versions the V4 model card endorses. Do not assume the latest tag works; do not assume your existing V3.2 deployment scripts are forward-compatible. The matrix below captures the shape of the decision — verify exact version numbers against current upstream release notes before you commit.

The implementation work each stack needed is itself instructive. HCA collapses many tokens into a single KV entry with no sparse selection step; CSA collapses fewer tokens per entry with a top-k selector and a sliding window. Both required new kernel paths — naively running V4 weights through a uniform DeepSeek Sparse Attention implementation built for V3.2 produces output that loads but is meaningfully worse than the same weights run on a V4-aware stack. The failure mode is silent; nothing throws. Validate with a benchmark, not a smoke test.

At 1M-token context, V4-Pro's KV cache occupies roughly 10% of V3.2's footprint; V4-Flash drops further to 7%. The chart below puts the numbers side by side. The practical consequence is not just "cheaper inference" — it is new workload archetypes that previously could not clear the cost-per-query bar.

What this unlocks.Three workload classes that sat just outside production-economic viability on V3.2 cross into "ship it" territory on V4:

• Full-codebase agents. Loading 500k-1M tokens of a real production codebase plus a task description was a cost-prohibitive luxury on V3.2 for most teams. V4 brings it into per-request economics that justify routine use, not ceremonial use.
• Multi-document corpus reasoning. Legal, financial, and regulatory workflows that span dozens of long documents per query benefit directly. The KV-cache budget that previously forced chunked retrieval can now afford whole-corpus context for the hardest workloads.
• Long-running agent sessions.Interleaved Thinking (Section 02) is more affordable to keep alive across many turns when each turn's KV is an order of magnitude smaller. Coherent multi-step agents stop costing what hourly human reasoning would cost.

On the operational side, re-budget your per-replica memory allocation. A V3.2 inference replica sized for a particular concurrent-request count at 128k context has substantial headroom on V4 at the same context — either raise concurrency on the same hardware, raise context, or downsize the replica. The correct choice depends on whether your workload is latency-bound or cost-bound; measure both before committing.

The rollout sequence that holds up across migrations is four phases run in order, not parallel. The temptation is to do stack-version pinning, tokenizer testing, mode routing, and cutover in a single sprint; the failure mode is that quality regressions become impossible to attribute. One axis at a time.

Two cross-cutting practices make every phase smoother. First, keep V3.2 reachable on a parallel endpoint for at least a week after full cutover — a quick rollback is the safety net that makes the rest of the plan executable. Second, treat the reasoning-mode routing decisions as configuration, not code, so you can re-route a workload class without a redeploy. The first production week almost always surfaces at least one workload that benefits from a different mode than your initial mapping assumed.

For teams without dedicated AI infrastructure capacity, our AI transformation engagements handle the migration end-to-end — inference-stack version pinning, benchmarking, reasoning-mode routing, tokenizer-aware cache rebuild planning, and per-workload cutover with measurable rollout. The same playbook applies to Claude 4.6 to 4.7 migrations and other frontier-model upgrades.

Most of the pitfalls below have appeared in this playbook already, in context. Collecting them here as a pre-flight checklist makes them easier to catch before the cutover meeting.

One pitfall not in the matrix because it deserves its own paragraph: assuming FP4 quantization-aware training in V4 translates to immediate FP4 inference wins on your hardware today. On current GPUs, peak throughput for FP4×FP8 operations is identical to FP8×FP8 — the FP4 weights save memory, not FLOPs. Purpose-built hardware in the next 12-24 months could make FP4 roughly 1.33x more efficient than FP8 at the same quality, but that lane is a forecast, not a present-day cost line. Plan migrations on FP8 economics; treat FP4 as the optionality lane it actually is.