Skip to content

feat: separate image loader - #29712

Closed
fanshuaishuai1 wants to merge 27 commits into
sgl-project:mainfrom
fanshuaishuai1:dev/fanshuaishuai/feat_overlap_image_load
Closed

fanshuaishuai1 wants to merge 27 commits into
sgl-project:mainfrom
fanshuaishuai1:dev/fanshuaishuai/feat_overlap_image_load

Conversation

@fanshuaishuai1

@fanshuaishuai1 fanshuaishuai1 commented Jun 30, 2026 •

Copy link
Copy Markdown

Port the multiprocess overlapped image-loading pipeline onto the current EncoderScheduler/MMEncoder structure: a pool of loader processes decode each collected IMAGE batch off the GPU path while a separate event-loop thread runs the GPU encode, so the next batch loads while the current one encodes.

  • Add image_loader.py (torch.multiprocessing worker pool)
  • EncoderScheduler spawns the loader pool + preprocess thread; IMAGE groups are enqueued for out-of-process decode, AUDIO/VIDEO stay on the inline path
  • batch_encode accepts preloaded images (rank-0 only); TP workers reload inline so collective broadcasts stay aligned
  • Register SGLANG_ENCODER_IMAGE_LOADER_WORKERS in environ.py

Motivation

Modifications

Accuracy Tests

Speed Tests and Profiling

Checklist

Review and Merge Process

  1. Ping Merge Oncalls to start the process. See the PR Merge Process.
  2. Get approvals from CODEOWNERS and other reviewers.
  3. Trigger CI tests with comments or contact authorized users to do so.
    • Common commands include /tag-and-rerun-ci, /tag-run-ci-label, /rerun-failed-ci
  4. After green CI and required approvals, ask Merge Oncalls or people with Write permission to merge the PR.
image

CI States

Latest PR Test (Base): ❌ Run #30974500404
Latest PR Test (Extra): ❌ Run #30974500205

Port the multiprocess overlapped image-loading pipeline onto the current
EncoderScheduler/MMEncoder structure: a pool of loader processes decode each
collected IMAGE batch off the GPU path while a separate event-loop thread runs
the GPU encode, so the next batch loads while the current one encodes.

- Add image_loader.py (torch.multiprocessing worker pool)
- EncoderScheduler spawns the loader pool + preprocess thread; IMAGE groups are
  enqueued for out-of-process decode, AUDIO/VIDEO stay on the inline path
- batch_encode accepts preloaded images (rank-0 only); TP workers reload inline
  so collective broadcasts stay aligned
- Register SGLANG_ENCODER_IMAGE_LOADER_WORKERS in environ.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@gemini-code-assist

Copy link
Copy Markdown
Contributor

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

@liusy58

liusy58 commented Jul 10, 2026

Copy link
Copy Markdown
Collaborator

@fanshuaishuai1 Please resolve the conflicts.

@liusy58

liusy58 commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator

@fanshuaishuai1 Please fix the lint

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@liusy58

liusy58 commented Jul 15, 2026

Copy link
Copy Markdown
Collaborator

LGTM, let's see the CI status.

@liusy58 liusy58 added the run-ci CI: run the baseline test suite on this PR label Jul 15, 2026
@liusy58

liusy58 commented Jul 17, 2026

Copy link
Copy Markdown
Collaborator

It seems that only TP=1 is currently supported. Should we support TP > 1 in this PR, or leave it for a follow-up?

@fanshuaishuai1

Copy link
Copy Markdown
Author

It seems that only TP=1 is currently supported. Should we support TP > 1 in this PR, or leave it for a follow-up?

leave it for a follow-up

@liusy58

liusy58 commented Jul 21, 2026

Copy link
Copy Markdown
Collaborator

@fanshuaishuai1 In that case, we should raise an error when TP > 1.

Images are preloaded on rank 0 only while TP workers load inline, and the
loader-consumer thread dispatches on a second event loop, so the ZMQ send
order can diverge from rank-0's collective forward order. Fail fast at
startup instead of risking a collective mismatch. The DP worker path is
unaffected since it forces tp_size=1.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@fanshuaishuai1

Copy link
Copy Markdown
Author

@fanshuaishuai1 In that case, we should raise an error when TP > 1.

Done

@fanshuaishuai1 fanshuaishuai1 changed the title separate image loader feat: separate image loader Jul 22, 2026
@liusy58

liusy58 commented Jul 30, 2026

Copy link
Copy Markdown
Collaborator

We need an option to turn this feature on.

fanshuaishuai1 and others added 15 commits July 31, 2026 00:58
Add SGLANG_ENCODER_ENABLE_IMAGE_LOADER (EnvBool, default on) to gate the
multiprocess overlapped image-loading pipeline. When disabled, the loader
process pool and preprocess/encode thread are not spawned and IMAGE batches
decode inline on the dispatch path.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@liusy58

liusy58 commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

@fanshuaishuai1 Please stop merge main, this will trigger the CI limits

coalesce_same_turn: bool = False,
request_timeout: float = ENCODER_REQ_TIMEOUT,
):
if encoder.server_args.tp_size > 1:

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'm not sure if this will break the current logic (e.g., cases where the encoder is intended to run with TP > 1). I'd like to make this feature configurable via an environment variable.

@fanshuaishuai1

Copy link
Copy Markdown
Author

@fanshuaishuai1 Please stop merge main, this will trigger the CI limits

get

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Thanks @fanshuaishuai1. Closing this because it has had no updates in 91 days.

Reopen it if the work is still relevant.

Some directories moved recently, so an older branch may need retargeting:
sgl-kernel/ -> python/sglang/kernels/aot/, python/sglang/jit_kernel/
-> python/sglang/kernels/jit/, docs/ -> docs/docs/ (.mdx),
bench_serving.py -> benchmark/serving.py, test/srt/ -> test/registered/.

@github-actions github-actions Bot closed this Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

run-ci CI: run the baseline test suite on this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants