豆包向量化API是什么
豆包向量化API是由字节跳动研发的语义向量化模型，名为Doubao-embedding，主要面向向量检索的使用场景，支持中、英双语，能处理最长4K的上下文长度。目前提供两个版本，text-240715：最高维度向量 2560，支持 512、1024、2048 降维使用。中英文 Retrieval效果较 text-240515 版本有较大提升，推荐使用该版本。text-240515：最高维度向量 2048，支持 512、1024 降维使用。API的Host为maas-api.ml-platform-cn-beijing.volces.com，Region为cn-beijing。
使用Doubao-embedding API之前，需要通过设置环境变量或在代码中直接修改，配置VOLC_ACCESSKEY和VOLC_SECRETKEY。字节跳动提供了统一的SDK接入方式，包括Golang、Python和Java的SDK。
豆包向量化API的主要功能
语义向量化：将文本内容转换为语义向量，这些向量能表达文本的语义信息。
支持多种语言：支持中文和英文文本的向量化处理。
长文本处理：能处理最长4K（即4096个字符）的上下文长度，适合长文本的向量化。
高维向量输出：提供2048维的向量输出，同时支持512维和1024维的降维使用，适应不同的应用场景和计算资源。
向量检索优化：生成的向量适用于文档相似度比较、信息检索等向量检索任务。
易于集成：提供Golang、Python和Java的SDK，方便开发者在不同编程环境中集成和使用。
灵活的输入输出：API的输入是一个包含文本内容的列表，输出则是包含每个文本向量化结果的列表，其中包含向量和对应的序号。
检索效果优化：在检索场景中，建议为查询文本添加指令前缀，提高检索的效果和准确度。
适用于多种应用：适用于搜索引擎、推荐系统、知识图谱、自然语言处理等多种应用场景。
豆包向量化API的项目地址
向量化API调用指南地址：https://www.volcengine.com/docs/82379/1263524
如何获取豆包向量化API的API key鉴权
API Key是用于API鉴权的密钥，确保在调用API时能验证身份。在使用API进行开发时，需要在HTTP请求的Header中添加Authorization字段，在实际调用API时，需要将VOLC_ACCESSKEY替换为实际API Key。
注册账号：前往火山引擎官网并注册账号。
登录控制台：使用账号登录火山引擎控制台。
创建API Key：在控制台中，找到API访问秘钥部分，点击创建API Key。需要为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")
// fetch ak&sk from environmental variables
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) { // the returned error always type of *api.Error
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");
// fetch ak&sk from environmental variables
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()); //object: object type 恒为embedding，embedding: embedding向量，index: 列表中序号
} 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"))
# 豆包embedding模型用于检索场景，query建议必须添加如下instruction前缀保证检索效果
query_instruction = '为这个句子生成表示以用于检索相关文章：'
query = "天是什么颜色？"
document = "天空呈现颜色主要与“瑞利散射”现象有关..."
req = {
"input": [
query_instruction + query, # query text
document, # document text
]
}
resp = test_embeddings(maas, endpoint_id="ep-xxx-xxx", req=req) # endpoint 使用方舟 2.0 模型接入
embeddings = [item["embedding"] for item in resp.data]
豆包向量化API的数据结构
豆包向量化API（Doubao-embedding API）的数据结构主要包括输入（Input）和输出（Output）两个部分。
输入（Input）：输入部分主要是一个包含需要向量化文本内容的列表（list），例如：json
{
"input": [
"天很蓝",
"海很深"
]
}
输出（Output）：输出部分包括以下字段：
req_id：请求ID，标识这次API调用的唯一标识符。
data：包含每个查询的向量化结果的列表，其中每个结果包括：
embedding：一个浮点数列表，表示文本的向量。
index：向量的序号，与输入查询的顺序相对应。
object：通常为”embedding”，表示结果类型。
豆包向量化API的注意事项
API Host和Region：确保请求发送到正确的API主机和区域，例如maas-api.ml-platform-cn-beijing.volces.com和cn-beijing 。
鉴权：使用API Key进行鉴权时，确保选择一个不过期的API key以避免调用失败。可以通过火山引擎的控制台界面获取API Key，确保在调用API时使用它进行鉴权 。
选择合适的模型：根据应用的具体需求和上下文窗口的大小，选择相应的模型。例如，如果需要处理较长的上下文，可以选择Doubao-pro-128k模型 。
调用参数：根据需要选择合适的模型和调整API参数，如max_tokens、temperature、top_p等，获得最佳效果 。
流式调用与非流式调用：流式调用支持实时接收模型生成的响应，适合需要即时反馈的场景。非流式调用是等待模型完成所有生成后一次性返回结果。根据应用场景选择合适的调用方式 。
错误处理：错误信息会包含错误代码和描述。首先，检查错误信息确定问题所在，然后根据错误信息进行相应的调整，如修正请求参数或检查鉴权配置 。
数据格式：API返回的数据通常是JSON格式，包括id、choices、message、finish_reason、logprobs、created、model、object和usage等字段。具体字段的详细说明请参考API文档 。
豆包向量化API的应用场景
信息检索：用于构建搜索引擎和推荐系统，提供相关文档或信息的检索服务。
文档分类：对文档进行分类和标签化，便于管理和查找。
语义搜索：提供基于语义理解的搜索服务，提高搜索结果的相关性和准确度。
知识图谱构建：通过文本向量化，构建实体和概念之间的关联，形成知识图谱。
内容推荐：在内容平台中，根据用户兴趣和内容相似度推荐相关内容。
聊天机器人：作为聊天机器人的语义理解模块，提供更自然的人机交互体验。
