文档中心

向量数据库VikingDB

API参考

签名鉴权与调用示例

知识库支持通过 API 接口进行操作，数据面接口支持使用火山引擎 API Key 或 AK/SK 进行鉴权。本文介绍访问密钥的获取方式，并提供 AK/SK 签名鉴权和完整调用的多语言示例代码。

获取 API 访问密钥

在调用知识库的各项能力之前，请先获取 API Key 或 AK/SK。登录火山引擎控制台，进入【访问控制】—【API 访问密钥】，可在 API Key 区域创建和管理 API Key。
AK/SK 包括以下内容：

Access Key ID：简称为 AK，用于标识用户。
Access Key Secret：简称为 SK，用于验证用户的密钥。

请按照以下步骤创建您自己的 AK/SK：

登录火山引擎控制台。
在控制台右上角，将鼠标指针悬停在头像上，然后在弹出菜单中点击 API 访问密钥。
在 API 访问密钥页面上点击新建密钥。在此处获取的 AK/SK 可以作为调用相关接口的凭证。
为了您的数据和资金安全，请务必妥善保管您的 AK/SK，不要轻易向他人披露。另外，由于主账号的权限过大，根据权限最小化原则，建议您新建子账号，并使用子账号的 AK/SK。
关于 AK/SK 的进一步信息，请参见 Access Key（密钥）管理。

签名鉴权

签名是 API 请求中经过计算得到的一串编码字符串，用于身份认证和防止数据被篡改。

签名的时效性

与 AK/SK 不同，每个请求的签名都是独立且临时的，一个签名只能用于一次特定的请求，不能长期固定使用。

签名的计算方式

签名由签名生成函数 prepare_request 基于以下参数计算而来：

参数	含义	说明
method	请求方法	影响签名计算，例如 GET、POST。
path	请求路径	例如 `/api/collection/create`。
ak	Access Key ID	标识 API 调用者。
sk	Access Key Secret	用于 HMAC-SHA256 计算签名（需保密）。
params	查询参数	适用于 GET 请求等。
data	请求体	适用于 POST、PUT 请求。
doseq	查询参数的格式控制	影响 params 的格式。

签名生成函数示例代码

签名生成函数的各语言示例代码见下方说明。
如需了解通过源码生成签名的详情，请参考签名源码示例；如需了解通过 SDK 生成签名的详情，请参考 SDK 概览。
以下为通过 Python SDK 生成签名的示例代码。

安装火山引擎程序包。
```
pip install volcengine
```

生成签名。

import json
import sys
import requests

from volcengine.auth.SignerV4 import SignerV4
from volcengine.base.Request import Request
from volcengine.Credentials import Credentials

def prepare_request(method, path, ak, sk, params=None, data=None, doseq=0):
    if params:
        for key in params:
            if (
                type(params[key]) == int
                or type(params[key]) == float
                or type(params[key]) == bool
            ):
                params[key] = str(params[key])
            # elif sys.version_info[0] != 3: # 在 Python 3.x 中，不需要这部分代码
            #     if type(params[key]) == unicode:
            #         params[key] = params[key].encode("utf-8")
            elif type(params[key]) == list:
                if not doseq:
                    params[key] = ",".join(params[key])
    r = Request()
    r.set_shema("https")
    r.set_method(method)
    r.set_connection_timeout(10)
    r.set_socket_timeout(10)
    mheaders = {
        "Accept": "application/json",
        "Content-Type": "application/json",
    }
    r.set_headers(mheaders)
    if params:
        r.set_query(params)
    r.set_path(path)
    if data is not None:
        r.set_body(json.dumps(data))
    # 生成签名
    credentials = Credentials(ak, sk, "air", "cn-north-1")
    SignerV4.sign(r, credentials)
    return r

以下为通过 Java SDK 生成签名的示例代码。

打开火山引擎 SDK for Java 的 README，在获取与安装小节查看火山引擎 SDK for Java 的最新版本号。
安装火山引擎程序包。
请将{latest_ver}替换为火山引擎 SDK for Java 的最新版本号。例如在本文的示例中，该版本号为1.0.256。具体版本号请以您打开的页面为准。
```
<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>volc-sdk-java</artifactId>
    <version>{latest_ver}</version>
</dependency> 
```

生成签名。

package javaTest;

import java.util.List;

import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.config.RequestConfig;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

import com.volcengine.auth.ISignerV4;
import com.volcengine.auth.impl.SignerV4Impl;
import com.volcengine.model.Credentials;
import com.volcengine.service.SignableRequest;

public class sign {
  public static SignableRequest prepareRequest(String host, String path, String method, List<NameValuePair> params, String body, String ak, String sk) throws Exception {
    SignableRequest request = new SignableRequest();
    request.setMethod(method);
    request.setHeader("Accept", "application/json");
    request.setHeader("Content-Type", "application/json");
    request.setHeader("Host", "api-knowledgebase.mlp.cn-beijing.volces.com");
    request.setEntity(new StringEntity(body, "utf-8"));

    URIBuilder builder = request.getUriBuilder();
    builder.setScheme("https");
    builder.setHost(host);
    builder.setPath(path);
    if (params != null) {
      builder.setParameters(params);
    }

    RequestConfig requestConfig = RequestConfig.custom().setSocketTimeout(5000).setConnectTimeout(2000).build();
    request.setConfig(requestConfig);

    Credentials credentials = new Credentials("cn-north-1", "air");
    credentials.setAccessKeyID(ak);
    credentials.setSecretAccessKey(sk);

    // 签名
    ISignerV4 ISigner = new SignerV4Impl();
    ISigner.sign(request, credentials);

    return request;
  }

以下为通过 Go SDK 生成签名的示例代码。

安装火山引擎程序包。

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

生成签名。

package main

import (
        "bytes"
        "fmt"
        "net/http"
        "net/url"
        "strings"
        "io/ioutil"
        "github.com/volcengine/volc-sdk-golang/base"
)

const (
        testAk = "***"
        testSk = "***"
)

func PrepareRequest(method string, path string, ak string, sk string, query url.Values, body []byte) *http.Request {
        u := url.URL{
                Scheme:   "https",
                Host:     "api-knowledgebase.mlp.cn-beijing.volces.com",
                Path:     "/api/knowledge/collection/search",
        }
        if query != nil {
                u.RawQuery = query.Encode()
        }
        req, _ := http.NewRequest(strings.ToUpper(method), u.String(), bytes.NewReader(body))
        req.Header.Add("Accept", "application/json")
        req.Header.Add("Content-Type", "application/json")
        req.Header.Add("Host", "api-knowledgebase.mlp.cn-beijing.volces.com")
        credential := base.Credentials{
                AccessKeyID:     ak,
                SecretAccessKey: sk,
                Service:         "air",
                Region:          "cn-north-1",
        }
        req = credential.Sign(req)
        return req
}

以下为通过 Node.js SDK 生成签名的示例代码。

安装火山引擎程序包。
```
pnpm add @volcengine/openapi
```

生成签名。
调用函数signer生成请求体 header 后，将生成好的 header 注入到用户请求函数中。

import { Signer } from '@volcengine/openapi';
import type { RequestObj } from '@volcengine/openapi/lib/base/types';

interface Options {
  pathname: string
  method: 'GET' | 'POST'
  body?: string // json 字符串，当且仅当 post 请求
  region: 'cn-beijing' | 'cn-shanghai'
  params?: Record<string, any> // 当且仅当 get 请求
}

function signer({ pathname, method, body, region, params }: Options) {
  const requestObj: RequestObj = {
   region, 
   headers: {
     Accept: 'application/json',
     'Content-type': 'application/json'
   },
   method,
   body,
   pathname,
   params,
 }

  const signer = new Signer(requestObj, 'air')
    signer.addAuthorization({
      accessKeyId: 'ak', // 替换为用户 ak
      secretKey: 'sk', // 替换为用户 sk
  })
  return requestObj.headers
}

目前未提供 C# 和 PHP 语言的 SDK 签名生成方式，您可以参考对应的源码来生成签名。
相关示例见后续示例说明。

知识库 API 调用示例

获取 AK/SK 后，可以将签名生成函数和具体接口调用写进同一个脚本文件。以下为对接签名生成逻辑与创建知识库接口的 Python 示例代码。
请将 main 函数中的ak、sk分别替换为您自己的 AK 和 SK。

import json
import requests
from volcengine.auth.SignerV4 import SignerV4
from volcengine.base.Request import Request
from volcengine.Credentials import Credentials

#签名生成逻辑
def prepare_request(method, path, params=None, data=None, doseq=0):
    #创建request
    if params:
        for key in params:
            if (
                    isinstance(params[key], int)
                    or isinstance(params[key], float)
                    or isinstance(params[key], bool)
            ):
                params[key] = str(params[key])
            elif isinstance(params[key], list):
                if not doseq:
                    params[key] = ",".join(params[key])
    r = Request()
    r.set_shema("http")
    r.set_method(method)
    r.set_connection_timeout(10)
    r.set_socket_timeout(10)
    mheaders = {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Host": g_knowledge_base_domain
    }
    r.set_headers(mheaders)
    if params:
        r.set_query(params)
    r.set_host(g_knowledge_base_domain)
    r.set_path(path)
    if data is not None:
        r.set_body(json.dumps(data))
    # 生成签名
    credentials = Credentials(ak, sk, "air", "cn-north-1")
    SignerV4.sign(r, credentials)
    return r

#创建知识库逻辑
def create():
    #创建知识库的请求方式
    method = "POST"
    #创建知识库的请求路径
    path = "/api/knowledge/collection/create"
    #创建知识库所需要的一些参数
    request_params = {
        "name": "lzm_test2",
        "data_type": "unstructured_data",
        "preprocessing": {
            "chunking_strategy":"custom_balance",
            "multi_modal":["image_ocr"]
        },
        "index": {
            "cpu_quota": 1,
            "embedding_model": "doubao-embedding-and-m3",
            "embedding_dimension": 2048,
            "quant": "int8",
            "index_type": "hnsw_hybrid"
        },
    }
    info_req = prepare_request(method=method, path=path, data=request_params)
    rsp = requests.request(
        method=info_req.method,
        url="https://{}{}".format(g_knowledge_base_domain, info_req.path),
        headers=info_req.headers,
        data=info_req.body
    )
    print(rsp.text)

if __name__ == "__main__":
    ak = '刚才申请到的ak'
    sk = '刚才申请到的sk'
    g_knowledge_base_domain = "api-knowledgebase.mlp.cn-beijing.volces.com"
    #调用创建知识库的函数
    create()

下方示例代码提供了调用知识库 API 的全流程示例，包括签名、检索、生成、流式/非流式结果解析。
Main.java
您只需要将示例代码中的以下占位符替换为知识库的真实相关参数，即可完成一次简单的检索生成调用。

your ak：您的 AK。
your sk：您的 SK。
your query：您的提问。
your collection：知识库名称，可从前端界面获取。
default：知识库所属项目，可从前端界面获取。
your resource_id：知识库 ID，可从前端界面获取。

下方示例代码提供了调用知识库 API 的全流程示例，包括签名、检索、生成、流式/非流式结果解析。
main.go
您只需要将示例代码中的以下占位符替换为知识库的真实相关参数，即可完成一次简单的检索生成调用。

your ak：您的 AK。
your sk：您的 SK。
your query：您的提问。
your collection：知识库名称，可从前端界面获取。
default：知识库所属项目，可从前端界面获取。
your resource id：知识库 ID，可从前端界面获取。

下方示例代码提供了调用知识库 search 接口的示例，包括生成签名和检索。
您只需要将示例代码中的以下占位符替换为知识库的真实相关参数，即可完成一次简单的检索生成调用。

_ak：您的 AK。
_sk：您的 SK。
_path：接口路径。
华北区域的_region 、_service 和 _host 可直接使用示例默认值。

using System;
using System.Collections.Generic;
using System.Collections.Immutable;
using System.Collections.Specialized;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Web;

class GitHubSign
{
    private readonly string _region;
    private readonly string _service;
    private readonly string _schema;
    private readonly string _host;
    private readonly string _path;
    private readonly string _ak;
    private readonly string _sk;

    private static readonly Encoding Utf8 = Encoding.UTF8;

    private readonly HttpClient _httpClient;

    public GitHubSign(string region, string service, string schema, string host, string path, string ak, string sk)
    {
        _region = region;
        _service = service;
        _schema = schema;
        _host = host;
        _path = path;
        _ak = ak;
        _sk = sk;
        _httpClient = new HttpClient();
    }

    public HttpResponseMessage Request(HttpMethod method, List<KeyValuePair<string, string>> queryList,
        byte[]? body, string contentType,
        DateTimeOffset date, string action, string version)
    {
        body ??= Array.Empty<byte>();
        if (string.IsNullOrWhiteSpace(contentType))
        {
            contentType = "application/x-www-form-urlencoded";
        }

        string xContentSha256 = ToHexString(HashSha256(body));
        string xDate = date.UtcDateTime.ToString("yyyyMMdd'T'HHmmss'Z'");
        string shortXDate = xDate[..8];
        string signHeader = "host;x-date;x-content-sha256;content-type";

        var realQueryList = new NameValueCollection();
        queryList.ForEach(s => realQueryList.Add(s.Key, s.Value));
        realQueryList.Add("Action", action);
        realQueryList.Add("Version", version);

        var query = string.Join("&", realQueryList.AllKeys.ToImmutableSortedSet().Select(key =>
        {
            var values = realQueryList.GetValues(key)?.ToImmutableSortedSet() ?? ImmutableSortedSet<string>.Empty;
            return string.Join("&",
                values.Select(value => $"{HttpUtility.UrlEncode(key)}={HttpUtility.UrlEncode(value)}"));
        }));
        string canonicalStringBuilder =
            $"{method}\n" +
            $"{_path}\n" +
            $"{query}\n" +
            $"host:{_host}\n" +
            $"x-date:{xDate}\n" +
            $"x-content-sha256:{xContentSha256}\n" +
            $"content-type:{contentType}\n" +
            $"\n" +
            $"{signHeader}\n" +
            $"{xContentSha256}";

        string hashCanonicalString = ToHexString(HashSha256(Utf8.GetBytes(canonicalStringBuilder)));
        string credentialScope = $"{shortXDate}/{_region}/{_service}/request";
        string signString = $"HMAC-SHA256\n{xDate}\n{credentialScope}\n{hashCanonicalString}";

        byte[] signKey = GenSigningSecretKeyV4(_sk, shortXDate, _region, _service);
        string signature = ToHexString(HmacSha256(signKey, signString));

        Uri url = new Uri($"{_schema}://{_host}{_path}?{query}");
        var request = new HttpRequestMessage();
        request.Method = method;
        request.RequestUri = url;
        request.Headers.TryAddWithoutValidation("Host", _host);
        request.Headers.Add("X-Date", xDate);
        request.Headers.Add("X-Content-Sha256", xContentSha256);
        request.Headers.TryAddWithoutValidation("Authorization",
            $"HMAC-SHA256 Credential={_ak}/{credentialScope}, SignedHeaders={signHeader}, Signature={signature}");
        HttpContent content = new ByteArrayContent(body);
        content.Headers.ContentType = new MediaTypeHeaderValue(contentType);
        request.Content = content;


        return _httpClient.Send(request);
    }

    private byte[] GenSigningSecretKeyV4(string secretKey, string date, string region, string service)
    {
        byte[] kDate = HmacSha256(Utf8.GetBytes(secretKey), date);
        byte[] kRegion = HmacSha256(kDate, region);
        byte[] kService = HmacSha256(kRegion, service);
        return HmacSha256(kService, "request");
    }

    private static byte[] HmacSha256(byte[] secret, string text)
    {
        using HMACSHA256 mac = new HMACSHA256(secret);
        var hash = mac.ComputeHash(Encoding.UTF8.GetBytes(text));
        return hash;
    }

    private static byte[] HashSha256(byte[] data)
    {
        using SHA256 sha = SHA256.Create();
        var hash = sha.ComputeHash(data);
        return hash;
    }

    private static string ToHexString(byte[]? bytes)
    {
        if (bytes == null)
        {
            return "";
        }

        StringBuilder sb = new StringBuilder();
        foreach (var t in bytes)
        {
            sb.Append(t.ToString("X2"));
        }

        return sb.ToString().ToLower();
    }
}

下方示例代码提供了一个通用的 PHP 请求示例，包含接口签名与请求发送逻辑。
您只需要将示例代码中的ak、sk、Path、body、method替换为知识库的真实相关参数即可。其余参数（如Service、Region、Host、Content-Type等）已按默认服务配置填写，一般情况下无需修改。

<?php
/**
 * Copyright (year) Beijing Volcano Engine Technology Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
require 'vendor/autoload.php';
// 需要自行安装 composer（https://getcomposer.org/doc/00-intro.md），并安装GuzzleHttp依赖， composer require guzzlehttp/guzzle:^7.0
use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;
$Service = "air";
$Version = "2018-01-01";
$Region = "cn-north-1";
$Host = "api-knowledgebase.mlp.cn-beijing.volces.com";
$ContentType = "application/json";
$Path = ""; //请求路径
/**
 * @throws GuzzleException
 */
// 第一步：创建一个 API 请求函数。签名计算的过程包含在该函数中。
function request($method, $header, $ak, $sk, $body)
{
 // 第二步：创建身份证明。其中的 Service 和 Region 字段是固定的。ak 和 sk 分别代表
 // AccessKeyID 和 SecretAccessKey。同时需要初始化签名结构体。一些签名计算时需要的属性也在这里处理。
 // 初始化身份证明结构体
 global $Service, $Region, $Host, $Version, $ContentType, $Path;
 $credential = [
 'accessKeyId' => $ak,
 'secretKeyId' => $sk,
 'service' => $Service,
 'region' => $Region,
 ];
 $requestParam = [
 // body是http请求需要的原生body
 'body' => $body,
 'host' => $Host,
 'path' => $Path,
 'method' => $method,
 'contentType' => $ContentType,
 'date' => gmdate('Ymd\THis\Z'),
 ];
 // 第三步：接下来开始计算签名。在计算签名前，先准备好用于接收签算结果的 signResult 变量，并设置一些参数。
 // 初始化签名结果的结构体
 $xDate = $requestParam['date'];
 $shortXDate = substr($xDate, 0, 8);
 $xContentSha256 = hash('sha256', $requestParam['body']);
 $signResult = [
 'Host' => $requestParam['host'],
 'X-Content-Sha256' => $xContentSha256,
 'X-Date' => $xDate,
 'Content-Type' => $requestParam['contentType']
 ];
 // 第四步：计算 Signature 签名。
 $signedHeaderStr = join(';', ['content-type', 'host', 'x-content-sha256', 'x-date']);
 $canonicalRequestStr = join("\n", [
 $requestParam['method'],
 $requestParam['path'],
 '',
 join("\n", ['content-type:' . $requestParam['contentType'], 'host:' . $requestParam['host'], 'x-content-sha256:' . $xContentSha256, 'x-date:' . $xDate]),
 '',
 $signedHeaderStr,
 $xContentSha256
 ]);
 $hashedCanonicalRequest = hash("sha256", $canonicalRequestStr);
 $credentialScope = join('/', [$shortXDate, $credential['region'], $credential['service'], 'request']);
 $stringToSign = join("\n", ['HMAC-SHA256', $xDate, $credentialScope, $hashedCanonicalRequest]);
 $kDate = hash_hmac("sha256", $shortXDate, $credential['secretKeyId'], true);
 $kRegion = hash_hmac("sha256", $credential['region'], $kDate, true);
 $kService = hash_hmac("sha256", $credential['service'], $kRegion, true);
 $kSigning = hash_hmac("sha256", 'request', $kService, true);
 $signature = hash_hmac("sha256", $stringToSign, $kSigning);
 $signResult['Authorization'] = sprintf("HMAC-SHA256 Credential=%s, SignedHeaders=%s, Signature=%s", $credential['accessKeyId'] . '/' . $credentialScope, $signedHeaderStr, $signature);
 $header = array_merge($header, $signResult);
 // 第五步：将 Signature 签名写入 HTTP Header 中，并发送 HTTP 请求。
 $client = new Client([
 'base_uri' => 'https://' . $requestParam['host'],
 'timeout' => 120.0,
 ]);
 return $client->request($method, 'https://' . $requestParam['host'] . $requestParam['path'], [
 'headers' => $header,
 'body' => $requestParam['body']
 ]);
}
$now = time();
$body = [
]; // 请求体
$requestBody =json_encode($body);
$AK = '';
$SK = '';
try {
 $response = request("POST",[], $AK, $SK, $requestBody);
 print_r($response->getBody()->getContents());
} catch (GuzzleException $e) {
 print_r($e->getMessage());
}

最近更新时间：2026.09.08 20:33:08

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

签名的时效性 #

签名的计算方式 #

签名生成函数示例代码 #

签名的时效性

签名的计算方式

签名生成函数示例代码