对话检索
对话检索接口，就是将对话用户的请求发送给机器人，获得机器人的回复。
检索多轮对话，也同时会从知识库、意图识别、对话脚本中获得答案并按照算法回复最佳答案，也是 Chatopera 官方最推荐的集成形式，使用检索多轮对话接口，可以定制出更为智能的对话机器人。 了解详情，请阅读《多轮对话的工作机制》。
检索多轮对话
多轮对话是通过脚本规则、函数编程实现问答服务，在检索多轮对话接口中，同时融合了知识库参与回复决策，返回结果，尤其是通过知识库答案路由到指定话题的指定触发器，非常实用。为了方便使用，宜先理解多轮对话的工作机制和工作原理，熟悉多轮对话机制可以真正将 Chatopera 机器人平台的能量发挥到最大。
Chatbot#command("POST", "/conversation/query", body)
body / JSON Object
{
"fromUserId": "{{userId}}",
"textMessage": "想要说些什么",
"faqBestReplyThreshold": 0.6,
"faqSuggReplyThreshold": 0.35,
"extras": {},
"isDebug": false
}
| key | type | required | description |
|---|---|---|---|
| fromUserId | string | ✔ | 用户唯一 ID，用户 ID 由业务系统传递或生成，保证每个用户用唯一字符串 |
| textMessage | string | ✔ | 用户输入的对话文字 |
| faqBestReplyThreshold | number | ✘ | 知识库最佳回复阈值，知识库中置信度超过该值通过返回值string和params返回；可以在机器人平台管理控制台的设置页面设置默认值，使用 API 传递参数覆盖默认值 |
| faqSuggReplyThreshold | number | ✘ | 知识库建议回复阈值，知识库中置信度超过该值的问答对通过返回值faq属性返回；可以在机器人平台管理控制台的设置页面设置默认值，使用 API 传递参数覆盖默认值 |
| isDebug | boolean | ✘ | 是否返回调试信息，调试信息包括匹配信息等 |
| extras | JSONObject 或 JSONArray | ✘ | 在消息中，添加自定义的信息，然后在多轮对话脚本的函数 this.message.extras 和 this.user.history 中使用 |
其中，extras 用以支持更灵活，自定义的场景，使用参考。
result/ JSON Object
{
"rc": 0,
"data": {
"state": "default",
"string": "方法",
"logic_is_unexpected": false,
"logic_is_fallback": false,
"service": {
"provider": "faq",
"docId": "{{doctId}}",
"score": 0.3781,
"faqBestReplyThreshold": 0.37,
"faqSuggReplyThreshold": 0.1,
"categories": ["x", "y"]
},
"botName": "小巴巴",
"faq": [
{
"id": "{{doctId}}",
"score": 0.3781,
"post": "查看相似问题不可能的",
"categories": ["x", "y"]
}
]
}
}
state: 业务字段，可以在多轮对话脚本中设置
string: 机器人回复的文本内容
topicName: 机器人会话主题
logic_is_fallback: 是否是兜底回复
botName: 机器人的名字
faq: 知识库中匹配 textMessage 的相似度超过 faqSuggReplyThreshold的记录，数组类型
service代表返回的数据来源，provider:conversation指多轮对话，provider:faq指知识库，provider:intent指意图识别；不同数据来源也会提供相应信息。
| provider | key | 解释 |
|---|---|---|
| faq | 知识库 | |
| docId | 文档 ID | |
| post | 标准问 | |
| score | 分数 | |
| intent | 意图识别 | 更多描述参考意图匹配器 |
| intent.name | 意图名称 | |
| intent.state | 意图会话状态 | |
| intent.entities | 意图中的命名实体 | |
| llm | 大语言模型（LLM） | |
| conversation | 多轮对话 | |
| fallback | 兜底回复 | |
| mute | 该用户被该机器人屏蔽 |
检索知识库
Chatbot#command("POST", "/faq/query", body)
body / JSON Object
{
"query": "查找相似的问题",
"fromUserId": "{{userId}}",
"faqBestReplyThreshold": 0.5,
"faqSuggReplyThreshold": 0.1
}
查询匹配是根据阈值设置的，也就是faqBestReplyThreshold和faqSuggReplyThreshold，前者是最佳回复阈值，后者是建议回复阈值，前者高于后者，都在 [0-1]区间，是问题相似度，值越大，越从知识库查询相似度高的记录，1 代表问题和查询完全一样。
result/ JSON Object
{
"rc": 0,
"data": [
{
"id": "{{docId}}",
"score": 0.48534,
"post": "查看相似问题不可能的",
"replies": [
{
"rtype": "plain",
"enabled": true,
"content": "方法"
}
],
"categories": [
"节日",
"农历"
]
},
{
"id": "{{docId}}",
"score": 0.32699,
"post": "聊天",
"replies": [
{
"rtype": "plain",
"content": "foo",
"enabled": true
},
{
"rtype": "plain",
"content": "bar",
"enabled": true
}
],
"categories": []
}
]
}
categories 是分类信息。分类是树状结构，返回值是按照树状结构顺序的数组。
检索意图识别
意图识别是基于请求者的文本内容分析意图，然后基于意图追问意图槽位信息的对话，这部分的详细介绍参考https://docs.chatopera.com/products/chatbot-platform/intent.html，下面重点介绍在系统集成中，通过意图识别服务提供智能问答。
什么是“会话”
“会话”(session)在代表一个用户对话的周期，认为用户在这个周期内是为了完成某个任务的。从确定任务，到得到和这个任务相关的信息，这个 session 就正常结束了，但是如果用户变化了任务，这个 session 就不能正常结束。开发者选择什么时候创建新的 session，但是服务器端决定什么时候完成这个 session，session 的管理涉及：意图的确定，意图参数的确定，会话最大空闲时间，会话是否解决(resolved)。
- 训练完成后请求对话，需要先创建会话，会话会绑定 0-1 个任务：刚开始不知道用户意图，当确定用户意图后，该 session 就只和这个意图相关；
- 会话有最大空闲日期，如果在半个小时内没有更新，会被服务器删除；
- 会话可以任意创建，只要没有超过最大空闲日期都是有效的；
- 不同的用户使用不同的会话，同一个用户可以同时有多个会话，但是为了实际效果，用户最好同时只使用一个会话；
- 当用户的意图和槽位信息被全部确认，会话包含的 resolved 字段会被设置为 true，这时开发者可以再次创建一个新的会话。
创建会话
Chatbot#command("POST", "/clause/prover/session", body)
body / JSON Object
{
"uid": "{{userId}}",
"channel": "{{channelId}}"
}
| key | type | required | description |
|---|---|---|---|
| userID | string | ✔ | 用户标识，由字母和数字组成的字符串。开发者自定义，保证每个用户唯一 |
| channelId | string | ✔ | 用户来源的渠道标识，由字母和数字组成的字符串。由开发者自定义，保证每个渠道唯一 |
result/ JSON Object
{
"rc": 0,
"data": {
"intent_name": null,
"uid": "{{userId}}",
"channel": "{{channelId}}",
"resolved": null,
"id": "{{sessionId}}",
"entities": null,
"createdate": "2019-08-28 18:08:51",
"updatedate": "2019-08-28 18:08:51"
"ttl": 3600
},
"error": null
}
intent_name: 意图名字
id: 会话 ID
resolved: 该会话是否完成收集参数
entities: 参数列表，完成填槽或待填槽
ttl: 该会话信息在多少秒后过期，每个会话默认是 1 小时的空闲周期，在该时间内没有跟进的对话，则会话过期
检索意图识别
Chatbot#command("POST", "/clause/prover/chat", body)
body / JSON Object
{
"fromUserId": "{{userId}}",
"session": {
"id": "{{sessionId}}"
},
"message": {
"textMessage": "我想购买明天火车票"
}
}
| key | type | required | description |
|---|---|---|---|
| userId | string | ✔ | 用户唯一 ID，用户 ID 由业务系统传递或生成，保证每个用户用唯一字符串 |
| sessionId | string | ✔ | 使用创建会话接口创建 |
| textMessage | string | ✔ | 用户输入的对话文字 |
result/ JSON Object
{
"rc": 0,
"data": {
"session": {
"intent_name": "{{intentName}}",
"uid": "{{userId}}",
"channel": "{{channelId}}",
"resolved": false,
"id": "{{sessionId}}",
"entities": [
{
"name": "cityName",
"val": "中国首都"
}
],
"createdate": "2019-08-28 18:15:24",
"updatedate": "2019-08-28 18:15:24",
"ttl": 3595
},
"message": {
"textMessage": "你想做什么工具",
"is_fallback": null,
"is_proactive": true
}
},
"error": null
}
查看会话详情
Chatbot#command("GET", "/clause/prover/session/{{sessionId}}")
result/ JSON Object
{
"rc": 0,
"data": {
"intent_name": "{{intentName}}",
"uid": "{{userId}}",
"channel": "{{channelId}}",
"resolved": false,
"id": "{{sessionId}}",
"entities": null,
"createdate": "2019-08-28 18:41:56",
"updatedate": "2019-08-28 18:41:56",
"ttl": 3600
},
"error": null
}