机器人对话API文档

简介

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/service/chat
• 生产环境
  【华北机房】https://unit.bj.baidubce.com/rpc/2.0/unit/service/chat
  【华东机房】https://unit.su.baidubce.com/rpc/2.0/unit/service/chat
  【华南机房】https://unit.gz.baidubce.com/rpc/2.0/unit/service/chat
  【全国域名】https://unit-api.baidu.com/rpc/2.0/unit/service/chat

注：全国域名包含三地域三运营商的IP接入，不需要自己解决三个地域的流量调度问题。在某个接入点异常或者用户到接入点之间的骨干网异常时，该域名能够自动切换至其他地域的接入点（前提是目标地域有部署生产环境），在最大程度上减少对话调用异常。

URL参数：

Header如下：

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

请求参数说明

请求参数详细说明

service_id与skill_ids的组合关系

在一次请求中，service_id与skill_ids两者可以组合使用，不同的组合关系所代表的语义如下表。

利用session_id实现多轮对话

session保存了历史会话信息，随着对话的进行，在客户端和UNIT之间来回传递，并且被不断更新。理论上客户端与UNIT双方都可以对session进行更新与修改，然而，多数开发者并没有修改session的需求，而session数据的体量偏大，又对网络传输的流量与延时产生了额外的压力。

为了解决这一矛盾，UNIT支持基于session_id的会话托管：客户端在首轮对话时传入一个空的session_id字段，在应答阶段，UNIT会把会话信息托管在云端并且为其分配一个session_id。在后续对话中，客户端只需要继续传入这个session_id，并在dialog_state.contexts["SYS_REMEMBERED_SKILLS"]中设定一个技能ID列表，避免处于列表中的技能session被清空，就可以基于历史会话信息与机器人进行多轮对话，而无需接触复杂的原始session。

总结起来，开发者可以选择以下两种方式与机器人对话API进行多轮对话：

• 方式１：客户端在首轮会话时以“session”为key传入一个空串，UNIT会在应答中以“session”为key，返回原始的会话数据（一个json字符串）。如需进行多轮对话，客户端在后续对话中以“session”为key，继续传送前轮返回的会话数据。在这种方式下，开发者可以对会话数据做出自己想要的修改（只要符合UNIT的格式要求）。
• 方式2：客户端在首轮会话时以“session_id”为key传入一个空串，UNIT会把会话数据托管在云端，在应答中以“session_id”为key，返回一个用于指代云端的会话数据的ID号。如需进行多轮对话，客户端在后续对话中以“session_id”为key，继续传送前轮返回的ID号。在这种方式下，开发者没有办法修改会话数据。
• 另外需要在dialog_state.contexts["SYS_REMEMBERED_SKILLS"]中设定一个技能ID列表，避免处于列表中的技能session被清空，导致无法完成多轮对话。

无论以上哪种方式，只要传入一个空的session_id或者session字段，即代表不再继承历史会话信息，后续将开始新的对话。

dialog_state.contexts

dialog_state.contexts字段以一个开放的json对象存储所有与对话相关的上下文信息。我们当前预留了一个key，用于开发者控制各个技能的session记忆，如下表：

request.user_id

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

request.query_info

request.query：本轮请求query

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

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

  • CHOICE：用户点击了一个界面选择项

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

  • @UNIT：发起对上轮意图/词槽/问答对的干预[机器人级的干预功能正在开发中，当前暂不支持]

  • RESET：清空session。

    key	类型	说明
    event_name	string	=RESET

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

响应参数说明

响应参数详细说明

response_list的排序规则

排序分为三轮完成。

第一轮：如果请求中传递了skill_ids，按照skill_ids的顺序排列。否则，按照机器人配置的技能优先级排列。

第二轮：从前到后遍历第一轮排序结果：

​如果某个技能应答的action_list[0].id与其上一轮应答（如有）相同，且action_list[0].type为"clarify"，该技能的应答移到末尾。

​ 本轮排序的目的是避免低优先级技能对新请求的有效应答被高优先级技能的重复澄清覆盖掉。

第三轮：从前到后遍历第二轮排序结果

​ 如果某个技能的action_list[0].type为failure，该技能的应答移到末尾。

注：UNIT网站的机器人对话体验窗口中，每次对话展现的是response_list的第一个应答，在新一轮请求中记忆产出该应答的技能session。

response_list[].action_list[].custom_reply

• 用户自定义应答，如果action_type为event，对应事件定义在此处。
• 这里预定义一个event，对应『执行函数』动作：

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

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

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

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

请求示例代码

提示一：使用示例代码前，请记得替换其中的示例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/service/chat";
        try {
            // 请求参数
            String params = "{\"log_id\":\"UNITTEST_10000\",\"version\":\"2.0\",\"service_id\":\"S10000\",\"session_id\":\"\",\"request\":{\"query\":\"你好\",\"user_id\":\"88888\"},\"dialog_state\":{\"contexts\":{\"SYS_REMEMBERED_SKILLS\":[\"1057\"]}}}";
            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();
    }
}

/*
 * Copyright (C) 2018 Baidu, Inc. All Rights Reserved.
 */
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/service/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': 'UNITTEST_10000',
    'version': '2.0',
    'service_id': 'S10000',
    'session_id': '',
    'request': {
        'query': '你好',
        'user_id': '88888'
    },
    'dialog_state': {
        'contexts': {
            'SYS_REMEMBERED_SKILLS': ['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/service/chat?access_token=' . $token;
$bodys = '{"log_id":"UNITTEST_10000","version":"2.0","service_id":"S10000","session_id":"","request":{"query":"你好","user_id":"88888"},"dialog_state":{"contexts":{"SYS_REMEMBERED_SKILLS":["1057"]}}}';
$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/service/chat?access_token=' + access_token
post_data = "{\"log_id\":\"UNITTEST_10000\",\"version\":\"2.0\",\"service_id\":\"S10000\",\"session_id\":\"\",\"request\":{\"query\":\"你好\",\"user_id\":\"88888\"},\"dialog_state\":{\"contexts\":{\"SYS_REMEMBERED_SKILLS\":[\"1057\"]}}}"
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/service/chat?access_token=" + token;
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(host);
            request.Method = "post";
            request.ContentType = "application/json";
            request.KeepAlive = true;
            string str = "{\"log_id\":\"UNITTEST_10000\",\"version\":\"2.0\",\"service_id\":\"S10000\",\"session_id\":\"\",\"request\":{\"query\":\"你好\",\"user_id\":\"88888\"},\"dialog_state\":{\"contexts\":{\"SYS_REMEMBERED_SKILLS\":[\"1057\"]}}}"; // 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/service/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数据（如：{"log_id":"UNITTEST_10000","version":"2.0","service_id":"S10000","session_id":"","request":{"query":"你好","user_id":"88888"},"dialog_state":{"contexts":{"SYS_REMEMBERED_SKILLS":["1057"]}}}; // 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/service/chat?access_token={access_token}' --data '{"log_id":"robotTest_12345","version":"2.0","service_id":"S10000","session_id":"","request":{"query":"你好","user_id":"88888"},"dialog_state":{"contexts":{"SYS_REMEMBERED_SKILLS":["1057"]}}}'

错误信息

点此查看