parse.py 23 KB
Newer Older
1
# SPDX-License-Identifier: Apache-2.0
2
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
3

4
5
from abc import ABC, abstractmethod
from collections import UserDict
6
from collections.abc import Callable, Iterator, Mapping, Sequence, Set
7
8
9
10
11
12
from typing import (
    TYPE_CHECKING,
    Any,
    Generic,
    Literal,
    NamedTuple,
13
14
    TypeAlias,
    TypeGuard,
15
16
    TypeVar,
)
17
18
19

import numpy as np
import torch
20
from typing_extensions import assert_never
21

22
from vllm.utils.collection_utils import is_list_of
23
from vllm.utils.import_utils import LazyLoader
24

25
from .audio import AudioResampler, AudioSpec, normalize_audio
26
27
28
29
30
31
32
33
34
35
from .inputs import (
    AudioItem,
    HfAudioItem,
    HfImageItem,
    HfVideoItem,
    ImageItem,
    ModalityData,
    MultiModalDataDict,
    MultiModalFieldConfig,
    MultiModalKwargsItems,
36
    MultiModalUUIDDict,
37
38
    VideoItem,
)
39
from .media import MediaWithBytes
40
41
42
43

_T = TypeVar("_T")
_I = TypeVar("_I")

44
45
46
47
48
if TYPE_CHECKING:
    import PIL.Image as PILImage
else:
    PILImage = LazyLoader("PILImage", globals(), "PIL.Image")

49
50

class ModalityDataItems(ABC, Generic[_T, _I]):
51
    """
52
53
    Represents data items for a modality in
    [`MultiModalDataItems`][vllm.multimodal.parse.MultiModalDataItems].
54
    """
55

56
    def __init__(self, data: _T, modality: str) -> None:
57
58
        super().__init__()

59
        self.data: _T = data
60
61
62
        self.modality = modality

    def __repr__(self) -> str:
63
        return f"{type(self).__name__}(modality={self.modality!r}, len={len(self)})"
64
65
66
67
68
69
70
71
72

    def __len__(self) -> int:
        return self.get_count()

    def __getitem__(self, index: int) -> _I:
        return self.get(index)

    if TYPE_CHECKING:
        # Auto-generated
73
        def __iter__(self) -> Iterator[_I]: ...
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

    @abstractmethod
    def get_count(self) -> int:
        """Get the number of data items."""
        raise NotImplementedError

    @abstractmethod
    def get(self, index: int) -> _I:
        """Get a data item by its index."""
        raise NotImplementedError

    def get_all(self) -> list[_I]:
        """Get all data items."""
        return [self.get(idx) for idx in range(self.get_count())]

89
90
91
92
93
94
    def get_item_for_hash(self, index: int) -> object:
        return self.get(index)

    def get_all_items_for_hash(self) -> list[object]:
        return [self.get_item_for_hash(idx) for idx in range(self.get_count())]

95
96
97
98
99
100
101
102
103
104
105
106
    @abstractmethod
    def get_processor_data(self) -> Mapping[str, object]:
        """Get the data to pass to the HF processor."""
        raise NotImplementedError

    @abstractmethod
    def get_passthrough_data(self) -> Mapping[str, object]:
        """Get the data to pass directly to the model."""
        raise NotImplementedError


class ProcessorBatchItems(ModalityDataItems[Sequence[_T], _T]):
107
    """Base class for data items that are arranged in a list."""
108

109
110
111
112
    def _unwrap(self, item: _T | MediaWithBytes[_T]) -> _T:
        """Extract media from wrapper if present."""
        return item.media if isinstance(item, MediaWithBytes) else item

113
114
115
116
    def get_count(self) -> int:
        return len(self.data)

    def get(self, index: int) -> _T:
117
118
119
120
        return self._unwrap(self.data[index])

    def get_item_for_hash(self, index: int) -> _T | MediaWithBytes[_T]:
        # Return raw item for hashing (preserves original_bytes if present)
121
122
123
        return self.data[index]

    def get_processor_data(self) -> Mapping[str, object]:
124
        return {f"{self.modality}s": self.get_all()}
125
126
127
128
129

    def get_passthrough_data(self) -> Mapping[str, object]:
        return {}


130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def validate_embedding_ndim(
    tensor: torch.Tensor,
    modality: str,
    index: int | None = None,
) -> None:
    """Validate tensor ndim for multimodal embeddings.

    Single embeddings should be 2D (seq_len, hidden_size).
    Batched embeddings should be 3D (batch, seq_len, hidden_size).

    Args:
        tensor: The tensor to validate.
        modality: The modality name for error messages (e.g., "image", "audio").
        index: Optional index for list items, included in error messages.
    """
    if tensor.ndim < 2 or tensor.ndim > 3:
        idx_str = f" [{index}]" if index is not None else ""
        raise ValueError(
            f"{modality.capitalize()} embedding{idx_str} must be 2D "
            f"(seq_len, hidden_size) or 3D (batch, seq_len, hidden_size), "
            f"got {tensor.ndim}D tensor with shape {tuple(tensor.shape)}"
        )


154
class EmbeddingItems(
155
    ModalityDataItems[torch.Tensor | list[torch.Tensor], torch.Tensor]
156
):
157
158
159
160
    """
    Base class for data items that are expressed as a batched embedding tensor,
    or a list of embedding tensors (one per item).
    """
161

162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
    def __init__(
        self,
        data: torch.Tensor | list[torch.Tensor],
        modality: str,
        expected_hidden_size: int | None = None,
    ) -> None:
        super().__init__(data, modality)

        # Validate ndim first (before hidden_size which depends on correct ndim)
        self._validate_ndim()

        # Validate hidden dimension if expected size is provided
        if expected_hidden_size is not None:
            self._validate_hidden_size(expected_hidden_size)

    def _validate_ndim(self) -> None:
        """Validate that embedding tensors have correct ndim (2D or 3D)."""
        if isinstance(self.data, torch.Tensor):
            validate_embedding_ndim(self.data, self.modality)
        else:
            # List of tensors: each should be 2D (seq_len, hidden_size)
            for idx, tensor in enumerate(self.data):
                if tensor.ndim != 2:
                    raise ValueError(
                        f"{self.modality.capitalize()} embedding [{idx}] must be "
                        f"2D (seq_len, hidden_size), got {tensor.ndim}D tensor "
                        f"with shape {tuple(tensor.shape)}"
                    )

    def _validate_hidden_size(self, expected_hidden_size: int) -> None:
        """Validate that embedding hidden dimension matches expected size.

        This validates hidden dimensions to prevent vulnerabilities: Embeddings
        with correct ndim but wrong hidden dimension could bypass initial
        checks and cause crashes during model inference when dimensions don't match.
        """
        if isinstance(self.data, torch.Tensor):
            # Batched tensor: shape is (batch, seq_len, hidden_size)
            actual_hidden_size = self.data.shape[-1]
            if actual_hidden_size != expected_hidden_size:
                raise ValueError(
                    f"{self.modality.capitalize()} embedding hidden dimension "
                    f"mismatch: got {actual_hidden_size}, but model expects "
                    f"{expected_hidden_size}. Embedding shape: {tuple(self.data.shape)}"
                )
        else:
            # List of tensors: each has shape (seq_len, hidden_size)
            for idx, tensor in enumerate(self.data):
                actual_hidden_size = tensor.shape[-1]
                if actual_hidden_size != expected_hidden_size:
                    raise ValueError(
                        f"{self.modality.capitalize()} embedding [{idx}] hidden "
                        f"dimension mismatch: got {actual_hidden_size}, but model "
                        f"expects {expected_hidden_size}. "
                        f"Embedding shape: {tuple(tensor.shape)}"
                    )

219
220
221
222
223
224
    def _unwrap(
        self, item: torch.Tensor | MediaWithBytes[torch.Tensor]
    ) -> torch.Tensor:
        """Extract media from wrapper if present."""
        return item.media if isinstance(item, MediaWithBytes) else item

225
226
227
    def get_count(self) -> int:
        return len(self.data)

228
    def get(self, index: int) -> torch.Tensor:
229
        return self._unwrap(self.data[index])
230
231
232
233
234
235
236

    def get_processor_data(self) -> Mapping[str, object]:
        return {}

    def get_passthrough_data(self) -> Mapping[str, object]:
        return {f"{self.modality}_embeds": self.data}

237
238
239
    def get_feature_size(self, item_idx: int) -> int:
        return len(self.get(item_idx))

240

241
242
243
class DictEmbeddingItems(
    ModalityDataItems[Mapping[str, torch.Tensor], Mapping[str, torch.Tensor]]
):
244
245
246
247
248
249
250
251
252
253
254
    """
    Base class for data items that are expressed as a dictionary of tensors.

    Usually, the dictionary keys correspond to the outputs of HF processor.
    """

    def __init__(
        self,
        data: Mapping[str, torch.Tensor],
        modality: str,
        required_fields: set[str],
255
256
257
258
        fields_factory: Callable[
            [Mapping[str, torch.Tensor]],
            Mapping[str, MultiModalFieldConfig],
        ],
259
    ) -> None:
260
261
        from transformers.feature_extraction_utils import BatchFeature

262
263
264
265
266
        super().__init__(data, modality)

        missing_required_data_keys = required_fields - data.keys()
        if missing_required_data_keys:
            data_keys = set(data.keys())
267
268
269
270
            msg = (
                f"The data should contain the fields: {required_fields}, "
                f"but only found the following keys: {data_keys}"
            )
271
272
            raise ValueError(msg)

273
274
275
276
277
278
279
        fields_config = fields_factory(data)
        missing_required_fields = required_fields - fields_config.keys()
        if missing_required_fields:
            fields = set(fields_config.keys())
            msg = f"{required_fields=} should be a subset of {fields=}"
            raise ValueError(msg)

280
281
282
        self.fields_config = fields_config
        self.required_fields = required_fields

283
        self._kwargs = MultiModalKwargsItems.from_hf_inputs(
284
285
286
287
288
            BatchFeature(dict(data)),
            fields_config,
        )

    def get_count(self) -> int:
289
        return len(self._kwargs[self.modality])
290
291

    def get(self, index: int) -> Mapping[str, torch.Tensor]:
292
        return self._kwargs[self.modality][index].get_data()
293
294
295
296
297
298
299
300

    def get_processor_data(self) -> Mapping[str, object]:
        return {}

    def get_passthrough_data(self) -> Mapping[str, object]:
        return self.data


301
302
class AudioProcessorItems(ProcessorBatchItems[HfAudioItem | None]):
    def __init__(self, data: Sequence[HfAudioItem | None]) -> None:
303
304
        super().__init__(data, "audio")

305
306
    def get_audio_length(self, item_idx: int) -> int:
        audio = self.get(item_idx)
307
308
309
        if audio is None:
            raise ValueError(f"Cannot get length of cached audio at {item_idx}")

310
311
        return len(audio)

312
313

class AudioEmbeddingItems(EmbeddingItems):
314
315
316
317
318
319
    def __init__(
        self,
        data: torch.Tensor | list[torch.Tensor],
        expected_hidden_size: int | None = None,
    ) -> None:
        super().__init__(data, "audio", expected_hidden_size)
320
321
322
323
324
325
326


class ImageSize(NamedTuple):
    width: int
    height: int


327
328
class ImageProcessorItems(ProcessorBatchItems[HfImageItem | None]):
    def __init__(self, data: Sequence[HfImageItem | None]) -> None:
329
330
331
332
        super().__init__(data, "image")

    def get_image_size(self, item_idx: int) -> ImageSize:
        image = self.get(item_idx)
333
334
        if image is None:
            raise ValueError(f"Cannot get size of cached image at {item_idx}")
335

336
        if isinstance(image, PILImage.Image):
337
338
339
340
341
342
343
344
345
            return ImageSize(*image.size)
        if isinstance(image, (np.ndarray, torch.Tensor)):
            _, h, w = image.shape
            return ImageSize(w, h)

        assert_never(image)


class ImageEmbeddingItems(EmbeddingItems):
346
347
348
349
350
351
    def __init__(
        self,
        data: torch.Tensor | list[torch.Tensor],
        expected_hidden_size: int | None = None,
    ) -> None:
        super().__init__(data, "image", expected_hidden_size)
352
353


354
class VideoProcessorItems(ProcessorBatchItems[HfVideoItem | None]):
355
356
    def __init__(
        self,
357
        data: Sequence[HfVideoItem | None],
358
        metadata: dict[str, Any] | list[dict[str, Any] | None] | None = None,
359
    ) -> None:
360
        super().__init__(data, "video")
361

362
        self.metadata = metadata
363

364
    def get_num_frames(self, item_idx: int) -> int:
365
366
367
368
369
        video = self.get(item_idx)
        if video is None:
            raise ValueError(f"Cannot get length of cached video at {item_idx}")

        return len(video)
370
371

    def get_frame_size(self, item_idx: int) -> ImageSize:
372
373
374
375
376
377
378
        video = self.get(item_idx)
        if video is None:
            raise ValueError(f"Cannot get size of cached video at {item_idx}")
        if len(video) == 0:
            raise ValueError(f"Cannot get size of empty video at {item_idx}")

        image = video[0]
379

380
        if isinstance(image, PILImage.Image):
381
382
383
384
385
386
387
            return ImageSize(*image.size)
        if isinstance(image, (np.ndarray, torch.Tensor)):
            _, h, w = image.shape
            return ImageSize(w, h)

        assert_never(image)

388
389

class VideoEmbeddingItems(EmbeddingItems):
390
391
392
393
394
395
    def __init__(
        self,
        data: torch.Tensor | list[torch.Tensor],
        expected_hidden_size: int | None = None,
    ) -> None:
        super().__init__(data, "video", expected_hidden_size)
396
397


Roger Wang's avatar
Roger Wang committed
398
399
400
401
402
403
404
class VisionChunkProcessorItems(ProcessorBatchItems[Any]):
    """Processor items for vision chunks (unified image and video chunks)."""

    def __init__(self, data: Sequence[Any]) -> None:
        super().__init__(data, "vision_chunk")


405
406
407
408
409
_D = TypeVar("_D", bound=ModalityDataItems[Any, Any])


class MultiModalDataItems(UserDict[str, ModalityDataItems[Any, Any]]):
    """
410
411
    As [`MultiModalDataDict`][vllm.multimodal.inputs.MultiModalDataDict], but
    normalized such that each entry corresponds to a list.
412
413
    """

414
415
416
417
418
419
420
421
422
    def select(self, modalities: Set[str]):
        """
        Construct a new `MultiModalDataItems` instance containing only the
        selected modalities.
        """
        return MultiModalDataItems(
            {modality: self[modality] for modality in modalities}
        )

423
424
425
    def get_count(self, modality: str, *, strict: bool = True) -> int:
        """
        Get the number of data items belonging to a modality.
426

427
        If `strict=False`, return `0` instead of raising [`KeyError`][]
428
429
430
431
432
        even if the modality is not found.
        """
        if modality not in self:
            if strict:
                available_modalities = set(self.keys())
433
434
435
436
                raise KeyError(
                    f"Modality {modality!r} not found. "
                    f"Available modalities: {available_modalities}"
                )
437
438
439
440
441
442
443
444
445
446
447
448

            return 0

        return self[modality].get_count()

    def get_all_counts(self) -> Mapping[str, int]:
        """Get the number of items belonging to each modality."""
        return {m: items.get_count() for m, items in self.items()}

    def get_items(
        self,
        modality: str,
449
        typ: type[_D] | tuple[type[_D], ...],
450
451
452
453
454
455
456
    ) -> _D:
        """
        Get the data items belonging to a modality,
        requiring that they belong to a certain type.
        """
        if modality not in self:
            available_modalities = set(self.keys())
457
458
459
460
            raise KeyError(
                f"Modality {modality!r} not found. "
                f"Available modalities: {available_modalities}"
            )
461
462
463

        items = self[modality]
        if not isinstance(items, typ):
464
465
466
467
468
            raise TypeError(
                f"Invalid type of data items for {modality=}. "
                f"Expected type: {typ}, but "
                f"found type: {type(items)}"
            )
469

470
        return items  # type: ignore[return-value]
471
472


473
ModalityDataParser: TypeAlias = Callable[
474
    [ModalityData[Any]], ModalityDataItems[Any, Any] | None
475
]
476
477
478
479


class MultiModalDataParser:
    """
480
481
    Parses [`MultiModalDataDict`][vllm.multimodal.inputs.MultiModalDataDict]
    into [`MultiModalDataItems`][vllm.multimodal.parse.MultiModalDataItems].
482
483
484
485

    Args:
        target_sr (float, optional): Enables automatic resampling of audio
            items to the model's expected sampling rate.
486
487
488
        target_channels (int, optional): Target number of audio channels.
            If provided, normalizes audio to this many channels (e.g., 1 for mono).
            If None, audio channels are passed through unchanged.
489
490
491
492
        expected_hidden_size (int, optional): Expected hidden dimension for
            embedding inputs. If provided, validates that user-supplied
            embeddings have the correct hidden size to prevent crashes
            during model inference.
493
494
    """

495
496
497
    def __init__(
        self,
        *,
498
        target_sr: float | None = None,
499
        target_channels: int | None = None,
500
        audio_resample_method: Literal["pyav", "scipy"] = "pyav",
501
        video_needs_metadata: bool = False,
502
        expected_hidden_size: int | None = None,
503
    ) -> None:
504
505
        super().__init__()

506
507
508
509
        self.audio_resampler = AudioResampler(
            target_sr=target_sr,
            method=audio_resample_method,
        )
510
        self.target_channels = target_channels
511
        self.video_needs_metadata = video_needs_metadata
512
        self.expected_hidden_size = expected_hidden_size
513

514
515
516
    @classmethod
    def is_embeddings(
        cls, data: object
517
    ) -> TypeGuard[torch.Tensor | list[torch.Tensor]]:
518
519
        if isinstance(data, torch.Tensor):
            return data.ndim == 3
520
        if is_list_of(data, torch.Tensor) and len(data) > 0:
521
            return data[0].ndim == 2  # type: ignore[index]
522
523
524

        return False

525
526
527
    def _get_audio_with_sr(
        self,
        audio: AudioItem,
528
    ) -> tuple[np.ndarray, float | None]:
529
530
531
532
533
534
535
536
537
538
539
        if isinstance(audio, tuple):
            return audio
        if isinstance(audio, list):
            return np.array(audio), None
        if isinstance(audio, np.ndarray):
            return audio, None
        if isinstance(audio, torch.Tensor):
            return audio.numpy(), None

        assert_never(audio)

540
541
542
    def _get_video_with_metadata(
        self,
        video: VideoItem,
543
    ) -> tuple[np.ndarray, dict[str, Any] | None]:
544
545
546
547
548
549
550
551
552
553
554
        if isinstance(video, tuple):
            return video
        if isinstance(video, list):
            return np.array(video), None
        if isinstance(video, np.ndarray):
            return video, None
        if isinstance(video, torch.Tensor):
            return video.numpy(), None

        assert_never(video)

555
556
557
    def _parse_audio_data(
        self,
        data: ModalityData[AudioItem],
558
    ) -> ModalityDataItems[Any, Any] | None:
559
        if data is None:
560
561
            return None

562
        if self.is_embeddings(data):
563
            return AudioEmbeddingItems(data, self.expected_hidden_size)
564

565
        data_items: list[AudioItem]
566
        if (
567
568
            (is_list_of(data, float) and len(data) > 0)
            or (isinstance(data, (np.ndarray, torch.Tensor)) and data.ndim == 1)
569
570
            or isinstance(data, tuple)
        ):
571
572
573
574
            data_items = [data]
        elif isinstance(data, (np.ndarray, torch.Tensor)):
            data_items = [elem for elem in data]
        else:
575
            data_items = data  # type: ignore[assignment]
576
577
578
579
580
581
582

        new_audios = list[np.ndarray]()
        for data_item in data_items:
            audio, orig_sr = self._get_audio_with_sr(data_item)
            if orig_sr is None:
                new_audio = audio
            else:
583
                new_audio = self.audio_resampler.resample(audio, orig_sr=orig_sr)
584

585
586
587
588
589
            # Apply channel normalization if target_channels is set
            if self.target_channels is not None:
                spec = AudioSpec(target_channels=self.target_channels)
                new_audio = normalize_audio(new_audio, spec)

590
591
592
593
594
595
596
            new_audios.append(new_audio)

        return AudioProcessorItems(new_audios)

    def _parse_image_data(
        self,
        data: ModalityData[ImageItem],
597
    ) -> ModalityDataItems[Any, Any] | None:
598
        if data is None:
599
600
            return None

601
        if self.is_embeddings(data):
602
            return ImageEmbeddingItems(data, self.expected_hidden_size)
603

604
605
        if isinstance(data, (PILImage.Image, MediaWithBytes)) or (
            isinstance(data, (np.ndarray, torch.Tensor)) and data.ndim == 3
606
        ):
607
608
609
610
611
612
613
614
615
616
617
            data_items = [data]
        elif isinstance(data, (np.ndarray, torch.Tensor)):
            data_items = [elem for elem in data]
        else:
            data_items = data

        return ImageProcessorItems(data_items)

    def _parse_video_data(
        self,
        data: ModalityData[VideoItem],
618
    ) -> ModalityDataItems[Any, Any] | None:
619
        if data is None:
620
621
            return None

622
        if self.is_embeddings(data):
623
            return VideoEmbeddingItems(data, self.expected_hidden_size)
624

625
        data_items: list[VideoItem]
626
627
        if (is_list_of(data, PILImage.Image) and len(data) > 0) or (
            isinstance(data, (np.ndarray, torch.Tensor)) and data.ndim == 4
628
        ):
629
630
631
            data_items = [data]
        elif isinstance(data, (np.ndarray, torch.Tensor)):
            data_items = [elem for elem in data]
632
633
        elif isinstance(data, tuple) and len(data) == 2:
            data_items = [data]
634
        else:
635
            data_items = data  # type: ignore[assignment]
636

637
638
        new_videos = list[tuple[np.ndarray, dict[str, Any] | None]]()
        metadata_lst: list[dict[str, Any] | None] = []
639
640
641
        for data_item in data_items:
            video, metadata = self._get_video_with_metadata(data_item)
            if self.video_needs_metadata:
642
643
644
645
646
                if metadata is None:
                    raise ValueError(
                        "Video metadata is required but not found in mm input. "
                        "Please check your video input in `multi_modal_data`"
                    )
647
648
649
650
651
652
653
654
655
                new_videos.append((video, metadata))
                metadata_lst.append(metadata)
            else:
                new_videos.append(video)

        if not self.video_needs_metadata:
            metadata = None

        return VideoProcessorItems(new_videos, metadata=metadata_lst)
656

Roger Wang's avatar
Roger Wang committed
657
658
659
660
661
    def _parse_vision_chunk_data(
        self,
        data: ModalityData[Any],
    ) -> ModalityDataItems[Any, Any] | None:
        """Parse vision chunk data (unified image and video chunks)."""
662
        if data is None:
Roger Wang's avatar
Roger Wang committed
663
            return None
664

Roger Wang's avatar
Roger Wang committed
665
666
        if self.is_embeddings(data):
            raise ValueError("Do not support embedding data for vision_chunk right now")
667

668
669
        if isinstance(data, dict):
            data = [data]
670

Roger Wang's avatar
Roger Wang committed
671
672
        return VisionChunkProcessorItems(data)

673
674
675
676
677
    def _get_subparsers(self) -> Mapping[str, ModalityDataParser]:
        return {
            "audio": self._parse_audio_data,
            "image": self._parse_image_data,
            "video": self._parse_video_data,
Roger Wang's avatar
Roger Wang committed
678
            "vision_chunk": self._parse_vision_chunk_data,
679
680
        }

681
    def parse_mm_data(self, mm_data: MultiModalDataDict) -> MultiModalDataItems:
682
683
684
685
686
687
688
        subparsers = self._get_subparsers()

        mm_items = MultiModalDataItems()
        for k, v in mm_data.items():
            if k not in subparsers:
                raise ValueError(f"Unsupported modality: {k}")

689
690
691
            # ignore empty embedding data
            if (parsed_data := subparsers[k](v)) is not None:
                mm_items[k] = parsed_data
692
693

        return mm_items
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710


MultiModalUUIDItems: TypeAlias = dict[str, Sequence[str | None]]
"""
As [`MultiModalUUIDDict`][vllm.multimodal.inputs.MultiModalUUIDDict], but
normalized such that each entry corresponds to a list.
"""


def parse_mm_uuids(mm_uuids: MultiModalUUIDDict | None) -> MultiModalUUIDItems:
    if mm_uuids is None:
        return {}

    return {
        modality: [uuids] if isinstance(uuids, str) else uuids
        for modality, uuids in mm_uuids.items()
    }