Skip to main content
通用文本向量

同步介面API詳情

通用文本向量模型可將文本資料轉換為數值向量,用於語義搜尋、推薦、聚類、分類等下遊任務。

模型概覽

  • 新加坡
  • 北京
  • 中國香港
模型名稱向量維度最大行數單行最大處理Token數(單價(每百萬輸入Token)支援語種免費額度(注)
qwen3.7-text-embedding2560、2,048、1,536、1,024(預設)、768、512、25620128,000$0.07中文、英語、西班牙語、法語、葡萄牙語、印尼語、日語、韓語、德語、俄羅斯語等201種主流語種與方言100萬Token有效期間:百鍊開通後90天內
text-embedding-v4
屬於Qwen3-Embedding系列
2,048、1,536、1,024(預設)、768、512、256、128、64108,192$0.07中文、英語、西班牙語、法語、葡萄牙語、印尼語、日語、韓語、德語、俄羅斯語等100+主流語種100萬Token有效期間:百鍊開通後90天內
text-embedding-v31,024(預設)、768、512中文、英語、西班牙語、法語、葡萄牙語、印尼語、日語、韓語、德語、俄羅斯語等50+主流語種50萬Token有效期間:百鍊開通後90天內
關於模型限流,請參考限流

前提條件

若熟悉OpenAI生態,可使用相容API快速遷移;DashScope API則提供更豐富的專屬特性。請根據您的需求選擇。 您需要已擷取與配置 API Key配置API Key到環境變數。如果通過SDK調用,還需要安裝DashScope SDK。請將範例程式碼中的 DASHSCOPE_API_HOST 替換為擷取的 API Host。

OpenAI相容

使用SDK調用時需配置的base_url:
  • 新加坡:https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
  • 華北2(北京):https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
  • 中國香港:https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
使用HTTP方式調用時需配置的endpoint:
  • 新加坡:POSThttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings
  • 華北2(北京):POSThttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings
  • 中國香港:POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/embeddings
調用時請將{WorkspaceId}替換為真實的業務空間ID

請求體

modelstring必選調用的模型名稱,參考模型概覽表格中的模型名稱進行選擇。inputarray<string> 或 string 或 file必選輸入待處理的文本。可以是字串(string)、字串列表(array)或檔案(file)。不同模型版本支援的文本長度和批量大小不同,具體如下:
  • qwen3.7-text-embedding 模型:
    • 輸入為字串:最長支援 128,000 Token。
    • 輸入為字串列表或檔案:最多支援 20 條(行),每條(行)最長支援 128,000 Token。
  • text-embedding-v3 / v4 模型:
    • 輸入為字串:最長支援 8,192 Token。
    • 輸入為字串列表或檔案:最多支援 10 條(行),每條(行)最長支援 8,192 Token。
dimensions integer 可選指定的向量維度,必須為以下值之一:2560(僅適用於qwen3.7-text-embedding)、2048(僅適用於text-embedding-v4)、1536(僅適用於text-embedding-v4)1024、768、512、256、128 或 64,預設值為1024。encoding_format string 可選用於控制返回的Embedding格式,當前僅支援float格式。
  • 輸入字串
  • 輸入字串列表
  • 輸入檔案
  • Python
  • Java
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # 如果使用華北2(北京)地區的模型,需要使用華北2(北京)地區的 API KEY,擷取連結:https://bailian.console.alibabacloud.com/?tab=model#/api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您沒有配置環境變數,請在此處用您的API Key進行替換
    # 以下為新加坡地區URL,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的URL不同。
    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())

響應對象

dataarray任務輸出資訊。

屬性

embeddinglist本次調用返回object對象的value,類型是元素為float資料的數組,包含具體Embedding向量。indexinteger本結構中的演算法結果對應的輸入文字在輸入數組中的索引值。objectstring本次調用返回的object物件類型,預設為embedding。
modelstring本次調用的模型名。objectstring本次調用返回的data類型,預設為list。usageobject

屬性

prompt_tokensinteger使用者輸入文本轉換成Token後的長度。total_tokens integer本次請求輸入內容的 Token 數目,演算法的計量是根據使用者輸入字串被模型Tokenizer解析之後對應的Token數目來進行。
idstring請求唯一標識。可用於請求明細溯源和問題排查。
{
  "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"
}

DashScope

使用SDK調用時需配置的base_url:
  • 新加坡:https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
  • 華北2(北京):https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
  • 中國香港:https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1
使用HTTP方式調用時需配置的endpoint:
  • 新加坡:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
  • 華北2(北京):POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
  • 中國香港:POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
調用時請將{WorkspaceId}替換為真實的業務空間ID

請求體

modelstring必選調用的模型,參考模型概覽表格中的模型名稱進行選擇。inputstringarray<string>必選輸入待處理的文本。可以是字串(string)、字串列表(array)或檔案(file)。不同模型版本支援的文本長度和批量大小不同,具體如下:
  • qwen3.7-text-embedding 模型:
    • 輸入為字串:最長支援 128,000 Token。
    • 輸入為字串列表或檔案:最多支援 20 條(行),每條(行)最長支援 128,000 Token。
  • text-embedding-v3 / v4 模型:
    • 輸入為字串:最長支援 8,192 Token。
    • 輸入為字串列表或檔案:最多支援 10 條(行),每條(行)最長支援 8,192 Token。
text_type string可選
通過 HTTP 調用時,請將 text_type放入parameters對象中。
文本轉換為向量後可以應用於檢索、聚類、分類等下遊任務,對檢索這類非對稱任務為了達到更好的檢索效果建議區分查詢文本(query)和底庫文本(document)類型,入庫、聚類、分類等對稱任務可以不用特殊指定,採用系統預設值document即可。dimension integer 可選
通過 HTTP 調用時,請將 dimension放入parameters對象中。
指定的向量維度,必須為以下值之一:2560(僅適用於qwen3.7-text-embedding)、2048(僅適用於text-embedding-v4)、1536(僅適用於text-embedding-v4)1024、768、512、256、128 或 64,預設值為1024。output_type string 可選
通過 HTTP 調用時,請將 output_type放入parameters對象中。
使用者指定輸出離散向量表示只適用於qwen3.7-text-embedding、``text-embedding-v3text-embedding-v4模型,取值在dense、sparse、dense&sparse之間,預設取dense,只輸出連續向量。instruct string 可選添加自訂任務說明,可用於指導模型理解查詢意圖。建議使用英文撰寫,通常可帶來約 1%–5% 的效果提升。
  • 輸入字串
  • 輸入字串列表
  • 輸入檔案
  • Python
  • Java
  • curl
import dashscope
from http import HTTPStatus

# 以下為新加坡地區URL,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的URL不同。
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='風急天高猿嘯哀, 渚清沙白鳥飛回, 無邊落木蕭蕭下, 不盡長江滾滾來',
    dimension=1024,
    output_type="dense&sparse"
)

print(resp) if resp.status_code == HTTPStatus.OK else print(resp)

響應對象

status_code string狀態代碼,表示請求的執行結果(如 200 表示成功)。request_id string請求唯一標識。可用於請求明細溯源和問題排查。code string請求失敗,表示錯誤碼,成功時返回參數中該參數為空白。message string請求失敗,表示失敗詳細資料,成功時返回參數中該參數為空白。outputobject任務輸出資訊。

屬性

embeddingsarray本次請求的演算法輸出內容,是一個由結構組成的數組,每一個數組中包含一個對應的輸入 text 的演算法輸出內容。
sparse_embedding array對應字串的演算法輸出離散向量表示 (sparse embedding僅適用於text-embedding-v3text-embedding-v4)。
index integer詞彙或字元在詞彙表中的位置索引。value float表示該 Token 的權重或重要性分數,值越高,表示該 Token 在當前文本上下文中的重要性或相關性越大。token string實際的文本單元或詞彙表中的詞。
embedding array對應字串的演算法輸出連續向量表示 (dense embedding)。text_index integer本結構中的演算法結果對應的輸入文字在輸入數組中的索引值。
usageobject

屬性

total_tokens integer本次請求輸入內容的 token 數目,演算法的計量是根據使用者輸入字串被模型tokenizer解析之後對應的token 數目來進行。
{   "status_code": 200,
    "request_id": "1ba94ac8-e058-99bc-9cc1-7fdb37940a46",
    "code": "",
    "message": "",
    "output":{
        "embeddings": [
          {
             "sparse_embedding":[
               {"index":7149,"value":0.829,"token":"風"},
               .....
               {"index":111290,"value":0.9004,"token":"哀"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 0
          },
          {
             "sparse_embedding":[
               {"index":246351,"value":1.0483,"token":"渚"},
               .....
               {"index":2490,"value":0.8579,"token":"回"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 1
          },
          {
             "sparse_embedding":[
               {"index":3759,"value":0.7065,"token":"無"},
               .....
               {"index":1130,"value":0.815,"token":"下"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 2
          },
          {
             "sparse_embedding":[
               {"index":562,"value":0.6752,"token":"不"},
               .....
               {"index":1589,"value":0.7097,"token":"來"}],
             "embedding": [-0.001945948973298072,-0.005336422007530928, ...],
             "text_index": 3
          }
        ]
    },
    "usage":{
        "total_tokens":27
    }
}

錯誤碼

如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。