对话检索

对话检索接口，就是将对话用户的请求发送给机器人，获得机器人的回复。

检索多轮对话：从多轮对话获得回复
检索知识库：从知识库获得回复
检索意图识别：从意图识别模块获得回复

检索多轮对话，也同时会从 FAQ 知识库、RAG 知识库、意图识别、对话脚本中获得答案并按照算法回复最佳答案，也是 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	FAQ 知识库
	docId	文档 ID
	post	标准问
	score	分数
rag	RAG 知识库
	model	模型信息，e.g. qwen2.5:14b
	think	推理信息
intent	意图识别	更多描述参考意图匹配器
	intent.name	意图名称
	intent.state	意图会话状态
	intent.entities	意图中的命名实体
llm	大语言模型（LLM）
conversation	多轮对话
fallback	兜底回复
mute	该用户被该机器人屏蔽

检索 RAG 知识库

RAG 知识库通过用户上传的文档生成答案，结合大语言模型和向量数据库等技术。

Chatbot#command("POST", "/rag/query", body)

body / JSON Object

{
 "query": "海南有几个机场"
}

result/ JSON Object

{
    "rc": 0, // rc = 0 当对话请求正确处理时; rc 等于其它值，对话请求异常，服务未能顺利执行
    "data": {
        "think": null, // 机器人推理内容
        "content": "海南有三个民用机场：海口美兰国际机场、三亚凤凰国际机场和琼海博鳌机场。", // 机器人回复内容
        "is_logic_fallback": false, // 是否解答问题：1）false - 已经解答; 2) true - 未能解答
        "model": "qwen2.5:14b", // 本次问答使用的模型
        "prompt": "1. 使用下面的上下文信息回答末尾的问题\n2. 如果你不知道，就说\"I_DONT_KNOW\", 不要胡说.\n3. 让答案尽量的简洁，只用3、4个句子回答问题.\n\n上下文信息: \n海口有海口美兰国际机场，位于海口市美兰区，航线飞往国内大中城市，也有飞往国际的专机。从海口去美兰国际机场，除了地铁快速到达外，有绕城高速直达，还有琼文高速和223国道，交通非常便利。海南有三个民用机场：海口美兰国际机场、三亚凤凰国际机场和琼海博鳌机场。\n\n\n问题: 海南有几个机场\n答案:" // 系统提示词
    }
}

检索 FAQ 知识库

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
}