对话API接口3.0

简介

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

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

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

文档约定

参数结构约定

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

对话接口描述

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

请求说明

HTTP方法：POST

请求URL：

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

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

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。

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

• 客户端在首轮会话时以“session_id”为key传入一个空串，UNIT会把会话数据托管在云端，在应答中以“session_id”为key，返回一个用于指代云端的会话数据的ID号。如需进行多轮对话，客户端在后续对话中以“session_id”为key，继续传送前轮返回的ID号。在这种方式下，开发者没有办法修改会话数据。

注意：

• 只要传入一个空的session_id，即代表不再继承历史会话信息，后续将开始新的对话。
• session_id的有效期为30分钟，多轮对话间隔超过30分钟需重新开始对话。

context

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

SYS_CHAT_HIST参数使用示例格式：

• SYS_CHAT_HIST中传入的最后一个问句需要与query一致。比如：第一轮，query是“你好”，SYS_CHAT_HIST传入“你好”；第二轮，query是“今天天气怎样”，SYS_CHAT_HIST传入的是“你好”“你也好啊”“今天天气怎样”这三条数据。

"context": {
    "SYS_REMEMBERED_SKILLS": [],
    "SYS_CHAT_HIST": [
        "问句1",
        "回复1",
        "问句2",
        "回复2",
        "问句3"
    ]
}

request.terminal_id

• 开发者为其用户分配的id，用于区别开发者的每个最终用户。

request.query_info

request.query：本轮请求query

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

request.client_options

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

client_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"
  },
}

对于每个候选项，attributes、slot_updates两个key，分别说明如下：

request.updates

request.updates：干预操作信息

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

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

  • op当前支持DEFINE，ADD，REMOVE三种方式（当updates.type为「DEFINE」时，支持「DEFINE」；当updates.type为「MODIFY」时，支持「ADD」，「REMOVE」），value格式为：

  • 当op为「DEFINE」或「ADD」时，value格式为：

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

  • 当op为「REMOVE」时，根据index_mode参数取值的不同，value格式有以下两种为：

    • 当index_mode为SPAN时，value格式为：

    key	类型	说明
    index_mode	string enum	index_mode取值SPAN
    begin	int	如果是query中不包含的词槽（如GPS位置信息等），取值-1
    length	int	如果是query中不包含的词槽（如GPS位置信息等），取值-1

    • 当index_mode为NAME时，value格式为：

    key	类型	说明
    index_mode	string enum	index_mode取值NAME
    name	string	词槽名

响应参数说明

响应参数详细说明

response_list的排序规则

排序分为三轮完成。

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

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

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

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

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

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

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

responses[].actions[].custom_reply

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

result.responses[].actions[].options[].info

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

• result.response.actions[].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/v3/chat";
        try {
            // 请求参数
            String params = "{\"version\":\"3.0\",\"service_id\":\"S10000\",\"session_id\":\"\",\"log_id\":\"7758521\",\"request\":{\"terminal_id\":\"88888\",\"query\":\"你好\"}}";
            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/v3/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 = {
    'version': '3.0',
    'service_id': 'S10000',
    'session_id': '',
    'log_id': 'UNITTEST_10000',
   
    
    'request': {
        'query': '你好',
        'terminal_id': '88888'
    }
};
// 携带数据发送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/v3/chat?access_token=' . $token;
$bodys = '{"version":"3.0","service_id":"S10000","session_id":"","log_id":"7758521","request":{"terminal_id":"88888","query":"你好"}}';
$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/v3/chat?access_token=' + access_token
post_data = "{\"version\":\"3.0\",\"service_id\":\"S10000\",\"session_id\":\"\",\"log_id\":\"7758521\",\"request\":{\"terminal_id\":\"88888\",\"query\":\"你好\"}}"
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/v3/chat?access_token=" + token;
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(host);
            request.Method = "post";
            request.ContentType = "application/json";
            request.KeepAlive = true;
            string str = "{\"version\":\"3.0\",\"service_id\":\"S10000\",\"session_id\":\"\",\"log_id\":\"7758521\",\"request\":{\"terminal_id\":\"88888\",\"query\":\"你好\"}}"; // 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/v3/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数据（如：{\"version\":\"3.0\",\"service_id\":\"S10000\",\"session_id\":\"\",\"log_id\":\"7758521\",\"request\":{\"terminal_id\":\"88888\",\"query\":\"你好\"}}; // 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/v3/chat?access_token={access_token}' --data '{"version":"3.0","service_id":"S10000","session_id":"","log_id":"7758521","request":{"terminal_id":"88888","query":"你好"}}'

错误信息