Skip to content

Add out-of-tree DFlash extension points - #38740

Merged
BBuf merged 3 commits into
sgl-project:mainfrom
yuhanchan:oot-dflash-extension-points
Sep 20, 2026
Merged

BBuf merged 3 commits into
sgl-project:mainfrom
yuhanchan:oot-dflash-extension-points

Conversation

@yuhanchan

@yuhanchan yuhanchan commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Motivation

Out-of-tree platforms currently cannot use DFlash without patching SGLang
internals. DFlash support, draft attention backend selection, speculative KV-
cache location assignment, and graph-capture behavior are hard-coded for
built-in platforms.

Modifications

  • Add conservative DFlash capability APIs to SRTPlatform.
  • Allow out-of-tree platforms to provide speculative KV-cache locations.
  • Allow custom draft attention backends and platform-specific fallback
    backends.
  • Respect support_cuda_graph() when initializing the DFlash draft worker.
  • Add unit coverage for capability defaults, backend validation and fallback,
    and cache-location dispatch.

Existing behavior for built-in platforms remains unchanged.

Accuracy Tests

This changes platform integration and dispatch rather than model computation.

Added focused unit tests covering:

  • Conservative defaults for platforms without DFlash support.
  • Acceptance of an out-of-tree draft attention backend.
  • Fallback to the platform’s default attention backend.
  • Actionable errors when no default backend is implemented.
  • Cache-location dispatch following the active platform.

Local runtime tests were not run because the checkout does not currently have
torch or pytest installed. Python syntax validation passed.

Speed Tests and Profiling

Not run. No model kernels or numerical operations are changed. Built-in
platforms retain their existing implementations; the new dispatch path is
used only by out-of-tree platforms.

Checklist

  • Format your code according to the [formatting guide](https://
    docs.sglang.io/developer_guide/contribution_guide.html#format-code-with-pre-
    commit).
  • Add unit tests according to the [unit-test guide](https://
    docs.sglang.io/developer_guide/contribution_guide.html#run-and-add-unit-
    tests).
  • Documentation is not required because this adds internal platform
    extension points with docstrings.
  • Accuracy and speed benchmarks are not applicable because model
    computation is unchanged.
  • Follow the SGLang code-style guidance.

CI States

Latest PR Test (Base): ❌ Run #35443345709
Latest PR Test (Extra): ❌ Run #35443345603
Latest PR Test (AMD ROCm 10): ❌ Run #35443345692

@alexnails alexnails left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have not really scoped the other parts of spec dec yet, what does it look to lift eagle and other spec dec methods?

@yuhanchan

Copy link
Copy Markdown
Contributor Author

@alexnails This PR is explicitly targeting adding a DFlash OOT, I have not looked at other spec dec method yet.

handle_speculative_decoding(args)

self.assertEqual(args.speculative_draft_attention_backend, "custom_backend")
self.assertTrue(any("got 'typo'" in message for message in logs.output))

@BBuf BBuf Sep 16, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This assertion does not match the new warning message: the implementation logs does not support attention_backend 'typo', without got. This test should fail once it is executed. Could we update the assertion or the warning text?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed!

PlatformWithoutDefault(),
),
patch(
"sglang.srt.arg_groups.overrides.attention_backends_of",

@BBuf BBuf Sep 16, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

speculative_hook imports attention_backends_of directly, so patching the symbol in overrides will not replace the binding used by the code under test. Could we patch sglang.srt.arg_groups.speculative_hook.attention_backends_of instead?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed!

return "triton" if get_platform().is_hip else "flashinfer"

def is_supported_backend(backend: str) -> bool:
return backend in supported_draft_backends or (

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For an out-of-tree platform, should this capability hook be authoritative rather than additive? Currently, any backend in supported_draft_backends is accepted even if supports_speculative_draft_attention_backend() returns False, and trtllm_mha bypasses the hook entirely. This may defer an unsupported-backend failure until initialization. Could we branch on is_out_of_tree() first and add tests for explicit built-in backend values on an OOT platform?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! that makes sense, fixed!

def get_fallback_backend() -> str:
if current_platform.is_out_of_tree():
try:
return current_platform.get_default_attention_backend()

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the result of get_default_attention_backend() also be validated with supports_speculative_draft_attention_backend()? A platform default attention backend may not necessarily be supported by the DFlash draft worker. Alternatively, a dedicated get_default_speculative_draft_attention_backend() hook might make this contract clearer.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed!

@yuhanchan
yuhanchan force-pushed the oot-dflash-extension-points branch 3 times, most recently from e4cd96a to 076a625 Compare September 17, 2026 00:05
@@ -0,0 +1,190 @@
import unittest

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The test file is too long, can we clean up this?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did a clean up, lint, and rebase~

@yuhanchan
yuhanchan force-pushed the oot-dflash-extension-points branch from 076a625 to a02e333 Compare September 18, 2026 22:51
…points

# Conflicts:
#	python/sglang/srt/platforms/interface.py
@yuhanchan
yuhanchan force-pushed the oot-dflash-extension-points branch from a02e333 to c8dce21 Compare September 18, 2026 23:04
@BBuf BBuf added the run-ci CI: run the baseline test suite on this PR label Sep 19, 2026
@BBuf
BBuf merged commit 99a44c8 into sgl-project:main Sep 20, 2026
183 of 207 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

jit-kernel run-ci CI: run the baseline test suite on this PR speculative-decoding

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants