插件使用说明

golang

请安装 volc-sdk-golang >= 1.0.122。

go get -u github.com/volcengine/volc-sdk-golang

python

需要按照如下方式安装 volcengine>=1.0.110。

python -m pip install --upgrade volcengine

java

请使用版本 volc-sdk-java>=1.0.125。

<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>volc-sdk-java</artifactId>
    <version>最新版本</version>
</dependency>

头条搜索插件

• 【插件功能】

  • 基于外部输入的必要性判断后，调用头条搜索能力，实时获取新闻、法律等互联网资讯。

• 【使用场景】

  • 强时效性知识问答

  • 权威信息源定义

  • 互联网资讯补充

• 【适配范围】

  • 云雀大模型（Skylark）

• 【使用效果】

  • 输入：今天北京的天气怎么样？

  • 使用头条搜索插件

  • 输出：北京今天多云转晴，6～18°C，偏北风3-4级。

golang

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"))

    req := &api.ChatReq{
        Model: &api.Model{
            Name: "${YOUR_MODEL_NAME}",
        },
        Messages: []*api.Message{
            {
                Role:    maas.ChatRoleOfUser,
                Content: "今天的新闻",
            },
        },
        Parameters: &api.Parameters{
            MaxNewTokens: 512,
            Temperature:  0.8,
        },
        // 添加这个标记，以使用联网功能
        Plugins: []string{"browsing"},    
    }
    TestNormalChat(r, req)
    TestStreamChat(r, req)
}

func TestNormalChat(r *maas.MaaS, req *api.ChatReq) {
    got, status, err := r.Chat(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("chat answer", mustMarshalJson(got))
    fmt.Println("chat answer content", got.Choice.Message.Content)
    // 参考引用通过这个字段透传，URL是联网链接，idx指的是这个是第几个链接
    fmt.Println("chat answer reference", mustMarshalJson(got.Choice.Message.References))
}

func TestStreamChat(r *maas.MaaS, req *api.ChatReq) {
    ch, err := r.StreamChat(req)
    if err != nil {
        errVal := &api.Error{}
        if errors.As(err, &errVal) { // the returned error always type of *api.Error
            fmt.Println("meet maas error", errVal.Error())
        }
        return
    }

    for resp := range ch {
        if resp.Error != nil {
            // it is possible that error occurs during response processing
            fmt.Println(mustMarshalJson(resp.Error))
            return
        }
        fmt.Println(mustMarshalJson(resp))
        // last response may contain `usage`
        if resp.Usage != nil {
            // last message, will return full response including usage, role, finish_reason, reference, etc.
            fmt.Println(mustMarshalJson(resp.Usage))
        }
        // 流式接口，reference 列表随最后一个 message 返回
        if resp.GetChoice().GetMessage().GetReferences() != nil {
        // last message, will return full response including usage, role, finish_reason, reference, etc.
            fmt.Println(mustMarshalJson(resp.GetChoice().GetMessage().GetReferences()))
        }
    }
}

func mustMarshalJson(v interface{}) string {
    s, _ := json.Marshal(v)
    return string(s)
}

python

import os
from volcengine.maas import MaasService, MaasException, ChatRole

def test_chat(maas, req):
    try:
        resp = maas.chat(req)
        print(resp)
        print(resp.choice.message.content)
        # 参考引用通过这个字段透传，URL是联网链接，idx指的是这个是第几个链接
        print(resp.choice.message.references)
    except MaasException as e:
        print(e)

    
def test_stream_chat(maas, req):
    try:
        resps = maas.stream_chat(req)
        for resp in resps:
            print(resp)
            print(resp.choice.message.content)
            # 流式接口，reference 列表随最后一个 message 返回
            print(resp.choice.message.references)
    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"
    req = {
        "model": {
            "name": "${YOUR_MODEL_NAME}"
        },
        "parameters": {
            "max_new_tokens": 2000,
            "temperature": 0.8
        },
        "messages": [
            {
                "role": ChatRole.USER,
                "content": "今天的新闻"
            },
        ],
        # 添加这个标记，以使用联网功能
        "plugins": ["browsing"],
    }
    
    test_chat(maas, req)
    test_stream_chat(maas, req)

java

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 PluginDemo {
    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.ChatReq req = Api.ChatReq.newBuilder()
                .setModel(Api.Model.newBuilder().setName("${YOUR_MODEL_NAME}"))
                .setParameters(Api.Parameters.newBuilder()
                        .setMaxNewTokens(2000)
                        .setTemperature(0.8f)
                )
                // 添加这个标记，以使用联网功能
                .addPlugins("browsing")
                .addMessages(Api.Message.newBuilder().setRole(Const.MaasChatRoleOfUser).setContent("今天的新闻"))
                .build();

        testChat(maasService, req);
        testStreamChat(maasService, req);
    }

    private static void testChat(MaasService maasService, Api.ChatReq req) {
        try {
            Api.ChatResp resp = maasService.chat(req);
            System.out.println(resp.getChoice().getMessage().getContent());
            // 参考引用通过这个字段透传，URL是联网链接，idx指的是这个是第几个链接
            System.out.println(resp.getChoice().getMessage().getReferencesList());
            System.out.println(resp.getUsage());
        } catch (MaasException e) {
            System.out.println("code: " + e.getCode());
            System.out.println("code_n: " + e.getCodeN());
            System.out.println("message: " + e.getMsg());
            e.printStackTrace();
        }
    }

    private static void testStreamChat(MaasService maasService, Api.ChatReq req) {
        Stream<Api.ChatResp> resps = null;
        try {
            resps = maasService.streamChat(req);
        } catch (MaasException e) {
            e.printStackTrace();
        }


        assert resps != null;

        // it is possible that error occurs during response processing
        try {
            resps.forEach(resp -> {
                System.out.println(resp.getChoice().getMessage().getContent());

                // last message, will return full response including usage, role, finish_reason, etc.
                if (resp.getUsage().isInitialized()) {
                    System.out.println(resp.getUsage());
                    // 流式接口，reference 列表随最后一个 message 返回Ï
                    System.out.println(resp.getChoice().getMessage().getReferencesList());
                }

            });
        } catch (RuntimeException e) {
            Throwable cause = e.getCause();
            if (cause instanceof MaasException) {
                System.out.println("code: " + ((MaasException) cause).getCode());
                System.out.println("code_n: " + ((MaasException) cause).getCodeN());
                System.out.println("message: " + ((MaasException) cause).getMsg());
            }
            System.out.println("caught: " + e);
        }
    }
}