Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
"""A singular `image` column holding a list takes the plural path: TRL wraps the cell
again, so two images reach the processor as [[[img, img]]]. unslothai/unsloth#3605."""
import textwrap
import pytest
from unsloth.models.rl_replacements import (
_unsloth_grpo_image_cell,
_unsloth_reject_grpo_image_list,
grpo_trainer__generate_and_score_completions,
)
class _Img:
def __init__(self, name):
self.name = name
def __repr__(self):
return f"<{self.name}>"
def test_cell_helper_keeps_a_list_and_wraps_a_single_image():
a, b = _Img("a"), _Img("b")
assert _unsloth_grpo_image_cell(None) is None
assert _unsloth_grpo_image_cell(a) == [a]
assert _unsloth_grpo_image_cell([a, b]) == [a, b]
assert _unsloth_grpo_image_cell((a, b)) == [a, b]
assert _unsloth_grpo_image_cell([a, b]) != [[a, b]]
def test_the_reporter_shape_is_flattened_not_nested():
a, b = _Img("a"), _Img("b")
inputs = [{"image": [a, b]}, {"image": [a, b]}]
images = [_unsloth_grpo_image_cell(example.get("image")) for example in inputs]
assert images == [[a, b], [a, b]]
before = [[example.get("image")] for example in inputs]
assert before == [[[a, b]], [[a, b]]]
def test_single_image_cells_are_unchanged():
a = _Img("a")
inputs = [{"image": a}, {"image": a}]
assert [_unsloth_grpo_image_cell(x.get("image")) for x in inputs] == [[a], [a]]
def test_patcher_rewrites_the_installed_trl_extraction():
"""Read TRL's file, not the class: importing unsloth already replaced the method."""
trl_grpo = pytest.importorskip("trl.trainer.grpo_trainer")
with open(trl_grpo.__file__, "r", encoding = "utf-8") as fh:
module_source = fh.read()
start = module_source.find(" def _generate_and_score_completions(")
assert start != -1, "TRL renamed _generate_and_score_completions"
source = module_source[start:]
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", source
)
assert "_unsloth_grpo_image_cell" in patched or "_unsloth_reject_grpo_image_list" in patched
if "_unsloth_grpo_image_cell" in patched:
assert '[[example.get("image")] if example.get("image") is not None' not in patched
assert 'kwargs = {"images": [[img] for img in images]}' not in patched
def test_trl_0_22_placeholder_count_follows_the_cell():
source = (
' has_images = "image" in inputs[0]\n'
" if has_images:\n"
' images = [example.get("image") for example in inputs]\n'
' kwargs = {"images": [[img] for img in images]}\n'
" for prompt in prompts:\n"
" if isinstance(prompt, list): # i.e., when using conversational data\n"
" prepare_multimodal_messages(prompt, num_images=1)\n"
)
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", source
)
assert "_unsloth_grpo_image_cell(img)" in patched
assert "num_images=1)" not in patched
assert "len(_unsloth_cell)" in patched
a, b = _Img("a"), _Img("b")
calls = []
def prepare_multimodal_messages(prompt, num_images):
calls.append(num_images)
namespace = {
"inputs": [{"image": [a, b]}],
"prompts": [[{"role": "user", "content": "x"}]],
"prepare_multimodal_messages": prepare_multimodal_messages,
"_unsloth_grpo_image_cell": _unsloth_grpo_image_cell,
}
exec(textwrap.dedent(patched), namespace)
assert namespace["kwargs"]["images"] == [[a, b]]
assert calls == [2]
def test_guard_names_the_column_and_the_issue():
a, b = _Img("a"), _Img("b")
_unsloth_reject_grpo_image_list([{"image": a}])
_unsloth_reject_grpo_image_list([{"image": [a]}])
_unsloth_reject_grpo_image_list([{"prompt": "x"}])
_unsloth_reject_grpo_image_list([])
with pytest.raises(ValueError) as excinfo:
_unsloth_reject_grpo_image_list([{"image": [a, b]}])
message = str(excinfo.value)
assert "`images`" in message
assert "3605" in message
def test_the_guard_reads_every_row_not_only_the_first():
"""A list cell in any row desyncs images from placeholders, so every row must be checked."""
a, b = _Img("a"), _Img("b")
for rows in (
[{"image": [a, b]}, {"image": a}],
[{"image": a}, {"image": [a, b]}],
[{"image": a}, {"image": a}, {"image": [a, b]}],
[{"image": None}, {"image": [a, b]}],
):
with pytest.raises(ValueError) as excinfo:
_unsloth_reject_grpo_image_list(rows)
assert "3605" in str(excinfo.value)
for rows in (
[{"image": a}, {"image": a}],
[{"image": [a]}, {"image": [a]}],
[{"prompt": "x"}, {"prompt": "y"}],
["not a dict", 7],
[],
None,
):
_unsloth_reject_grpo_image_list(rows)
def test_guard_is_injected_when_no_anchor_matches():
source = " def _generate_and_score_completions(self, inputs):\n return inputs\n"
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", source
)
assert "_unsloth_reject_grpo_image_list(inputs)" in patched
lines = patched.splitlines()
assert lines[1].strip() == "_unsloth_reject_grpo_image_list(inputs)"
def test_guard_is_injected_when_the_legacy_reference_calls_drift():
"""A legacy TRL must also pass image counts into the reference logprob calls, or images are
sliced by sample index and dropped, showing as a token/feature mismatch."""
source = (
" def _generate_and_score_completions(self, inputs):\n"
' has_images = "image" in inputs[0]\n'
" if has_images:\n"
' images = [example.get("image") for example in inputs]\n'
' kwargs = {"images": [[img] for img in images]}\n'
" ref = self._get_per_token_logps_and_entropies(\n"
" self.model,\n"
' pixel_values=prompt_inputs.get("pixel_values"), image_grid_thw=None,\n'
" )\n"
" return inputs\n"
)
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", source
)
assert "_unsloth_grpo_image_cell(img)" in patched
assert "_unsloth_reject_grpo_image_list(inputs)" in patched
lines = patched.splitlines()
assert lines[1].strip() == "_unsloth_reject_grpo_image_list(inputs)"
def test_guard_stays_off_a_trl_whose_reference_calls_do_take_the_counts():
"""The installed TRL is fully plumbed, so a multi image row works and must not be refused."""
trl_grpo = pytest.importorskip("trl.trainer.grpo_trainer")
with open(trl_grpo.__file__, "r", encoding = "utf-8") as fh:
module_source = fh.read()
start = module_source.find(" def _generate_and_score_completions(")
assert start != -1, "TRL renamed _generate_and_score_completions"
source = module_source[start:]
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", source
)
assert "_unsloth_reject_grpo_image_list(inputs)" not in patched
if 'pixel_values=prompt_inputs.get("pixel_values")' in source:
assert 'pixel_values=prompt_inputs.get("pixel_values")' not in patched
assert "**_unsloth_legacy_vision," in patched
def _legacy_source(*, with_placeholder_helper):
"""TRL 0.20.0/0.21.0 against TRL 0.22.x. Both take the legacy `[[img] for img in images]`
cell spelling; only 0.22.x factored the placeholders out into a helper that takes a count.
0.20.0 and 0.21.0 inline one {"type": "image"} per user message, with no count at all."""
head = (
" def _generate_and_score_completions(self, inputs):\n"
" prompts = [x['prompt'] for x in inputs]\n"
" kwargs = {}\n"
' has_images = "image" in inputs[0]\n'
" if has_images:\n"
' images = [example.get("image") for example in inputs]\n'
' kwargs = {"images": [[img] for img in images]}\n'
)
if with_placeholder_helper:
placeholders = (
" for prompt in prompts:\n"
" if isinstance(prompt, list): # i.e., when using conversational data\n"
" prepare_multimodal_messages(prompt, num_images=1)\n"
)
else:
placeholders = (
" for prompt in prompts:\n"
" if isinstance(prompt, list):\n"
" for message in prompt:\n"
" if message.get('role') == 'user':\n"
" message['content'] = [{'type': 'image'}, message['content']]\n"
)
tail = (
" ref = self._get_per_token_logps_and_entropies(\n"
" self.model,\n"
' pixel_values=prompt_inputs.get("pixel_values"),\n'
' image_grid_thw=prompt_inputs.get("image_grid_thw"),\n'
' pixel_attention_mask=prompt_inputs.get("pixel_attention_mask"),\n'
' image_sizes=prompt_inputs.get("image_sizes"),\n'
" )\n"
" return inputs\n"
)
return head + placeholders + tail
def test_a_trl_that_cannot_size_its_placeholders_refuses_the_multi_image_row():
"""Without the guard, a TRL that cannot size its placeholders gets two images for one
placeholder and fails inside the processor, naming neither the column nor the fix."""
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", _legacy_source(with_placeholder_helper = False)
)
assert "_unsloth_grpo_image_cell(img)" in patched
assert "_unsloth_reject_grpo_image_list(inputs)" in patched
assert patched.splitlines()[1].strip() == "_unsloth_reject_grpo_image_list(inputs)"
def test_a_trl_that_can_size_its_placeholders_is_not_refused():
"""The control, and the reason the guard cannot simply key on the legacy cell spelling:
0.22.x takes the same spelling and does size its placeholders, so it must keep working."""
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", _legacy_source(with_placeholder_helper = True)
)
assert "_unsloth_grpo_image_cell(img)" in patched
assert "len(_unsloth_cell) if _unsloth_cell else 0" in patched
assert "_unsloth_reject_grpo_image_list(inputs)" not in patched
def _run_legacy_placeholders(cells):
"""Execute the rewritten TRL 0.22.x block and report what the processor would be handed."""
source = (
' has_images = "image" in inputs[0]\n'
" if has_images:\n"
' images = [example.get("image") for example in inputs]\n'
' kwargs = {"images": [[img] for img in images]}\n'
" for prompt in prompts:\n"
" if isinstance(prompt, list): # i.e., when using conversational data\n"
" prepare_multimodal_messages(prompt, num_images=1)\n"
)
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", source
)
calls = []
namespace = {
"inputs": [{"image": cell} for cell in cells],
"prompts": [[{"role": "user", "content": "x"}] for _ in cells],
"prepare_multimodal_messages": lambda prompt, num_images: calls.append(num_images),
"_unsloth_grpo_image_cell": _unsloth_grpo_image_cell,
}
exec(textwrap.dedent(patched), namespace)
return namespace["kwargs"].get("images", None), calls
def test_an_empty_cell_takes_no_placeholder_so_a_mixed_batch_stays_in_step():
"""An image-less row must take no placeholder: one placeholder leaves the prompt a token ahead
of the pixels, which a real Gemma 3 processor rejects."""
a, b = _Img("a"), _Img("b")
assert _run_legacy_placeholders([a, []]) == ([[a], []], [1, 0])
assert _run_legacy_placeholders([[a, b], []]) == ([[a, b], []], [2, 0])
assert _run_legacy_placeholders([[], a]) == ([[], [a]], [0, 1])
def test_an_all_empty_image_column_is_demoted_to_a_text_batch():
"""TRL does this itself from 0.24.0. Without it the processor is handed [[], []] against
zero placeholders, which is an IndexError inside the processor rather than a text run."""
images, calls = _run_legacy_placeholders([[], []])
assert images is None, images
assert calls == []
def test_a_none_cell_is_left_to_fail_exactly_as_it_does_on_main():
"""The guard mirrors TRL's own `all(img_list == [])`, which never fires for a None entry.
Diverging from TRL's extraction here is a bigger change than the bug is worth."""
images, calls = _run_legacy_placeholders([None, None])
assert images == [None, None], images
assert calls == [0, 0]
class _VllmTrainer:
def __init__(self, use_vllm, vllm_mode):
self.use_vllm = use_vllm
self.vllm_mode = vllm_mode
def test_the_guard_refuses_a_multi_image_row_only_in_legacy_vllm_server_mode():
"""Legacy vLLM server mode passes raw cells to VLLMClient.generate, so list cells reach list.save()."""
a, b = _Img("a"), _Img("b")
rows = [{"image": [a, b]}, {"image": a}]
with pytest.raises(ValueError) as excinfo:
_unsloth_reject_grpo_image_list(rows, _VllmTrainer(True, "server"))
assert "3605" in str(excinfo.value)
_unsloth_reject_grpo_image_list(rows, _VllmTrainer(True, "colocate"))
_unsloth_reject_grpo_image_list(rows, _VllmTrainer(False, "server"))
_unsloth_reject_grpo_image_list(rows, _VllmTrainer(False, None))
_unsloth_reject_grpo_image_list(rows, object())
_unsloth_reject_grpo_image_list([{"image": a}], _VllmTrainer(True, "server"))
# No trainer means the anchors did not land at all, so nothing is known to carry it.
with pytest.raises(ValueError):
_unsloth_reject_grpo_image_list(rows)
def test_the_legacy_guard_is_installed_with_the_trainer_and_the_modern_one_is_not():
trl_grpo = pytest.importorskip("trl.trainer.grpo_trainer")
with open(trl_grpo.__file__, "r", encoding = "utf-8") as fh:
module_source = fh.read()
start = module_source.find(" def _generate_and_score_completions(")
source = module_source[start:]
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", source
)
if 'kwargs = {"images": [[img] for img in images]}' in source:
assert "_unsloth_reject_grpo_image_list(inputs, self)" in patched
else:
assert "_unsloth_reject_grpo_image_list(inputs" not in patched
def test_demoting_an_all_empty_column_also_clears_the_image_flag():
"""Emptying `kwargs` is not enough: `has_images` gates the legacy vLLM paths, which read
the raw cells rather than `kwargs`, so a still-true flag submits `[[], ...]` as an image
payload and server mode calls `.save()` on an empty list."""
source = (
' has_images = "image" in inputs[0]\n'
" if has_images:\n"
' images = [example.get("image") for example in inputs]\n'
' kwargs = {"images": [[img] for img in images]}\n'
" for prompt in prompts:\n"
" if isinstance(prompt, list): # i.e., when using conversational data\n"
" prepare_multimodal_messages(prompt, num_images=1)\n"
)
patched = grpo_trainer__generate_and_score_completions(
"_generate_and_score_completions", source
)
assert "has_images = False" in patched
namespace = {
"inputs": [{"image": []}, {"image": []}],
"prompts": [[{"role": "user", "content": "x"}] for _ in range(2)],
"prepare_multimodal_messages": lambda prompt, num_images: None,
"_unsloth_grpo_image_cell": _unsloth_grpo_image_cell,
}
exec(textwrap.dedent(patched), namespace)
assert namespace["has_images"] is False
assert namespace["kwargs"] == {}
namespace = {
"inputs": [{"image": _Img("a")}, {"image": _Img("b")}],
"prompts": [[{"role": "user", "content": "x"}] for _ in range(2)],
"prepare_multimodal_messages": lambda prompt, num_images: None,
"_unsloth_grpo_image_cell": _unsloth_grpo_image_cell,
}
exec(textwrap.dedent(patched), namespace)
assert namespace["has_images"] is True
assert len(namespace["kwargs"]["images"]) == 2