豆包向量化API – 字節(jié)跳動(dòng)推出的語義向量化模型

豆包向量化API是字節(jié)跳動(dòng)推出的一款先進(jìn)的語義向量化模型，命名為Doubao-embedding。該API專為向量檢索場(chǎng)景而設(shè)計(jì)，支持中英文雙語處理，并能夠處理最長(zhǎng)達(dá)4096個(gè)字符的上下文。

豆包向量化API是什么

豆包向量化API是字節(jié)跳動(dòng)研發(fā)的高性能語義向量化模型，名為Doubao-embedding，主要應(yīng)用于向量檢索領(lǐng)域。該API提供兩個(gè)版本：text-240715，具有最高2560維的向量輸出，支持512、1024和2048維的降維使用；text-240515，最高2048維，支持512和1024維降維。相較于text-240515版本，text-240715在中英文檢索效果上有顯著提升，因而推薦用戶優(yōu)先使用該版本。API的主機(jī)地址為maas-api.ml-platform-cn-beijing.volces.com，所在區(qū)域?yàn)?code>cn-beijing。

在使用Doubao-embedding API之前，用戶需通過設(shè)置環(huán)境變量或在代碼中配置VOLC_ACCESSKEY和VOLC_SECRETKEY。字節(jié)跳動(dòng)為開發(fā)者提供了統(tǒng)一的SDK接入方式，支持Golang、Python和Java等多種編程語言。

豆包向量化API的主要功能

• 語義向量化：將輸入的文本轉(zhuǎn)化為語義向量，準(zhǔn)確表達(dá)文本的內(nèi)涵。
• 多語言支持：兼容中文和英文文本的向量處理。
• 長(zhǎng)文本處理能力：可處理最多4096個(gè)字符的上下文，適合長(zhǎng)文本的向量化需求。
• 高維向量輸出：提供2048維向量輸出，并支持512維和1024維的降維選項(xiàng)，以適應(yīng)不同的應(yīng)用需求。
• 優(yōu)化向量檢索：生成的向量非常適合于文檔相似度比較和信息檢索等任務(wù)。
• 便捷集成：提供多種編程語言的SDK，方便開發(fā)者在不同環(huán)境中快速集成使用。
• 靈活的輸入輸出：API輸入為文本列表，輸出為對(duì)應(yīng)文本的向量化結(jié)果列表，便于后續(xù)處理。
• 檢索效果提升：在進(jìn)行檢索時(shí)，建議在查詢文本前添加指令前綴，以提高效果和準(zhǔn)確性。
• 廣泛適用：適用于搜索引擎、推薦系統(tǒng)、知識(shí)圖譜、自然語言處理等多種應(yīng)用場(chǎng)景。

豆包向量化API的項(xiàng)目地址

• API調(diào)用指南地址：https://www.volcengine.com/docs/82379/1263524

如何獲取豆包向量化API的API key鑒權(quán)

API Key是用于調(diào)用API的鑒權(quán)密鑰，確保身份驗(yàn)證。在開發(fā)過程中，需要在HTTP請(qǐng)求的Header中添加Authorization字段，并將VOLC_ACCESSKEY替換為實(shí)際API Key。

• 注冊(cè)賬號(hào)：訪問火山引擎官網(wǎng)進(jìn)行賬號(hào)注冊(cè)。
• 登錄控制臺(tái)：使用注冊(cè)的賬號(hào)登錄火山引擎控制臺(tái)。
• 創(chuàng)建API Key：在控制臺(tái)中找到API訪問秘鑰部分，點(diǎn)擊創(chuàng)建API Key，并為其設(shè)置一個(gè)易于識(shí)別的名稱。創(chuàng)建后，系統(tǒng)將提供一串字符作為API Key，務(wù)必妥善保管，防止泄露。

豆包向量化API的SDK接入方式

• Golang SDK接入方式
  • 安裝SDK：通過go get命令安裝Golang SDK。

    go get -u github.com/volcengine/volc-sdk-golang

  • 設(shè)置API Key：在代碼中配置VOLC_ACCESSKEY和VOLC_SECRETKEY。

    package main
    
    import (
        "encoding/json"
        "errors"
        "fmt"
        "os"
        api "github.com/volcengine/volc-sdk-golang/service/maas/models/api/v2"
        client "github.com/volcengine/volc-sdk-golang/service/maas/v2"
    )
    
    func main() {
        r := client.NewInstance("maas-api.ml-platform-cn-beijing.volces.com","cn-beijing")
        r.SetAccessKey(os.Getenv("VOLC_ACCESSKEY"))
        r.SetSecretKey(os.Getenv("VOLC_SECRETKEY"))
        req := &api.EmbeddingsReq{
            Input: []string{
                "天很藍(lán)","海很深",},}
        endpointId := "{YOUR_ENDPOINT_ID}"
        TestEmbeddings(r,endpointId,req)
    }
    
    func TestEmbeddings(r *client.MaaS,endpointId string,req *api.EmbeddingsReq) {
        if got,status,err := r.Embeddings(endpointId,req); err != nil {
            errVal := &api.Error{}
            if errors.As(err,&errVal) {
                fmt.Printf("meet maas error=%v,status=%d\n",errVal,status)
            }
            return
        } else {
            answer,_ := json.Marshal(got)
            fmt.Println("embeddings answer",string(answer))
        }
    }

• Java SDK接入方式
  • 添加依賴：在pom.xml文件中添加Java SDK的依賴。

    <dependency>
        <groupId>com.volcengine</groupId>
        <artifactId>volc-sdk-java</artifactId>
        <version>LATEST</version>
    </dependency>

  • 設(shè)置API Key：在代碼中設(shè)置VOLC_ACCESSKEY和VOLC_SECRETKEY。

    package com.volcengine.example.maas.v2;
    
    import com.volcengine.model.maas.api.v2.*;
    import com.volcengine.service.maas.MaasException;
    import com.volcengine.service.maas.v2.MaasService;
    import com.volcengine.service.maas.v2.impl.MaasServiceImpl;
    import java.util.ArrayList;
    import java.util.Arrays;
    
    public class EmbeddingsV2Demo {
        public static void main(String[] args) {
            MaasService maasService = new MaasServiceImpl("maas-api.ml-platform-cn-beijing.volces.com","cn-beijing");
            maasService.setAccessKey(System.getenv("VOLC_ACCESSKEY"));
            maasService.setSecretKey(System.getenv("VOLC_SECRETKEY"));
            EmbeddingsReq tReq = new EmbeddingsReq()
                .withInput(new ArrayList(Arrays.asList(
                    "天很藍(lán)","海很深"
                )));
            String endpointId = "${YOUR_ENDPOINT_ID}";
            testEmbeddings(maasService,endpointId,tReq);
        }
    
        private static void testEmbeddings(MaasService maasService,String endpointId,EmbeddingsReq req) {
            try {
                EmbeddingsResp resp = maasService.embeddings(endpointId,req);
                System.out.println(resp.getObject());
                System.out.println(resp.getData());
            } catch (MaasException e) {
                System.out.println("req_id: " + e.getRequestId());
                System.out.println("code: " + e.getCode());
                System.out.println("code_n: " + e.getCodeN());
                System.out.println("message: " + e.getMsg());
                e.printStackTrace();
            }
        }
    }

• Python SDK接入方式
  • 安裝SDK：通過pip安裝火山引擎的Python SDK。

    pip install volcengine-python-sdk

  • 配置環(huán)境變量：在.env文件或系統(tǒng)環(huán)境變量中設(shè)置VOLC_ACCESSKEY和VOLC_SECRETKEY。

    VOLC_ACCESSKEY=您的AccessKey
    VOLC_SECRETKEY=您的SecretKey
    ENDPOINT_ID=您的EndpointId

  • 編寫代碼：使用SDK進(jìn)行API調(diào)用的示例代碼：

    import os
    from volcengine.maas.v2 import MaasService
    from volcengine.maas import MaasException,ChatRole
    
    def test_embeddings(maas,endpoint_id,req):
        try:
            resp = maas.embeddings(endpoint_id,req)
            print(resp)
            return resp
        except MaasException as e:
            print(e)
    
    if __name__ == '__main__':
        maas = MaasService('maas-api.ml-platform-cn-beijing.volces.com','cn-beijing')
        maas.set_ak(os.getenv("VOLC_ACCESSKEY"))
        maas.set_sk(os.getenv("VOLC_SECRETKEY"))
    
        query_instruction = '為這個(gè)句子生成表示以用于檢索相關(guān)文章：'
        query = "天是什么顏色？"
        document = "天空呈現(xiàn)顏色主要與“瑞利散射”現(xiàn)象有關(guān)..."
    
        req = {
            "input": [
                query_instruction + query,document,]
        }
        resp = test_embeddings(maas,endpoint_id="ep-xxx-xxx",req=req)
        embeddings = [item["embedding"] for item in resp.data]

豆包向量化API的數(shù)據(jù)結(jié)構(gòu)

豆包向量化API的數(shù)據(jù)結(jié)構(gòu)主要分為輸入（Input）和輸出（Output）兩個(gè)部分。

• 輸入（Input）：輸入部分是一個(gè)包含需要向量化的文本列表，示例如下：

  {
    "input": [
      "天很藍(lán)","海很深"
    ]
  }

• 輸出（Output）：輸出部分包含以下字段：

• • req_id：請(qǐng)求ID，標(biāo)識(shí)此次API調(diào)用的唯一標(biāo)識(shí)。
  • data：包含每個(gè)輸入文本的向量化結(jié)果的列表，每個(gè)結(jié)果包括：
    • embedding：一個(gè)浮點(diǎn)數(shù)列表，表示文本的向量。
    • index：向量的序號(hào)，按照輸入順序排列。
    • object：通常為“embedding”，表示結(jié)果的類型。

豆包向量化API的注意事項(xiàng)

• API主機(jī)和區(qū)域：確保請(qǐng)求發(fā)送至正確的API主機(jī)和區(qū)域，例如maas-api.ml-platform-cn-beijing.volces.com和cn-beijing。
• 鑒權(quán)：在使用API Key進(jìn)行鑒權(quán)時(shí)，確保選擇一個(gè)有效且不過期的API Key，以免調(diào)用失敗。可通過火山引擎控制臺(tái)獲取API Key，并在調(diào)用時(shí)使用。
• 選擇合適的模型：根據(jù)具體需求和上下文長(zhǎng)度，選擇適當(dāng)?shù)哪Ｐ汀＠纾粜杼幚磔^長(zhǎng)上下文，建議使用Doubao-pro-128k模型。
• 調(diào)整調(diào)用參數(shù)：根據(jù)需求選擇合適的模型并調(diào)整API參數(shù)，如max_tokens、temperature、top_p等，以優(yōu)化效果。
• 流式與非流式調(diào)用：流式調(diào)用適合實(shí)時(shí)反饋場(chǎng)景，而非流式調(diào)用則在模型完成所有生成后一次性返回結(jié)果。根據(jù)具體應(yīng)用選擇合適的調(diào)用方式。
• 錯(cuò)誤處理：錯(cuò)誤信息將包含錯(cuò)誤代碼和描述。首先檢查錯(cuò)誤信息以確定問題，然后根據(jù)具體情況進(jìn)行相應(yīng)調(diào)整，如修正請(qǐng)求參數(shù)或檢查鑒權(quán)設(shè)置。
• 數(shù)據(jù)格式：API返回的數(shù)據(jù)通常為JSON格式，包含id、choices、message、finish_reason、logprobs、created、model、object和usage等字段，具體字段含義請(qǐng)參考API文檔。

豆包向量化API的應(yīng)用場(chǎng)景

• 信息檢索：構(gòu)建搜索引擎和推薦系統(tǒng)，提供相關(guān)文檔或信息的檢索服務(wù)。
• 文檔分類：對(duì)文檔進(jìn)行分類和標(biāo)記，便于管理和查找。
• 語義搜索：提供基于語義理解的搜索服務(wù)，提高結(jié)果的相關(guān)性和準(zhǔn)確性。
• 知識(shí)圖譜構(gòu)建：通過文本向量化建立實(shí)體與概念之間的聯(lián)系，形成知識(shí)圖譜。
• 內(nèi)容推薦：在內(nèi)容平臺(tái)中，根據(jù)用戶興趣和內(nèi)容相似度進(jìn)行相關(guān)內(nèi)容推薦。
• 機(jī)器人：作為機(jī)器人的語義理解模塊，提供更自然的人機(jī)交互體驗(yàn)。