Skip to main content
Embedding de texto de uso geral

Synchronous API

O modelo de embedding de texto de uso geral converte dados textuais em vetores numéricos para tarefas subsequentes, como busca semântica, recomendação, clustering e classificação.

Visão geral do modelo

  • Singapore
  • China (Beijing)
  • China (Hong Kong)
ModeloDimensões do embeddingMáximo de linhasMáximo de tokens por linha(Note)Preço (por 1 milhão de tokens de entrada)Idiomas suportadosCota gratuita(Note)
qwen3.7-text-embedding2.560, 2.048, 1.536, 1.024 (padrão), 768, 512, 25620128.000$0,07Chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão, russo e mais de 200 outros idiomas e dialetos principais1 milhão de tokensValidade: 90 dias após a ativação do Model Studio
text-embedding-v4
Parte da série Qwen3-Embedding
2.048, 1.536, 1.024 (padrão), 768, 512, 256, 128, 64108.192$0,07Chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão, russo e mais de 100 outros idiomas principais1 milhão de tokensValidade: 90 dias após a ativação do Model Studio
text-embedding-v31.024 (padrão), 768, 512Chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão, russo e mais de 50 outros idiomas principais500.000 tokensValidade: 90 dias após a ativação do Model Studio
Para consultar os limites de taxa dos modelos, veja Rate limiting.

Pré-requisitos

Usuários familiarizados com o ecossistema OpenAI podem utilizar a API compatível com OpenAI para uma migração rápida. A API DashScope oferece recursos adicionais exclusivos. Obtain an API key e export the API key as an environment variable. Se você utilizar um SDK para fazer chamadas, install the DashScope SDK.

Compatibilidade com OpenAI

Nuvem pública

Obase_urla ser configurado para chamadas de SDK: Oendpointa ser configurado para chamadas HTTP:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings Substitua {WorkspaceId} pelo seu workspace ID real. Configure obase_urlpara chamadas de SDK:
  • Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1. Substitua WorkspaceId pelo seu workspace ID real.
  • China (Beijing): https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
  • China (Hong Kong): https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1. Substitua WorkspaceId pelo seu workspace ID real.
Configure oendpointpara chamadas HTTP:
  • Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings. Substitua WorkspaceId pelo seu workspace ID real.
  • China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings
  • China (Hong Kong): POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/embeddings. Substitua WorkspaceId pelo seu workspace ID real.
Substitua {WorkspaceId} pelo seu workspace ID real.

Request body

  • Input string
  • Input string list
  • Input file
  • Python
  • Java
  • curl
import os
from openai import OpenAI

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

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

print(completion.model_dump_json())
modelstringrequiredNome do modelo a ser chamado. Consulte a tabela Model overview para ver os nomes dos modelos.
inputarray<string> or string or filerequiredTexto de entrada a ser processado. A entrada pode ser uma string, um array de strings ou um arquivo. Os limites de tamanho do texto e do lote variam conforme a versão do modelo:
  • Modelo qwen3.7-text-embedding:
    • Entrada de string: Até 128.000 tokens.
    • Entrada de lista de strings ou arquivo: Até 20 itens (linhas), sendo cada item (linha) limitado a 128.000 tokens.
  • Modelos text-embedding-v3 / v4:
    • Entrada de string: Comprimento máximo de 8.192 tokens.
    • Entrada de lista de strings ou arquivo: Até 10 itens (linhas), sendo cada item (linha) limitado a 8.192 tokens.
dimensions integer optionalDimensão dos vetores de embedding de saída. Deve ser um dos seguintes valores: 2560 (apenas para qwen3.7-text-embedding),2048 (apenas para text-embedding-v4), 1536 (apenas para text-embedding-v4), 1024, 768, 512, 256, 128 ou 64. O valor padrão é 1024.
encoding_format string optionalFormato do embedding retornado. Atualmente, apenas float é suportado.

Response object

{
  "data": [
    {
      "embedding": [
        -0.0695386752486229, 0.030681096017360687, ...
      ],
      "index": 0,
      "object": "embedding"
    },
    ...
    {
      "embedding": [
        -0.06348952651023865, 0.060446035116910934, ...
      ],
      "index": 5,
      "object": "embedding"
    }
  ],
  "model": "qwen3.7-text-embedding",
  "object": "list",
  "usage": {
    "prompt_tokens": 184,
    "total_tokens": 184
  },
  "id": "73591b79-d194-9bca-8bb5-xxxxxxxxxxxx"
}
dataarrayLista dos objetos de embedding resultantes.

Property

embeddinglistVetor de embedding, retornado como um array de números de ponto flutuante.indexintegerÍndice do texto de entrada correspondente no array de entrada.objectstringTipo do objeto. O valor é sempre embedding.
modelstringNome do modelo utilizado nesta chamada.
objectstringTipo do objeto. O valor é sempre list.
usageobject

Property

prompt_tokensintegerNúmero de tokens no texto de entrada.total_tokens integerNúmero total de tokens na entrada. Essa contagem é determinada pela forma como o tokenizador do modelo analisa a string de entrada.
idstringIdentificador único da requisição, usado para rastreamento e solução de problemas.

DashScope

Public cloud

base_urlpara chamadas de SDK: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1 Endpoint para chamadas HTTP: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding Substitua {WorkspaceId} pelo seu workspace ID real. base_urlpara chamadas de SDK:
  • Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1. Substitua WorkspaceId pelo seu workspace ID real.
  • China (Beijing): https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
  • China (Hong Kong): https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1. Substitua WorkspaceId pelo seu workspace ID real.
Endpoint para chamadas HTTP:
  • Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding. Substitua WorkspaceId pelo seu workspace ID real.
  • China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
  • China (Hong Kong): POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding. Substitua WorkspaceId pelo seu workspace ID real.
Substitua {WorkspaceId} pelo seu workspace ID real.

Request body

  • Input string
  • Input string list
  • Input file
  • Python
  • Java
  • curl
import dashscope
from http import HTTPStatus

# This is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs differ by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

resp = dashscope.TextEmbedding.call(
    model="qwen3.7-text-embedding",
    input='A swift wind, a high sky, and the gibbons cry mournfully. A clear islet, white sand, and the birds fly back. Boundless rustling woods shed their leaves. The endless Yangtze River comes rolling in.',
    dimension=1024,
    output_type="dense&sparse"
)

print(resp) if resp.status_code == HTTPStatus.OK else print(resp)
modelstringrequiredO modelo a ser utilizado. Para obter uma lista dos modelos disponíveis, consulte a tabela Model overview.
inputstringouarray<string>requiredO texto a ser processado. A entrada pode ser uma string, um array de strings ou um arquivo. O comprimento de texto suportado e o tamanho do lote variam conforme a versão do modelo.
  • Modelo qwen3.7-text-embedding:
    • Entrada de string: Até 128.000 tokens.
    • Entrada de lista de strings ou arquivo: Até 20 itens (linhas), sendo cada item (linha) limitado a 128.000 tokens.
  • Modelos text-embedding-v3 / v4:
    • Entrada de string: Comprimento máximo de 8.192 tokens.
    • Entrada de lista de strings ou arquivo: Até 10 itens (linhas), sendo cada item (linha) limitado a 8.192 tokens.
text_type stringoptional
Ao fazer uma chamada HTTP, coloque text_typeno objeto parameters.
O texto convertido em embeddings pode ser aplicado em tarefas subsequentes, como recuperação, clustering e classificação. Para tarefas assimétricas, como recuperação, recomenda-se diferenciar entre texto de consulta (query) e texto de documento (document) para obter melhor desempenho. Em tarefas simétricas, como indexação, clustering e classificação, utilize o valor padrão do sistema: document.
dimension integer optional
Ao fazer uma chamada HTTP, coloque dimensionno objeto parameters.
Define a dimensão do embedding para o vetor de saída. Os valores válidos são 2560 (apenas para qwen3.7-text-embedding),2048 (apenas para text-embedding-v4), 1536 (apenas para text-embedding-v4), 1024, 768, 512, 256, 128 ou 64. O valor padrão é 1024.
output_type string optional
Ao fazer uma chamada HTTP, coloque output_typeno objeto parameters.
Especifica o tipo de vetor de saída. Este parâmetro aplica-se apenas aos modelos qwen3.7-text-embedding,``text-embedding-v3 e text-embedding-v4. Os valores válidos são dense, sparse e dense&sparse. O padrão é dense, que retorna apenas a representação vetorial densa.
instruct string optionalFornece instruções personalizadas para orientar o modelo na compreensão da intenção da consulta. Recomenda-se o uso de instruções em inglês, pois geralmente melhoram o desempenho em 1% a 5%.

Response object

{   "status_code": 200,
    "request_id": "1ba94ac8-e058-99bc-9cc1-7fdb37940a46",
    "code": "",
    "message": "",
    "output":{
        "embeddings": [
          {
             "sparse_embedding":[
               {"index":7149,"value":0.829,"token":"swift"},
               .....
               {"index":111290,"value":0.9004,"token":"mournfully"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 0
          },
          {
             "sparse_embedding":[
               {"index":246351,"value":1.0483,"token":"islet"},
               .....
               {"index":2490,"value":0.8579,"token":"back"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 1
          },
          {
             "sparse_embedding":[
               {"index":3759,"value":0.7065,"token":"Boundless"},
               .....
               {"index":1130,"value":0.815,"token":"leaves"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 2
          },
          {
             "sparse_embedding":[
               {"index":562,"value":0.6752,"token":"endless"},
               .....
               {"index":1589,"value":0.7097,"token":"in"}],
             "embedding": [-0.001945948973298072,-0.005336422007530928, ...],
             "text_index": 3
          }
        ]
    },
    "usage":{
        "total_tokens":27
    }
}
status_code stringO código de status HTTP. O valor 200 indica sucesso.
request_id stringUm identificador exclusivo para a requisição. Utilize este ID para rastrear e solucionar problemas da requisição.
code stringO código de erro retornado caso a requisição falhe. Este campo fica vazio em requisições bem-sucedidas.
message stringUma mensagem de erro detalhada caso a requisição falhe. Este campo fica vazio em requisições bem-sucedidas.
outputobjectO resultado da tarefa.

Properties

embeddingsarrayA saída do modelo para a requisição. Trata-se de um array de objetos, onde cada objeto corresponde a um texto de entrada.
sparse_embedding arrayA representação vetorial esparsa da string correspondente. Aplica-se apenas a text-embedding-v3 e text-embedding-v4.
index integerO índice do token no vocabulário.value floatIndica o peso ou pontuação de importância do Token. Quanto maior o valor, maior a importância ou relevância do Token no contexto atual do texto.token stringO texto do token.
embedding arrayA representação vetorial densa para a string correspondente.text_index integerO índice do texto correspondente no array de entrada.
usageobject

Properties

total_tokens integerA quantidade de tokens na entrada, calculada pelo tokenizador do modelo.

Códigos de erro

Se a chamada do modelo falhar, consulte Error Messages.
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
API em tempo real
Incorporação de Texto
Produção de Modelos