Embedding de texto - OpenSearch - Centro de documentación de Alibaba Cloud

Convierte texto en representaciones vectoriales densas mediante una API POST. Utilice los embeddings de texto para crear sistemas de búsqueda semántica, pipelines de generación aumentada por recuperación (RAG), clasificación de texto y aplicaciones de búsqueda por similitud.

Modelos disponibles

Hay seis modelos disponibles. Elija según los idiomas que maneje su aplicación, la longitud de entrada que necesite y la dimensión del vector que se ajuste a su índice:

Modelo	ID de servicio	Idiomas	Longitud máxima de entrada	Dimensión del vector	Límite de QPS
Servicio de vectorización de texto OpenSearch -001	`ops-text-embedding-001`	Multilingüe (más de 40)	300	1536	50
Servicio de embedding de texto OpenSearch-Chino-001	`ops-text-embedding-zh-001`	Chino	1024	768	—
Servicio de embedding de texto OpenSearch-Inglés-001	`ops-text-embedding-en-001`	Inglés	512	768	—
Servicio general de embedding de texto OpenSearch-002	`ops-text-embedding-002`	Multilingüe (más de 100)	8192	1024	—
Embedding de texto GTE-Multilingüe-Base	`ops-gte-sentence-embedding-multilingual-base`	Multilingüe (más de 70)	8192	768	—
Embedding de texto Qwen3-0.6B	`ops-qwen3-embedding-0.6b`	Multilingüe (más de 100)	32k	1024	—

Notas:

ops-text-embedding-001 tiene un límite de QPS predeterminado de 50, compartido entre su cuenta de Alibaba Cloud y todos los usuarios de RAM. Para solicitar un límite mayor, envíe un ticket.
ops-text-embedding-002 ofrece compatibilidad con más idiomas y un mejor rendimiento de recuperación que ops-text-embedding-001.
ops-qwen3-embedding-0.6b es un modelo de 0.6B parámetros de la serie Qwen3.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

Credenciales de autenticación (clave de API) para la plataforma abierta AI Search
Un endpoint de servicio: llame a la API a través de Internet o mediante una nube privada virtual (VPC). Para obtener más información, consulte Obtener la dirección de registro del servicio

Referencia de la API

Solicitud

Método: POST

URL:

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

Parámetro de ruta	Descripción	Ejemplo
`host`	Endpoint del servicio, accesible a través de Internet o mediante una VPC	`****-hangzhou.opensearch.aliyuncs.com`
`workspace_name`	Nombre del espacio de trabajo	`default`
`service_id`	ID de servicio del modelo que se utilizará	`ops-text-embedding-001`

Restricciones: El cuerpo de la solicitud no debe superar los 8 MB.

Parámetros de encabezado

Parámetro	Tipo	Obligatorio	Descripción	Ejemplo
`Content-Type`	String	Sí	Debe ser `application/json`	`application/json`
`Authorization`	String	Sí	Clave de API en formato de token Bearer	`Bearer OS-d1**2a`

Parámetros del cuerpo

Parámetro	Tipo	Obligatorio	Descripción	Ejemplo
`input`	Array o String	Sí	Texto para generar el embedding. Pase hasta 32 cadenas por solicitud. No se aceptan cadenas vacías. La longitud máxima por cadena depende del modelo.	`["Science and technology are the primary productive forces", "opensearch product documentation"]`
`input_type`	String	No	Indica cómo se utilizará la entrada. Valores válidos: `query` o `document` (predeterminado).	`document`

**Elección de input_type:**

Utilice document cuando genere embeddings de texto que se almacenará en su índice vectorial; por ejemplo, contenido de artículos o descripciones de productos guardados para su posterior recuperación.
Utilice query cuando genere el embedding de una consulta de búsqueda que se comparará con documentos indexados al momento de la consulta.

Establecer correctamente input_type permite que el modelo optimice las representaciones vectoriales para cada función. Si se omite, el modelo utiliza document como valor predeterminado.

Parámetros de respuesta

Parámetro	Tipo	Descripción	Ejemplo
`request_id`	String	ID de la solicitud	`B4AB89C8-B135-****-A6F8-2BAB801A2CE4`
`latency`	Float o Int	Duración de la solicitud en milisegundos	`10`
`usage`	Object	Información de medición generada por esta llamada	`{"token_count": 3072}`
`usage.token_count`	Int	Número de tokens consumidos por esta llamada	`3072`
`result.embeddings`	List	Arreglo de resultados de embedding, con una entrada por cada cadena de entrada	Consulte el ejemplo a continuación
`result.embeddings[].index`	Int	Posición de la cadena de entrada a la que corresponde este resultado (base cero)	`0`
`result.embeddings[].embedding`	List(Float)	Vector correspondiente a esta cadena de entrada	`[0.003143, 0.009750, ..., -0.017395]`

El arreglo result.embeddings conserva el orden de entrada mediante el campo index, lo que le permite asignar cada resultado a su cadena de origen al procesar un lote.

Ejemplos

Generar embedding de una sola cadena

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())

Generar embeddings de varias cadenas

Pase un arreglo para generar embeddings de hasta 32 cadenas en una sola solicitud. El arreglo de respuesta embeddings contiene una entrada por cada cadena de entrada, asociada mediante 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])

Reemplace <your-api-key> en los ejemplos de cURL con su clave de API real. En Python, establezca la variable de entorno OPENSEARCH_API_KEY antes de ejecutar el script.

Respuesta exitosa

{
    "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
                ]
            }
        ]
    }
}

Respuesta de error

Cuando una solicitud falla, la respuesta incluye un code y un message que describen el problema:

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

Para consultar la lista completa de códigos de estado, vea Códigos de estado.