Alibaba Cloud Model Studio: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

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

const OpenAI = require("openai");

// Initialize the OpenAI client.
const openai = new OpenAI({
    // If you have not set an environment variable, replace this with your API key.
    // API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    apiKey: process.env.DASHSCOPE_API_KEY,
    // This is the URL for the Singapore region. Replace {WorkspaceId} with your workspace ID.
    baseURL: 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1'
});

async function getEmbedding() {
    try {
        const inputTexts = "The quality of the clothes is excellent";
        const completion = await openai.embeddings.create({
            model: "qwen3.7-text-embedding",
            input: inputTexts,
            dimensions: 1024 // Specify the vector dimension. This parameter is only supported by qwen3.7-text-embedding, text-embedding-v3, and text-embedding-v4.
        });

        console.log(JSON.stringify(completion, null, 2));
    } catch (error) {
        console.error('Error:', error);
    }
}

getEmbedding();

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3.7-text-embedding",
    "input": "The quality of the clothes is excellent"
}'

import os
import dashscope

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma 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",
)

input_text = "The quality of the clothes is excellent"
resp = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input=input_text,
)

print(resp)

import com.alibaba.dashscope.embeddings.TextEmbedding;
import com.alibaba.dashscope.embeddings.TextEmbeddingParam;
import com.alibaba.dashscope.embeddings.TextEmbeddingResult;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

import java.util.Collections;
public class Main {
    static {
        Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        // If you are using the China (Beijing) region, replace the URL with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
    }
     public static void main(String[] args) {
        String inputTexts = "The quality of the clothes is excellent";
        try {
            // Build the request parameters.
            TextEmbeddingParam param = TextEmbeddingParam
                    .builder()
                    .model("qwen3.7-text-embedding")
                    // Input text.
                    .texts(Collections.singleton(inputTexts))
                    .build();

            // Create a model instance and make a call.
            TextEmbedding textEmbedding = new TextEmbedding();
            TextEmbeddingResult result = textEmbedding.call(param);

            // Print the result.
            System.out.println(result);

        } catch (NoApiKeyException e) {
            // Catch and handle the exception for a missing API key.
            System.err.println("An exception occurred during the API call: " + e.getMessage());
            System.err.println("Please check if your API key is configured correctly.");
            e.printStackTrace();
        }
    }
}

# ======= Important =======
# If you use a model in the China (Beijing) region, replace base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
# === Remove this comment before running ===

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3.7-text-embedding",
    "input": {
        "texts": [
        "The quality of the clothes is excellent"
        ]
    }
}'

import dashscope
import json
import os

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma 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",
)

# A entrada pode ser um vídeo.
# video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20250107/lbcemt/new+video.mp4"
# input = [{'video': video}]
# Ou uma imagem.
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
resp = client.multimodal.embeddings.create(
    model="tongyi-embedding-vision-plus",
    input=input
)

print(json.dumps(resp.model_dump(), indent=4))

import com.alibaba.dashscope.embeddings.MultiModalEmbedding;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemImage;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingItemVideo;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingParam;
import com.alibaba.dashscope.embeddings.MultiModalEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;

import java.util.Collections;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        // If you are using the China (Beijing) region, replace the URL with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
    }
    public static void main(String[] args) {
        try {
            MultiModalEmbedding embedding = new MultiModalEmbedding();
            // The input can be a video.
            // MultiModalEmbeddingItemVideo video = new MultiModalEmbeddingItemVideo(
            //     "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20250107/lbcemt/new+video.mp4");
            // Or an image.
            MultiModalEmbeddingItemImage image = new MultiModalEmbeddingItemImage(
                "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png");

            MultiModalEmbeddingParam param = MultiModalEmbeddingParam.builder()
                // If you have not set an environment variable, add your Model Studio API key by using .apiKey("sk-xxx")
                .model("tongyi-embedding-vision-plus")
                .contents(Collections.singletonList(image))
                .build();

            MultiModalEmbeddingResult result = embedding.call(param);
            System.out.println(result);

        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.err.println("An exception occurred during the API call: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

import dashscope
import json
import os

# A configuração abaixo refere-se à região China (Pequim). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Vetor multimodal fundido: combina texto, imagens e vídeos em um único vetor fundido.
# Adequado para casos de uso como recuperação cross-modal e busca de imagens.
text = "This is a test text for generating a multimodal fused vector"
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20250107/lbcemt/new+video.mp4"

# A entrada contém texto, uma imagem e um vídeo. Um vetor fundido é gerado ao definir o parâmetro enable_fusion.
input_data = [
    {"text": text},
    {"image": image},
    {"video": video}
]

# Use qwen3-vl-embedding para gerar um vetor fundido.
resp = client.multimodal.embeddings.create(
    model="qwen3-vl-embedding",
    input=input_data,
    enable_fusion=True,
    # Parâmetro opcional: especifica a dimensão do vetor. Valores suportados: 2560, 2048, 1536, 1024, 768, 512 e 256. Padrão: 2560.
    # dimension = 1024
)

print(json.dumps(resp.model_dump(), indent=4))

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        // If you have not set an environment variable, replace the following line with your Model Studio API key: String apiKey = "sk-xxx";
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        // Use enable_fusion to combine text, an image, and a video into a single fused vector.
        String requestBody = "{"
                + "\"model\": \"qwen3-vl-embedding\","
                + "\"input\": {"
                + "  \"contents\": ["
                + "    {\"text\": \"This is a test text for generating a multimodal fused vector\"},"
                + "    {\"image\": \"https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png\"},"
                + "    {\"video\": \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20250107/lbcemt/new+video.mp4\"}"
                + "  ]"
                + "},"
                + "\"parameters\": {"
                + "  \"enable_fusion\": true"
                + "}"
                + "}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding"))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

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

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.

Restrições de entrada e idioma

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)}")

import os
import dashscope

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma 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=["I like it and will buy from here again"],
    # Defina a dimensão do vetor como 256
    dimension=256
)

print(f"Dimensão do vetor: {len(resp.embeddings[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.

# Exemplo: adicione uma instrução para otimizar a qualidade de recuperação ao construir vetores 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"
)

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.

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 os
import dashscope
import numpy as np

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma 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):
    """Calcule a similaridade de cosseno."""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def semantic_search(query, documents, top_k=5):
    """Realize uma busca semântica."""
    # Gere o embedding da consulta.
    query_resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=query,
        dimension=1024
    )
    query_embedding = query_resp.embeddings[0].embedding

    # Gere os embeddings dos documentos.
    doc_resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=documents,
        dimension=1024
    )

    # Calcule as similaridades.
    similarities = []
    for i, doc_emb in enumerate(doc_resp.embeddings):
        similarity = cosine_similarity(query_embedding, doc_emb.embedding)
        similarities.append((i, similarity))

    # Ordene e retorne os resultados top-k.
    similarities.sort(key=lambda x: x[1], reverse=True)
    return [(documents[i], sim) for i, sim in similarities[:top_k]]

# Exemplo de uso
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"Similaridade: {sim:.3f}, Documento: {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 os
import dashscope
import numpy as np

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma 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):
    """Calcule a similaridade de cosseno."""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
def build_recommendation_system(user_history, all_items, top_k=10):
    """Construa um sistema de recomendação."""
    # Gere os embeddings do histórico do usuário.
    history_resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=user_history,
        dimension=1024
    )

    # Calcule o embedding de preferência do usuário pela média.
    user_embedding = np.mean([
        emb.embedding for emb in history_resp.embeddings
    ], axis=0)

    # Gere os embeddings de todos os itens.
    items_resp = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=all_items,
        dimension=1024
    )

    # Calcule as pontuações de recomendação.
    recommendations = []
    for i, item_emb in enumerate(items_resp.embeddings):
        score = cosine_similarity(user_embedding, item_emb.embedding)
        recommendations.append((all_items[i], score))

    # Ordene e retorne os resultados da recomendação.
    recommendations.sort(key=lambda x: x[1], reverse=True)
    return recommendations[:top_k]

# Exemplo de uso
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"Pontuação de recomendação: {score:.3f}, Filme: {movie}")

Clustering de texto

Agrupe textos semelhantes analisando as distâncias entre seus embeddings.

# O scikit-learn é necessário: pip install scikit-learn
import os
import dashscope
import numpy as np
from sklearn.cluster import KMeans

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma 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):
    """Agrupe um conjunto de textos."""
    # 1. Obtenha os embeddings de todos os 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 o algoritmo KMeans para agrupar.
    kmeans = KMeans(n_clusters=n_clusters, random_state=0, n_init='auto').fit(embeddings)

    # 3. Organize e retorne os resultados.
    clusters = {i: [] for i in range(n_clusters)}
    for i, label in enumerate(kmeans.labels_):
        clusters[label].append(texts[i])
    return clusters

# Exemplo de uso
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 os
import dashscope
import numpy as np

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma 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):
    """Calcule a similaridade de cosseno."""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def classify_text_zero_shot(text, labels):
    """Realize a classificação de texto zero-shot."""
    # 1. Obtenha os embeddings do texto de entrada e de todos os rótulos.
    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. Calcule a similaridade com cada rótulo.
    scores = [cosine_similarity(text_embedding, label_emb) for label_emb in label_embeddings]

    # 3. Retorne o rótulo com a maior similaridade.
    best_match_index = np.argmax(scores)
    return labels[best_match_index], scores[best_match_index]

# Exemplo de uso
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"Texto de entrada: '{text_to_classify}'")
print(f"A categoria mais compatível: '{label}' (Similaridade: {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 os
import dashscope
import numpy as np

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx",
    # As API Keys variam conforme a região. Para obter uma 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):
    """Calcule a similaridade de cosseno."""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def detect_anomaly(new_comment, normal_comments, threshold=0.6):
    # 1. Gere os embeddings de todos os comentários normais e do novo comentário.
    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. Calcule o embedding central (média) dos comentários normais.
    normal_embeddings = np.array(embeddings[:-1])
    normal_center_vector = np.mean(normal_embeddings, axis=0)

    # 3. Calcule a similaridade entre o embedding do novo comentário e o embedding central.
    new_comment_embedding = np.array(embeddings[-1])
    similarity = cosine_similarity(new_comment_embedding, normal_center_vector)

    # 4. Determine se é uma anomalia.
    is_anomaly = similarity < threshold
    return is_anomaly, similarity

# Exemplo de uso
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("--- Exemplo de detecção de anomalias ---")
for desc, comment in test_comments.items():
    is_anomaly, score = detect_anomaly(comment, normal_user_comments)
    result = "Sim" if is_anomaly else "Não"
    print(f"Comentário: '{comment}'")
    print(f"É anomalia: {result} (Similaridade com as amostras normais: {score:.3f})\n")

Referência da API

• Embedding de texto geral
  • Synchronous processing API
• Embedding multimodal

  Multimodal embedding 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.