bge-large-zh是中文文本表示模型，可将任意文本映射为低维稠密向量，以用于检索、分类、聚类或语义匹配等任务，并可支持为大模型调用外部知识。
本文详细介绍了 bge-large-zh 的SDK及API使用方法。

API Host

Host：maas-api.ml-platform-cn-beijing.volces.com
Region: cn-beijing

API SDK

提供统一 SDK 的接入形式（需要用 ak/sk 进行旁路鉴权，火山鉴权逻辑可以参考）

• Golang SDK: https://github.com/volcengine/volc-sdk-golang

• Python SDK: https://github.com/volcengine/volc-sdk-python

• Java SDK: https://github.com/volcengine/volc-sdk-java

Golang

// Usage:
//
// 1. go get -u github.com/volcengine/volc-sdk-golang
// 2. VOLC_ACCESSKEY=XXXXX VOLC_SECRETKEY=YYYYY go run main.go
package main

import (
    "encoding/json"
    "errors"
    "fmt"
    "os"

    "github.com/volcengine/volc-sdk-golang/service/maas"
    "github.com/volcengine/volc-sdk-golang/service/maas/models/api"
)

func main() {
		r := maas.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"))

		reqE := &api.EmbeddingsReq{
				Model: &api.Model{
						Name: "bge-large-zh",
				},
				Input: []string{"天很蓝", "海很深"},
		}
		TestEmbeddings(r, reqE)
}

func TestEmbeddings(r *maas.MaaS, req *api.EmbeddingsReq) {
		got, status, err := r.Embeddings(req)
		if 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
		}
		fmt.Println("embeddings answer", mustMarshalJson(got))
}

Python

'''
Usage:

1. python3 -m pip install --user volcengine
2. VOLC_ACCESSKEY=XXXXX VOLC_SECRETKEY=YYYYY python main.py
'''
import os
from volcengine.maas import MaasService, MaasException


def test_embeddings(maas, req):
    try:
        resp = maas.embeddings(req)
        print(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"))

    # document: "https://www.volcengine.com/docs/82379/1099475"
    # embeddings
    embeddingsReq = {
        "model": {
            "name": "bge-large-zh"
        },
        "input": [
            "天很蓝",
            "海很深"
        ]
    }

    test_embeddings(maas, embeddingsReq)

Java

/*
# pom.xml
<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>volc-sdk-java</artifactId>
    <version>LATEST</version>
</dependency>
*/

package com.volcengine.example.maas;

import com.volcengine.helper.Const;
import com.volcengine.model.maas.api.Api;
import com.volcengine.service.maas.MaasException;
import com.volcengine.service.maas.MaasService;
import com.volcengine.service.maas.impl.MaasServiceImpl;

import java.util.stream.Stream;

public class EmbeddingsDemo {
    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"));

        Api.EmbeddingsReq tReq = Api.EmbeddingsReq.newBuilder()
                .setModel(Api.Model.newBuilder().setName("bge-large-zh"))
                .addInput("天很蓝")
                .addInput("海很深")
                .build();
        testEmbeddings(maasService, tReq);
    }

    private static void testEmbeddings(MaasService maasService, Api.EmbeddingsReq req) {
        try {
            Api.EmbeddingsResp resp = maasService.embeddings(req);
            System.out.println(resp.getObject());
            System.out.println(resp.getDataList()); //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();
        }
    }
}

API Specification

Embeddings

主要参考 OpenAI 和 HuggingFace
Parameters 记录可选控制参数，具体哪些参数可用依赖模型服务（模型详情页会描述哪些参数可用）

Input

Output

{
    "index": 0,
    "embedding": [
        0.04307687282562256,
        -0.005127846263349056
    ],
    "object": "embedding",
}

{
    "prompt_tokens": 18,
    "completion_tokens": 317,
    "total_tokens": 335
}

{
    "code": "UnauthorizedCode",
    "code_n": 123456,
    "message": "You are not authorized"
}