Inference Engineering · Lesson 11 · Practical API ControlsHome · Glossary · Your Lab

Practical API Controls

The knobs that change output, cost, and request lifetime.

Commit a prediction before revealing the model.
Today's win: classify API controls as generation limits, sampling controls, observability, transport, or constrained decoding and predict their operational effect.

The setup

Lesson 10 traced one request end to end; here we turn the practical knobs on it. Some controls change the recipe's randomness, some cap the number of bites, some choose whether plates leave one-by-one, and some force the final dish into a mold. They are not interchangeable performance knobs.

1 · Bound the request

A generated-token ceiling (for example max_tokens in vLLM or max_completion_tokens in newer APIs) caps work; the context limit caps prompt plus output. EOS (EOS = the special end-of-sequence token a model emits to stop) and supported stop sequences can end earlier. Timeouts and cancellation must propagate so abandoned requests stop consuming decode slots. Parameter support is model- and server-specific.

2 · Control sampling

Temperature reshapes logits; top-p/top-k truncate the candidate set; a seed can improve repeatability but does not guarantee identical output across engines, hardware, batching, or versions.

3 · Choose transport and observability

Streaming reduces time to visible text but not model compute. Logprobs expose token scores at extra payload or compute cost. Usage counters are necessary for limits and billing.

4 · Constrain the output

JSON schema, grammars, and structured-output modes mask invalid next tokens during decoding. They improve syntactic validity but do not guarantee that values are true or semantically correct.

5 · Treat controls as a contract

Validate unsupported combinations, set server-side ceilings, and document defaults. Client max_tokens is not a substitute for admission control or a total context check. Next, Lesson 12 zooms out to the engine that runs many such requests at once.

On YOUR cluster live-tested · course lab

Your vLLM deployments already expose the OpenAI-compatible request surface used in the course. Supported fields and defaults depend on the deployed vLLM/model generation config, so inspect that version before promising an API contract.

Study next: sources & lab companionvLLM serving · Chat API controls · Structured outputs

Final check

← Lesson 10Lesson 12 →
References

vLLM serving · Chat API controls · Structured outputs

Practical API Controls

The knobs that change output, cost, and request lifetime.

Today's win: classify API controls as generation limits, sampling controls, observability, transport, or constrained decoding and predict their operational effect.

The picture

Lesson 10 traced one request end to end; here we turn the practical knobs on it. Some controls change the recipe's randomness, some cap the number of bites, some choose whether plates leave one-by-one, and some force the final dish into a mold. They are not interchangeable performance knobs.

Bound the requestA generated-token ceiling (for example max_tokens in vLLM or max_completion_tokens in newer APIs) caps work; the context limit caps prompt plus output
Control samplingTemperature reshapes logits; top-p/top-k truncate the candidate set; a seed can improve repeatability but does not guarantee identical output across engines, hardware, batching, or versions
Choose transport and observabilityStreaming reduces time to visible text but not model compute
Constrain the outputJSON schema, grammars, and structured-output modes mask invalid next tokens during decoding

1 · Bound the request

A generated-token ceiling (for example max_tokens in vLLM or max_completion_tokens in newer APIs) caps work; the context limit caps prompt plus output. EOS (EOS = the special end-of-sequence token a model emits to stop) and supported stop sequences can end earlier. Timeouts and cancellation must propagate so abandoned requests stop consuming decode slots. Parameter support is model- and server-specific.

SAMPLING · reshape, then truncate, then draw one token raw probabilities T temperature reshapes T<1 sharper T>1 flatter top-p / top-k truncate kept masked one token sampled OTHER CONTROL FAMILIES · not sampling, not interchangeable limitsmax_tokens · stop · ctx transportstream = delivery only observelogprobs · usage constrainedJSON mask = form only
Notice that temperature reshapes the whole distribution while top-p/top-k only cut the candidate set, and a token is then drawn from what remains. The families below are not sampling knobs: limits bound work, streaming changes delivery (not compute), and a JSON schema constrains form (not truth).

2 · Control sampling

Temperature reshapes logits; top-p/top-k truncate the candidate set; a seed can improve repeatability but does not guarantee identical output across engines, hardware, batching, or versions.

TEMPERATURE · one knob that scales how peaked the distribution is T = 0.2sharp · near-greedy T = 1.0the model's own spread T = 1.8flat · more random temperature divides the logits before softmax; it never adds or removes candidates
Notice temperature only rescales the existing distribution: low values concentrate mass on the top token (toward deterministic), high values spread it toward uniform. This matters because temperature controls creativity-vs-consistency, but it is a separate lever from top-p/top-k, which decide how many candidates survive at all.

3 · Choose transport and observability

Streaming reduces time to visible text but not model compute. Logprobs expose token scores at extra payload or compute cost. Usage counters are necessary for limits and billing.

TRUNCATION · two ways to decide which candidates survive top-k = 3 · fixed count keep 3drop rest top-p = 0.9 · cumulative mass until 90% massdrop tail top-p adapts: a confident step keeps few candidates, an uncertain step keeps many
Notice top-k always keeps the same number of candidates while top-p keeps however many are needed to reach a probability mass. This matters because top-p adapts to model confidence: narrow when the model is sure and wide when it is unsure, which is usually a better safety net than a fixed k.

4 · Constrain the output

JSON schema, grammars, and structured-output modes mask invalid next tokens during decoding. They improve syntactic validity but do not guarantee that values are true or semantically correct.

LIMITS & LIFETIME · bound the work, and release it when abandoned prompt tokens completion ≤ max_tokens must fit context window EOS or a matched stop string can end generation before max_tokens. client stays connected decode slot held, tokens stream released on normal completion timeout / client disconnect cancel must propagate to the engine free the slot + KV, or capacity leaks client max_tokens is not admission control; set server-side ceilings too
Notice limits do two jobs: max_tokens and the context window bound how much work a request can demand, while timeouts and cancellation bound how long it occupies a slot. This matters because an abandoned request that is not cancelled keeps decoding into the void, holding KV (the KV cache is the per-request attention memory the model builds up while generating; computed in Lesson 14) and a batch slot every other user is waiting on.

5 · Treat controls as a contract

Validate unsupported combinations, set server-side ceilings, and document defaults. Client max_tokens is not a substitute for admission control or a total context check. Next, Lesson 12 zooms out to the engine that runs many such requests at once.

CONSTRAINED DECODING · the schema controls form, never truth JSON schema { "city": string, "pop": integer } the required shape per-step token mask allowed: { " c i t y … illegal next tokens → −∞ logit always parseable {"city":"Paris","pop":9} valid JSON · value may be wrong ✓ guarantees: syntax, required keys, types, enums ✗ does not guarantee: correct, current, or truthful field values
Notice the mask only removes tokens that would violate the schema; the model still chooses among the legal ones. This matters because constrained decoding eliminates parse errors and retries, but a perfectly-formed object can still hold a wrong number; structure validity is not factual validity.

On YOUR cluster live-tested · course lab

Your vLLM deployments already expose the OpenAI-compatible request surface used in the course. Supported fields and defaults depend on the deployed vLLM/model generation config, so inspect that version before promising an API contract.

Check yourself

← Lesson 10Lesson 12 →
References

vLLM serving · Chat API controls · Structured outputs