12. Capacity planning — forecast tokens, peaks, limits, and headroom before launch week

~22 min read. A lead AI engineer does not optimize a single number; they make the tradeoff visible, measured, and reversible.

Builds on 00-eli5.md. The dispatch board needs enough cars, carpool lane policy, boot space, and fuel ledger history to survive peak demand.

---

What previous chapters solved before this pressure appears

Edge choices changed where inference runs, but capacity pressure remains. Earlier chapters gave us token cost, latency rooms, batching, KV memory, routing, and dashboards. What still breaks is launch planning that forecasts requests per second but not prompt tokens, output tokens, route mix, context length, cache hit rate, retries, and peak burst shape.

The accumulated lesson is already visible in the taxi fleet. meter ticks expose money, the ETA call exposes perceived wait, the dispatch board exposes route choice, and the fuel ledger keeps those choices honest. This file adds the next constraint without forgetting the earlier ones: every optimization relieves one pressure and creates another that some subsystem must absorb.

What this file solves

This file starts from launch traffic matches QPS forecast, yet p99 explodes because average prompt length doubled and cache hit rate collapsed. It shows the concrete design move a lead engineer makes, the artifact to inspect, and the signal that proves the optimization helped instead of merely moving pain elsewhere.

The opening failure shows up in a concrete artifact

The failure is not abstract: launch traffic matches QPS forecast, yet p99 explodes because average prompt length doubled and cache hit rate collapsed. Here is the early artifact a reviewer can inspect.

A capacity review forecasts token shape and bursts, not request count alone.

Launch-week forecast:

Resource	Baseline p95	Launch p95	Headroom	Risk
requests/sec	100	300	400	okay
prompt tokens/sec	180k	720k	650k	shortfall
output tokens/sec	6k	19.5k	22k	tight
active KV tokens	90k	310k	240k	memory risk

A smart team might try to fix the most visible line in that artifact. That is tempting, and it is incomplete. The root cause is planning by request count instead of resource shape. So how do we forecast the actual scarce resources: tokens/sec, prefill, KV memory, queues, rate limits, and budget headroom? This is the root-cause pivot: not a local metric problem, a boundary-and-pressure problem.

A tiny version exposes the whole mechanism

A toy request makes the pressure visible: one request looks fine in isolation, but after route mix, retries, context, or output length changes, the user-visible workflow changes. The smallest example is enough to show why the lever must be measured at the workflow boundary.

Rule: Capacity is planned from token shape, route mix, concurrency, and peak burst behavior, not QPS alone.

Why this rule exists. The taxi fleet needs more than ride count: distance, luggage, rush hour, cancellations, and airport vans decide capacity. The fuel ledger matters because it shows whether the new pressure landed in cost, latency, memory, quality, or operator attention.

---

1) Forecast resource shape, not only request count

Start with the workflow, not the vendor feature. In Maya's review, the team takes one request and follows it from API ingress to model call, tool call, runtime behavior, and resource consequence. That cross-layer trace is the shortest path from symptom to lever. If the symptom is cost, the trace follows meter ticks. If the symptom is silence, it follows the ETA call. If the symptom is serving pressure, it follows the carpool lane and boot space.

user request
    │
    ▼
API gateway ── route/version ──► model/runtime
    │                              │
    │                              ├─ tokens / queue / KV / output
    │                              ▼
    └──────── outcome ◄──────── fuel ledger row

The counterintuitive part is that the most obvious metric can improve while the product gets worse. A smaller bill can hide more failed outcomes. Higher tokens/sec can hide longer queueing. A shorter prompt can hide missing evidence. The mechanism in this chapter is useful only when the trace keeps the relieved pressure and the newly created pressure in the same picture.

2) The launch plan before the autoscaler

Picture the chapter as a pressure transfer, not a free lunch.

Before optimization                    After optimization
┌──────────────────────┐              ┌──────────────────────┐
│ visible pain          │              │ relieved pain         │
│ cost / wait / memory  │──change──►   │ lower local metric    │
└──────────┬───────────┘              └──────────┬───────────┘
           │                                      │
           ▼                                      ▼
 hidden cause not named                 new pressure appears
 retries, route mix, context,           quality, queueing, cache,
 output, provider limits                memory, fallback, ops

The diagram is the reason this module keeps returning to the fuel ledger. The ledger is where the second box becomes visible instead of surfacing as an invoice surprise, p99 incident, or quality complaint weeks later.

3) Maya builds a peak-week capacity sheet for a coding assistant

Maya threads one workload through the design review: a production assistant with real traffic, route versions, prompt versions, and outcome labels.

Attempt A — optimize the visible line

The first attempt changes the local knob associated with the opening symptom. The local dashboard improves. The team celebrates too early because the request boundary is still broken: retries, quality loss, queueing, cache misses, or memory pressure move elsewhere.

Attempt B — optimize with the pressure chain

The second attempt keeps the artifact, the rule, and the guardrail together. Maya writes the expected improvement, the pressure that may worsen, the owner of that pressure, and the rollback trigger. The dispatch board may change a route, the memorized route may change a prompt prefix, or the carpool lane may change scheduling, but the same request ID proves whether the user outcome survived.

4) Why token-shaped forecasts beat request-shaped forecasts

The plausible alternative is attractive because it is simpler to explain in a status update: change one knob, quote one percentage, and move on. That works for demos. It fails for lead-level ownership because it cannot answer which workload benefits and which workload pays.

Use this chapter's mechanism when the workload has the shape named in the opening artifact. Use the alternative when the product is small enough, stable enough, or low-risk enough that the extra machinery would cost more than it saves. The decision is not about elegance; it is about whether the signal-to-operator cost is worth it.

5) Burstiness and context length decide headroom

Concrete numbers make the tradeoff review honest. The sample prices and memory figures below are illustrative; replace them with the provider, hardware, and workload numbers in your own stack.

Scenario	Fresh input	Cached input	Output	Extra condition	Lesson
Baseline day	100	0	400	60 tok/s	6k output tok/s
Launch peak	300	0	650	55 tok/s	19.5k output tok/s
Long-context cohort	60	0	400	KV heavy	192k active prompt tok
Retry spike 15%	300	0	650	15% repair	22.4k effective tok/s
Cache miss event	300	0	650	0% cache	prefill 2x

The table teaches the design habit: every row says what improved and what might have worsened. If a row cannot name both, the proposal is not ready for production review.

6) The launch that had enough QPS and not enough KV memory

Walk the failure from top to bottom. The user action enters the API. The application builds a prompt or route. The runtime spends tokens, queue time, cache memory, or output steps. The dashboard records a local improvement. Then the user-visible metric moves the wrong way.

That failure is not bad luck. It is what happens when the optimization changes one layer and the observation stops one layer too early. In a review, Maya asks for the missing link: where did the pressure go after the local metric improved? If nobody can answer, the change ships behind a small canary or does not ship.

7) Signals that reveal whether capacity planning is healthy

• Healthy behavior: headroom exists for tokens/sec, prefill, KV memory, queue, and budget.
• First degrading metric: queue wait or allocation failures rise while QPS looks on plan.
• Misleading beginner metric: request count alone, because token shape and route mix decide load.
• Expert graph: forecast vs actual by prompt tokens, output tokens, active tokens, route mix, cache hit, retries, and p95/p99.

Mini-FAQ. "Why not watch the simplest metric?" Because the simplest metric is often the one the optimization directly manipulates. You need a paired guardrail that shows whether the system merely moved pain into another layer.

8) Boundaries where the chapter's lever works and where it turns pathological

• Strong fit: launch planning, enterprise tenant onboarding, traffic migrations, and seasonal peaks.
• Pathology: tiny workloads where manual limits are enough.
• Scale or workload limit: when vendor rate limits, procurement lead times, or hardware supply become the binding constraint.

This boundary is not a disclaimer. It is a routing rule for engineering attention. The best optimization in one endpoint can be the wrong default for another endpoint with different latency tolerance, risk, context length, or outcome value.

9) Wrong mental model to replace

The wrong model is that capacity equals QPS. The better model is multidimensional headroom: request rate is only the envelope around token rate, memory, route mix, burstiness, and budget.

The replacement model should change how you speak in design review. Do not say, "this reduces cost" or "this improves latency" without naming the request slice, expected magnitude, guardrail, and rollback trigger. Say which meter ticks, ETA call, carpool lane, or boot space pressure changed.

10) Other failure shapes you will recognize

1. Forecast failure. forecast uses average prompt length only.
2. Route failure. route mix shifts toward strong model during incidents.
3. Cache-hit failure. cache-hit assumptions not stress-tested.
4. Batch failure. batch window widened to hide insufficient capacity.
5. Rate failure. rate limits ignored until launch day.
6. Regional failure. regional failover doubles traffic in one region.
7. Budget failure. budget cap trips before technical capacity.

11) Cross-topic reinforcement — the same pressure shape returns

• Dashboards provide historical distributions for forecasts.
• KV cache turns context and concurrency into memory headroom.
• Batching and routing are capacity levers with product side effects.
• Honest admission next explains why these forecasts still need empirical load tests.

12) Design-review questions that catch shallow plans

1. Can you forecast p95 prompt and output tokens?
2. What happens when cache hit rate drops to zero?
3. How much retry and fallback headroom exists?
4. Which resource runs out first under peak?

Where this shows up in production

• Enterprise support bot — turns route, token, cache, retry, and outcome rows into cost per resolved ticket rather than model spend per message.
• Coding assistant — separates inline completions from agentic edits because typing flow, repo context, and repair loops have different budgets.
• Search answer product — pays for rewriting, retrieval, reranking, synthesis, citations, and judge calls as one user-visible answer.
• Voice assistant — treats dead air, cancellation, and local fallback as product features because users notice 100 ms gaps.
• Back-office summarizer — uses larger queues and batches because humans care about daily throughput more than first-token immediacy.
• Commerce assistant — protects purchase-changing actions with stronger routes while letting read-only advice run cheaper.
• Internal data copilot — attributes spend by tenant, dataset, prompt version, and tool path so one team cannot hide another team's budget.
• Education tutor — spends tokens on safety and pedagogy rules, then watches whether shorter answers still teach well.
• Legal review workflow — keeps evidence and citation context even when compression pressure is high because unsupported claims are worse than cost.
• Healthcare intake helper — uses conservative routing and buffered streaming because safety checks are part of the latency path.
• Marketing content tool — controls output length and variant count because creative generation can silently explode spend.
• Incident-response copilot — prefers predictable latency and logs over clever savings during high-severity operations.

Recall — rebuild capacity planning from memory

1. What concrete failure opened this chapter, and which artifact made it inspectable?
2. What root cause made the naive fix insufficient?
3. State the rule in one sentence without using vendor language.
4. Which pressure does the mechanism relieve, and which new pressure can it create?
5. Which operational signal degrades first when the mechanism is misapplied?
6. Where is the boundary where this lever becomes pathological?
7. How does this chapter reuse the fuel ledger or dispatch board from earlier chapters?
8. What would you put in the rollback trigger for this optimization?

Interview Q&A

Q: What problem does capacity planning actually solve?

A: It relieves the specific pressure from the opening failure: launch traffic matches QPS forecast, yet p99 explodes because average prompt length doubled and cache hit rate collapsed. The important answer names the workflow metric, the moved pressure, and the guardrail that keeps the optimization honest.

Common wrong answer to avoid: It is just a generic way to make LLMs cheaper or faster.

Q: Why is the naive fix dangerous?

A: Because the naive fix attacks the visible symptom while the root cause is the root cause is planning by request count instead of resource shape. so how do we forecast the actual scarce resources. It can improve a local metric and damage outcome quality, tail latency, memory, or operational clarity.

Common wrong answer to avoid: If the local metric improves, the product improved.

Q: What artifact would you inspect first?

A: The first artifact is the joined request trace or table for this chapter: route/version, token buckets, latency stages, outcome, and the topic-specific signal. Without it, the team debates guesses.

Common wrong answer to avoid: I would start by changing model parameters.

Q: How do you know the optimization worked?

A: The relieved pressure improves while the guardrail remains stable: headroom exists for tokens/sec, prefill, KV memory, queue, and budget. You also check the first degrading metric: queue wait or allocation failures rise while QPS looks on plan.

Common wrong answer to avoid: The dashboard line for cost or latency went down.

Q: When should you avoid this lever?

A: Avoid it in the pathological case: tiny workloads where manual limits are enough. The workload shape must match the mechanism, or the optimization moves cost into quality, memory, or user wait.

Common wrong answer to avoid: Use it everywhere because it is a best practice.

Q: What is the common wrong mental model?

A: The wrong model is that capacity equals QPS. The better model is multidimensional headroom: request rate is only the envelope around token rate, memory, route mix, burstiness, and budget.

Common wrong answer to avoid: The obvious intuition is good enough.

Q: How does this connect to earlier chapters?

A: It reuses the workflow boundary from cost anatomy, the stage trace from latency anatomy, and the fuel ledger discipline. The lever should be explained as pressure relief plus a new pressure, not as an isolated trick.

Common wrong answer to avoid: Earlier chapters are background only; this mechanism stands alone.

Apply now (10 min)

Step 1 — model the exercise. Use the modeled table in this chapter, then pick one feature you own or know. Fill in the same rows with rough numbers, change one assumption, and reproduce from memory which metric should improve, which guardrail could fail, and what rollback trigger you would set.

Step 2 — your turn. Pick a real LLM feature and write the same artifact with your own rough numbers. Name the pressure relieved, the pressure created, the owner, and the metric that would prove the change unsafe.

Step 3 — reproduce from memory. Close the file and redraw the two diagrams: request trace and pressure transfer. Then restate the rule and the first degrading metric without looking.

What you should remember

This chapter explained why the opening failure is not solved by changing one local knob. The useful move is to make the request boundary inspectable, apply the topic rule, and watch the paired guardrail so the optimization cannot hide its cost in another subsystem.

You learned to describe the lever as pressure movement: what it relieves, what it creates, and which team or resource absorbs the new cost. That is the difference between a trick and an operating practice.

Carry the diagnostic forward: if the dashboard cannot show the artifact, the route or version, the user outcome, and the first degrading signal in one place, the optimization is not yet reviewable.

Remember:

• Capacity is planned from token shape, route mix, concurrency, and peak burst behavior, not QPS alone.
• The first artifact to inspect is the trace/table that exposes launch traffic matches QPS forecast, yet p99 explodes because average prompt length doubled and cache hit rate collapsed.
• The first degrading signal is: queue wait or allocation failures rise while QPS looks on plan.
• The misleading beginner signal is: request count alone, because token shape and route mix decide load.
• Every optimization must name what pressure it relieves, what pressure it creates, and who owns the new cost.

---

Bridge. Capacity planning turns the whole module into a forecast, but forecasts still rest on moving assumptions. The final chapter names the honest limits: prices, models, workloads, and user behavior shift, so optimization must stay empirical.

→ ./13-honest-admission.md