豆包向量化API

豆包向量化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

豆包向量化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文檔。