Skip to main content

API síncrona

El modelo de embedding de texto de propósito general convierte datos de texto en vectores numéricos para tareas posteriores como búsqueda semántica, recomendación, agrupación y clasificación.

Resumen de modelos

  • Singapore
  • China (Beijing)
  • China (Hong Kong)
ModeloDimensiones de embeddingFilas máximasMáximo de tokens por línea(Nota)Precio (por 1M tokens de entrada)Idiomas admitidosCuota gratuita(Nota)
qwen3.7-text-embedding2,560, 2,048, 1,536, 1,024 (predeterminado), 768, 512, 25620128,000$0.07Chino, inglés, español, francés, portugués, indonesio, japonés, coreano, alemán, ruso y más de 200 idiomas y dialectos principales adicionales1 millón de tokensValidez: 90 días después de activar Model Studio
text-embedding-v4
Parte de la serie Qwen3-Embedding
2,048, 1,536, 1,024 (predeterminado), 768, 512, 256, 128, 64108,192$0.07Chino, inglés, español, francés, portugués, indonesio, japonés, coreano, alemán, ruso y más de 100 idiomas principales adicionales1 millón de tokensValidez: 90 días después de activar Model Studio
text-embedding-v31,024 (predeterminado), 768, 512Chino, inglés, español, francés, portugués, indonesio, japonés, coreano, alemán, ruso y más de 50 idiomas principales adicionales500,000 tokensValidez: 90 días después de activar Model Studio
Para conocer los límites de tasa del modelo, consulte Limitación de tasa.

Requisitos previos

Los usuarios familiarizados con el ecosistema OpenAI pueden utilizar la API compatible con OpenAI para una migración rápida. La API DashScope ofrece funciones únicas adicionales. Obtenga una clave API y exporte la clave API como variable de entorno. Si utiliza un SDK para realizar las llamadas, instale el SDK de DashScope.

Compatibilidad con OpenAI

Elbase_urla configurar para llamadas SDK:
  • Singapur: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1. Reemplace WorkspaceId con su ID de espacio de trabajo real.
  • China (Pekín): https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
  • China (Hong Kong): https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1. Reemplace WorkspaceId con su ID de espacio de trabajo real.
Elendpointa configurar para llamadas HTTP:
  • Singapur: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings. Reemplace WorkspaceId con su ID de espacio de trabajo real.
  • China (Pekín): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings
  • China (Hong Kong): POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/embeddings. Reemplace WorkspaceId con su ID de espacio de trabajo real.
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Cuerpo de la solicitud

modelstringrequeridoEl nombre del modelo a llamar. Consulte la tabla Resumen de modelos para ver los nombres de los modelos.inputarray<string> or string or filerequeridoEl texto de entrada a procesar. La entrada puede ser una cadena, una matriz de cadenas o un archivo. Los límites de longitud de texto y tamaño de lote varían según la versión del modelo:
  • Modelo qwen3.7-text-embedding:
    • Entrada de cadena: Hasta 128,000 tokens.
    • Entrada de lista de cadenas o archivo: Hasta 20 elementos (líneas), con cada elemento (línea) de hasta 128,000 tokens.
  • Modelos text-embedding-v3 / v4:
    • Entrada de cadena: Longitud máxima de 8,192 tokens.
    • Entrada de lista de cadenas o archivo: Hasta 10 elementos (líneas), con cada elemento (línea) de hasta 8,192 tokens.
dimensions integer opcionalLa dimensión de los vectores de embedding de salida. Debe ser uno de los siguientes valores: 2560 (for qwen3.7-text-embedding only),2048 (solo para text-embedding-v4), 1536 (solo para text-embedding-v4), 1024, 768, 512, 256, 128 o 64. El valor predeterminado es 1024.encoding_format string opcionalEl formato de embedding devuelto. Actualmente, solo se admite float.
  • Cadena de entrada
  • Lista de cadenas de entrada
  • Archivo de entrada
  • Python
  • Java
  • curl
  • CLI de dashscope
import os
from openai import OpenAI

client = OpenAI(
    # If you use a model in the China (Beijing) region, you must use an API key from that region. Get one at: https://modelstudio.console.alibabacloud.com/model/settings/api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # If the environment variable is not set, replace the placeholder with your API key.
    # This is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs differ by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

completion = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input='The clothes are of good quality and look good, definitely worth the wait. I love them.',
    dimensions=1024,
    encoding_format="float"
)

print(completion.model_dump_json())

Objeto de respuesta

dataarrayUna lista de los objetos de embedding resultantes.

Propiedad

embeddinglistEl vector de embedding, devuelto como una matriz de números de punto flotante.indexintegerEl índice del texto de entrada correspondiente en la matriz de entrada.objectstringEl tipo de objeto. El valor siempre es embedding.
modelstringEl nombre del modelo utilizado para esta llamada.objectstringEl tipo de objeto. El valor siempre es list.usageobject

Propiedad

prompt_tokensintegerEl número de tokens en el texto de entrada.total_tokens integerEl número total de tokens en la entrada. Este recuento se determina según cómo el tokenizador del modelo analiza la cadena de entrada.
idstringUn identificador único de solicitud, utilizado para rastreo y solución de problemas.
{
  "data": [
    {
      "embedding": [
        -0.0695386752486229, 0.030681096017360687, ...
      ],
      "index": 0,
      "object": "embedding"
    },
    ...
    {
      "embedding": [
        -0.06348952651023865, 0.060446035116910934, ...
      ],
      "index": 5,
      "object": "embedding"
    }
  ],
  "model": "qwen3.7-text-embedding",
  "object": "list",
  "usage": {
    "prompt_tokens": 184,
    "total_tokens": 184
  },
  "id": "73591b79-d194-9bca-8bb5-xxxxxxxxxxxx"
}

DashScope

base_urlpara llamadas SDK:
  • Singapur: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1. Reemplace WorkspaceId con su ID de espacio de trabajo real.
  • China (Pekín): https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
  • China (Hong Kong): https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1. Reemplace WorkspaceId con su ID de espacio de trabajo real.
Endpoint para llamadas HTTP:
  • Singapur: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding. Reemplace WorkspaceId con su ID de espacio de trabajo real.
  • China (Pekín): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
  • China (Hong Kong): POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding. Reemplace WorkspaceId con su ID de espacio de trabajo real.
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Cuerpo de la solicitud

modelstringrequeridoEl modelo a utilizar. Para obtener una lista de modelos disponibles, consulte la tabla Resumen de modelos.inputstringoarray<string>requeridoEl texto a procesar. La entrada puede ser una cadena, una matriz de cadenas o un archivo. La longitud de texto admitida y el tamaño del lote varían según la versión del modelo.
  • Modelo qwen3.7-text-embedding:
    • Entrada de cadena: Hasta 128,000 tokens.
    • Entrada de lista de cadenas o archivo: Hasta 20 elementos (líneas), con cada elemento (línea) de hasta 128,000 tokens.
  • Modelos text-embedding-v3 / v4:
    • Entrada de cadena: Longitud máxima de 8,192 tokens.
    • Entrada de lista de cadenas o archivo: Hasta 10 elementos (líneas), con cada elemento (línea) de hasta 8,192 tokens.
text_type stringopcional
Al realizar una llamada HTTP, coloque text_typeen el objeto parameters.
El texto convertido a embeddings se puede aplicar a tareas posteriores como recuperación, agrupación y clasificación. Para tareas asimétricas como la recuperación, se recomienda diferenciar entre texto de consulta (query) y texto de documento (document) para lograr un mejor rendimiento de recuperación. Para tareas simétricas como indexación, agrupación y clasificación, simplemente puede usar el valor predeterminado del sistema de document.dimension integer opcional
Al realizar una llamada HTTP, coloque dimensionen el objeto parameters.
Especifica la dimensión de embedding para el vector de salida. Los valores válidos son 2560 (for qwen3.7-text-embedding only),2048 (solo para text-embedding-v4), 1536 (solo para text-embedding-v4), 1024, 768, 512, 256, 128 o 64. El valor predeterminado es 1024.output_type string opcional
Al realizar una llamada HTTP, coloque output_typeen el objeto parameters.
Especifica el tipo de vector de salida. Este parámetro aplica solo a los modelos qwen3.7-text-embedding,``text-embedding-v3 y text-embedding-v4. Los valores válidos son dense, sparse y dense&sparse. El valor predeterminado es dense, que devuelve solo la representación vectorial densa. Las salidas de vectores dispersos (sparse y dense&sparse) solo se admiten a través de la API DashScope.instruct string opcionalProporciona instrucciones personalizadas para guiar al modelo en la comprensión de la intención de la consulta. Se recomiendan instrucciones en inglés, ya que generalmente mejoran el rendimiento entre un 1% y un 5%.
  • Cadena de entrada
  • Lista de cadenas de entrada
  • Archivo de entrada
  • Python
  • Java
  • curl
import os
import dashscope

# La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    # Las API Key son específicas de cada región. Para obtener una API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

resp = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input='A swift wind, a high sky, and the gibbons cry mournfully. A clear islet, white sand, and the birds fly back. Boundless rustling woods shed their leaves. The endless Yangtze River comes rolling in.',
    dimension=1024,  # Especifique la dimensión del vector (solo la admiten qwen3.7-text-embedding, text-embedding-v3 y text-embedding-v4)
    output_type="dense&sparse"
)

print(resp)

Objeto de respuesta

status_code stringEl código de estado HTTP. Un valor de 200 indica éxito.request_id stringUn identificador único para la solicitud. Utilice este ID para rastrear y solucionar problemas de la solicitud.code stringEl código de error devuelto si la solicitud falla. Este campo está vacío para solicitudes exitosas.message stringUn mensaje de error detallado si la solicitud falla. Este campo está vacío para solicitudes exitosas.outputobjectEl resultado de la tarea.

Propiedades

embeddingsarrayLa salida del modelo para la solicitud. Es una matriz de objetos, donde cada objeto corresponde a un texto de entrada.
sparse_embedding arrayLa representación vectorial dispersa de la cadena correspondiente. Esto aplica solo a text-embedding-v3 y text-embedding-v4.
index integerEl índice del token en el vocabulario.valor floatIndica el peso o la puntuación de importancia del Token. Cuanto mayor sea el valor, mayor será la importancia o relevancia del Token en el contexto de texto actual.token stringEl texto del token.
embedding arrayLa representación vectorial densa para la cadena correspondiente.text_index integerEl índice del texto correspondiente en la matriz de entrada.
usageobject

Propiedades

total_tokens integerEl número de tokens en la entrada, calculado por el tokenizador del modelo.
{
    "request_id": "1ba94ac8-e058-99bc-9cc1-7fdb37940a46",
    "embeddings": [
      {
         "index": 0,
         "sparse_embedding":[
           {"index":7149,"value":0.829,"token":"swift"},
           .....
           {"index":111290,"value":0.9004,"token":"mournfully"}],
         "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
      },
      {
         "index": 1,
         "sparse_embedding":[
           {"index":246351,"value":1.0483,"token":"islet"},
           .....
           {"index":2490,"value":0.8579,"token":"back"}],
         "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
      },
      {
         "index": 2,
         "sparse_embedding":[
           {"index":3759,"value":0.7065,"token":"Boundless"},
           .....
           {"index":1130,"value":0.815,"token":"leaves"}],
         "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
      },
      {
         "index": 3,
         "sparse_embedding":[
           {"index":562,"value":0.6752,"token":"endless"},
           .....
           {"index":1589,"value":0.7097,"token":"in"}],
         "embedding": [-0.001945948973298072,-0.005336422007530928, ...]
      }
    ],
    "usage":{
        "total_tokens":27
    }
}

Códigos de error

Si falla una llamada al modelo, consulte Mensajes de error.