Text embedding - OpenSearch - Centre de documentation Alibaba Cloud

Modèles disponibles

Six modèles sont proposés. Choisissez celui qui correspond aux langues prises en charge par votre application, à la longueur d'entrée requise et à la dimension de vecteur adaptée à votre index :

Modèle	ID de service	Langues	Longueur d'entrée maximale	Dimension du vecteur	Limite QPS
OpenSearch text vectorization service -001	`ops-text-embedding-001`	Multilingue (40+)	300	1536	50
OpenSearch Text Embedding Service-Chinese-001	`ops-text-embedding-zh-001`	Chinois	1024	768	—
OpenSearch Text Embedding Service-English-001	`ops-text-embedding-en-001`	Anglais	512	768	—
OpenSearch General Text Embedding Service-002	`ops-text-embedding-002`	Multilingue (100+)	8192	1024	—
GTE Text Embedding-Multilingual-Base	`ops-gte-sentence-embedding-multilingual-base`	Multilingue (70+)	8192	768	—
Qwen3 Text Embedding-0.6B	`ops-qwen3-embedding-0.6b`	Multilingue (100+)	32k	1024	—

Notes :

Le modèle ops-text-embedding-001 dispose d'une limite QPS par défaut de 50, partagée entre votre compte Alibaba Cloud et tous les utilisateurs RAM. Pour demander une augmentation, créez un ticket.
Le modèle ops-text-embedding-002 offre une prise en charge linguistique plus large et de meilleures performances de récupération que ops-text-embedding-001.
Le modèle ops-qwen3-embedding-0.6b est un modèle de 0,6 milliard de paramètres issu de la série Qwen3.

Prérequis

Avant de commencer, vérifiez que vous disposez des éléments suivants :

Des identifiants d'authentification (clé API) pour l'AI Search Open Platform
Un endpoint de service — appelez l'API via Internet ou à travers un VPC. Pour plus de détails, consultez Obtenir l'adresse d'enregistrement du service

Référence de l'API

Requête

Méthode : POST

URL :

{host}/v3/openapi/workspaces/{workspace_name}/text-embedding/{service_id}

Paramètre de chemin	Description	Exemple
`host`	Endpoint de service, accessible via Internet ou à travers un VPC	`****-hangzhou.opensearch.aliyuncs.com`
`workspace_name`	Nom de l'espace de travail	`default`
`service_id`	ID de service du modèle à utiliser	`ops-text-embedding-001`

Contraintes : Le corps de la requête ne doit pas dépasser 8 Mo.

Paramètres d'en-tête

Paramètre	Type	Obligatoire	Description	Exemple
`Content-Type`	String	Oui	Doit être `application/json`	`application/json`
`Authorization`	String	Oui	Clé API au format jeton Bearer	`Bearer OS-d1**2a`

Paramètres du corps

Paramètre	Type	Obligatoire	Description	Exemple
`input`	Array ou String	Oui	Texte à intégrer. Transmettez jusqu'à 32 chaînes par requête. Les chaînes vides ne sont pas acceptées. La longueur maximale par chaîne dépend du modèle.	`["Science and technology are the primary productive forces", "opensearch product documentation"]`
`input_type`	String	Non	Indique l'utilisation prévue de l'entrée. Valeurs valides : `query` ou `document` (par défaut).	`document`

**Choix du paramètre input_type :**

Utilisez document pour intégrer du texte destiné à votre index vectoriel, par exemple le contenu d'un article ou des descriptions de produits stockés pour une récupération ultérieure.
Utilisez query pour intégrer une requête de recherche qui sera comparée aux documents indexés au moment de l'interrogation.

Définir correctement le paramètre input_type permet au modèle d'optimiser les représentations vectorielles pour chaque rôle. En cas d'omission, le modèle utilise document comme valeur par défaut.

Paramètres de réponse

Paramètre	Type	Description	Exemple
`request_id`	String	ID de la requête	`B4AB89C8-B135-****-A6F8-2BAB801A2CE4`
`latency`	Float ou Int	Durée de la requête en millisecondes	`10`
`usage`	Object	Informations de comptabilisation générées par cet appel	`{"token_count": 3072}`
`usage.token_count`	Int	Nombre de tokens consommés par cet appel	`3072`
`result.embeddings`	List	Tableau des résultats d'intégration, une entrée par chaîne d'entrée	Voir l'exemple ci-dessous
`result.embeddings[].index`	Int	Position de la chaîne d'entrée à laquelle ce résultat correspond (base zéro)	`0`
`result.embeddings[].embedding`	List(Float)	Vecteur pour cette chaîne d'entrée	`[0.003143, 0.009750, ..., -0.017395]`

Le tableau result.embeddings préserve l'ordre des entrées via le champ index ; vous pouvez ainsi mapper chaque résultat à sa chaîne source lors du traitement d'un lot.

Exemples

Intégrer une seule chaîne

cURL

curl -X POST \
  "http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/text-embedding/ops-text-embedding-001" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "input": "opensearch product documentation",
    "input_type": "query"
  }'

Python

import os
import requests

host = "http://****-hangzhou.opensearch.aliyuncs.com"
workspace = "default"
service_id = "ops-text-embedding-001"
api_key = os.environ.get("OPENSEARCH_API_KEY")

url = f"{host}/v3/openapi/workspaces/{workspace}/text-embedding/{service_id}"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}",
}
payload = {
    "input": "opensearch product documentation",
    "input_type": "query",
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Intégrer plusieurs chaînes

Transmettez un tableau pour intégrer jusqu'à 32 chaînes en une seule requête. Le tableau embeddings de la réponse contient une entrée par chaîne d'entrée, associée via le champ index.

cURL

curl -X POST \
  "http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/text-embedding/ops-text-embedding-001" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "input": [
      "Science and technology are the primary productive forces",
      "opensearch product documentation"
    ],
    "input_type": "query"
  }'

Python

import os
import requests

host = "http://****-hangzhou.opensearch.aliyuncs.com"
workspace = "default"
service_id = "ops-text-embedding-001"
api_key = os.environ.get("OPENSEARCH_API_KEY")

url = f"{host}/v3/openapi/workspaces/{workspace}/text-embedding/{service_id}"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}",
}
payload = {
    "input": [
        "Science and technology are the primary productive forces",
        "opensearch product documentation",
    ],
    "input_type": "query",
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
# data["result"]["embeddings"] is a list of objects, one per input string.
# Each object has an "index" field that maps back to the original input position.
for item in data["result"]["embeddings"]:
    print(item["index"], item["embedding"][:5])

Remplacez <your-api-key> dans les exemples cURL par votre clé API réelle. En Python, définissez la variable d'environnement OPENSEARCH_API_KEY avant d'exécuter le script.

Réponse réussie

{
    "request_id": "B4AB89C8-B135-****-A6F8-2BAB801A2CE4",
    "latency": 38,
    "usage": {
        "token_count": 3072
    },
    "result": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.02868066355586052,
                    0.022033605724573135,
                    -0.0417383536696434,
                    -0.044081952422857285,
                    0.02141784131526947,
                    -8.240503375418484E-4,
                    -0.01309406291693449,
                    -0.02169642224907875,
                    -0.03996409475803375,
                    0.008053945377469063,
                    ...
                    -0.05131729692220688,
                    -0.016595875844359398
                ]
            }
        ]
    }
}

Réponse d'erreur

Lorsqu'une requête échoue, la réponse inclut un code code et un message message décrivant le problème :

{
    "request_id": "651B3087-8A07-****-B931-9C4E7B60F52D",
    "latency": 0,
    "code": "InvalidParameter",
    "message": "JSON parse error: Cannot deserialize value of type `InputType` from String \"xxx\""
}

Pour obtenir la liste complète des codes d'état, consultez Codes d'état.