Embeddings avec /v1/embeddings

Cette page décrit comment utiliser la route OpenAI-compatible /v1/embeddings exposée par le gateway Clovis afin de générer des représentations vectorielles (embeddings) à partir de contenus textuels.

Les embeddings sont utilisés pour des cas d’usage comme la recherche sémantique, la similarité, le clustering, ou encore l’indexation vectorielle pour un pipeline RAG (retrieval).

Endpoint

Embeddings

POST/v1/embeddings

URL complète (Gateway Clovis)

Gateway Clovis

{
  POST https://llm-gateway.clovis-ai.fr/v1/embeddings
  Authorization: Bearer <CLOVIS_API_KEY>
  Content-Type: application/json
}

Structure

Chaque requête doit inclure un JSON similaire à :

Corps de requête

{
  "model": "ClovisEmbedding",
  "input": "Explique-moi ce qu’est un embedding.",
  "encoding_format": "float"
}

Entrée multiple (batch)

{
  "model": "ClovisEmbeddings",
  "input": [
      "Document 1 : texte à vectoriser",
      "Document 2 : texte à vectoriser",
      "Document 3 : texte à vectoriser"
  ],
  "encoding_format": "float"
}

Description des champs

Champ	Type	Obligatoire	Description
model	string	✔️	Nom du modèle d’embedding
input	stringarray	✔️	Texte (ou liste de textes) à convertir en embeddings
encoding_format	string	✔️	Format de sortie de l’embedding (ex: float, base64 )
user	string		Identifiant utilisateur (utile pour traçabilité / logs)

Réponse de l’API

Tableau principal de la réponse

Exemple de réponse

{
  "object": "list",
  "data": [
      {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.9821, 0.4421, 0.1182]
      }
  ],
  "model": "ClovisEmbeddings",
  "usage": {
      "prompt_tokens": 12,
      "total_tokens": 12
  }
}

Détail du champ data

Champ	Type	Description
object	string	Type d’objet retourné ("embedding")
index	int	Index correspondant à l’entrée fournie dans input
embedding	array	Vecteur numérique (dimension dépend du modèle)

Info

Si input contient plusieurs textes, data contiendra plusieurs objets embeddings, chacun avec un index correspondant.

Détails du champ usage

Champ	Type	Description
prompt_tokens	int	Nombre de tokens utilisés pour l’entrée
total_tokens	int	Total facturé (pas de génération, donc pas de completion_tokens)

Exemples d’utilisation

cURL

Question

curl https://llm-gateway.clovis-ai.fr/v1/embeddings -H "Content-Type: application/json" -H "Authorization: Bearer sk-xxxxxxxx" -d '{
  "model": "ClovisEmbeddings",
  "input": "Le RAG combine recherche vectorielle et génération de texte.",
  "encoding_format": "float"
}'

Question

curl https://llm-gateway.clovis-ai.fr/v1/embeddings -H "Content-Type: application/json" -H "Authorization: Bearer sk-xxxxxxxx" -d '{
  "model": "ClovisEmbeddings",
  "input": [
    "Chunk 1 : introduction...",
    "Chunk 2 : détails...",
    "Chunk 3 : conclusion..."
  ],
  "encoding_format": "float"
}'

Javascript

require('dotenv').config();
const axios = require('axios');

async function testEmbeddings() {
  try {
    const payload = {
      model: ClovisEmbeddings,
      input: 'Basile',
      encoding_format: 'float'
    };
    const res = await axios.post('https://llm-gateway.clovis-ai.fr/v1/embeddings', payload, {
      headers: {
        Authorization: 'Bearer sk-xxxxxxxx',
        'Content-Type': 'application/json',
      },
    });

    return true;
  } catch (err) {
    console.error('/embeddings failed:', err.response?.status, err.message);
    return false;
  }
}
module.exports = testEmbeddings;