技能私有化对话API文档

简介

Hi，您好，欢迎使用百度智能对话定制与服务平台（UNIT）私有化部署产品

UNIT私有化部署包部署成功后，即可获得与在线API基本完全相同的接口，相关接口将会启动，即可参考本文档开始调用测试。如果您对文档内容有任何疑问，可以通过以下几种方式联系我们：

1. 在百度云控制台内提交工单，工单类型请选择人工智能-智能对话定制与服务平台UNIT服务；
2. 进入UNIT开发者论坛发帖交流；

文档约定

参数结构约定

• 所有参数都使用 UTF8 编码
• 输入、输出中，所有offset、begin、length字段的单位为字符（编码无关）

对话接口描述

基于用户输入的文本内容（语音输入最终也转为文本），返回技能理解与应答的信息。调用本对话API的前提是您已经完成了UNIT的私有化部署。

请求说明

HTTP方法：POST

请求URL：http://{IP}:{PORT}/unit/bot/chat

注：IP是部署服务的机器IP，PORT是对话服务的端口号

Header如下：

Body中放置请求参数，参数详情如下：

请求参数说明

请求参数详细说明

bot_id

• 登录unit.baidu.com,新建技能后在【我的技能】列表中可看到技能ID，如下图：

request.user_id

• 开发者为其用户分配的id，用于区别开发者的每个最终用户。
• UNIT保留两种形式的id，开发者在为最终用户分配id时应当避免分配这些形式的id。

request.query_info

request.query：本轮请求query

• query_info.type为TEXT时，为常规的文本型query
• query_info.type为EVENT时，代表query是一个事件，事件为一组K-V（json），且其中必须包含一个名为『event_name』的key，其他自便。

• 我们预定义三种event_name及对应的数据格式： "CHOOSE","@UNIT"和"RESET"

  • CHOOSE：用户点击了一个界面选择项，比如用户选择技能让用户澄清的多个选项中的一个，技能：有两首您想听的歌，你想听哪首--1……，2……；USER：第1首。

    key	类型	说明
    event_name	string	=CHOICE
    interaction_id	string	选项来自哪个interaction_id（会由技能返回）
    index	string	点击了第几个选项（从1开始）

  • @UNIT：发起对上轮意图/词槽/问答对的干预

    key	类型	说明
    event_name	string	=@UNIT
    （此处不需要其他数据，干预信息从updates字段传入）	-	-

    （通过@UNIT和updates字段配合传入的干预信息会被平台记录下来，可以在对话日志→反馈学习界面中查看和操作。注意，updates字段传入的干预信息要和当前模型版本的schema一致，否则不保证结果的正确性。）

  • RESET：清空session，即重置会话状态，会清空当前技能已存储的意图与词槽信息。

    key	类型	说明
    event_name	string	=RESET

request.updates

request.updates：干预操作信息

• target为INTENT时，value为一个string，代表要干预的意图。

• target为SLOT时，value为一个object，代表要干预的词槽：

  • op当前仅支持DEFINE，value格式为：

    key	类型	说明
    begin	int	如果是query中不包含的词槽（如GPS位置信息等），取值-1
    length	int	如果是query中不包含的词槽（如GPS位置信息等），取值-1
    original_word	string	词槽值
    normalized_word	string	归一化后的词槽值（标准表达）
    word_type	string	预留字段
    name	string	词槽名

request.client_session

request.client_session：用于在多轮中实现多选一的对话效果，查看详细使用说明。

• 使用这个字段它必须包含两个key，它们是client_results和candidate_options（值可以分别设为空串和空list）
• 注意client_session 字段的类型是string，传入的K-V结构数据需要转义成字符串。例如："client_session": "{\"client_results\":\"\", \"candidate_options\":[]}"

candidate_options详细介绍：

示例格式：

{
  "attributes": {
    "attr_name_1": "attr_value_1",
    "attr_name_2": "attr_value_2"
  },
  "slot_updates": {
    "slot_name_1": "slot_value_1",
    "slot_name_2": "slot_value_2"
  },
  "remember": true
}

对于每个候选项，attributes、slot_updates、remember三个key，分别说明如下： | key|类型|说明| | ---|---|---| | attributes|object|一组kv，记录该候选的若干属性及属性值，attr_name可自行设定，attr_value支持int、float和string类型的值，如：{"movie_name":"花样年华", "year":1998, "actor":"梁朝伟"}| | slot_updates|object|用户提供的候选项所对应的词槽，即选择成功以后会加入到解析结果中的词槽信息,如：{"user_movie": "花样年华1998"}| | remember|bool|optional,是否对当前结果进行记录，解析相同query时，默认选择同一结果|

利用session_id实现多轮对话

bot_session.session_id：会话ID

• 历史会话信息bot_session会在平台中保留30分钟

• 当前请求中的bot_session.session_id与保留中的某个会话相同时，当前会话将继承历史会话的意图和词槽信息以及对话状态，来实现多轮对话。

  • 您可以单独上轮响应的session_id值，bot_session字段的类型是string，传入K-V结构的数据需要先转化成json字符串，然后需要对该json字符串转义成string类型后传入该字段，例如："bot_session": "{\"session_id\":\"value\"}"
  • 也可以传入上轮响应的bot_session值，上轮响应的bot_session值已经是转义好的数据，不需要开发者再次进行转义。
• 当前请求中的bot_session.session_id无法从历史会话信息中匹配到相同结果时，将开启一次新的会话。

响应参数说明

响应参数详细说明

response_list[].action_list[].custom_reply

• 用户自定义应答，如果action_type为event，对应事件定义在此处。

• 这里预定义一个event，对应『执行函数』动作：

  key	类型	说明
  event_name	string	=EXEC
  func	string	具体执行函数

result.response.action_list[].refine_detail.option_list[].info

这个字段是一个kvdict，我们预定义2种格式：

• result.response.action_list[].type 为 clarify 时

  Key	类型	说明
  name	string	意图、词槽的英文名
  text	string	意图、词槽的中文描述
  value	string optional	词槽值（仅针对词槽）

• result.response.action_list[].type 为 guide/faqguide 时

  Key	类型	说明
  next_expect_intent	String	下一意图

请求示例代码

提示一：使用示例代码前，请记得替换其中的示例IP、PORT、Token、请求参数等信息。

提示二：部分语言依赖的类或库，请在代码注释中查看下载地址。

提示三：私有化不校验access_token，可以传空或任意字符串。

  package com.baidu.ai.aip.unit;
  import com.baidu.ai.aip.utils.HttpUtil;
  /*
   * unit对话服务
   */
  public class UnitService {
      /**
       * 重要提示代码中所需工具类
       * FileUtil,Base64Util,HttpUtil,GsonUtils请从
       * https://ai.baidu.com/file/658A35ABAB2D404FBF903F64D47C1F72
       * https://ai.baidu.com/file/C8D81F3301E24D2892968F09AE1AD6E2
       * https://ai.baidu.com/file/544D677F5D4E4F17B4122FBD60DB82B3
       * https://ai.baidu.com/file/470B3ACCA3FE43788B5A963BF0B625F3
       * 下载
       */
      private static String utterance() {
          // 请求URL
          String talkUrl = "http://{IP}:{PORT}/unit/bot/chat";
          try {
              // 请求参数
              String params = "{\"bot_session\":\"\",\"log_id\":\"7758521\",\"request\":{\"bernard_level\":1,\"client_session\":\"{\\\"client_results\\\":\\\"\\\", \\\"candidate_options\\\":[]}\",\"query\":\"你好\",\"query_info\":{\"asr_candidates\":[],\"source\":\"KEYBOARD\",\"type\":\"TEXT\"},\"updates\":\"\",\"user_id\":\"88888\"},\"bot_id\":\"1057\",\"version\":\"2.0\"}";
              String accessToken = "";
              String result = HttpUtil.post(talkUrl, accessToken, "application/json", params);
              return result;
          } catch (Exception e) {
              e.printStackTrace();
          }
          return null;
      }
      public static void main(String[] args) {
          utterance();
      }
  }

  var https = require('https');
  var qs = require('querystring');
  var param = qs.stringify({
      'access_token': ''
  });
  var options = {
      hostname: 'aip.baidubce.com',
      path: '/rpc/2.0/unit/bot/chat?' + param,
      method: 'POST',
      headers: {
          'Content-Type': 'application/json; charset=UTF-8'
      }
  };
  var req = https.request(
      options,
      function (res) {
          // 在标准输出中查看运行结果
          res.pipe(process.stdout);
      }
  );
  var postData = {
      'log_id': '7758521',
      'version': '2.0',
      'request': {
          'user_id': '88888',
          'query_info': {
              'asr_candidates': [],
              'type': 'TEXT',
              'source': 'KEYBOARD'
           },
           'bernard_level': 1,
           'updates': '',
           'query': '你好',
           'client_session': '{"client_results":"", "candidate_options":[]}'
      },
      'bot_session': '',
      'bot_id': '1057'
  };
  // 携带数据发送https请求
  req.write(JSON.stringify(postData));
  req.end();

  <?php
  /**
   * 发起http post请求(REST API), 并获取REST请求的结果
   * @param string $url
   * @param string $param
   * @return - http response body if succeeds, else false.
   */
  function request_post($url = '', $param = '')
  {
      if (empty($url) || empty($param)) {
          return false;
      }
      $postUrl = $url;
      $curlPost = $param;
      // 初始化curl
      $curl = curl_init();
      curl_setopt($curl, CURLOPT_URL, $postUrl);
      curl_setopt($curl, CURLOPT_HEADER, 0);
      // 要求结果为字符串且输出到屏幕上
      curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
      curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
      // post提交方式
      curl_setopt($curl, CURLOPT_POST, 1);
      curl_setopt($curl, CURLOPT_POSTFIELDS, $curlPost);
      // 运行curl
      $data = curl_exec($curl);
      curl_close($curl);
      return $data;
  }
  $token = '';
  $url = 'http://{IP}:{PORT}/unit/bot/chat?access_token=' . $token;
  $bodys = '{"bot_session":"","log_id":"7758521","request":{"bernard_level":1,"client_session":"{\"client_results\":\"\", \"candidate_options\":[]}","query":"你好","query_info":{"asr_candidates":[],"source":"KEYBOARD","type":"TEXT"},"updates":"","user_id":"88888"},"bot_id":"1057","version":"2.0"}';
  $res = request_post($url, $bodys);
  var_dump($res);

  # encoding:utf-8
  import requests
  
  access_token = ''
  url = 'http://{IP}:{PORT}/unit/bot/chat'
  post_data = "{\"bot_session\":\"\",\"log_id\":\"7758521\",\"request\":{\"bernard_level\":1,\"client_session\":\"{\\\"client_results\\\":\\\"\\\", \\\"candidate_options\\\":[]}\",\"query\":\"你好\",\"query_info\":{\"asr_candidates\":[],\"source\":\"KEYBOARD\",\"type\":\"TEXT\"},\"updates\":\"\",\"user_id\":\"88888\"},\"bot_id\":\"1057\",\"version\":\"2.0\"}"
  headers = {'content-type': 'application/x-www-form-urlencoded'}
  response = requests.post(url, data=post_data, headers=headers)
  if response:
      print (response.json())

  using System;
  using System.Collections.Generic;
  using System.IO;
  using System.Net;
  using System.Text;
  using System.Web.Script.Serialization;
  using System.Net.Http;
  namespace com.baidu.ai
  {
      public class Utterance
      {
          // unit对话接口
          public static string unit_utterance()
          {
              string token = "";
              string host = "http://{IP}:{PORT}/unit/bot/chat";
              HttpWebRequest request = (HttpWebRequest)WebRequest.Create(host);
              request.Method = "post";
              request.ContentType = "application/json";
              request.KeepAlive = true;
              string str = "{\"bot_session\":\"\",\"log_id\":\"7758521\",\"request\":{\"bernard_level\":1,\"client_session\":\"{\\\"client_results\\\":\\\"\\\", \\\"candidate_options\\\":[]}\",\"query\":\"你好\",\"query_info\":{\"asr_candidates\":[],\"source\":\"KEYBOARD\",\"type\":\"TEXT\"},\"updates\":\"\",\"user_id\":\"88888\"},\"bot_id\":\"1057\",\"version\":\"2.0\"}"; // json格式
              byte[] buffer = Encoding.UTF8.GetBytes(str);
              request.ContentLength = buffer.Length;
              request.GetRequestStream().Write(buffer, 0, buffer.Length);
              HttpWebResponse response = (HttpWebResponse)request.GetResponse();
              StreamReader reader = new StreamReader(response.GetResponseStream(), Encoding.UTF8);
              string result = reader.ReadToEnd();
              Console.WriteLine("对话接口返回:");
              Console.WriteLine(result);
              return result;
          }
      }
  }

  #include <iostream>
  #include <curl/curl.h>
  // libcurl库下载链接：https://curl.haxx.se/download.html
  // unit对话接口url
  const static std::string get_utterance_url = "http://{IP}:{PORT}/unit/bot/chat";
  static std::string s_get_utterance_result;
  /**
   * curl发送http请求调用的回调函数，回调函数中对返回的json格式的body进行了解析，解析结果储存在全局的静态变量当中
   * @param 参数定义见libcurl文档
   * @return 返回值定义见libcurl文档
   */
  static size_t callback(void *ptr, size_t size, size_t nmemb, void *stream) {
      // 获取到的body存放在ptr中，先将其转换为string格式
      s_get_utterance_result = std::string((char *) ptr, size * nmemb);
      return size * nmemb;
  }
  /**
   * 调用对话接口，返回int格式的结果，具体格式解析见百度大脑文档
   * @param json_result 以string格式返回的json格式的结果
   * @param json_request_body 以string格式传递的json数据（如：{"bot_session":"","log_id":"7758521","request":{"bernard_level":1,"client_session":"{\"client_results\":\"\", \"candidate_options\":[]}","query":"你好","query_info":{"asr_candidates":[],"source":"KEYBOARD","type":"TEXT"},"updates":"","user_id":"88888"},"bot_id":"1057","version":"2.0"}; // json格式 ）
   * @param access_token 以string格式传入的access token数据，access token获取方式见access_token获取相关文档及代码
   * @return 调用成功返回0，发生错误返回其他错误码
   */
  int unit_utterance(std::string &json_result, const std::string json_request_body,
               const std::string &access_token) {
      std::string url = get_utterance_url + "?access_token=" + access_token;
      CURL *curl = NULL;
      CURLcode result_code;
      int is_success = 0;
      curl = curl_easy_init();
      if (curl) {
          curl_easy_setopt(curl, CURLOPT_URL, url.data());
          curl_easy_setopt(curl, CURLOPT_POST, 1);
          curl_slist *headers = NULL;
          headers = curl_slist_append(headers, "Content-Type:application/json;charset=UTF-8");
          curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
          curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json_request_body.data());
          curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, callback);
          result_code = curl_easy_perform(curl);
          if (result_code != CURLE_OK) {
              fprintf(stderr, "curl_easy_perform() failed: %s\n",
                      curl_easy_strerror(result_code));
              is_success = 1;
              return is_success;
          }
          json_result = s_get_utterance_result;
          curl_easy_cleanup(curl);
          is_success = 0;
      } else {
          fprintf(stderr, "curl_easy_init() failed.");
          is_success = 1;
      }
      return is_success;
  }

  ``` shell
  #!/bin/bash
  curl -i -k 'http://{IP}:{PORT}/unit/bot/chat' --data '{"bot_session":"","log_id":"7758521","request":{"bernard_level":1,"client_session":"{\"client_results\":\"\", \"candidate_options\":[]}","query":"你好","query_info":{"asr_candidates":[],"source":"KEYBOARD","type":"TEXT"},"updates":"","user_id":"88888"},"bot_id":"1057","version":"2.0"}'

错误信息