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
Obtenha uma chave de API e exporte a chave de API como variável de ambiente. Caso utilize o OpenAI SDK ou DashScope SDK para realizar chamadas, instale o SDK.
Obter embeddings
Embedding de texto
Para fazer uma solicitação de API, especifique o texto para embedding e o modelo a ser usado.
API compatível com OpenAI
import os
from openai import OpenAI
input_text = "The quality of the clothes is excellent"
client = OpenAI(
# If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
# 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"),
# The following is the base URL for the Beijing region. If you use a model in the Singapore region, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
)
completion = client.embeddings.create(
model="text-embedding-v4",
input=input_text
)
print(completion.model_dump_json())
const OpenAI = require("openai");
const openai = new OpenAI({
// If you have not set an environment variable, replace this line with your Model Studio API key: apiKey:'sk-xxx',
// 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,
// The following is the base URL for the Beijing region. If you use a model in the Singapore region, replace baseURL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
baseURL: 'https://{WorkspaceId}.cn-beijing.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: "text-embedding-v4",
input: inputTexts
});
console.log(JSON.stringify(completion, null, 2));
} catch (error) {
console.error('Error:', error);
}
}
getEmbedding();
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "text-embedding-v4",
"input": "The quality of the clothes is excellent"
}'
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="text-embedding-v4",
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: "text-embedding-v4",
input: inputTexts,
dimensions: 1024 // Specify the vector dimension. This parameter is only supported by 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": "text-embedding-v4",
"input": "The quality of the clothes is excellent"
}'
DashScope
import dashscope
from http import HTTPStatus
# This is the URL for the China (Beijing) region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
input_text = "The quality of the clothes is excellent"
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=input_text,
)
if resp.status_code == HTTPStatus.OK:
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 {
// This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your workspace ID.
static {Constants.baseHttpApiUrl="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("text-embedding-v4")
// 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 =======
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the URL for the China (Beijing) region. URLs are region-specific.
# === Remove this comment before running ===
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "text-embedding-v4",
"input": {
"texts": [
"The quality of the clothes is excellent"
]
}
}'
import dashscope
from http import HTTPStatus
# If you use a model in the China (Beijing) region, replace base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
input_text = "The quality of the clothes is excellent"
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=input_text,
)
if resp.status_code == HTTPStatus.OK:
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("text-embedding-v4")
// 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": "text-embedding-v4",
"input": {
"texts": [
"The quality of the clothes is excellent"
]
}
}'
Vetores multimodais independentes
Gere vetores separados para diferentes tipos de conteúdo, como texto, imagens e vídeos. Essa abordagem é útil para processar cada tipo de conteúdo individualmente.
Para gerar vetores multimodais independentes, use o DashScope SDK ou chame a API diretamente. Este recurso não está disponível na API compatível com OpenAI nem no console.
Python
import dashscope
import json
import os
from http import HTTPStatus
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# The URL above is for the Singapore region. If you use a model in the Beijing region, replace base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
# The input can be a video.
# video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20250107/lbcemt/new+video.mp4"
# input = [{'video': video}]
# Or an image.
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
resp = dashscope.MultiModalEmbedding.call(
# If you have not set an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
# 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'),
model="tongyi-embedding-vision-plus",
input=input
)
print(json.dumps(resp.output, indent=4))
Java
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();
}
}
}
Vetores multimodais fusionados
Combine conteúdos de diferentes modalidades, como texto, imagens e vídeos, em um único vetor fusionado. Isso viabiliza aplicações como busca de texto para imagem, busca de imagem para imagem, busca de texto para vídeo e recuperação entre modalidades.
Para gerar vetores multimodais fusionados, use o Python DashScope SDK ou chame a API diretamente. Este recurso não está disponível na API compatível com OpenAI, no Java DashScope SDK nem no console.
qwen3-vl-embedding: Gera vetores fusionados e independentes. Para gerar um vetor fusionado, defina o parâmetro booleanoenable_fusioncomotrue.qwen2.5-vl-embedding: Suporta apenas embeddings fusionados, sem suporte a embeddings independentes.
Python
import dashscope
import json
import os
from http import HTTPStatus
# The following configuration is for the China (Beijing) region. When making the call, replace {WorkspaceId} with your actual workspace ID. Configurations are region-specific.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
# Multimodal fused vector: Combines text, images, and videos into a single fused vector.
# Suitable for use cases like cross-modal retrieval and image search.
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"
# The input contains text, an image, and a video. A fused vector is generated by setting the enable_fusion parameter.
input_data = [
{"text": text},
{"image": image},
{"video": video}
]
# Use qwen3-vl-embedding to generate a fused vector.
resp = dashscope.MultiModalEmbedding.call(
# If you have not set an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen3-vl-embedding",
input=input_data,
enable_fusion=True,
# Optional parameter: Specifies the vector dimension. Supported values: 2560, 2048, 1536, 1024, 768, 512, and 256. Default: 2560.
# dimension = 1024
)
print(json.dumps(resp.output, indent=4))
Java (HTTP)
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 conforme o tipo de dados de entrada e o caso de uso.
Processamento de texto simples ou código: Utilize
text-embedding-v4. Modelo de maior desempenho, 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 fusionado: Para representar entradas de modalidade única ou mista como um embedding fusionado em casos de uso como recuperação entre modalidades e busca de imagens, utilize
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-flashou o modelo multimodal de uso geralmultimodal-embedding-v1.
Processamento de dados em grande escala: Para processar grandes volumes de dados de texto não em tempo real, utilize
text-embedding-v4com a API de lote compatível com OpenAI e reduza significativamente os custos.
A tabela a seguir detalha as especificações de todos os modelos de embedding disponíveis.
Embedding de texto
Beijing
|
Modelo |
Dimensões do embedding |
Tamanho do lote |
Máx. de tokens por lote (nota) |
Preço (por 1.000 tokens de entrada) |
Cota gratuita (nota) |
Idiomas |
|
text-embedding-v4 Parte da série Qwen3-Embedding |
2.048, 1.536, 1.024 (padrão), 768, 512, 256, 128 ou 64 |
10 |
33.000 |
CNY 0,0005 chamada de API em lote: CNY 0,00025 |
1 milhão de tokens Válido por 90 dias após a ativação do Model Studio |
Mais de 100 idiomas, incluindo chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão e russo |
|
text-embedding-v3 |
1.024 (padrão), 768, 512, 256, 128 ou 64 |
8.192 |
CNY 0,0005 chamada de API em lote: CNY 0,00025 |
500.000 tokens cada Válido por 90 dias após a ativação do Model Studio |
Mais de 50 idiomas, incluindo chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão e russo |
|
|
text-embedding-v2 |
1.536 |
25 |
2.048 |
CNY 0,0007 chamada de API em lote: CNY 0,00035 |
Chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão e russo |
|
|
text-embedding-v1 |
Chinês, inglês, espanhol, francês, português e indonésio |
|||||
|
text-embedding-async-v2 |
100.000 |
CNY 0,0007 |
20 milhões de tokens Válido por 90 dias após a ativação do Model Studio |
Chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão e russo |
||
|
text-embedding-async-v1 |
Chinês, inglês, espanhol, francês, português e indonésio |
Singapore
|
Modelo |
Dimensões do embedding |
Tamanho do lote |
Máx. de tokens por lote (nota) |
Preço (por 1.000 tokens de entrada) |
Cota gratuita (nota) |
Idiomas |
|
text-embedding-v4 Parte da série Qwen3-Embedding |
2.048, 1.536, 1.024 (padrão), 768, 512, 256, 128 ou 64 |
10 |
8.192 |
USD 0,000514 |
sem cota gratuita |
Mais de 100 idiomas, incluindo chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão e russo |
|
text-embedding-v3 |
1.024 (padrão), 768, 512, 256, 128 ou 64 |
Mais de 50 idiomas, incluindo chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão e russo |
Beijing
|
Nome do modelo |
Dimensões do embedding |
Tamanho do lote |
Máx. de tokens por lote (Nota) |
Preço / 1M tokens |
Idioma |
|
text-embedding-v4 Parte da série Qwen3-Embedding |
2.048, 1.536, 1.024 (padrão), 768, 512, 256, 128, 64 |
10 |
8.192 |
$0,072 |
Mais 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 |
Hong Kong
|
Nome do modelo |
Dimensões do embedding |
Tamanho do lote |
Máx. de tokens por lote (Nota) |
Preço / 1M tokens |
Idioma |
|
text-embedding-v4 Parte da série Qwen3-Embedding |
2.048, 1.536, 1.024 (padrão), 768, 512, 256, 128, 64 |
10 |
8.192 |
$0,07 |
Mais 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 |
Singapore
|
Nome do modelo |
Dimensões do embedding |
Tamanho do lote |
Máx. de tokens por lote (Nota) |
Preço / 1M tokens |
Idioma |
Cota gratuita (Nota) |
|
text-embedding-v4 Parte da série Qwen3-Embedding |
2.048, 1.536, 1.024 (padrão), 768, 512, 256, 128, 64 |
10 |
8.192 |
$0,07 |
Mais 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 |
1 milhão de tokens Válido por 90 dias após a ativação do Model Studio |
|
text-embedding-v3 |
1.024 (padrão), 768, 512 |
Mais de 50 idiomas principais, incluindo chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão e russo |
500.000 tokens Válido por 90 dias após a ativação do Model Studio |
O tamanho do lote corresponde ao 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 solicitação, com limite de 8.192 tokens cada. 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.
Embedding multimodal
Este modelo gera embeddings a partir de entradas de texto, imagem ou vídeo. Utilize 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 aceitam múltiplas entradas do mesmo tipo, como várias imagens. Para detalhes, consulte as limitações de cada modelo.
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 1.000 tokens) |
Cota gratuita (Nota) |
|
qwen3-vl-embedding |
2560 (padrão), 2048, 1536, 1024, 768, 512, 256 |
32.000 tokens |
Até 10 MB por imagem |
Até 50 MB por arquivo de vídeo |
Imagem/Vídeo: CNY 0,0018 Texto: CNY 0,0007 |
1 milhão de tokens Esta cota gratuita expira 90 dias após a ativação do Model Studio. |
|
qwen2.5-vl-embedding |
2048, 1024 (padrão), 768, 512 |
Até 5 MB por imagem |
||||
|
tongyi-embedding-vision-plus-2026-03-06 |
1152 (padrão), 1024, 512, 256, 128, 64 |
1.024 tokens |
Recomendado: até 5 MB por imagem; máximo: 10 MB. Suporta até 64 imagens. |
Até 50 MB por arquivo de vídeo A codificação de vídeo deve ser H.264 ou H.265. |
CNY 0,0005 |
|
|
tongyi-embedding-vision-flash-2026-03-06 |
768 (padrão), 512, 256, 128, 64 |
CNY 0,00015 |
||||
|
tongyi-embedding-vision-plus |
1152 |
Até 3 MB por imagem. Suporta até 8 imagens. |
Até 10 MB por arquivo de vídeo |
CNY 0,0005 |
||
|
tongyi-embedding-vision-flash |
768 |
CNY 0,00015 |
||||
|
multimodal-embedding-v1 |
1.024 |
512 tokens |
Até 3 MB por imagem |
Até 10 MB por arquivo de vídeo |
Imagem/Vídeo: CNY 0,0009 Texto: CNY 0,0007 |
Singapore
|
Modelo |
Dimensões do embedding |
Limite de comprimento de texto |
Limite de tamanho de imagem |
Limite de tamanho de vídeo |
Preço (por 1.000 tokens) |
Singapore
|
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 (Nota) |
|
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 expira 90 dias após a ativação do Model Studio. |
|
tongyi-embedding-vision-flash |
768 |
Imagem/Vídeo: $0,03 Texto: $0,09 |
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) |
|
qwen3-vl-embedding |
2560 (padrão), 2048, 1536, 1024, 768, 512, 256 |
32.000 tokens |
Até 1 imagem com tamanho máximo de 5 MB |
Até 50 MB por arquivo de vídeo |
Imagem/Vídeo: $0,258 Texto: $0,1 |
|
multimodal-embedding-v1 |
1024 |
512 tokens |
Até 8 imagens, com tamanho máximo de 3 MB cada. |
Até 10 MB por arquivo de vídeo |
Teste gratuito |
Restrições de entrada e idioma
|
Modelo multimodal fusionado |
||||
|
Modelo |
Texto |
Imagem |
Vídeo |
Limite de solicitação |
|
qwen3-vl-embedding |
Suporta 33 idiomas principais, como chinês, inglês, japonês, coreano, francês e alemão. |
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 solicitação não pode exceder 20. O número de imagens não pode ultrapassar 5. Imagens, texto e vídeos compartilham esse limite. |
|
Modelo multimodal independente |
||||
|
Modelo |
Texto |
Imagem |
Vídeo |
Limite de solicitação |
|
tongyi-embedding-vision-plus |
Chinês/Inglês |
JPG, 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-v1 |
O total de elementos de conteúdo em uma única solicitação não pode exceder 20. Uma solicitaçã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 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 parcial de informações semânticas.
API compatível com OpenAI
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="text-embedding-v4",
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)}")
DashScope
import dashscope
# If you use a model in the China (Beijing) region, replace base_http_api_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
resp = dashscope.TextEmbedding.call(
model="text-embedding-v4",
input=["I like it and will buy from here again"],
# Set the vector dimension to 256
dimension=256
)
print(f"Vector dimension: {len(resp.output['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. Contudo, em tarefas como clustering ou classificação, nas quais todos os textos exercem 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 o modelo text-embedding-v4 a otimizar a qualidade do vetor para cenários específicos de recuperação, melhorando a precisão. Ao usar esse 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="text-embedding-v4",
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 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.
|
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. |
Custos maiores de computação e armazenamento. Não garante correspondência exata para palavras-chave. |
Busca semântica, P&R com IA, recomendação de conteúdo. |
|
sparse |
Alta eficiência computacional, focando em correspondência exata para palavras-chave e permitindo filtragem rápida. |
Falta compreensão semântica e não consegue processar 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 de chamada de API é idêntica ao modo de vetor único. |
Requer mais armazenamento, e a arquitetura do sistema e a lógica de recuperação são mais complexas. |
Mecanismo de busca híbrida de alta qualidade para produção. |
Casos de uso
O código a seguir serve apenas para fins de demonstração. Em produção, pré-calcule e armazene embeddings em um banco de dados vetorial. Assim, basta gerar o embedding da consulta para recuperação.
Busca semântica
Execute 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="text-embedding-v4",
input=query,
dimension=1024
)
query_embedding = query_resp.output['embeddings'][0]['embedding']
# Generate the document embeddings.
doc_resp = TextEmbedding.call(
model="text-embedding-v4",
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="text-embedding-v4",
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="text-embedding-v4",
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="text-embedding-v4",
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
Execute 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="text-embedding-v4",
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 fins de 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="text-embedding-v4",
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
-
Embedding de texto geral
-
Embedding multimodal
Códigos de erro
Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolução.
Limitação de taxa
Para as condições de limitação de taxa do modelo, consulte Limitação de taxa.
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 |