Skip to main content
Embedding e rerank

Embedding

Os modelos de embedding convertem dados como texto, imagens e vídeos em vetores para tarefas subsequentes, incluindo busca semântica, recomendação, clustering, classificação e detecção de anomalias.

Pré-requisitos

Obtain an API key e export the API key as an environment variable. Se você usar o OpenAI SDK ou DashScope SDK para fazer chamadas, install the SDK.

Obter embeddings

  • Text embedding
  • Independent multimodal vectors
  • Multimodal fused vectors
Para fazer uma requisição de API, especifique o texto a ser convertido em embedding e o modelo a ser usado.
  • OpenAI compatible API
  • 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/en/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())

Seleção de modelo

Escolha o modelo adequado com base no tipo de dados de entrada e no caso de uso.
  • Processamento de texto simples ou código: Use qwen3.7-text-embedding. É o modelo de maior desempenho e oferece recursos avançados, como instrução de tarefa e vetor esparso, atendendo à maioria dos casos de uso de processamento de texto.
  • Processamento de conteúdo multimodal:
    • Embedding fundido: Para representar entradas de modalidade única ou mista como um embedding fundido em casos de uso como recuperação entre modalidades e busca de imagens, use qwen3-vl-embedding. Por exemplo, insira uma imagem de uma camisa com o texto "encontre um estilo semelhante que pareça mais jovem", e o modelo fundirá a imagem e a instrução da tarefa em um único embedding para processamento.
    • Embedding independente: Para gerar um embedding independente para cada parte da entrada (como uma imagem e sua legenda correspondente), use tongyi-embedding-vision-plus, tongyi-embedding-vision-flash ou o modelo multimodal de uso geral multimodal-embedding-v1.
  • Processamento de dados em grande escala: Para processar grandes volumes de dados de texto não em tempo real, use qwen3.7-text-embedding ou text-embedding-v4 com a OpenAI compatible batch API para reduzir custos significativamente.
A tabela a seguir detalha as especificações de todos os modelos de embedding disponíveis.

Text embedding

  • Beijing
  • Hong Kong
  • Singapore
Nome do modeloDimensões do embeddingTamanho do loteMáximo de tokens por lote (Note)Preço / 1M tokensIdioma
text-embedding-v4
Parte da série Qwen3-Embedding
2.048, 1.536, 1.024 (padrão), 768, 512, 256, 128, 64108.192$0,072Mais de 100 idiomas principais, incluindo chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão, russo e várias linguagens de programação
O tamanho do lote é o número máximo de textos por chamada de API. Por exemplo, o text-embedding-v4 tem tamanho de lote de 10, permitindo incluir até 10 textos para vetorização por requisição, sendo cada texto limitado a 8.192 tokens. Esse limite aplica-se a:
  • Entrada de array de strings: O array pode conter até 10 elementos.
  • Entrada de arquivo: O arquivo de texto pode conter até 10 linhas.

Multimodal embedding

Este modelo gera embeddings a partir de entradas de texto, imagem ou vídeo. Use esses embeddings para tarefas como classificação de vídeo e imagem, recuperação de imagem-texto e busca de texto para imagem ou texto para vídeo.
A API aceita entradas únicas de texto, imagem ou vídeo, além de combinações como texto e imagens. Alguns modelos suportam múltiplas entradas do mesmo tipo, como várias imagens. Para detalhes, consulte as limitações de cada modelo.
  • Singapore
  • China (Beijing)

Modelo

Dimensões do embedding

Limite de comprimento de texto

Limite de tamanho de imagem

Limite de tamanho de vídeo

Preço (por 1M tokens)

Cota gratuita(Note)

tongyi-embedding-vision-plus

1152

1.024 tokens

Até 3 MB por imagem. Suporta até 8 imagens.

Até 10 MB por arquivo de vídeo

Imagem/Vídeo: $0,09

Texto: $0,09

1 milhão de tokens

Esta cota gratuita é válida por 90 dias a partir da ativação do Model Studio, do lançamento do modelo ou da aprovação da solicitação, o que ocorrer por último.

tongyi-embedding-vision-flash

768

Imagem/Vídeo: $0,03

Texto: $0,09

Restrições de entrada e idioma

Modelo multimodal fundido
ModeloTextoImagemVídeoLimite de requisição
qwen3-vl-embeddingSuporta 33 idiomas principais, como chinês, inglês, japonês, coreano, francês e alemão.
Chinês, Japonês, Coreano, Indonésio, Vietnamita, Tailandês, Inglês, Francês, Alemão, Russo, Português, Espanhol, Italiano, Sueco, Dinamarquês, Tcheco, Norueguês, Holandês, Finlandês, Turco, Polonês, Suaíli, Romeno, Sérvio, Grego, Cazaque, Uzbeque, Cebuano, Árabe, Urdu, Persa, Hindi/Devanagari e Hebraico.
JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS e SGI (URL ou Base64 suportado)MP4, AVI e MOV (apenas URL)O total de elementos de conteúdo em uma única requisição não pode exceder 20. O número de imagens não pode exceder 5. Imagens, texto e vídeos compartilham esse limite.
Modelo multimodal independente
ModeloTextoImagemVídeoLimite de requisição
tongyi-embedding-vision-plusChinês/InglêsJPG, PNG e BMP (URL ou Base64 suportado)MP4, MPEG, AVI, MOV, MPG, WEBM, FLV e MKV (apenas URL)Sem limite no número de elementos de conteúdo. O total de tokens de entrada não deve exceder o limite de tokens.
tongyi-embedding-vision-flash
multimodal-embedding-v1O total de elementos de conteúdo em uma única requisição não pode exceder 20. Uma requisição pode conter no máximo 1 imagem, 1 vídeo e 20 entradas de texto. Esses itens compartilham o limite total.

Recursos principais

Personalizar dimensões de vetor

Os modelos qwen3.7-text-embedding, text-embedding-v4, text-embedding-v3, tongyi-embedding-vision-plus, tongyi-embedding-vision-flash, qwen3-vl-embedding aceitam dimensões de vetor personalizadas. Dimensões maiores preservam mais informações semânticas, mas aumentam os custos de armazenamento e computação.
  • Casos de uso geral (Recomendado): A dimensão 1024 oferece equilíbrio ideal entre desempenho e custo, adequada para a maioria das tarefas de busca semântica.
  • Cenários de alta precisão: Para aplicações que exigem alta precisão, selecione a dimensão 1536 ou 2048. Isso melhora a precisão, mas aumenta significativamente a sobrecarga de armazenamento e computação.
  • Ambientes com recursos limitados: Em cenários sensíveis a custos, selecione a dimensão 768 ou inferior. Isso reduz significativamente o consumo de recursos, embora haja perda de algumas informações semânticas.
import os
from openai import OpenAI

client = OpenAI(
    # API Keys are region-specific. To get an API Key, see https://www.alibabacloud.com/help/en/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 está disponível apenas no DashScope SDK e na API.
Para obter resultados ideais em tarefas de busca, vetorize o conteúdo de forma diferente conforme sua função. O parâmetro text_type atende a essa finalidade:
  • text_type: 'query': Use para texto de consulta fornecido pelo usuário. O modelo gera um vetor "semelhante a título", mais direcional e otimizado para recuperação de informações.
  • text_type: 'document' (padrão): Use para o texto do documento armazenado em sua base de conhecimento. O modelo gera um vetor "semelhante a corpo", com informações mais abrangentes e otimizado para correspondência.
Ao comparar texto curto com texto longo, distinga entre query e document. No entanto, para tarefas como clustering ou classificação, em que todos os textos têm a mesma função, não é necessário definir esse parâmetro.

Instruções de tarefa (instruct)

Este parâmetro está disponível apenas no DashScope SDK e na API.
Forneça uma instrução de tarefa clara em inglês para orientar os modelos qwen3.7-text-embedding e text-embedding-v4 a otimizar a qualidade do vetor para cenários específicos de recuperação, melhorando a precisão. O qwen3.7-text-embedding aprimora a capacidade de seguir instruções em 16,4% em relação ao text-embedding-v4, portanto, recomendamos seu uso prioritário. Ao usar este recurso, defina o parâmetro text_type como query.
# Example: Add an instruction to optimize retrieval quality when building document vectors.
resp = dashscope.TextEmbedding.call(
    model="qwen3.7-text-embedding",
    input="Research papers on machine learning",
    text_type="query",
    instruct="Given a research paper query, retrieve relevant research paper"
)

Vetores densos e esparsos

Este parâmetro está disponível apenas no DashScope SDK e na API.
Os modelos qwen3.7-text-embedding, text-embedding-v4 e text-embedding-v3 oferecem três tipos de saída de vetor para atender a diferentes estratégias de recuperação. O embedding esparso do qwen3.7-text-embedding adota uma nova estratégia de treinamento semelhante ao SPLADE, que melhora a eficácia em 8,4% e adiciona suporte à recuperação entre idiomas.

Tipo de vetor (output_type)

Vantagens

Limitações

Casos de uso

dense

Compreensão semântica profunda que identifica sinônimos e contexto para resultados mais relevantes.

Maior custo de computação e armazenamento. Não garante correspondência exata para palavras-chave.

Busca semântica, Q&A com IA, recomendação de conteúdo.

sparse

Alta eficiência computacional, focando na correspondência exata de palavras-chave e permitindo filtragem rápida.

Falta compreensão semântica e não processa sinônimos ou contexto.

Recuperação de logs, busca de SKU de produtos, filtragem precisa de informações.

dense&sparse

Combina correspondência semântica e de palavras-chave para resultados de busca ideais. O custo de geração permanece inalterado, e a sobrecarga da chamada de API é idêntica à do modo de vetor único.

Exige mais armazenamento, e a arquitetura do sistema e a lógica de recuperação tornam-se mais complexas.

Mecanismo de busca híbrida de alta qualidade para produção.

Casos de uso

O código a seguir serve apenas para demonstração. Em produção, pré-compute e armazene embeddings em um banco de dados vetorial. Assim, basta gerar o embedding da consulta para recuperação.

Busca semântica

Realize correspondência semântica precisa calculando a similaridade entre o embedding da consulta e os embeddings dos documentos.
import dashscope
import numpy as np
from dashscope import TextEmbedding

# To use a model from the China (Beijing) region, change base_http_api_url to: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

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."""
    # Generate the query embedding.
    query_resp = TextEmbedding.call(
        model="qwen3.7-text-embedding",
        input=query,
        dimension=1024
    )
    query_embedding = query_resp.output['embeddings'][0]['embedding']

    # Generate the document embeddings.
    doc_resp = TextEmbedding.call(
        model="qwen3.7-text-embedding",
        input=documents,
        dimension=1024
    )

    # Calculate similarities.
    similarities = []
    for i, doc_emb in enumerate(doc_resp.output['embeddings']):
        similarity = cosine_similarity(query_embedding, doc_emb['embedding'])
        similarities.append((i, similarity))

    # Sort and return the top-k results.
    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 recomendação

Analise os embeddings do histórico comportamental de um usuário para identificar seus interesses e recomendar itens semelhantes.
import dashscope
import numpy as np
from dashscope import TextEmbedding

# To use a model from the China (Beijing) region, change base_http_api_url to: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

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."""
    # Generate user history embeddings.
    history_resp = TextEmbedding.call(
        model="qwen3.7-text-embedding",
        input=user_history,
        dimension=1024
    )

    # Calculate the user preference embedding by averaging.
    user_embedding = np.mean([
        emb['embedding'] for emb in history_resp.output['embeddings']
    ], axis=0)

    # Generate all item embeddings.
    items_resp = TextEmbedding.call(
        model="qwen3.7-text-embedding",
        input=all_items,
        dimension=1024
    )

    # Calculate recommendation scores.
    recommendations = []
    for i, item_emb in enumerate(items_resp.output['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 semelhantes analisando as distâncias entre seus embeddings.
# scikit-learn is required: pip install scikit-learn
import dashscope
import numpy as np
from sklearn.cluster import KMeans

# To use a model from the China (Beijing) region, change base_http_api_url to: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

def cluster_texts(texts, n_clusters=2):
    """Cluster a set of texts."""
    # 1. Get the embeddings for all texts.
    resp = dashscope.TextEmbedding.call(
        model="qwen3.7-text-embedding",
        input=texts,
        dimension=1024
    )
    embeddings = np.array([item['embedding'] for item in resp.output['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}")

Classificação de texto

Realize classificação de texto zero-shot calculando a similaridade entre o embedding de um texto de entrada e embeddings de rótulos predefinidos. Esse processo classifica o texto em novas categorias sem exigir exemplos pré-rotulados.
import dashscope
import numpy as np

# To use a model from the China (Beijing) region, change base_http_api_url to: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

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. Get the embeddings for the input text and all labels.
    resp = dashscope.TextEmbedding.call(
        model="qwen3.7-text-embedding",
        input=[text] + labels,
        dimension=1024
    )
    embeddings = resp.output['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})")

Detecção de anomalias

Identifique dados anômalos calculando a similaridade entre o embedding de um texto e o embedding central de amostras normais. Dados que se desviam significativamente desse padrão são considerados anomalias.
O threshold no exemplo serve apenas para demonstração. O valor ideal varia conforme o conteúdo e a distribuição dos dados; portanto, calibre-o usando seu próprio conjunto de dados.
import dashscope
import numpy as np

# To use a model from the China (Beijing) region, change base_http_api_url to: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

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. Generate embeddings for all normal comments and the new comment.
    all_texts = normal_comments + [new_comment]
    resp = dashscope.TextEmbedding.call(
        model="qwen3.7-text-embedding",
        input=all_texts,
        dimension=1024
    )
    embeddings = [item['embedding'] for item in resp.output['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")

Referência da API

Códigos de erro

Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Error codes para resolução.

Limitação de taxa

Para as condições de limitação de taxa do modelo, consulte Rate limiting.

Desempenho do modelo (MTEB/CMTEB)

Benchmarks de avaliação

  • MTEB (Massive Text Embedding Benchmark): Benchmark abrangente que avalia o desempenho de uso geral de embeddings de texto em tarefas como classificação, clustering e recuperação.
  • CMTEB (Chinese Massive Text Embedding Benchmark): Benchmark em grande escala específico para avaliar embeddings de texto em chinês.
  • As pontuações variam de 0 a 100. Pontuações mais altas indicam melhor desempenho.

Modelo

MTEB

MTEB (tarefa de recuperação)

CMTEB

CMTEB (tarefa de recuperação)

text-embedding-v3 (512 dimensões)

62,11

54,30

66,81

71,88

text-embedding-v3 (768 dimensões)

62,43

54,74

67,90

72,29

text-embedding-v3 (1024 dimensões)

63,39

55,41

68,92

73,23

text-embedding-v4 (512 dimensões)

64,73

56,34

68,79

73,33

text-embedding-v4 (1024 dimensões)

68,36

59,30

70,14

73,98

text-embedding-v4 (2048 dimensões)

71,58

61,97

71,99

75,01

Plano de Tokens
Playground de Modelos
  • Music generation
Inferência do Modelo
Avaliação
Compressão de Modelos
Estatísticas e Monitoramento
Suporte
Embedding - Alibaba Cloud Model Studio