refactor(embedding): share embedding normalization for future multimodal embeddings

- Extract normalization into a shared utility and reuse it in Llama.embed().

- Preserve existing normalization modes, bool compatibility, zero-vector
handling, and raw ranking scores.

Signed-off-by: JamePeng <jame_peng@sina.com>

Author: JamePeng

llama_cpp/_utils.py

@@ -3,6 +3,38 @@
 
 from typing import Any, Dict
 
+
+def normalize_embedding(vector, mode=2):
+    """Normalize an embedding using llama.cpp modes; return a list.
+
+    vector (sequence[float]): Input embedding; zero vectors stay unchanged.
+    mode (bool/int): True selects L2 (2), False selects no normalization (-1).
+        <0: None; preserve the original values.
+         0: MaxInt16; scale max(abs(x)) to 32760, retaining floating-point values.
+         1: L1; divide by sum(abs(x)) so absolute values sum to one.
+         2: L2; divide by sqrt(sum(x**2)) to produce a unit-length vector.
+        >2: Lp; divide by sum(abs(x)**p)**(1/p), with p = mode.
+    """
+    import numpy as np
+
+    if isinstance(mode, bool):
+        mode = 2 if mode else -1
+    if not isinstance(mode, int):
+        raise TypeError("normalize must be a bool or int")
+    values = list(vector)
+    if mode < 0:
+        return values
+    array = np.asarray(values, dtype=np.float32)
+    if mode == 0:
+        norm = float(np.max(np.abs(array))) if array.size else 0.0
+    elif mode == 1:
+        norm = float(np.sum(np.abs(array)))
+    elif mode == 2:
+        norm = float(np.linalg.norm(array))
+    else:
+        norm = float(np.sum(np.abs(array) ** mode) ** (1.0 / mode))
+    return values if norm == 0 else ((array / norm) * (32760.0 if mode == 0 else 1.0)).tolist()
+
 # Avoid "LookupError: unknown encoding: ascii" when open() called in a destructor
 outnull_file = open(os.devnull, "w")
 errnull_file = open(os.devnull, "w")

llama_cpp/llama.py

@@ -82,7 +82,7 @@
     clear_log_filters,
     reset_log_filters,
 )
-from ._utils import suppress_stdout_stderr
+from ._utils import suppress_stdout_stderr, normalize_embedding
 
 
 def _format_speculative_duration(seconds: float) -> str:
@@ -3166,43 +3166,7 @@ def embed(
             raise TypeError("normalize must be a bool or int")
 
         def normalize_vector(vector: Sequence[float]) -> List[float]:
-            values = list(vector)
-            # -1 (NONE): preserve the original vector. RANK always preserves
-            # raw classification scores regardless of the requested mode.
-            if normalize_mode == -1 or is_rank:
-                return values
-
-            array = np.asarray(values, dtype=np.float32)
-            # Compute y = scale * x / norm(x).
-            if normalize_mode == 0:
-                # 0 (MAX_INT16): y = 32760 * x / max(abs(x)). The result
-                # remains floating point; this is scaling, not int16 quantization.
-                norm = float(np.max(np.abs(array))) if array.size else 0.0
-                scale = 32760.0
-            elif normalize_mode == 1:
-                # 1 (TAXICAB / L1): y = x / sum(abs(x)).
-                norm = float(np.sum(np.abs(array)))
-                scale = 1.0
-            elif normalize_mode == 2:
-                # 2 (EUCLIDEAN / L2): y = x / sqrt(sum(x_i ** 2)).
-                norm = float(np.linalg.norm(array))
-                scale = 1.0
-            elif normalize_mode > 2:
-                # p > 2 (PNORM): y = x / (sum(abs(x_i) ** p)) ** (1/p).
-                # The mode itself is p; NORM_MODE_PNORM = 6 selects the L6 norm.
-                norm = float(
-                    np.sum(np.abs(array) ** normalize_mode)
-                    ** (1.0 / normalize_mode)
-                )
-                scale = 1.0
-            else:
-                # Other negative modes retain the existing passthrough behavior.
-                return values
-
-            # Zero vectors remain zero rather than producing NaNs on division.
-            if norm == 0.0:
-                return values
-            return ((array / norm) * scale).tolist()
+            return list(vector) if is_rank else normalize_embedding(vector, normalize_mode)
 
         if isinstance(input, str):
             inputs: List[Union[str, List[int]]] = (