API publiqueEmbeddings

Embeddings

Transforme un ou plusieurs textes en vecteurs numériques denses, compatibles avec le format openai.embeddings.create. Cas d'usage principal : la vectorisation de documents pour la recherche sémantique et l'alimentation d'une base vectorielle (RAG).

stablev1compatible OpenAI

Endpoint#endpoint

POSThttps://ai.3gks.cloud/v1/embeddingsauth : Bearer sk-3gk-…

Compatibilité OpenAI. Le SDK officiel openai Python et Node.js fonctionne immédiatement via client.embeddings.create en pointant base_url sur notre domaine. Aucune réécriture nécessaire.

Backend dédié. Les embeddings sont servis par une ou plusieurs instances vLLM dédiées (--task embed), distinctes des modèles de chat. Quand plusieurs sont configurées (typiquement 1 par GPU), la passerelle répartit en round-robin. Il n'y a pas de fallback Scaleway sur cet endpoint : si l'administrateur n'a configuré aucune instance, la requête renvoie 503.

Paramètres requête#params

Champ	Description
model string requis	Identifiant du modèle d'embedding : <code>3gk-embed</code> (alias stable, découplé du modèle sous-jacent). ex. "3gk-embed"
input string \| string[] \| number[] \| number[][] requis	Texte(s) à vectoriser. Une chaîne unique, un tableau de chaînes (max 2048 entrées), ou des token ids déjà encodés (un tableau ou un tableau de tableaux).
encoding_format "float" \| "base64" défaut "float"	Format des vecteurs retournés. En <code>base64</code>, chaque <code>embedding</code> est une chaîne base64 au lieu d'un tableau de floats.
dimensions integer · > 0	Tronque la dimension des vecteurs retournés. Pris en compte uniquement si le modèle supporte la troncature de dimension.
user string	Identifiant opaque de l'utilisateur final. Utile pour le débogage côté admin.

Lots d'entrées. Le champ input accepte jusqu'à 2048 chaînes en un seul appel. La réponse retourne un vecteur par entrée, dans l'ordre, chacun identifié par son index. Regrouper vos textes par lots réduit le nombre d'allers-retours réseau.

Exemples#exemples

python

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.3gks.cloud/v1",
    api_key="sk-3gk-7XQp4kL8…",
)

response = client.embeddings.create(
    model="3gk-embed",
    input=[
        "Le contrat couvre la responsabilité civile.",
        "La franchise s'élève à 300 €.",
    ],
)

for item in response.data:
    print(item.index, len(item.embedding))

Format de réponse#response

Réponse JSON conforme à l'API OpenAI : un objet list dont le tableau data contient un objet embedding par entrée, ordonné par index. Le champ usage indique le nombre de tokens consommés.

application/json

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.045, 0.0871, …]
    }
  ],
  "model": "3gk-embed",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

Avec encoding_format: "base64", le champ embedding est une chaîne base64 (encodage des floats little-endian) au lieu d'un tableau — plus compact à transporter. Le SDK openai décode automatiquement.

Codes de réponse#status

200 OK

Succès · La réponse JSON contient le champ data avec un vecteur par entrée.

400

invalid_request · Corps invalide : input manquant, format incorrect, ou plus de 2048 entrées.

400

model_not_supported · L'identifiant demandé n'est pas un modèle d'embedding. Utilisez 3gk-embed.

401

auth_error · Clé absente, mal formée, révoquée ou compte suspendu.

502

upstream_error · L'instance vLLM d'embedding a renvoyé une erreur, un JSON invalide ou est injoignable.

503

upstream_error · Aucun modèle d'embedding n'est configuré côté admin.

Pour le détail du format d'erreur et des stratégies de retry, voir Codes d'erreur. Pour la liste des modèles disponibles, voir Models.

← Chat completions Rerank →