Skip to navigation
DevelopmentAPI ReferenceFull Library ReferenceNemo AutomodelNemo AutomodelComponentsModelsKimi K3nemo_automodel.components.models.kimi_k3.processing

nemo_automodel.components.models.kimi_k3.processing

View as Markdown

Local K3 image processing and the standard Hugging Face processor contract.

Module Contents

Classes

NameDescription
KimiK3ImageProcessorCheckpoint-compatible RGB patches, including resize and alpha compositing.
KimiK3ProcessorLocal image/text processor returning expanded tokens before native packing.
_BackgroundConfig-
_MediaConfig-

Functions

NameDescription
_load_imageLoad an image without discarding alpha before the configured resize stage.

Data

_Conversation

_ImageSource

API

class nemo_automodel.components.models.kimi_k3.processing.KimiK3ImageProcessor(
    media_proc_cfg: nemo_automodel.components.models.kimi_k3.processing._MediaConfig | None = None,
    kwargs: object = {}
)

Bases: BaseImageProcessor

Checkpoint-compatible RGB patches, including resize and alpha compositing.

Parameters:

media_proc_cfg
_MediaConfig | NoneDefaults to None

Image settings from the checkpoint’s preprocessor_config.json.

**kwargs
objectDefaults to {}

Hugging Face image-processor metadata.

media_proc_cfg
merge_size
int

Expose spatial merging to the native media-token validator.

model_input_names
= ['pixel_values', 'image_grid_thw']
nemo_automodel.components.models.kimi_k3.processing.KimiK3ImageProcessor._composite(
    image: Image.Image
) -> Image.Image

Apply the checkpoint’s background to transparent PIL images.

nemo_automodel.components.models.kimi_k3.processing.KimiK3ImageProcessor.preprocess(
    images: nemo_automodel.components.models.kimi_k3.processing._ImageSource | list[nemo_automodel.components.models.kimi_k3.processing._ImageSource],
    return_tensors: str | transformers.utils.TensorType | None = None,
    kwargs: object = {}
) -> transformers.feature_extraction_utils.BatchFeature

Resize, pad, normalize and flatten images in input order.

Parameters:

images
_ImageSource | list[_ImageSource]

PIL images, local paths, raw bytes, or data URLs.

return_tensors
str | TensorType | NoneDefaults to None

Hugging Face output tensor format.

**kwargs
objectDefaults to {}

Hugging Face preprocessing options; K3 uses checkpoint settings.

Returns: BatchFeature

FP32 tensor of shape [patches, 3, patch_size, patch_size], with images and their patches in row-major order.

class nemo_automodel.components.models.kimi_k3.processing.KimiK3Processor(
    image_processor: nemo_automodel.components.models.kimi_k3.processing.KimiK3ImageProcessor,
    tokenizer: TikTokenTokenizer
)

Bases: ProcessorMixin

Local image/text processor returning expanded tokens before native packing.

Parameters:

image_processor
KimiK3ImageProcessor

Local checkpoint-compatible image processor.

tokenizer
TikTokenTokenizer

Existing native K3 tokenizer and XTML chat encoder.

attributes
= ['image_processor', 'tokenizer']
image_placeholder
= '<|kimi_image_placeholder|>'
image_processor_class
= 'AutoImageProcessor'
image_token
= '<|media_pad|>'
image_token_id
= tokenizer.convert_tokens_to_ids(self.image_token)
model_input_names
list[str]

Return text and media fields consumed by the native model and pipeline collator.

tokenizer_class
= 'AutoTokenizer'
nemo_automodel.components.models.kimi_k3.processing.KimiK3Processor.__call__(
    text: str | list[str],
    images: nemo_automodel.components.models.kimi_k3.processing._ImageSource | list[nemo_automodel.components.models.kimi_k3.processing._ImageSource] | None = None,
    videos: object | None = None,
    padding: bool | str = False,
    truncation: bool = False,
    max_length: int | None = None,
    return_tensors: str | transformers.utils.TensorType | None = None,
    kwargs: object = {}
) -> transformers.feature_extraction_utils.BatchFeature

Process standard text/images inputs with expansion before truncation.

Parameters:

text
str | list[str]

Rendered prompts containing K3 image placeholders.

images
_ImageSource | list[_ImageSource] | NoneDefaults to None

Images flattened in prompt order.

videos
object | NoneDefaults to None

Unsupported; supplying videos raises ValueError.

padding
bool | strDefaults to False

Tokenizer padding policy.

truncation
boolDefaults to False

Whether to truncate text to max_length; removing image tokens raises.

max_length
int | NoneDefaults to None

Maximum token length after image expansion.

return_tensors
str | TensorType | NoneDefaults to None

Hugging Face output tensor format.

**kwargs
objectDefaults to {}

Tokenizer options. do_sample_frames is unused for image inputs.

Returns: BatchFeature

The text/media tensor layouts documented by _finish.

nemo_automodel.components.models.kimi_k3.processing.KimiK3Processor._finish(
    encoded: list[dict[str, list[int]]],
    media: transformers.feature_extraction_utils.BatchFeature,
    image_counts: list[int],
    padding: bool | str,
    return_tensors: str | transformers.utils.TensorType | None,
    max_length: int | None
) -> transformers.feature_extraction_utils.BatchFeature

Pad text and attach ordered media without shifting labels.

Parameters:

encoded
list[dict[str, list[int]]]

Token and optional assistant-mask lists, one per document.

media
BatchFeature

FP32 pixel_values [patches, 3, patch_size, patch_size] and integer image_grid_thw [images, 3].

image_counts
list[int]

Number of images owned by each document.

padding
bool | str

Tokenizer padding policy.

return_tensors
str | TensorType | None

Hugging Face output format.

max_length
int | None

Target length for max_length padding.

Returns: BatchFeature

BatchFeature with input_ids/attention_mask/optional assistant_masks

nemo_automodel.components.models.kimi_k3.processing.KimiK3Processor._image_prompts(
    images: list[Image.Image],
    media: transformers.feature_extraction_utils.BatchFeature
) -> list[str]

Build expanded placeholders from original resolutions and processed grids.

Parameters:

images
list[Image.Image]

Loaded PIL images in document order.

media
BatchFeature

image_grid_thw tensor [images, 3] and pixel_values tensor [patches, 3, patch_size, patch_size] from the local image processor.

Returns: list[str]

One fully expanded textual image span per image.

nemo_automodel.components.models.kimi_k3.processing.KimiK3Processor.apply_chat_template(
    conversation: nemo_automodel.components.models.kimi_k3.processing._Conversation | list[nemo_automodel.components.models.kimi_k3.processing._Conversation],
    tokenize: bool = False,
    return_dict: bool = False,
    return_tensors: str | transformers.utils.TensorType | None = None,
    padding: bool | str = False,
    truncation: bool = False,
    max_length: int | None = None,
    add_generation_prompt: bool = False,
    return_assistant_tokens_mask: bool = False,
    processor_kwargs: dict[str, object] | None = None,
    kwargs: object = {}
) -> str | list[str] | list[int] | list[list[int]] | torch.Tensor | transformers.feature_extraction_utils.BatchFeature

Render native XTML chats and optionally process images and assistant masks.

Parameters:

conversation
_Conversation | list[_Conversation]

One chat or a batch, with loaded images in content items.

tokenize
boolDefaults to False

Return tokens and processed images instead of rendered text.

return_dict
boolDefaults to False

Include masks and media with the token IDs.

return_tensors
str | TensorType | NoneDefaults to None

Hugging Face output tensor format.

padding
bool | strDefaults to False

Tokenizer padding policy.

truncation
boolDefaults to False

Truncate after image expansion; incomplete image spans are rejected.

max_length
int | NoneDefaults to None

Token limit or max_length padding target.

add_generation_prompt
boolDefaults to False

Append the native assistant generation prefix.

return_assistant_tokens_mask
boolDefaults to False

Mark assistant tokens before padding.

processor_kwargs
dict[str, object] | NoneDefaults to None

Image preprocessing options supplied by the VLM data pipeline.

**kwargs
objectDefaults to {}

Native K3 chat-rendering options, including tools and thinking settings.

Returns: str | list[str] | list[int] | list[list[int]] | torch.Tensor | BatchFeature

Rendered text, token IDs, or BatchFeature with the layouts documented by _finish.

nemo_automodel.components.models.kimi_k3.processing.KimiK3Processor.from_pretrained(
    pretrained_model_name_or_path: str | pathlib.Path,
    kwargs: object = {}
) -> nemo_automodel.components.models.kimi_k3.processing.KimiK3Processor
classmethod

Load local implementations using checkpoint data, without executing checkpoint Python.

class nemo_automodel.components.models.kimi_k3.processing._BackgroundConfig

Bases: typing.TypedDict

chessboard_gray_value
int
chessboard_square_on_top_left
bool
chessboard_square_size
int
chessboard_white_value
int
pattern
str
class nemo_automodel.components.models.kimi_k3.processing._MediaConfig

Bases: typing.TypedDict

fixed_output_tokens
int | None
image_mean
list[float]
image_std
list[float]
in_patch_limit
int
merge_kernel_size
int
patch_limit_on_one_side
int
patch_size
int
transparent_bg_config
_BackgroundConfig | None
transparent_bg_fill_stage
str
nemo_automodel.components.models.kimi_k3.processing._load_image(
    source: nemo_automodel.components.models.kimi_k3.processing._ImageSource
) -> Image.Image

Load an image without discarding alpha before the configured resize stage.

nemo_automodel.components.models.kimi_k3.processing._Conversation: TypeAlias = list[dict[str, object]]
 
nemo_automodel.components.models.kimi_k3.processing._ImageSource: TypeAlias = 'Image.Image | str | Path | bytes'