Skip to main content

Embedding

Los modelos de incrustación convierten datos como texto, imágenes y videos en vectores para tareas posteriores, incluyendo búsqueda semántica, recomendación, agrupamiento, clasificación y detección de anomalías.

Requisitos previos

Obtenga una clave de API y exporte la clave de API como variable de entorno. Si utiliza el SDK de OpenAI o el SDK de DashScope para realizar llamadas, instale el SDK.

Obtener embeddings

  • Embedding de texto
  • Vectores multimodales independientes
  • Vectores multimodales fusionados
Para realizar una solicitud de API, especifique el texto para generar el embedding y el modelo que se utilizará.
  • API compatible con OpenAI
  • DashScope
import os
from openai import OpenAI

input_text = "The quality of the clothes is excellent"

client = OpenAI(
    # API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # If you have not set an environment variable, replace this with your API key.
    # This is the URL for the Singapore region. Replace {WorkspaceId} with your workspace ID.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input=input_text
)

print(completion.model_dump_json())

Selección de modelo

Elija el modelo adecuado según su tipo de datos de entrada y caso de uso.
  • Procesamiento de texto plano o código: Utilice qwen3.7-text-embedding. Es el modelo de mayor rendimiento, que admite funciones avanzadas como instrucciones de tarea y vectores dispersos para cubrir la mayoría de los casos de uso de procesamiento de texto. Para escenarios sensibles a los costos que no requieren vectores dispersos u otras funciones avanzadas, utilice la versión ligera qwen3.7-text-embedding-flash, que mantiene la compatibilidad con 201 idiomas y un contexto de 128K a un precio más rentable.
  • Procesamiento de contenido multimodal:
    • Incrustación fusionada: Para representar entradas monomodales o de modalidades mixtas como una incrustación fusionada para casos de uso como la recuperación multimodal y la búsqueda de imágenes, utilice qwen3-vl-embedding. Por ejemplo, puede ingresar una imagen de una camisa con el texto "encuentra un estilo similar que se vea más juvenil", y el modelo fusiona la imagen y la instrucción de tarea en una sola incrustación para su procesamiento.
    • Incrustación independiente: Para generar una incrustación independiente para cada parte de entrada (como una imagen y su subtítulo de texto correspondiente), utilice tongyi-embedding-vision-plus, tongyi-embedding-vision-flash o el modelo multimodal de propósito general multimodal-embedding-v1.
  • Procesamiento de datos a gran escala: Para procesar datos de texto a gran escala y no en tiempo real, utilice qwen3.7-text-embedding o text-embedding-v4 con la API por lotes compatible con OpenAI para reducir significativamente los costos.
Esta tabla detalla las especificaciones de todos los modelos de embedding disponibles.

Embedding de texto

  • Beijing
  • Hong Kong
  • Singapore
Nombre del modeloDimensiones de embeddingTamaño del loteTokens máximos por lote (Nota)Precio / 1M tokensIdioma
text-embedding-v4
Parte de la serie Qwen3-Embedding
2,048, 1,536, 1,024 (predeterminado), 768, 512, 256, 128, 64108,192$0.072100+ idiomas principales, incluidos chino, inglés, español, francés, portugués, indonesio, japonés, coreano, alemán, ruso y múltiples lenguajes de programación
El tamaño de lote es el número máximo de textos por llamada a la API. Por ejemplo, text-embedding-v4 tiene un tamaño de lote de 10, lo que le permite incluir hasta 10 textos para vectorización por solicitud, donde cada texto está limitado a 8,192 tokens. Este límite se aplica a:
  • entrada de matriz de cadenas: La matriz puede contener hasta 10 elementos.
  • entrada de archivo: El archivo de texto puede contener hasta 10 líneas.

Embedding multimodal

Este modelo genera embeddings a partir de entradas de texto, imagen o video. Puede utilizar estos embeddings para tareas como clasificación de video e imagen, recuperación de texto-imagen y búsqueda de texto a imagen o de texto a video.
La API acepta entradas individuales de texto, imagen o video, así como combinaciones como texto e imágenes. Algunos modelos admiten múltiples entradas del mismo tipo, como varias imágenes. Para más detalles, consulte las limitaciones de cada modelo.
  • Singapore
  • China (Beijing)

Modelo

Dimensiones de embedding

Límite de longitud de texto

Límite de tamaño de imagen

Límite de tamaño de video

Precio (por 1M tokens)

Cuota gratuita(Nota)

tongyi-embedding-vision-plus

1152 (predeterminado), 1024, 512, 256, 128, 64

1,024 token

Hasta 3 MB por imagen. Admite hasta 8 imágenes.

Hasta 10 MB por archivo de video

Imagen/Video: $0.09

Texto: $0.09

1 millón de tokens

Esta cuota gratuita es válida durante 90 días a partir de la fecha de activación de Model Studio, lanzamiento del modelo o aprobación de la solicitud, lo que ocurra más tarde.

tongyi-embedding-vision-flash

768 (predeterminado), 512, 256, 128, 64

Imagen/Video: $0.03

Texto: $0.09

Restricciones de entrada e idioma

Modelo multimodal fusionado
ModeloTextoImagenVideoLímite de solicitudes
qwen3-vl-embeddingAdmite 33 idiomas principales, como chino, inglés, japonés, coreano, francés y alemán.
Chino, japonés, coreano, indonesio, vietnamita, tailandés, inglés, francés, alemán, ruso, portugués, español, italiano, sueco, danés, checo, noruego, neerlandés, finés, turco, polaco, suajili, rumano, serbio, griego, kazajo, uzbeko, cebuano, árabe, urdu, persa, hindi/devanagari y hebreo.
JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS y SGI (compatible con URL o Base64)MP4, AVI y MOV (solo URL)El número total de elementos de contenido en una sola solicitud no puede exceder 20. El número de imágenes no puede exceder 5. Las imágenes, el texto y los videos comparten este límite.
Modelo multimodal independiente
ModeloTextoImagenVideoLímite de solicitudes
tongyi-embedding-vision-plusChino/InglésJPG, PNG y BMP (compatible con URL o Base64)MP4, MPEG, AVI, MOV, MPG, WEBM, FLV y MKV (solo URL)No hay límite en el número de elementos de contenido. El número total de tokens de entrada no debe exceder el límite de tokens.
tongyi-embedding-vision-flash
multimodal-embedding-v1El número total de elementos de contenido en una sola solicitud no puede exceder 20. Una solicitud puede contener un máximo de 1 imagen, 1 video y 20 entradas de texto. Estos elementos comparten el límite total.

Características principales

Personalizar dimensiones de vectores

Los modelos qwen3.7-text-embedding, qwen3.7-text-embedding-flash, text-embedding-v4, text-embedding-v3, tongyi-embedding-vision-plus, tongyi-embedding-vision-flash y qwen3-vl-embedding admiten dimensiones de vectores personalizadas. Las dimensiones más altas conservan más información semántica, pero aumentan los costos de almacenamiento y computación.
  • Casos de uso generales (Recomendado): Una dimensión de 1024 proporciona un equilibrio óptimo entre rendimiento y costo, lo que lo hace ideal para la mayoría de las tareas de búsqueda semántica.
  • Escenarios de alta precisión: Para aplicaciones que requieren alta precisión, puede seleccionar una dimensión de 1536 o 2048. Esto mejora la precisión pero aumenta significativamente la sobrecarga de almacenamiento y cómputo.
  • Entornos con recursos limitados: En escenarios sensibles a los costos, seleccione una dimensión de 768 o inferior. Esto reduce significativamente el consumo de recursos a costa de cierta información semántica.
import os
from openai import OpenAI

client = OpenAI(
    # API Keys are region-specific. To get an API Key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # This is the base URL for the Singapore region. Replace {WorkspaceId} with your Workspace ID. URLs are region-specific.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

resp = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input=["I like it and will buy from here again"],
    # Set the vector dimension to 256
    dimensions=256
)
print(f"Vector dimension: {len(resp.data[0].embedding)}")

Texto de consulta vs. documento (text_type)

Este parámetro solo está disponible a través del SDK y la API de DashScope.
Para lograr resultados óptimos en tareas de búsqueda, debe vectorizar el contenido de manera diferente según su función. El parámetro text_type está diseñado para este propósito:
  • text_type: 'query': Utilícelo para el texto de consulta proporcionado por el usuario. El modelo genera un vector "tipo título" que es más direccional y está optimizado para la recuperación de información.
  • text_type: 'document' (predeterminado): Utilícelo para el texto del documento almacenado en su base de conocimientos. El modelo genera un vector "tipo cuerpo" que contiene información más completa y está optimizado para la coincidencia.
Al comparar texto corto con texto largo, debe distinguir entre query y document. Sin embargo, para tareas como clustering o clasificación donde todos los textos tienen la misma función, no necesita establecer este parámetro.

Instrucciones de tarea (instruct)

Este parámetro solo está disponible a través del SDK y la API de DashScope.
Puede proporcionar una instrucción de tarea clara en inglés para guiar a los modelos qwen3.7-text-embedding y text-embedding-v4 en la optimización de la calidad de los vectores para escenarios de recuperación específicos, mejorando la precisión. qwen3.7-text-embedding mejora la capacidad de seguimiento de instrucciones en un 16.4% respecto a text-embedding-v4, por lo que recomendamos utilizarlo primero. Al usar esta función, debe establecer el parámetro text_type en query.
# Ejemplo: agregue una instrucción para optimizar la calidad de la recuperación al construir vectores de documentos.
resp = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input="Research papers on machine learning",
    text_type="query",
    instruct="Given a research paper query, retrieve relevant research paper"
)

Vectores densos y dispersos

Este parámetro solo está disponible a través del SDK y la API de DashScope.
Los modelos qwen3.7-text-embedding, text-embedding-v4 y text-embedding-v3 admiten tres tipos de salida de vectores para adaptarse a diferentes estrategias de recuperación. La incrustación dispersa de qwen3.7-text-embedding utiliza una nueva estrategia de entrenamiento similar a SPLADE que mejora la eficacia en un 8.4% y añade compatibilidad para la recuperación entre idiomas.

Tipo de vector (output_type)

Ventajas

Limitaciones

Casos de uso

denso

Comprensión semántica profunda que identifica sinónimos y contexto para obtener resultados más relevantes.

Mayores costos de cómputo y almacenamiento. No garantiza una coincidencia exacta de palabras clave.

Búsqueda semántica, preguntas y respuestas impulsadas por IA, recomendación de contenido.

disperso

Alta eficiencia computacional, centrada en una coincidencia exacta de palabras clave y permitiendo un filtrado rápido.

Carece de comprensión semántica y no puede procesar sinónimos ni contexto.

Recuperación de registros, búsqueda de SKU de productos, filtrado preciso de información.

denso y disperso

Combina la coincidencia semántica y de palabras clave para obtener resultados de búsqueda óptimos. El costo de generación no cambia, y la sobrecarga de llamadas a la API es idéntica a la del modo de vector único.

Requiere más almacenamiento, y la arquitectura del sistema y la lógica de recuperación son más complejas.

Motor de búsqueda híbrida de alta calidad y nivel de producción.

Casos de uso

El siguiente código es solo con fines demostrativos. Para producción, precalcule y almacene los embeddings en una base de datos vectorial. De esta manera, solo necesitará generar el embedding de la consulta para la recuperación.

Búsqueda semántica

Realice una coincidencia semántica precisa calculando la similitud entre el embedding de la consulta y los embeddings del documento.
import os
import dashscope
import numpy as np

# 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 ha configurado una 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",
)

def cosine_similarity(a, b):
    """Calculate cosine similarity."""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def semantic_search(query, documents, top_k=5):
    """Perform semantic search."""
    # Genera el embedding de la consulta.
    query_resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=query,
        dimension=1024
    )
    query_embedding = query_resp.embeddings[0].embedding

    # Genera los embeddings de los documentos.
    doc_resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=documents,
        dimension=1024
    )

    # Calcula las similitudes.
    similarities = []
    for i, doc_emb in enumerate(doc_resp.embeddings):
        similarity = cosine_similarity(query_embedding, doc_emb.embedding)
        similarities.append((i, similarity))

    # Ordena y devuelve los k resultados principales.
    similarities.sort(key=lambda x: x[1], reverse=True)
    return [(documents[i], sim) for i, sim in similarities[:top_k]]

# Example usage
documents = [
    "Artificial intelligence is a branch of computer science",
    "Machine learning is an important method for achieving artificial intelligence",
    "Deep learning is a subfield of machine learning"
]
query = "What is AI?"
results = semantic_search(query, documents, top_k=2)
for doc, sim in results:
    print(f"Similarity: {sim:.3f}, Document: {doc}")

Sistema de recomendación

Analice los embeddings del historial de comportamiento de un usuario para identificar sus intereses y recomendar elementos similares.
import os
import dashscope
import numpy as np

# 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 ha configurado una 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",
)

def cosine_similarity(a, b):
    """Calculate cosine similarity."""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
def build_recommendation_system(user_history, all_items, top_k=10):
    """Build a recommendation system."""
    # Genera los embeddings del historial del usuario.
    history_resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=user_history,
        dimension=1024
    )

    # Calcula el embedding de preferencia del usuario promediando.
    user_embedding = np.mean([
        emb.embedding for emb in history_resp.embeddings
    ], axis=0)

    # Genera los embeddings de todos los elementos.
    items_resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=all_items,
        dimension=1024
    )

    # Calcula las puntuaciones de recomendación.
    recommendations = []
    for i, item_emb in enumerate(items_resp.embeddings):
        score = cosine_similarity(user_embedding, item_emb.embedding)
        recommendations.append((all_items[i], score))

    # Sort and return the recommendation results.
    recommendations.sort(key=lambda x: x[1], reverse=True)
    return recommendations[:top_k]

# Example usage
user_history = ["Science Fiction", "Action", "Suspense"]
all_movies = ["Future World", "Space Adventure", "Ancient War", "Romantic Journey", "Superhero"]
recommendations = build_recommendation_system(user_history, all_movies)
for movie, score in recommendations:
    print(f"Recommendation Score: {score:.3f}, Movie: {movie}")

Clustering de texto

Agrupe textos similares analizando las distancias entre sus embeddings.
# Se requiere scikit-learn: pip install scikit-learn
import os
import dashscope
import numpy as np
from sklearn.cluster import KMeans

# 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 ha configurado una 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",
)

def cluster_texts(texts, n_clusters=2):
    """Cluster a set of texts."""
    # 1. Obtiene los embeddings de todos los textos.
    resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=texts,
        dimension=1024
    )
    embeddings = np.array([item.embedding for item in resp.embeddings])

    # 2. Use the KMeans algorithm for clustering.
    kmeans = KMeans(n_clusters=n_clusters, random_state=0, n_init='auto').fit(embeddings)

    # 3. Organize and return the results.
    clusters = {i: [] for i in range(n_clusters)}
    for i, label in enumerate(kmeans.labels_):
        clusters[label].append(texts[i])
    return clusters

# Example usage
documents_to_cluster = [
    "Mobile phone company A releases a new phone",
    "Search engine company B launches a new system",
    "World Cup final: Argentina vs. France",
    "China wins another gold medal at the Olympics",
    "A company releases its latest AI chip",
    "European Cup match report"
]
clusters = cluster_texts(documents_to_cluster, n_clusters=2)
for cluster_id, docs in clusters.items():
    print(f"--- Cluster {cluster_id} ---")
    for doc in docs:
        print(f"- {doc}")

Clasificación de texto

Realice clasificación de texto zero-shot calculando la similitud entre el embedding de un texto de entrada y embeddings de etiquetas predefinidas. Este proceso clasifica el texto en nuevas categorías sin requerir ejemplos preetiquetados.
import os
import dashscope
import numpy as np

# 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 ha configurado una 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",
)

def cosine_similarity(a, b):
    """Calculate cosine similarity."""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def classify_text_zero_shot(text, labels):
    """Perform zero-shot text classification."""
    # 1. Obtiene los embeddings del texto de entrada y de todas las etiquetas.
    resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=[text] + labels,
        dimension=1024
    )
    embeddings = resp.embeddings
    text_embedding = embeddings[0].embedding
    label_embeddings = [emb.embedding for emb in embeddings[1:]]

    # 2. Calculate the similarity with each label.
    scores = [cosine_similarity(text_embedding, label_emb) for label_emb in label_embeddings]

    # 3. Return the label with the highest similarity.
    best_match_index = np.argmax(scores)
    return labels[best_match_index], scores[best_match_index]

# Example usage
text_to_classify = "The fabric of this dress is comfortable, and the style is nice too"
possible_labels = ["Digital Products", "Apparel & Accessories", "Food & Beverage", "Home & Living"]

label, score = classify_text_zero_shot(text_to_classify, possible_labels)
print(f"Input text: '{text_to_classify}'")
print(f"Best matching category: '{label}' (Similarity: {score:.3f})")

Detección de anomalías

Identifique datos anómalos calculando la similitud entre el embedding de un texto y el embedding central de muestras normales. Los datos que se desvían significativamente de este patrón se consideran una anomalía.
El valor threshold en el ejemplo es solo con fines demostrativos. El valor ideal varía según el contenido y la distribución de los datos, por lo que debe calibrarlo utilizando su propio conjunto de datos.
import os
import dashscope
import numpy as np

# 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 ha configurado una 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",
)

def cosine_similarity(a, b):
    """Calculate cosine similarity."""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def detect_anomaly(new_comment, normal_comments, threshold=0.6):
    # 1. Genera los embeddings de todos los comentarios normales y del comentario nuevo.
    all_texts = normal_comments + [new_comment]
    resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=all_texts,
        dimension=1024
    )
    embeddings = [item.embedding for item in resp.embeddings]

    # 2. Calculate the center embedding (average) of the normal comments.
    normal_embeddings = np.array(embeddings[:-1])
    normal_center_vector = np.mean(normal_embeddings, axis=0)

    # 3. Calculate the similarity between the new comment's embedding and the center embedding.
    new_comment_embedding = np.array(embeddings[-1])
    similarity = cosine_similarity(new_comment_embedding, normal_center_vector)

    # 4. Determine if it is an anomaly.
    is_anomaly = similarity < threshold
    return is_anomaly, similarity

# Example usage
normal_user_comments = [
    "Today's meeting was productive",
    "The project is progressing smoothly",
    "The new version will be released next week",
    "User feedback is positive"
]

test_comments = {
    "Normal comment": "The feature works as expected",
    "Anomaly - meaningless garbled text": "asdfghjkl zxcvbnm"
}

print("--- Anomaly Detection Example ---")
for desc, comment in test_comments.items():
    is_anomaly, score = detect_anomaly(comment, normal_user_comments)
    result = "Yes" if is_anomaly else "No"
    print(f"Comment: '{comment}'")
    print(f"Is anomaly: {result} (Similarity to normal samples: {score:.3f})\n")

Referencia de API

Códigos de error

Si la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para su resolución.

Limitación de tasa

Para conocer las condiciones de limitación de tasa del modelo, consulte Limitación de tasa.

Rendimiento del modelo (MTEB/CMTEB)

Evaluaciones comparativas

  • MTEB (Massive Text Embedding Benchmark): Un benchmark integral que evalúa el rendimiento de propósito general de los embeddings de texto en tareas como clasificación, clustering y recuperación.
  • CMTEB (Chinese Massive Text Embedding Benchmark): Un benchmark a gran escala diseñado específicamente para evaluar embeddings de texto en chino.
  • Las puntuaciones oscilan entre 0 y 100. Las puntuaciones más altas indican un mejor rendimiento.

Modelo

MTEB

MTEB (tarea de recuperación)

CMTEB

CMTEB (tarea de recuperación)

text-embedding-v3 (512 dimensiones)

62.11

54.30

66.81

71.88

text-embedding-v3 (768 dimensiones)

62.43

54.74

67.90

72.29

text-embedding-v3 (1024 dimensiones)

63.39

55.41

68.92

73.23

text-embedding-v4 (512 dimensiones)

64.73

56.34

68.79

73.33

text-embedding-v4 (1024 dimensiones)

68.36

59.30

70.14

73.98

text-embedding-v4 (2048 dimensiones)

71.58

61.97

71.99

75.01