豆包向量化API

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

豆包向量化API是字節(jié)跳動(dòng)推出的一款先進(jìn)的語義向量化模型，命名為Doubao-embedding。該API專為向量檢索場景而設(shè)計(jì)，支持中英文雙語處理，并能夠處理最長達(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

豆包向量化API的主要功能

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

注冊賬號(hào)：訪問火山引擎官網(wǎng)進(jìn)行賬號(hào)注冊。
登錄控制臺(tái)：使用注冊的賬號(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：請求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ū)域：確保請求發(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ù)具體需求和上下文長度，選擇適當(dāng)?shù)哪Ｐ汀＠纾粜杼幚磔^長上下文，建議使用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í)反饋場景，而非流式調(diào)用則在模型完成所有生成后一次性返回結(jié)果。根據(jù)具體應(yīng)用選擇合適的調(diào)用方式。
錯(cuò)誤處理：錯(cuò)誤信息將包含錯(cuò)誤代碼和描述。首先檢查錯(cuò)誤信息以確定問題，然后根據(jù)具體情況進(jìn)行相應(yīng)調(diào)整，如修正請求參數(shù)或檢查鑒權(quán)設(shè)置。
數(shù)據(jù)格式：API返回的數(shù)據(jù)通常為JSON格式，包含id、choices、message、finish_reason、logprobs、created、model、object和usage等字段，具體字段含義請參考API文檔。