> This page is for version 0.7.0 · 26.10.
> For other versions, use one of these documentation indexes:
> - Nightly (default): https://docs.nvidia.com/nemo/automodel/nightly/llms.txt
> - Latest: https://docs.nvidia.com/nemo/automodel/latest/llms.txt
> - 0.7.0 · 26.10: https://docs.nvidia.com/nemo/automodel/v0.7/llms.txt
> - 0.5.0 · 26.06: https://docs.nvidia.com/nemo/automodel/v0.5/llms.txt
> - 0.4.0 · 26.04: https://docs.nvidia.com/nemo/automodel/v0.4/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/automodel/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/automodel/_mcp/server.

# nemo_automodel.components.models.kimi_k3.processing

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

## Module Contents

### Classes

| Name                                                                                                | Description                                                                 |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`KimiK3ImageProcessor`](#nemo_automodel-components-models-kimi_k3-processing-KimiK3ImageProcessor) | Checkpoint-compatible RGB patches, including resize and alpha compositing.  |
| [`KimiK3Processor`](#nemo_automodel-components-models-kimi_k3-processing-KimiK3Processor)           | Local image/text processor returning expanded tokens before native packing. |
| [`_BackgroundConfig`](#nemo_automodel-components-models-kimi_k3-processing-_BackgroundConfig)       | -                                                                           |
| [`_MediaConfig`](#nemo_automodel-components-models-kimi_k3-processing-_MediaConfig)                 | -                                                                           |

### Functions

| Name                                                                              | Description                                                                |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`_load_image`](#nemo_automodel-components-models-kimi_k3-processing-_load_image) | Load an image without discarding alpha before the configured resize stage. |

### Data

[`_Conversation`](#nemo_automodel-components-models-kimi_k3-processing-_Conversation)

[`_ImageSource`](#nemo_automodel-components-models-kimi_k3-processing-_ImageSource)

### API

```python
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 | None` — default: None

Image settings from the checkpoint's preprocessor_config.json.

---

**`**kwargs`** `object` — default: \{}

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']`

---

```python
nemo_automodel.components.models.kimi_k3.processing.KimiK3ImageProcessor._composite(
    image: Image.Image
) -> Image.Image
```

Apply the checkpoint's background to transparent PIL images.

```python
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 | None` — default: None

Hugging Face output tensor format.

---

**`**kwargs`** `object` — default: \{}

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.

```python
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'`

---

```python
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] | None` — default: None

Images flattened in prompt order.

---

**`videos`** `object | None` — default: None

Unsupported; supplying videos raises ValueError.

---

**`padding`** `bool | str` — default: False

Tokenizer padding policy.

---

**`truncation`** `bool` — default: False

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

---

**`max_length`** `int | None` — default: None

Maximum token length after image expansion.

---

**`return_tensors`** `str | TensorType | None` — default: None

Hugging Face output tensor format.

---

**`**kwargs`** `object` — default: \{}

Tokenizer options. do_sample_frames is unused for image inputs.

---

**Returns:** `BatchFeature`

The text/media tensor layouts documented by \_finish.

```python
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

```python
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.

```python
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`** `bool` — default: False

Return tokens and processed images instead of rendered text.

---

**`return_dict`** `bool` — default: False

Include masks and media with the token IDs.

---

**`return_tensors`** `str | TensorType | None` — default: None

Hugging Face output tensor format.

---

**`padding`** `bool | str` — default: False

Tokenizer padding policy.

---

**`truncation`** `bool` — default: False

Truncate after image expansion; incomplete image spans are rejected.

---

**`max_length`** `int | None` — default: None

Token limit or max_length padding target.

---

**`add_generation_prompt`** `bool` — default: False

Append the native assistant generation prefix.

---

**`return_assistant_tokens_mask`** `bool` — default: False

Mark assistant tokens before padding.

---

**`processor_kwargs`** `dict[str, object] | None` — default: None

Image preprocessing options supplied by the VLM data pipeline.

---

**`**kwargs`** `object` — default: \{}

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.

```python
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.

```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`

---

```python
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`

---

```python
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.

```python
nemo_automodel.components.models.kimi_k3.processing._Conversation: TypeAlias = list[dict[str, object]]
```

```python
nemo_automodel.components.models.kimi_k3.processing._ImageSource: TypeAlias = 'Image.Image | str | Path | bytes'
```