更新时间:2024-10-16 GMT+08:00
分享

调用AI助手API

获取AI助手API调用地址

  1. 登录盘古大模型套件平台。
  2. 左侧导航栏选择“应用开发 > AI助手”,选择需要运行的AI助手,单击“查看”。
    图1 查看AI助手
  3. 在详情页面,AI助手API调用地址。
    图2 获取调用地址

获取Token

本示例中,通过使用Postman软件获取Token。

  1. 登录“我的凭证 > API凭证”页面,获取user name、domain name、project id。
    由于Assistant当前部署在“西南-贵阳一”区域,需要获取与“西南-贵阳一”区域对应的project id。
    图3 获取user name、domain name、project id
  2. 打开Postman,新建一个POST请求,并输入“西南-贵阳一”区域的“获取Token”接口。并填写请求Header参数。
    • 接口地址:https://iam.cn-southwest-2.myhuaweicloud.com/v3/auth/tokens
    • 请求Header参数名为Content-Type,参数值为application/json。
    图4 填写获取Token接口
  3. 填写“获取token”接口的请求体。在Postman中选择“Body > raw”选项,参考图5复制并填入以下代码,并填写user name、domain name、password。
    { 
        "auth": { 
            "identity": { 
                "methods": [ 
                    "password" 
                ], 
                "password": { 
                    "user": { 
                        "name": "username", //IAM用户名
                        "password": "********", //华为云账号密码
                        "domain": { 
                            "name": "domainname" //账号名
                        } 
                    } 
                } 
            }, 
            "scope": { 
                "project": { 
                    "name": "cn-southwest-2" //服务当前部署在“西南-贵阳一”区域,取值为cn-southwest-2
                } 
            } 
        } 
    }
    图5 填写请求Body
  4. 单击Postman界面“Send”按钮,发送请求。当接口返回状态为201时,表示Token接口调用成功,此时单击“Headers”选项,找到并复制“X-Subject-Token”参数对应的值,该值即为需要获取的Token。
    图6 获取Token

调用AI助手API

本示例中,通过使用Postman软件调用AI助手API,API的详细请求参数、响应参数介绍请参见AI助手API参数说明

  1. 打开Postman,新建一个POST请求,在地址栏填写获取AI助手API调用地址获取的调用地址。
  2. 在Header中配置IAM Token信息。
    • 请求Header参数名为X-Auth-Token,参数值为获取Token获取的token值。
    • 请求Header参数名为Content-Type,参数值为application/json。
    图7 构造请求
  3. 在Body中填写请求消息体。
    {
      "messages": [
        {
          "role": "user",
          "contents": [
            {
              "type": "text",
              "content": "帮我定个今天下午3点到8点金桥2303会议室"
            }
          ]
        }
      ],
      "assistant_running_param": {
        "instructions": "你是一个会议室预定助手,可以帮助员工预定会议室",
        "additional_instructions": "当前的日期为2024-1-25"
      }
    }
    图8 填写请求Body
  4. 查看请求调用结果。

    单击“Send”发送请求,请求调用成功后,查看返回结果。

    响应示例代码:

    {
        "assistant_session_id": "test_session_1",
        "assistant_id": "6c8eb381-2c34-4ebc-bcf4-3fccb703c977",
        "required_action": {  # 给出了Assistant的思考
            "action_id": "c7669ea3-1abd-4d17-aa67-5df19bf3aba5",
            "message_id": "07daf8d9-38a8-460c-8068-3ff420e76c8d",
            "thought": "好的,我需要先查询会议室的状态,然后才能帮您预定。现在开始查询会议室状态。",
            "tool_invoking": [
                {
                    "tool_invoking_id": "bdf4f51f-ee58-4a10-8b13-35d45c3ddbe4",
                    "action_id": "c7669ea3-1abd-4d17-aa67-5df19bf3aba5",
                    "tool_id": "meeting_room_status_query",
                    "tool_input": "{\"start\": \"2024-01-25 15:00\", \"end\": \"2024-01-25 20:00\", \"meetingRoom\": \"金桥2303\"}",
                    "metadata": "{\"url\":\"https://host/v1/api\",\"authType\":\"OAuth\"}",
                }
            ],
            "required": true,
            "usage": {
                "input_tokens": 589,
                "output_tokens": 85,
                "cost": 2941
            }
        },
        "assistant_messages": [
            {
                "message_id": "07daf8d9-38a8-460c-8068-3ff420e76c8d",
                "assistant_session_id": "test_session_1",
                "role": "assistant",
                "contents": [
                    {
                        "type": "text",
                        "content": ""
                    }
                ],
                "actions": [
                    {
                        "action_id": "c7669ea3-1abd-4d17-aa67-5df19bf3aba5",
                        "message_id": "07daf8d9-38a8-460c-8068-3ff420e76c8d",
                        "thought": "好的,我需要先查询会议室的状态,然后才能帮您预定。现在开始查询会议室状态。",
                        "tool_invoking": [
                            {
                                "tool_invoking_id": "bdf4f51f-ee58-4a10-8b13-35d45c3ddbe4",
                                "action_id": "c7669ea3-1abd-4d17-aa67-5df19bf3aba5",
                                "tool_id": "meeting_room_status_query",
                                "tool_input": "{\"start\": \"2024-01-25 15:00\", \"end\": \"2024-01-25 20:00\", \"meetingRoom\": \"金桥2303\"}",
                                "metadata": "{\"url\":\"https://host/v1/api\",\"authType\":\"OAuth\"}"
                            }
                        ],
                        "required": true,
                        "usage": {
                            "input_tokens": 589,
                            "output_tokens": 85,
                            "cost": 2941
                        }
                    }
                ]
            }
        ],
        "status": "requires_action"  # status为requires_action表示他需要对这个action进行反馈,required_action中给出了Assistant的思考
    }

AI助手API参数说明

  • 请求参数
    表1 请求Header参数

    参数

    是否必选

    参数类型

    描述

    X-Auth-Token

    String

    用户Token,通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)。

    Content-Type

    String

    发送的实体的MIME类型,参数值为“application/json”。

    表2 请求Body参数

    参数

    是否必选

    参数类型

    描述

    messages

    Array of messages objects

    对话信息,包含两个属性:role和content。

    assistant_running_param

    Json Schema

    用于更改AI助手的指令。包含instructions和additional_instructions两个参数。

    • instructions:AI助手的描述信息。
    • additional_instructions:用于在当前会话中向AI助手中补充附加信息,例如与用户查询问题相关的上下文信息。
    表3 messages

    参数

    是否必选

    参数类型

    描述

    content

    String

    表示对话的内容,对话内容为文本(text)类型。

    role

    String

    表示对话的角色,取值是user。

  • 响应参数
    表4 响应Body参数

    参数

    参数类型

    描述

    assistant_session_id

    String

    运行AI助手时的会话id。

    assistant_id

    String

    AI助手id。

    required_action

    Object

    表5 required_action

    AI助手的思考过程。

    assistant_messages

    Json Schema

    会话信息。

    status

    String

    会话状态。status为requires_action,表示需要对action进行反馈,required_action中给出了Assistant的思考。

    表5 required_action

    参数

    参数类型

    描述

    action_id

    String

    动作id。

    message_id

    String

    信息id。

    thought

    String

    AI助手基于思考做出的反馈。

    tool_invoking

    Array tool_invoking

    AI助手所调用的工具信息。

    required

    String

    请求状态。

    usage

    Json Schema

    大模型使用情况。

    表6 tool_invoking

    参数

    参数类型

    描述

    tool_invoking_id

    String

    工具调用id。

    action_id

    String

    动作id。

    tool_id

    String

    工具id。

    tool_output

    String

    调用工具产生的输出结果。

    metadata

    String

    调用接口信息。

相关文档