{"record":{"id":"bfe7f3b670be8003","repo":"ultralytics/ultralytics","slug":"prompt-embeddings-must-be-a-float32-array-with-sha","errorCode":null,"errorMessage":"Prompt embeddings must be a float32 array with shape (1, classes, dimensions).","messagePattern":"Prompt embeddings must be a float32 array with shape \\(1, classes, dimensions\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"ultralytics/models/yolo/model.py","lineNumber":415,"sourceCode":"            ValueError: If the file is invalid or belongs to a different YOLOE architecture.\n        \"\"\"\n        assert isinstance(self.model, YOLOEModel)\n        with np.load(file, allow_pickle=False) as data:\n            if set(data.files) != {\"embeddings\", \"names\", \"model\"}:\n                raise ValueError(\"Prompt embedding file must contain 'embeddings', 'names', and 'model'.\")\n            embeddings, names, model = data[\"embeddings\"], data[\"names\"], data[\"model\"]\n\n        if model.ndim != 0 or model.dtype.kind != \"U\":\n            raise ValueError(\"Prompt embedding model identifier must be a scalar string.\")\n        model_name = str(model.item())\n        if model_name != self._prompt_embedding_model():\n            raise ValueError(\n                f\"Prompt embeddings for model '{model_name}' cannot be loaded into '{self._prompt_embedding_model()}'.\"\n            )\n        if names.ndim != 1 or names.dtype.kind != \"U\":\n            raise ValueError(\"Prompt embedding class names must be a one-dimensional string array.\")\n        if embeddings.dtype != np.float32 or embeddings.ndim != 3 or embeddings.shape[0] != 1:\n            raise ValueError(\"Prompt embeddings must be a float32 array with shape (1, classes, dimensions).\")\n        if embeddings.shape[1] != len(names) or embeddings.shape[2] != self.model.model[-1].embed:\n            raise ValueError(\"Prompt embedding shape does not match the class names or model embedding dimension.\")\n        if not np.isfinite(embeddings).all():\n            raise ValueError(\"Prompt embeddings must contain only finite values.\")\n        self.set_classes(names.tolist(), torch.from_numpy(embeddings.copy()).to(next(self.model.parameters()).device))\n\n    def val(\n        self,\n        validator=None,\n        load_vp: bool = False,\n        refer_data: str | None = None,\n        **kwargs,\n    ):\n        \"\"\"Validate the model using text or visual prompts.\n\n        Args:\n            validator (callable, optional): A callable validator function. If None, a default validator is loaded.\n            load_vp (bool): Whether to load visual prompts. If False, text prompts are used.","sourceCodeStart":397,"sourceCodeEnd":433,"githubUrl":"https://github.com/ultralytics/ultralytics/blob/0449ea011cfd6c9a0d50a0bf1043aca5190cd476/ultralytics/models/yolo/model.py#L397-L433","documentation":"Raised by load_prompt_embeddings when the 'embeddings' array is not float32 with ndim 3 and a leading batch dim of exactly 1 — i.e. anything other than shape (1, classes, dimensions) in float32. The save path stores embeddings.detach().cpu().float() with that exact shape; float16/float64, 2-D matrices, or batch sizes > 1 are rejected.","triggerScenarios":"Loading an NPZ whose embeddings were saved as float16, float64, a 2-D (classes, dim) tensor, or a multi-object batch; converting tensors with .half() or squeezing away the batch dim before saving.","commonSituations":"Export pipelines that compress to fp16 before writing; hand-conversion from PyTorch .pt files where the (1, C, D) shape was collapsed to (C, D); concatenating multiple vocabularies along axis 0.","solutions":["Cast and reshape before saving: emb.astype(np.float32).reshape(1, num_classes, dim)","Keep exactly one batch entry — stack multiple classes along axis 1, not axis 0","Regenerate the file via save_prompt_embeddings on the source model"],"exampleFix":"# before: np.savez('pe.npz', embeddings=emb.astype(np.float16))  # wrong dtype\n# after\nnp.savez_compressed('pe.npz', embeddings=emb.astype(np.float32)[None])  # (1, C, D) float32","handlingStrategy":"validation","validationCode":"with np.load(f, allow_pickle=False) as d:\n    e = d['embeddings']\n    assert e.dtype == np.float32 and e.ndim == 3 and e.shape[0] == 1, \\\n        f'embeddings must be float32 (1, C, D); got {e.dtype} {e.shape}'","typeGuard":null,"tryCatchPattern":"try:\n    model.load_prompt_embeddings(f)\nexcept ValueError as e:\n    if 'float32 array' in str(e):\n        with np.load(f, allow_pickle=False) as d:\n            e = np.ascontiguousarray(d['embeddings'], dtype=np.float32)\n            if e.ndim == 2:\n                e = e[None]\n            np.savez_compressed(f, embeddings=e, names=d['names'], model=d['model'])\n        model.load_prompt_embeddings(f)\n    else:\n        raise","preventionTips":["Always cast to .float() (fp32) and keep a leading 1-sized batch axis before saving","Never save fp16 copies of prompt embeddings; compress the NPZ instead (savez_compressed)"],"tags":["yoloe","embeddings","npz","dtype","shape"],"backgroundTag":null,"analyzedSha":"0449ea011cfd6c9a0d50a0bf1043aca5190cd476","analyzedAt":"2026-08-15T02:34:13.413Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}