[TRTLLM-11353][feat] API to configure TeaCache coefficients

[o-stoner]

Summary by CodeRabbit

• New Features

  • Added CLI options to override TeaCache polynomial coefficients for visual generation models.
  • Enabled TeaCache support for LTX-2 with explicit coefficient configuration requirements.
  • Enhanced dual-transformer TeaCache handling for Wan 2.2 models.

• Documentation

  • Clarified per-model TeaCache coefficient requirements in feature matrix and configuration guides.
  • Updated examples with TeaCache configuration details and usage instructions.

• Tests

  • Expanded TeaCache unit test coverage for coefficient resolution, validation, and multi-backend scenarios.

Description

Extends TeaCache to accept user-supplied polynomial coefficients (rather than relying solely on the built-in checkpoint lookup table), unlocking two use cases:

1. Enable TeaCache on previously unsupported models — Wan 2.2 (T2V A14B, I2V A14B, TI2V-5B) and LTX-2, which had no entries in the built-in coefficient table.

2. Override defaults on already-supported models (Wan 2.1, FLUX.1, FLUX.2) to tune the rescale polynomial for a custom quality/latency trade-off.

When coefficients is omitted, the pipeline falls back to checkpoint-path matching against the built-in table (existing behavior preserved).

How to supply coefficients:

1.) Via YAML (passed to trtllm-serve --extra_visual_gen_options or to offline example scripts via the same flag):

cache:
  cache_backend: teacache
  teacache_thresh: 0.2
  use_ret_steps: false
  coefficients: [c0, c1, ...] # optional override; REQUIRED for LTX-2 and Wan 2.2
  coefficients_2: [c0, c1, ...] # REQUIRED for Wan 2.2 dual-stage (T2V/I2V A14B)

coefficients is the polynomial mapping raw → rescaled embedding distance (evaluated via np.poly1d). coefficients_2 is the second-stage polynomial used only by Wan 2.2 dual-transformer pipelines.

2.) Via CLI (offline example scripts):

--enable_teacache \
--teacache_thresh 0.2 \
--teacache_coefficients <c0> <c1> ... \
--teacache_coefficients_2 <c0> <c1> ...   # Wan 2.2 dual-stage only

Test Coverage

PR Checklist

Please review the following before submitting your PR:

• PR description clearly explains what and why. If using CodeRabbit's summary, please make sure it makes sense.

• PR Follows TRT-LLM CODING GUIDELINES to the best of your knowledge.

• Test cases are provided for new code paths (see test instructions)

• Any new dependencies have been scanned for license and vulnerabilities

• CODEOWNERS updated if ownership changes

• Documentation updated as needed

• Update tava architecture diagram if there is a significant design change in PR.

• The reviewers assigned automatically/manually are appropriate for the PR.

• Please check this after reviewing the above items as appropriate for this PR.

GitHub Bot Help

To see a list of available CI bot commands, please comment /bot help.

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #44077 [ run ] triggered by Bot. Commit: 55cab64 Link to invocation

[tensorrt-cicd]

PR_Github #44077 [ run ] completed with state SUCCESS. Commit: 55cab64
/LLM/main/L0_MergeRequest_PR pipeline #34507 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #44510 [ run ] triggered by Bot. Commit: 1d118f8 Link to invocation

[tensorrt-cicd]

PR_Github #44510 [ run ] completed with state SUCCESS. Commit: 1d118f8
/LLM/main/L0_MergeRequest_PR pipeline #34909 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #44802 [ run ] triggered by Bot. Commit: 553618c Link to invocation

[tensorrt-cicd]

PR_Github #44802 [ run ] completed with state SUCCESS. Commit: 553618c
/LLM/main/L0_MergeRequest_PR pipeline #35152 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #45000 [ run ] triggered by Bot. Commit: 553618c Link to invocation

[tensorrt-cicd]

PR_Github #45000 [ run ] completed with state SUCCESS. Commit: 553618c
/LLM/main/L0_MergeRequest_PR pipeline #35319 completed with status: 'SUCCESS'

CI Report

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #45462 [ run ] triggered by Bot. Commit: 68e8c7c Link to invocation

[tensorrt-cicd]

PR_Github #45462 [ run ] completed with state SUCCESS. Commit: 68e8c7c
/LLM/main/L0_MergeRequest_PR pipeline #35695 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

Link to invocation

[o-stoner]

/bot run --disable-fail-fast --add-multi-gpu-test

[tensorrt-cicd]

PR_Github #46670 [ run ] triggered by Bot. Commit: b545818 Link to invocation

[tensorrt-cicd]

PR_Github #46670 [ run ] completed with state SUCCESS. Commit: b545818
/LLM/main/L0_MergeRequest_PR pipeline #36712 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[o-stoner]

/bot run --disable-fail-fast --add-multi-gpu-test

[tensorrt-cicd]

PR_Github #46860 [ run ] triggered by Bot. Commit: f585bc9 Link to invocation

[tensorrt-cicd]

PR_Github #46860 [ run ] completed with state FAILURE. Commit: f585bc9

Link to invocation

[o-stoner]

/bot run --disable-fail-fast --add-multi-gpu-test

[tensorrt-cicd]

PR_Github #46865 [ run ] triggered by Bot. Commit: f585bc9 Link to invocation

[tensorrt-cicd]

PR_Github #46865 [ run ] completed with state FAILURE. Commit: f585bc9
/LLM/main/L0_MergeRequest_PR pipeline #36877 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

Link to invocation

[o-stoner]

/bot run --disable-fail-fast --add-multi-gpu-test

[o-stoner]

/bot run --disable-fail-fast --add-multi-gpu-test

[tburt-nv]

/bot run --disable-fail-fast --add-multi-gpu-test

[tensorrt-cicd]

PR_Github #47038 [ run ] triggered by Bot. Commit: f585bc9 Link to invocation

[tensorrt-cicd]

PR_Github #55099 [ run ] completed with state FAILURE. Commit: ed02787
/LLM/main/L0_MergeRequest_PR pipeline #44085 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #55274 [ run ] triggered by Bot. Commit: ed02787 Link to invocation

[tensorrt-cicd]

PR_Github #55274 [ run ] completed with state FAILURE. Commit: ed02787
/LLM/main/L0_MergeRequest_PR pipeline #44228 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #55340 [ run ] triggered by Bot. Commit: ed02787 Link to invocation

[tensorrt-cicd]

PR_Github #55340 [ run ] completed with state FAILURE. Commit: ed02787
/LLM/main/L0_MergeRequest_PR pipeline #44295 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #55352 [ run ] triggered by Bot. Commit: ed02787 Link to invocation

[tensorrt-cicd]

PR_Github #55352 [ run ] completed with state FAILURE. Commit: ed02787
/LLM/main/L0_MergeRequest_PR pipeline #44302 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #55535 [ run ] triggered by Bot. Commit: ed02787 Link to invocation

[tensorrt-cicd]

PR_Github #55535 [ run ] completed with state FAILURE. Commit: ed02787
/LLM/main/L0_MergeRequest_PR pipeline #44460 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #55551 [ run ] triggered by Bot. Commit: ed02787 Link to invocation

[tensorrt-cicd]

PR_Github #55551 [ run ] completed with state FAILURE. Commit: ed02787
/LLM/main/L0_MergeRequest_PR pipeline #44473 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[o-stoner]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #55566 [ run ] triggered by Bot. Commit: ed02787 Link to invocation

[tensorrt-cicd]

PR_Github #55566 [ run ] completed with state FAILURE. Commit: ed02787
/LLM/main/L0_MergeRequest_PR pipeline #44487 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[tburt-nv]

/bot run --stage-list "GB200-4_GPUs-PyTorch-PerfSanity-1,GB200-4_GPUs-PyTorch-PerfSanity-2"

[tensorrt-cicd]

PR_Github #55576 [ run ] triggered by Bot. Commit: 162c386 Link to invocation

[tensorrt-cicd]

PR_Github #55576 [ run ] completed with state SUCCESS. Commit: 162c386
/LLM/main/L0_MergeRequest_PR pipeline #44495 (Partly Tested) completed with status: 'SUCCESS'

CI Report

Link to invocation

[o-stoner]

/bot reuse-pipeline

[tensorrt-cicd]

PR_Github #55637 [ reuse-pipeline ] triggered by Bot. Commit: 778f2d6 Link to invocation

[tensorrt-cicd]

PR_Github #55637 [ reuse-pipeline ] completed with state SUCCESS. Commit: 778f2d6
Reusing PR_Github #55576 (Partly Tested) for commit 778f2d6

Link to invocation

[nv-guomingz]

LGTM for doc part