# `vllm_mlx.embedding`

Embedding engine using mlx-embeddings.

[View the complete module source at #L1-L131](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L1-L131).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: vllm_mlx.embedding
    options:
      members:
        - logger
        - EmbeddingEngine
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-vllm_mlx.embedding.EmbeddingEngine" markdown="1">
<summary><code>vllm_mlx.embedding.EmbeddingEngine</code> · class</summary>

```python
vllm_mlx.embedding.EmbeddingEngine(model_name: str)
```

Wrapper around mlx-embeddings for text embedding generation.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Constructs: `vllm_mlx.embedding.EmbeddingEngine`

**Exceptions and behavior**

Class `EmbeddingEngine` declares 7 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L19-L131](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L19-L131).

</details>

<details class="api-contract" id="contract-vllm_mlx.embedding.EmbeddingEngine.__init__" markdown="1">
<summary><code>vllm_mlx.embedding.EmbeddingEngine.__init__</code> · method</summary>

```python
vllm_mlx.embedding.EmbeddingEngine.__init__(model_name: str) -> not annotated
```

Method `EmbeddingEngine.__init__` updates `self.model_name`, `self._model`, `self._tokenizer`, `self._max_length`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Method `EmbeddingEngine.__init__` updates `self.model_name`, `self._model`, `self._tokenizer`, `self._max_length`.
No direct `raise` statement appears in this definition.

[View source #L27-L31](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L27-L31).

</details>

<details class="api-contract" id="contract-vllm_mlx.embedding.EmbeddingEngine.is_loaded" markdown="1">
<summary><code>vllm_mlx.embedding.EmbeddingEngine.is_loaded</code> · method</summary>

```python
vllm_mlx.embedding.EmbeddingEngine.is_loaded() -> bool
```

Return whether the embedding model has been loaded.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `bool`
- Direct return expressions: `self._model is not None`

**Exceptions and behavior**

Method `EmbeddingEngine.is_loaded` returns `self._model is not None`.
No direct `raise` statement appears in this definition.

[View source #L34-L37](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L34-L37).

</details>

<details class="api-contract" id="contract-vllm_mlx.embedding.EmbeddingEngine.load" markdown="1">
<summary><code>vllm_mlx.embedding.EmbeddingEngine.load</code> · method</summary>

```python
vllm_mlx.embedding.EmbeddingEngine.load() -> None
```

Load the embedding model and tokenizer.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `EmbeddingEngine.load` updates `self._model`, `self._tokenizer`; calls `logger.info`, `time.perf_counter`, `load`.
No direct `raise` statement appears in this definition.

[View source #L39-L47](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L39-L47).

</details>

<details class="api-contract" id="contract-vllm_mlx.embedding.EmbeddingEngine._ensure_loaded" markdown="1">
<summary><code>vllm_mlx.embedding.EmbeddingEngine._ensure_loaded</code> · method</summary>

```python
vllm_mlx.embedding.EmbeddingEngine._ensure_loaded() -> None
```

Method `EmbeddingEngine._ensure_loaded` calls `self.load`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `EmbeddingEngine._ensure_loaded` calls `self.load`.
No direct `raise` statement appears in this definition.

[View source #L49-L51](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L49-L51).

</details>

<details class="api-contract" id="contract-vllm_mlx.embedding.EmbeddingEngine._resolve_max_length" markdown="1">
<summary><code>vllm_mlx.embedding.EmbeddingEngine._resolve_max_length</code> · method</summary>

```python
vllm_mlx.embedding.EmbeddingEngine._resolve_max_length() -> int
```

Tokenizer truncation length from the model config (cached).

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `self._max_length`

**Exceptions and behavior**

Method `EmbeddingEngine._resolve_max_length` updates `self._max_length`; calls `resolve_max_length`, `getattr`; returns `self._max_length`.
No direct `raise` statement appears in this definition.

[View source #L53-L60](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L53-L60).

</details>

<details class="api-contract" id="contract-vllm_mlx.embedding.EmbeddingEngine.embed" markdown="1">
<summary><code>vllm_mlx.embedding.EmbeddingEngine.embed</code> · method</summary>

```python
vllm_mlx.embedding.EmbeddingEngine.embed(texts: str | list[str]) -> list[list[float]]
```

Generate embeddings for one or more texts.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `texts` | `str \| list[str]` | `yes` | `none` | A single string or list of strings. |

**Returns**

- Type: `list[list[float]]`
- Direct return expressions: `result`

**Exceptions and behavior**

Method `EmbeddingEngine.embed` calls `self._ensure_loaded`, `isinstance`, `inner_tokenizer`, `inner_tok`; returns `result`.
No direct `raise` statement appears in this definition.

[View source #L62-L109](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L62-L109).

</details>

<details class="api-contract" id="contract-vllm_mlx.embedding.EmbeddingEngine.count_tokens" markdown="1">
<summary><code>vllm_mlx.embedding.EmbeddingEngine.count_tokens</code> · method</summary>

```python
vllm_mlx.embedding.EmbeddingEngine.count_tokens(texts: str | list[str]) -> int
```

Approximate token count for usage reporting.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `texts` | `str \| list[str]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `int`
- Direct return expressions: `total`

**Exceptions and behavior**

Method `EmbeddingEngine.count_tokens` calls `self._ensure_loaded`, `isinstance`, `self._tokenizer.encode`, `len`; returns `total`.
No direct `raise` statement appears in this definition.

[View source #L111-L131](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L111-L131).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`EmbeddingEngine`](#contract-vllm_mlx.embedding.EmbeddingEngine) | class | `EmbeddingEngine(model_name: str)` | Wrapper around mlx-embeddings for text embedding generation. | [#L19-L131](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L19-L131) |
| [`EmbeddingEngine.__init__`](#contract-vllm_mlx.embedding.EmbeddingEngine.__init__) | method | `EmbeddingEngine.__init__(model_name: str) -> not annotated` | Method `EmbeddingEngine.__init__` updates `self.model_name`, `self._model`, `self._tokenizer`, `self._max_length`. | [#L27-L31](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L27-L31) |
| [`EmbeddingEngine.is_loaded`](#contract-vllm_mlx.embedding.EmbeddingEngine.is_loaded) | method | `EmbeddingEngine.is_loaded() -> bool` | Return whether the embedding model has been loaded. | [#L34-L37](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L34-L37) |
| [`EmbeddingEngine.load`](#contract-vllm_mlx.embedding.EmbeddingEngine.load) | method | `EmbeddingEngine.load() -> None` | Load the embedding model and tokenizer. | [#L39-L47](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L39-L47) |
| [`EmbeddingEngine._ensure_loaded`](#contract-vllm_mlx.embedding.EmbeddingEngine._ensure_loaded) | method | `EmbeddingEngine._ensure_loaded() -> None` | Method `EmbeddingEngine._ensure_loaded` calls `self.load`. | [#L49-L51](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L49-L51) |
| [`EmbeddingEngine._resolve_max_length`](#contract-vllm_mlx.embedding.EmbeddingEngine._resolve_max_length) | method | `EmbeddingEngine._resolve_max_length() -> int` | Tokenizer truncation length from the model config (cached). | [#L53-L60](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L53-L60) |
| [`EmbeddingEngine.embed`](#contract-vllm_mlx.embedding.EmbeddingEngine.embed) | method | `EmbeddingEngine.embed(texts: str \| list[str]) -> list[list[float]]` | Generate embeddings for one or more texts. | [#L62-L109](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L62-L109) |
| [`EmbeddingEngine.count_tokens`](#contract-vllm_mlx.embedding.EmbeddingEngine.count_tokens) | method | `EmbeddingEngine.count_tokens(texts: str \| list[str]) -> int` | Approximate token count for usage reporting. | [#L111-L131](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/embedding.py#L111-L131) |