豆包向量化API – 字節跳動推出的語義向量化模型

豆包向量化API是字節跳動推出的一款先進的語義向量化模型，命名為Doubao-embedding。該API專為向量檢索場景而設計，支持中英文雙語處理，并能夠處理最長達4096個字符的上下文。

豆包向量化API是什么

豆包向量化API是字節跳動研發的高性能語義向量化模型，名為Doubao-embedding，主要應用于向量檢索領域。該API提供兩個版本：text-240715，具有最高2560維的向量輸出，支持512、1024和2048維的降維使用；text-240515，最高2048維，支持512和1024維降維。相較于text-240515版本，text-240715在中英文檢索效果上有顯著提升，因而推薦用戶優先使用該版本。API的主機地址為maas-api.ml-platform-cn-beijing.volces.com，所在區域為cn-beijing。

在使用Doubao-embedding API之前，用戶需通過設置環境變量或在代碼中配置VOLC_ACCESSKEY和VOLC_SECRETKEY。字節跳動為開發者提供了統一的SDK接入方式，支持Golang、Python和Java等多種編程語言。

豆包向量化API的主要功能

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

豆包向量化API的項目地址

• API調用指南地址：https://www.volcengine.com/docs/82379/1263524

如何獲取豆包向量化API的API key鑒權

API Key是用于調用API的鑒權密鑰，確保身份驗證。在開發過程中，需要在HTTP請求的Header中添加Authorization字段，并將VOLC_ACCESSKEY替換為實際API Key。

• 注冊賬號：訪問火山引擎官網進行賬號注冊。
• 登錄控制臺：使用注冊的賬號登錄火山引擎控制臺。
• 創建API Key：在控制臺中找到API訪問秘鑰部分，點擊創建API Key，并為其設置一個易于識別的名稱。創建后，系統將提供一串字符作為API Key，務必妥善保管，防止泄露。

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

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

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

  • 設置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{
                "天很藍","海很深",},}
        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>

  • 設置API Key：在代碼中設置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(
                    "天很藍","海很深"
                )));
            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

  • 配置環境變量：在.env文件或系統環境變量中設置VOLC_ACCESSKEY和VOLC_SECRETKEY。

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

  • 編寫代碼：使用SDK進行API調用的示例代碼：

    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 = '為這個句子生成表示以用于檢索相關文章：'
        query = "天是什么顏色？"
        document = "天空呈現顏色主要與“瑞利散射”現象有關..."
    
        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的數據結構

豆包向量化API的數據結構主要分為輸入（Input）和輸出（Output）兩個部分。

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

  {
    "input": [
      "天很藍","海很深"
    ]
  }

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

• • req_id：請求ID，標識此次API調用的唯一標識。
  • data：包含每個輸入文本的向量化結果的列表，每個結果包括：
    • embedding：一個浮點數列表，表示文本的向量。
    • index：向量的序號，按照輸入順序排列。
    • object：通常為“embedding”，表示結果的類型。

豆包向量化API的注意事項

• API主機和區域：確保請求發送至正確的API主機和區域，例如maas-api.ml-platform-cn-beijing.volces.com和cn-beijing。
• 鑒權：在使用API Key進行鑒權時，確保選擇一個有效且不過期的API Key，以免調用失敗。可通過火山引擎控制臺獲取API Key，并在調用時使用。
• 選擇合適的模型：根據具體需求和上下文長度，選擇適當的模型。例如，若需處理較長上下文，建議使用Doubao-pro-128k模型。
• 調整調用參數：根據需求選擇合適的模型并調整API參數，如max_tokens、temperature、top_p等，以優化效果。
• 流式與非流式調用：流式調用適合實時反饋場景，而非流式調用則在模型完成所有生成后一次性返回結果。根據具體應用選擇合適的調用方式。
• 錯誤處理：錯誤信息將包含錯誤代碼和描述。首先檢查錯誤信息以確定問題，然后根據具體情況進行相應調整，如修正請求參數或檢查鑒權設置。
• 數據格式：API返回的數據通常為JSON格式，包含id、choices、message、finish_reason、logprobs、created、model、object和usage等字段，具體字段含義請參考API文檔。

豆包向量化API的應用場景

• 信息檢索：構建搜索引擎和推薦系統，提供相關文檔或信息的檢索服務。
• 文檔分類：對文檔進行分類和標記，便于管理和查找。
• 語義搜索：提供基于語義理解的搜索服務，提高結果的相關性和準確性。
• 知識圖譜構建：通過文本向量化建立實體與概念之間的聯系，形成知識圖譜。
• 內容推薦：在內容平臺中，根據用戶興趣和內容相似度進行相關內容推薦。
• 機器人：作為機器人的語義理解模塊，提供更自然的人機交互體驗。