技能对话API接口2.0

2.0版本已停止日常维护，建议使用3.0版本。

简介

Hi，您好，欢迎使用百度智能对话定制与服务平台（UNIT）技能对话API服务。

本文档主要针对API开发者，描述百度智能对话定制与服务平台技能对话接口服务的相关内容。如果您对文档内容有任何疑问，可以通过以下几种方式联系我们：

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

文档约定

参数结构约定

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

对话接口描述

基于用户输入的文本内容（语音输入最终也转为文本），返回技能理解与应答的信息。调用本对话API的前提是您已经在unit.baidu.com 已经创建了技能，并定义了技能（新建了对话意图或问答意图）、添加了对话模板/对话样本，且最少完成了一次模型的训练。

请求说明

HTTP方法：POST

请求URL：

• 沙盒环境
  【不区分机房】https://aip.baidubce.com/rpc/2.0/unit/bot/chat
• 生产环境
  【华北机房】https://unit.bj.baidubce.com/rpc/2.0/unit/bot/chat
  【华东机房】https://unit.su.baidubce.com/rpc/2.0/unit/bot/chat
  【华南机房】https://unit.gz.baidubce.com/rpc/2.0/unit/bot/chat
  【全国域名】https://unit-api.baidu.com/rpc/2.0/unit/bot/chat
• 注意：

1. 生产环境域名需将技能部署到生产环境后才可使用。
2. 若多技能有生产环境，建议购买、部署到同一机房。
3. 全国域名还在开发中，目前支持华北机房，若有其他需求，可与客服沟通。

URL参数：

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，分别说明如下：

利用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	下一意图

请求示例代码

提示一：使用示例代码前，请记得替换其中的示例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 = "https://aip.baidubce.com/rpc/2.0/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 = "#####调用鉴权接口获取的token#####";
            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': '您的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 = '#####调用鉴权接口获取的token#####';
$url = 'https://aip.baidubce.com/rpc/2.0/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 = '#####调用鉴权接口获取的token#####'
url = 'https://aip.baidubce.com/rpc/2.0/unit/bot/chat?access_token=' + access_token
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 = "#####调用鉴权接口获取的token#####";
            string host = "https://aip.baidubce.com/rpc/2.0/unit/bot/chat?access_token=" + token;
            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 = "https://aip.baidubce.com/rpc/2.0/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;
}

#!/bin/bash
curl -i -k 'https://aip.baidubce.com/rpc/2.0/unit/bot/chat?access_token={access_token}' --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"}'

错误信息