IAM authorization #

1. Go to IAM Console , select the LASFullAccess policy, and click Authorize.
   
   
2. On the Add Permission page, select the required sub-account.

   tip

   The AK set for the primary account does not require authorization.

API call preparation #

The interface uses a VolcanoEnginegeneral method; for detailed operations, refer to the request structure . In particular, pay attention to the signature process and SDK examples . After signing, a header will be added to the request.

Authorization: HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}

For example, here is an example in Python:
Reference documentation: volc-openapi-demos.

# coding:utf-8
"""
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.
"""

import datetime
import hashlib
import hmac
from urllib.parse import quote

import requests

# The following parameters vary by service, but are usually consistent within a service
Service = "las"
Version = "2024-06-30"
Region = "cn-beijing"
Host = "open.volcengineapi.com"
ContentType = "application/json"

# The request credentials are obtained from the IAM or STS service
AK = "AKExample***********"
SK = "QwERrtyasdf*********"
# When using temporary credentials, you need to pass SessionToken in the Header and include it in SignedHeader. Please manually add the X-Security-Token header in the header parameter
# SessionToken = ""


def norm_query(params):
    query = ""
    for key in sorted(params.keys()):
        if type(params[key]) == list:
            for k in params[key]:
                query = (
                        query + quote(key, safe="-_.~") + "=" + quote(k, safe="-_.~") + "&"
                )
        else:
            query = (query + quote(key, safe="-_.~") + "=" + quote(params[key], safe="-_.~") + "&")
    query = query[:-1]
    return query.replace("+", "%20")


# Step 1: Prepare helper functions.
# sha256 asymmetric encryption
def hmac_sha256(key: bytes, content: str):
    return hmac.new(key, content.encode("utf-8"), hashlib.sha256).digest()


# sha256 hash algorithm
def hash_sha256(content: str):
    return hashlib.sha256(content.encode("utf-8")).hexdigest()


# Step 2: Signature request function
def request(method, date, query, header, ak, sk, action, body):
    # Step 3: Create identity credentials. The Service and Region fields are fixed. ak and sk represent AccessKeyID and SecretAccessKey, respectively.
     It is also necessary to initialize the signature structure. Some properties required for signature calculation are also handled here.
    # Initialize the identity credentials structure
    credential = {
        "access_key_id": ak,
        "secret_access_key": sk,
        "service": Service,
        "region": Region,
    }
    # Initialize the signature structure
    request_param = {
        "body": body,
        "host": Host,
        "path": "/",
        "method": method,
        "content_type": ContentType,
        "date": date,
        "query": {"Action": action, "Version": Version, **query},
    }
    if body is None:
        request_param["body"] = ""
    # Step 4: Next, start calculating the signature. Before calculating the signature, prepare the signResult variable to receive the signature result and set some parameters.
    # Initialize the signature result structure
    x_date = request_param["date"].strftime("%Y%m%dT%H%M%SZ")
    short_x_date = x_date[:8]
    x_content_sha256 = hash_sha256(request_param["body"])
    sign_result = {
        "Host": request_param["host"],
        "X-Content-Sha256": x_content_sha256,
        "X-Date": x_date,
        "Content-Type": request_param["content_type"],
    }
    # Step 5: Calculate the Signature.
    signed_headers_str = ";".join(
        ["content-type", "host", "x-content-sha256", "x-date"]
    )
    # signed_headers_str = signed_headers_str + ";x-security-token"
    canonical_request_str = "\n".join(
        [request_param["method"].upper(),
         request_param["path"],
         norm_query(request_param["query"]),
         "\n".join(
             [
                 "content-type:" + request_param["content_type"],
                 "host:" + request_param["host"],
                 "x-content-sha256:" + x_content_sha256,
                 "x-date:" + x_date,
             ]
         ),
         "",
         signed_headers_str,
         x_content_sha256,
         ]
    )

    # Print the canonicalized request for debugging and comparison
    print(canonical_request_str)
    hashed_canonical_request = hash_sha256(canonical_request_str)

    # Print the hash value for debugging and comparison
    print(hashed_canonical_request)
    credential_scope = "/".join([short_x_date, credential["region"], credential["service"], "request"])
    string_to_sign = "\n".join(["HMAC-SHA256", x_date, credential_scope, hashed_canonical_request])

    # Print the final calculated signature string for debugging and comparison
    print(string_to_sign)
    k_date = hmac_sha256(credential["secret_access_key"].encode("utf-8"), short_x_date)
    k_region = hmac_sha256(k_date, credential["region"])
    k_service = hmac_sha256(k_region, credential["service"])
    k_signing = hmac_sha256(k_service, "request")
    signature = hmac_sha256(k_signing, string_to_sign).hex()

    sign_result["Authorization"] = "HMAC-SHA256 Credential={}, SignedHeaders={}, Signature={}".format(
        credential["access_key_id"] + "/" + credential_scope,
        signed_headers_str,
        signature,
    )
    header = {**header, **sign_result}
    # header = {**header, **{"X-Security-Token": SessionToken}}
    # Step 6: Write the Signature into the HTTP Header and send the HTTP request.
    r = requests.request(method=method,
                         url="https://{}{}".format(request_param["host"], request_param["path"]),
                         headers=header,
                         params=request_param["query"],
                         data=request_param["body"],
                         )
    return r.json()


if __name__ == "__main__":
    # response_body = request("Get", datetime.datetime.utcnow(), {}, {}, AK, SK, "ListUsers", None)
    # print(response_body)

    now = datetime.datetime.utcnow()

    data = {
    "app_identity": "volcano_engine_technology",
    "agent": "jd2question",
    "prompt": "关于java垃圾回收机制，给出11个问题每个问题一行,不需要序号",
    "is_stream": False
    }
    response_body = request(
        "POST", now, {}, {}, AK, SK, "GetQuestionsByLLMAndJD", json.dumps(data)
    )
    print(response_body)

API call #

Given Action and Version, the API call method is as follows

curl --location 'https://open.volcengineapi.com?Action={Action}&Version={Version}' \
--header 'Authorization: HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}' \
--header 'ServiceName: las' \
--header 'Content-Type: application/json' \
--data '{
  "app_identity": "volcano_engine_technology",
   "scene": 2,
  "prompt": "关于java内存模型，给出10个问题每个问题一行"
}'

The APIs for this release are as follows

Data-related APIs #

Dynamically update the RAG cache

• Action: InsertRagFaq

• Version: 2024-06-30

• Method: post

• Body parameters:

  Parameter	Type	Description	Example
  app_identity	string	Represents the tenant identifier	Tenant name, for example: volcano_engine_technology
  question	int	Represents the question	What is rag?
  answer	string	Represents the standard answer	rag is a good LLM conversational engineering framework.

• Return result:

  Parameter	Type	Description	Example
  code	int	Indicates success or failure	200: Success Non-200: Failure
  msg	string	Success or failure message	"Insert successful"

Conversation service-related APIs #

Generate conversation chat ID

• Action: NewChat

• Version: 2024-06-30

• Method: post

• Body parameters:

  Parameter	Type	Description	Example
  app_identity	string	Represents the tenant identifier	Tenant name, for example: volcano_engine_technology
  username	string	Username	"Jack@hotmail.com"

• Return result:

  Parameter	Type	Description	Example
  code	int	Indicates success or failure	200: Success Non-200: Failure
  msg	string	Success or failure message	"Call successful"
  data	{}	Result data	{"chat_id":"66711ab1b97cdfd66f1c32e5"}

Conversation service

• Action: CommonChat

• Version: 2024-06-30

• Method: post

• Body parameters:

  Parameter	Type	Description	Example
  app_identity	string	Represents the tenant identifier	Tenant name, for example: volcano_engine_technology
  chat_id	string	Represents a session_id for a conversation, which can be obtained via the chat_id generation API	xxxxxxx
  is_stream	bool	Indicates whether streaming response is enabled	True: Streaming response, similar to chatgpt, returns one character at a time False: Synchronous response, returns all output from the llm at once after completion
  history	[ {question: str, answer: str} ]	Array of historical conversations, excluding the latest user input	[ { "question": "Start java quiz", "answer": "Welcome to our mock interview session. We hope you can show your best self. Now, let us begin: What is the difference between JPA and Hibernate in Spring Boot?" }, { "question": "Not very familiar with this part", "answer": "Although your answer is not detailed enough, acknowledging your own shortcomings is also a strength. We hope you can gain a deeper understanding of this question in your future studies. Next question: In Spring MVC, what is the 'convention over configuration' principle of MVC?" }, { "question": "Convention is more standardized than configuration and requires much less code", "answer": "Your answer has captured the core idea of the 'convention over configuration' principle. Keep it up! Next question: What is the difference between Spring Cloud and Spring Boot?" } ]
  question	string	Latest user input	"I haven't used this much"
  chat_type	string	Conversation type, ["single", "multi"], default is multi	multi

• Return result: There are two types to distinguish:

  • Non-streaming return:

    Parameter	Type	Description	Example
    code	int	Indicates success or failure	200: Success Non-200: Failure
    msg	string	Success or failure message	"Call successful"
    data	{}	Result data	{"answer":""}

  • Streaming return:

    Parameter	Type	Description	Example
    data	string	A streaming string in JSON format; in this case, SSE is returned.	{"logid": "2024061813343101003702602494498", "choices": [{"delta": {"content": "\u4f60"}, "type": "knowledge", "stream": true, "done": false, "references": [], "answer_source": "doc"}]}