豆包向量化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的主要功能

• 语义向量化：将输入的文本转化为语义向量，准确表达文本的内涵。
• 多语言支持：兼容中文和英文文本的向量处理。
• 长文本处理能力：可处理最多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的应用场景

• 信息检索：构建搜索引擎和推荐系统，提供相关文档或信息的检索服务。
• 文档分类：对文档进行分类和标记，便于管理和查找。
• 语义搜索：提供基于语义理解的搜索服务，提高结果的相关性和准确性。
• 知识图谱构建：通过文本向量化建立实体与概念之间的联系，形成知识图谱。
• 内容推荐：在内容平台中，根据用户兴趣和内容相似度进行相关内容推荐。
• 机器人：作为机器人的语义理解模块，提供更自然的人机交互体验。