Embeddings

vllm-mlx prend en charge les embeddings de texte via mlx-embeddings, en exposant un point d'accès /v1/embeddings compatible OpenAI.

Installation

pip install mlx-embeddings>=0.0.5

Démarrage rapide

Lancer le serveur avec un modèle d'embeddings

# Précharger un modèle d'embeddings spécifique au démarrage
vllm-mlx serve my-llm-model --embedding-model mlx-community/all-MiniLM-L6-v2-4bit

Si vous n'utilisez pas --embedding-model, le modèle d'embeddings est chargé à la demande lors de la première requête, mais uniquement parmi les modèles autorisés par défaut.

Générer des embeddings avec le SDK OpenAI

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

# Texte unique
response = client.embeddings.create(
    model="mlx-community/all-MiniLM-L6-v2-4bit",
    input="Hello world"
)
print(response.data[0].embedding[:5])  # First 5 dimensions

# Lot de textes
response = client.embeddings.create(
    model="mlx-community/all-MiniLM-L6-v2-4bit",
    input=[
        "I love machine learning",
        "Deep learning is fascinating",
        "Natural language processing rocks"
    ]
)
for item in response.data:
    print(f"Text {item.index}: {len(item.embedding)} dimensions")

Utilisation avec curl

curl http://localhost:8000/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/all-MiniLM-L6-v2-4bit",
    "input": ["Hello world", "How are you?"]
  }'

Modèles pris en charge

Modèles disponibles à la demande :

Modèle	Cas d'usage	Taille
mlx-community/all-MiniLM-L6-v2-4bit	Rapide et compact	Small
mlx-community/embeddinggemma-300m-6bit	Haute qualité	300M
mlx-community/bge-large-en-v1.5-4bit	Optimal pour l'anglais	Large
mlx-community/multilingual-e5-small-mlx	Récupération multilingue	Small
mlx-community/multilingual-e5-large-mlx	Récupération multilingue	Large
mlx-community/bert-base-uncased-mlx	Référence BERT générale	Base
mlx-community/ModernBERT-base-mlx	Référence ModernBERT	Base

Les autres modèles d'embeddings nécessitent l'option --embedding-model au démarrage du serveur.

Gestion des modèles

Chargement à la demande

Par défaut, le modèle d'embeddings est chargé lors de la première requête sur /v1/embeddings. Vous pouvez alterner entre les modèles autorisés listés ci-dessus ; le modèle précédent est déchargé automatiquement.

Préchargement au démarrage

Utilisez --embedding-model pour charger un modèle au démarrage. Lorsque cette option est définie, seul ce modèle peut être utilisé pour les embeddings :

vllm-mlx serve my-llm-model --embedding-model mlx-community/all-MiniLM-L6-v2-4bit

Toute requête utilisant un modèle différent renverra une erreur 400.

Référence de l'API

POST /v1/embeddings

Génère des embeddings pour le ou les textes fournis.

Corps de la requête :

Champ	Type	Requis	Description
model	string	Oui	Identifiant d'un modèle d'embeddings pris en charge, ou le modèle fixé au démarrage si --embedding-model est utilisé
input	string ou list[string]	Oui	Texte(s) à encoder

Réponse :

{
  "object": "list",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.023, -0.982, ...]},
    {"object": "embedding", "index": 1, "embedding": [0.112, -0.543, ...]}
  ],
  "model": "mlx-community/all-MiniLM-L6-v2-4bit",
  "usage": {"prompt_tokens": 12, "total_tokens": 12}
}

API Python

Utilisation directe sans serveur

from vllm_mlx.embedding import EmbeddingEngine

engine = EmbeddingEngine("mlx-community/all-MiniLM-L6-v2-4bit")
engine.load()

vectors = engine.embed(["Hello world", "How are you?"])
print(f"Dimensions: {len(vectors[0])}")

tokens = engine.count_tokens(["Hello world"])
print(f"Token count: {tokens}")

Résolution des problèmes

mlx-embeddings non installé

pip install mlx-embeddings>=0.0.5

Modèle introuvable

Vérifiez que le nom du modèle correspond à l'un des identifiants autorisés listés ci-dessus, ou lancez le serveur avec --embedding-model pour fixer un modèle personnalisé. Vous pouvez télécharger les modèles pris en charge à l'avance :

huggingface-cli download mlx-community/all-MiniLM-L6-v2-4bit