前言
通用文本向量,是通義實驗室基于LLM底座的多語言文本統一向量模型,面向全球多個主流語種,提供高水準的向量服務,幫助開發者將文本數據快速轉換為高質量的向量數據。
模型概覽
模型中文名 | 模型英文名 | 數據類型 | 向量維度 | 最大輸入字符長度 | 支持語種 |
通用文本向量 | text-embedding-v1 | float(32) | 1536 | 2048 | 中文、英語、西班牙語、法語、葡萄牙語、印尼語。 |
text-embedding-v2 | 中文、英語、西班牙語、法語、葡萄牙語、印尼語、日語、韓語、德語、俄羅斯語。 |
SDK使用
前提條件
已開通服務并獲得API-KEY:API-KEY的獲取與配置。
已安裝最新版SDK:安裝DashScope SDK。
調用示例
SDK支持三種輸入,分別是字符串、字符串列表和文件。
需要使用您的API-KEY替換示例中的YOUR_DASHSCOPE_API_KEY,代碼才能正常運行。
設置API-KEY
export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY
輸入字符串
import dashscope
from http import HTTPStatus
def embed_with_str():
resp = dashscope.TextEmbedding.call(
model=dashscope.TextEmbedding.Models.text_embedding_v1,
input='衣服的質量杠杠的,很漂亮,不枉我等了這么久啊,喜歡,以后還來這里買')
if resp.status_code == HTTPStatus.OK:
print(resp)
else:
print(resp)
if __name__ == '__main__':
embed_with_str()
import java.util.Arrays;
import java.util.concurrent.Semaphore;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.embeddings.TextEmbedding;
import com.alibaba.dashscope.embeddings.TextEmbeddingParam;
import com.alibaba.dashscope.embeddings.TextEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
public final class Main {
public static void basicCall() throws ApiException, NoApiKeyException{
TextEmbeddingParam param = TextEmbeddingParam
.builder()
.model(TextEmbedding.Models.TEXT_EMBEDDING_V1)
.texts(Arrays.asList("風急天高猿嘯哀", "渚清沙白鳥飛回", "無邊落木蕭蕭下", "不盡長江滾滾來")).build();
TextEmbedding textEmbedding = new TextEmbedding();
TextEmbeddingResult result = textEmbedding.call(param);
System.out.println(result);
}
public static void callWithCallback() throws ApiException, NoApiKeyException, InterruptedException{
TextEmbeddingParam param = TextEmbeddingParam
.builder()
.model(TextEmbedding.Models.TEXT_EMBEDDING_V1)
.texts(Arrays.asList("風急天高猿嘯哀", "渚清沙白鳥飛回", "無邊落木蕭蕭下", "不盡長江滾滾來")).build();
TextEmbedding textEmbedding = new TextEmbedding();
Semaphore sem = new Semaphore(0);
textEmbedding.call(param, new ResultCallback<TextEmbeddingResult>() {
@Override
public void onEvent(TextEmbeddingResult message) {
System.out.println(message);
}
@Override
public void onComplete(){
sem.release();
}
@Override
public void onError(Exception err){
System.out.println(err.getMessage());
err.printStackTrace();
sem.release();
}
});
sem.acquire();
}
public static void main(String[] args){
try{
callWithCallback();
}catch(ApiException|NoApiKeyException|InterruptedException e){
e.printStackTrace();
System.out.println(e);
}
try {
basicCall();
} catch (ApiException | NoApiKeyException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
輸入字符串列表
from typing import Generator, List
import dashscope
from http import HTTPStatus
# 最多支持25條,每條最長支持2048tokens
DASHSCOPE_MAX_BATCH_SIZE = 25
def batched(inputs: List,
batch_size: int = DASHSCOPE_MAX_BATCH_SIZE) -> Generator[List, None, None]:
for i in range(0, len(inputs), batch_size):
yield inputs[i:i + batch_size]
def embed_with_list_of_str(inputs: List):
result = None # merge the results.
batch_counter = 0
for batch in batched(inputs):
resp = dashscope.TextEmbedding.call(
model=dashscope.TextEmbedding.Models.text_embedding_v1,
input=batch)
if resp.status_code == HTTPStatus.OK:
if result is None:
result = resp
else:
for emb in resp.output['embeddings']:
emb['text_index'] += batch_counter
result.output['embeddings'].append(emb)
result.usage['total_tokens'] += resp.usage['total_tokens']
else:
print(resp)
batch_counter += len(batch)
print(result)
if __name__ == '__main__':
inputs = ['風急天高猿嘯哀', '渚清沙白鳥飛回', '無邊落木蕭蕭下', '不盡長江滾滾來']
embed_with_list_of_str(inputs)
輸入文件
示例文件如下(文件名稱:texts_to_embedding.txt,其中每一行對應一個embedding)。
很不錯的一款產品,送人的額,非常喜歡,很不錯,好評哦,以后還會多多支持的 已經吃了,感覺不錯。第二次購買,這個價格很實惠,賣家還贈送了美容器和尺子,很愉悅的一次購物。 衣服的質量杠杠的,很漂亮,不枉我等了這么久啊,喜歡,以后還來這里買,我一次買了四件不到200塊錢,真好 用了一段時間了,感覺比傳統的風扇好用,廣度大,檔數多,靜音效果也不錯,關鍵是還很漂亮! 這個熱量低,比意面還低,關鍵是口感還好,挺好吃,多煮一會一級棒,我的減脂早餐就靠它了 整體評價:好 使用效果:好 包裝與外觀:好 三好商品 電視機很好,我給老爸買的,老人很喜歡,圖像清晰,音質很好,老人喜歡我滿意。 寶貝很輕巧,打的時候網彈力很足,兒子非常喜歡,五分好評,還送了羽毛球噢! 終于裝上,風很大,熱的還可以,排風聲音不小,安裝的師傅說不能直吹,安裝的時候非常滿意,最后還幫忙把棚頂給擦干凈了,非常感謝。 顏色很美。就是別人的盒子都是平整的,唯獨我的盒子有很嚴重的壓痕。本來想直接用這個盒子裝膠帶的..現在這個樣子強迫癥看著實在很糟心。壓成這樣要么包裝有問題,要么本來產品就有問題。而賣家一直在甩鍋快遞。由于包裹是被家里人拆開的,所以我也不知道是什么樣子的,不好跟賣家掰扯。但我看別的人都是紙盒裝的,想來我這個也是紙盒裝的。那么排除包裝的原因的話,很可能就是寄過來的就是個瑕疵品。比起同樣今天到貨的另一家,有個小瑕疵立馬給我補寄了一個,這家的處理方式真的..換貨..或者直接道歉說疏忽我都接受的。甩鍋真的不能忍。本來還給好幾個人推了這家店...就挺失望的 以后應該不會來了。這堅定的甩鍋態度我也不點退換了..請不要給我打電話改評,謝謝。
代碼如下:
from http import HTTPStatus from dashscope import TextEmbedding def embed_with_file_content(): # 文件中最多支持25條,每條最長支持2048tokens with open('texts_to_embedding.txt', 'r', encoding='utf-8') as f: resp = TextEmbedding.call( model=TextEmbedding.Models.text_embedding_v1, input=f) if resp.status_code == HTTPStatus.OK: print(resp) else: print(resp) if __name__ == '__main__': embed_with_file_content()
輸出示例
{
"status_code": 200, // 200 indicate success otherwise failed.
"request_id": "fd564688-43f7-9595-b986-737c38874a40", // The request id.
"code": "", // If failed, the error code.
"message": "", // If failed, the error message.
"output": {
"embeddings": [ // embeddings
{
"embedding": [ // one embedding output
-3.8450357913970947, ...,
3.2640624046325684
],
"text_index": 0 // the input index.
}
]
},
"usage": {
"total_tokens": 3 // the request tokens.
}
}
參數詳解
請求參數
參數名稱
必選
示例值
描述
model
是
text-embedding-v2
取值:調用的模型名稱,可以選擇text-embedding-v1或者text-embedding-v2。
說明:代表模型的英文名稱
input
是
衣服的質量杠杠的,很漂亮,不枉我等了這么久啊,喜歡,以后還來這里買
取值:input可以是字符串,字符串列表,或者打開的文件(需要embedding的內容,1行一條)。
說明:
input是字符串時最長支持2048tokens
input是字符串列表時最多支持25條,每條最長支持2048tokens
input是文件時最多支持25條,每條最長支持2048tokens
text_type
否
query
取值:query或者document,默認值為document
說明:文本轉換為向量后可以應用于檢索、聚類、分類等下游任務,對檢索這類非對稱任務為了達到更好的檢索效果建議區分查詢文本(query)和底庫文本(document)類型,聚類、分類等對稱任務可以不用特殊指定,采用系統默認值"document"即可。
響應參數
字段
類型
描述
示例值
output.embeddings
Array
本次請求的算法輸出內容是一個由結構組成的數組,每一個數組中包含一個對應的輸入text的算法輸出內容。
{ "embeddings": [ { "text_index": 0, "embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ] }, { "text_index": 1, "embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ] }, { "text_index": 2, "embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ] }, { "text_index": 3, "embedding": [ -0.006929283495992422, -0.005336422007530928, ... 省略 ] } ] }
output.embeddings.text_index
Integer
本結構中的算法結果對應的輸入文字在輸入數組中的索引值。
0,1,2,3...
output.embeddings.embedding
Array
對應字符串的算法輸出Embedding,Java SDK統一轉換為Double,參考模型輸出類型,進行比較的數據轉換。
[ -0.006929283495992422, -0.005336422007530928, ... 省略 ]
usage.input_tokens
Integer
本次請求輸入內容的token數目,算法的計量是根據用戶輸入字符串被模型tokenizer解析之后對應的token數目來進行。
12
request_id
String
本次請求的系統唯一碼。
7574ee8f-38a3-4b1e-9280-11c33ab46e51
Java SDK輸出字段考慮兼容性為double類型,可以按照模型輸出類型轉換為對應精度數據。
HTTP調用
本模型還可通過HTTP的方式進行調用,以適用更靈活的業務開發,下方示例提供了CURL命令,其中用POST方式請求了接口:https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
參數詳解
請求參數
字段
類型
傳參方式
必選
示例值
描述
Content-Type
String
Header
是
application/json
取值:固定值,無需更改。
說明:請求類型。
Authorization
String
Header
是
Bearer d1**2a
取值:需要填入您的API-KEY。
說明:API-KEY的獲取方式參考上方文檔中的調用前準備。
model
String
Body
是
text-embedding-v2
取值:調用模型名稱,text-embedding-v1或者text-embedding-v2。
說明:指明需要調用的模型。
input.texts
Array
Body
是
["風急天高猿嘯哀",
"渚清沙白鳥飛回",
"無邊落木蕭蕭下",
"不盡長江滾滾來"]
取值:文本內容,需要計算的輸入字符串,支持中英文。
說明:支持多條文本輸入,每次請求最多25條;每一條最長支持 2048 tokens。
parameters.text_type
String
Body
否
"text_type": "query"
取值:query或document,默認值為document。
說明:文本轉換為向量后可以應用于檢索、聚類、分類等下游任務,對于檢索這類非對稱任務,為了達到更好的檢索效果,建議區分查詢文本(query)和底庫文本(document)類型,聚類、分類等對稱任務可以不用特殊指定,采用系統默認值"document"即可。
響應參數
字段
類型
描述
示例值
output.embeddings
Array
本次請求的算法輸出內容是一個由結構組成的數組,每一個數組中包含一個對應的輸入text的算法輸出內容。
{ "embeddings": [ { "text_index": 0, "embedding": [ -0.006929283495992422, -0.005336422007530928, ...省略 ] }, { "text_index": 1, "embedding": [ -0.006929283495992422, -0.005336422007530928, ...省略 ] }, { "text_index": 2, "embedding": [ -0.006929283495992422, -0.005336422007530928, ...省略 ] }, { "text_index": 3, "embedding": [ -0.006929283495992422, -0.005336422007530928, ...省略 ] } ] }
output.embeddings.text_index
Integer
本結構中的算法結果對應的輸入文字在輸入數組中的索引值。
0,1,2,3...
output.embeddings.embedding
Array
對應字符串的算法輸出embedding。
[ -0.006929283495992422, -0.005336422007530928, ... 省略 ]
usage.total_tokens
Integer
本次請求輸入內容的token數目,算法的計量是根據用戶輸入字符串被模型tokenizer解析之后對應的token數目來進行。
12
request_id
String
本次請求的系統唯一碼。
7574ee8f-38a3-4b1e-9280-11c33ab46e51
Curl示例
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header 'Authorization: Bearer <your-dashscope-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"model": "text-embedding-v1",
"input": {
"texts": [
"風急天高猿嘯哀",
"渚清沙白鳥飛回",
"無邊落木蕭蕭下",
"不盡長江滾滾來"
]
},
"parameters": {
"text_type": "query"
}
}'
響應示例
調用成功示例
{ "output":{ "embeddings": [ { "text_index": 0, "embedding": [-0.006929283495992422,-0.005336422007530928, ...] }, { "text_index": 1, "embedding": [-0.006929283495992422,-0.005336422007530928, ...] }, { "text_index": 2, "embedding": [-0.006929283495992422,-0.005336422007530928, ...] }, { "text_index": 3, "embedding": [-0.006929283495992422,-0.005336422007530928, ...] } ] }, "usage":{ "total_tokens":12 }, "request_id":"d89c06fb-46a1-47b6-acb9-bfb17f814969" }
調用異常示例
{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1" }
說明在訪問請求出錯的情況下,輸出的結果中會通過code和message指明出錯原因。
狀態碼說明
DashScope通用狀態碼請查閱:返回狀態碼說明