密级	公开
版本	10D.2

AICP NLU 训练优化开发手册

1. 概述#

1.1 功能介绍#

NLU 训练优化服务提供了一系列的 HTTP 接口，支持面向知识的各生命周期的训练优化功能。

NLU 训练优化服务具体提供如下功能的接口：

语义模型训练
知识挖掘
文档拆分
文档问答
扩展问生成

1.2 模型特征串#

NLU 训练优化服务中的模型特征串同 NLU 能力服务中所用的模型特征串，常见的也是 cn_common (中文通用领域)。

1.3 访问认证#

访问接口所需的认证机制，请参见《AICP 10 开发通用规范》。

2. 功能描述#

2.1 语义模型训练#

语义模型训练是指针对指定问答库的问题进行训练，生成新的语义模型的功能。训练后的新语义模型在一般情况下，都有利于提高问答匹配准确率。

NLU 语义模型训练目前支持小语义模型训练以及大语义模型训练。

小语义模型运行速度较快
大语义模型运行速度较慢，但效果比小语义模型要好

语义模型训练基本流程为：

准备并上传数据集
包括：上传训练集(必需，原始数据集)、验证集(可选，已标注数据集)、测试集(可选)；
设置基础模型
设置训练所用的基础模型，可以是小语义模型或者大语义模型。
模型训练
基于上述上传的训练集、基础模型、验证集，以及算法参数，通过多次反复迭代训练，最终得到几组模型
模型评估(可选，需测试集)
对训练完成的模型，通过测试集进行验证，获取模型的准确率、召回率等相应指标项来进行模型评估，用户以此来判断模型是否符合预期
模型发布
根据模型评估结果，选择符合业务预期的模型，选用为所需模型，并通过 NLU 资源管理服务的“创建优化模型接口” 加入到资源管理服务中。

小语义模型训练要求的训练集资源可以比大语义模型多一些，所需资源如下表所示：

资源	小语义模型	大语义模型	格式
训练集知识库	必需	必需	知识库
训练验证集	可选	可选	验证集
负样本训练集	可选	-	负样本集
弱标注训练集	可选	-	弱标注集
测试集	可选	可选	测试集

2.1.1 知识库#

小语义模型、大语义模型训练时必需，作为训练集语料使用。

知识库文本为 UTF-8 编码，无BOM头，可以有多行，每一行是一个json，表示一个知识点。知识库中的多行即表示多个知识点。一般使用 mjsn 后缀。

每个知识点的 json 对象包含q和e两个字段，分别表示“标准问”和“扩展问列表”。

示例如下：

{"q": "标准问", "e": ["扩展问"]}
{"q": "标准问2", "e": ["扩展问111", "扩展问2222"]}

一个知识库内，要求知识的标准问唯一，扩展问允许为空列表。

在标准问或者扩展问中，如果有实体词或者词槽定义，需要由外部系统进行处理，训练服务内部不处理实体词或者词槽。

2.1.2 验证集/测试集#

验证集/测试集配合训练集（也即输入的知识库）进行模型的效果评估。

模型训练过程中，当指定验证集时，工具会自动进行准确率的效果验证，并根据准确率的变化自动停止训练；如不指定验证集，则工具仅使用训练集进行训练，直到满足训练轮数要求。

测试集是用于最终的效果测试，必须提供。在任务结束时，会对训练过程中保留的几个训练模型再使用测试集进行一次测试评估，并在训练结果中给出。用户可以选择其中的某个模型作为最终发布上线的语义模型。

验证集/测试集格式一样，均为文本格式，UTF-8 编码，无 BOM 头。每行包含两列文本，使用 \t 进行分割，第一列为测试问题，第二列为答案，也即命中的标准问。所有的答案都必须包含在知识库的标准问集合中，否则此条测试样本会被忽略。

怎么知道我的保单值多少钱现金价值表的作用

2.1.3 负样本集#

负样本集的内容为与知识库无关的任意问题，一般用于解决拒识率问题。目前负样本集仅用于小语义模型训练过程。

负样本集为文本文件，UTF-8编码，每一行一个问题。

2.1.4 弱标注集#

弱标注集用于优化识别错误的样本，目前仅用于小语义模型训练过程。

弱标注集包含多条数据，每条数据包含扩展问以及对应的错误标准问，UTF-8编码。

弱标注集为文本文件，UTF-8编码，每行一个样本。样本包含两列文本：扩展问，错误的标准问。两列间通过\t分割。

示例如下：

现金提现可以分期吗卡片挂失

2.2 知识挖掘#

知识挖掘提供扩展问挖掘及新知识发现的功能。基本流程为：

准备并上传对话记录(必选)
准备并上传忽略问题列表(可选)
准备并上传当前知识库(可选)
数据挖掘，输出针对当前知识库中已有知识点新发现的扩展问，以及新挖掘出的知识点

上述中的知识点为一个标准问和一组扩展问。

2.2.1 对话记录#

对话记录为历史对话记录文本，可以是实际对话交互过程中的机器人对话记录，也可以是之前的人工对话记录、第三方对话记录的。对话记录必须是 UTF-8编码，文本格式。

注：工具不会对对话记录中的问题或者答案进行区分，统一按文本行处理。

示例如下：

你好，你们银行的代付怎么收费？
还没有，准备今天办理
一年保本保息
我存了钱进信用卡，为什么还从银行卡扣款
没扣信用卡，从银行卡扣的
问下面签都需要什么资料

2.2.2 忽略问题列表#

忽略问题列表用于去除对话记录中相似的问题，然后再将结果送入下一阶段处理。忽略问题列表非必需。

注：工具所需忽略问题列表格式为普通文本文件格式，一行一个问题。

示例如下：

好的，多谢
好的知道了
明白了多谢
知道了多谢

2.2.3 知识库#

在知识挖掘过程中，可以传入当前的知识库。这样知识挖掘会从已有对话记录中，针对现有知识点发现、提取新的扩展问法，而生成的新知识点也是在当前知识库以外的结果。

知识库文本为 UTF-8 编码，无 BOM 头，可以有多行，每一行是一个 json, 表示一个知识点。知识库中的多行即表示多个知识点。一般使用 mjsn 后缀。

每个知识点的json对象包含q、e和i三个字段，分别表示“标准问”、“扩展问列表”，和“知识点Id”。整个知识库中要求i字段值唯一。

示例如下：

{"q": "标准问1", "e": ["扩展问1-1", "扩展问1-2"], "i": "xxxx"}
{"q": "标准问2", "e": ["扩展问2-1", "扩展问2-2"], "i": "xxxx"}

2.3 文档拆分#

文档拆分用于从指定的业务文档中提取问题和答案对。

只需要指定单篇或一个目录下的多篇文档，即可对文档进行拆分工作，形成新的问答对。

文档内容为纯文本格式，UTF-8 编码，无 BOM 头。

如果是指定文件名称，后缀名不限，如果是指定目录路径，则会自动搜索目录下所有 '.txt' 后缀的文件进行处理。

目前的文档拆分功能要求原始文档最好有一定的多级目录格式。因此建议为 word 另存为 txt 方式导出的文本。

2.4 文档问答#

文档问答用于从指定的业务文档中搜索指定问题的答案。

在文档问答时，需要指定搜索的文档列表和具体的问题，则可以输出对应的答案、以及是从哪篇文档中找到的此答案。也可以输出多个候选的答案。

文档内容为纯文本格式，UTF-8 编码，无 BOM 头。

2.5 扩展问生成#

扩展问生成针对输入的标准问题，自动生成该标准问题的扩展问。

3. 接口描述#

以下描述中，URI 前面都省略了 /v10/nlu/train/{property}。

3.1 模型训练#

接口说明	接口	备注
发起模型训练任务	`POST /model_train`	返回 `taskId`
查询任务状态和结果	`GET /model_train/<taskId>`
结束任务	`DELETE /model_train/<taskId>`

3.1.1 发起模型训练任务#

POST /model_train

请求消息

参数	类型	必选	说明
baseModelPath	String	是	基础模型，必选。目前只支持增量训练，因此必选
kbPath	String	是	训练用的知识库文件
verifySetPath	String	否	训练用验证集文件，可选。如果为空，训练到最大迭代轮数`maxEpochs`，否则会使用此验证集确定是否自动停止训练


testSetPath	String	是	测试集文件，必选，可以和验证集使用同一个文件
outputPath	String	是	模型输出目录，已有的目录会被先删除然后重建
config	Object	否	配置
config.maxEpochs	Integer	否	训练时最大迭代轮数，取值`[1,+∞)` 小模型默认为10，大模型默认为300
config.maxEpochs	Integer	否	训练时最大迭代轮数，取值`[1,+∞)` 小模型默认为10，大模型默认为300
config.keepModels	Integer	否	模型最大保存数量，取值`[0,+∞)` 默认为5
config.keepModels	Integer	否	模型最大保存数量，取值`[0,+∞)` 默认为5
config.batchSize	Integer	否	训练时候的batch大小，取值`[1,+∞)` 小模型默认512，大模型默认32
config.batchSize	Integer	否	训练时候的batch大小，取值`[1,+∞)` 小模型默认512，大模型默认32
config.notifyUrl	String	否	回调接口地址
以下字段仅在小语义模型训练时有效
negativeDataPath	String	否	负样本训练集，可选。
weakDataPath	String	否	弱标注训练集，可选。
config.numBatchs	Integer	否	每个epoch包含的batch数量，取值`[1,+∞)` 不传时自动选择合适的值
config.numBatchs	Integer	否	每个epoch包含的batch数量，取值`[1,+∞)` 不传时自动选择合适的值
以下字段仅在大语义模型训练时有效
config.saveModelStep	Integer	否	每隔多少步保存一次模型，取值`[1,+∞)`，默认1000
config.learningRate	Float	否	学习率，取值`(0.0,1.0)`，默认0.00005

小语义模型训练请求示例如下：

{
  "baseModelPath": "/mnt/models/base_training_model_small/",
  "kbPath": "/mnt/kb/tr_knw.mjsn",
  "verifySetPath": "/mnt/kb/question.txt",
  "testSetPath": "/mnt/kb/question.txt",
  "outputPath": "/mnt/models/output/",
  "config": {
    "maxEpochs": 10,
    "keepModels": 5,
    "batchSize": 512,
    "negativeDataPath": "/mnt/kb/negativeData.txt",
    "weakDataPath": "/mnt/kb/weakData.txt",
    "numBatchs": 30,
    "saveModelStep": 100,
    "learningRate": 0.5
  }
}

大语义模型训练请求示例如下：

{
  "baseModelPath": "/mnt/models/base_training_model_big/",
  "kbPath": "/mnt/kb/tr_knw.mjsn",
  "verifySetPath": "/mnt/kb/question.txt",
  "testSetPath": "/mnt/kb/question.txt",
  "outputPath": "/mnt/models/output/",
  "config": {
    "maxEpochs": 300,
    "keepModels": 5,
    "batchSize": 32,
    "saveModelStep": 1000,
    "learningRate": 0.00005
  }
}

响应消息

{
  "created": {
    "taskId": "xxxx"
  }
}

注：回调接口发送body内容同“查询模型训练任务的状态和结果”接口的响应体内容，但 status 项只能为 WORKING, FINISHED, ERROR。在过程中也会通知进度信息，因此会发送多次WORKING, 但只有一次 FINSIHED 或者 ERROR。

3.1.2 查询任务状态和结果#

GET /model_train/<taskId>

请求消息

无

响应消息

参数	类型	说明
taskId	String	由创建知识挖掘接口返回的任务Id
status	String	任务状态，可以为 `WAIT`, `TRAIN`, `EVAL`, `FINISHED`, `ERROR`
`status` 为 `WAIT` 时
waitTaskCount	Integer	处于等待状态的任务数，包括自己
`status` 为 `TRAIN`或者 `EVAL` 时
epochFinished	Integer	已完成的迭代次，由于中间可能提前停止,因此这里只是已完成的迭代次数
progress	Float	进度百分比
estimatedNeedTime	Integer	预计结束还需要的时间，s为单位
`status` 为 `FINISHED` 时
epochFinished	Integer	总共完成的迭代次数
results	Object	模型训练的结果，当 `status` 为 `FINISHED` 时有此项
results[#].epoch	Integer	第几轮迭代的结果
results[#].steps	Integer	第几步迭代的结果，仅大语义模型有此项
results[#].modelPath	String	模型的路径
results[#].eval	Object	测试集评估结果
results[#].eval.rate	Array Of Float	从 Top1 到 Top10 的正确率
results[#].type	String	模型类型，小语义模型为`SMALL`，大语义模型为`BIG`
results[#].trainedTime	Integer	模型训练时间,为Unix时间戳，单位秒
`status` 为 `ERROR` 时
error	Obejct	错误
error.code	Integer	错误代码
error.message	String	错误提示消息

// 训练任务排队中
{
  "taskId": "xxxx",
  "status": "WAIT",
  "waitTaskCount": 3,
}

// 训练任务训练中
{
  "taskId": "xxxx",
  "status": "TRAIN",
  "progress": 0.04,
  "epochFinished": 12,
  "estimatedNeedTime": 3044,
}

// 训练任务训练过程已结束，评估模型效果中
{
  "taskId": "xxxx",
  "status": "EVAL",
  "progress": 0.84,
  "epochFinished": 12,
  "estimatedNeedTime": 366,
}

// 小语义模型训练结果
{
    "taskId": "xxxx",
    "status": "FINISHED",
    "epochFinished": 3,
    "results": [  // 这里只保留当前最好的N个模型
        {
            "epoch": 1,
            "modelPath": "/mnt/models/output/ep1",
            "eval": {
                "rate": [0.909195,0.940132,0.953595,0.960756,0.965053,0.967631,0.970496,0.973074,0.976797,0.979662]
            },
            "type": "SMALL",
            "trainedTime": 1603957335
        },
        {
            "epoch": 2,
            "modelPath": "/mnt/models/output/ep2",
            "eval": {
                "rate": [0.910914,0.940705,0.954741,0.962188,0.965626,0.969636,0.97336,0.975652,0.977943,0.980521]
            },
            "type": "SMALL",
            "trainedTime": 1603957372
        },
        {
            "epoch": 3,
            "modelPath": "/mnt/models/output/ep3",
            "eval": {
                "rate": [0.910627,0.941278,0.954741,0.961329,0.965912,0.968777,0.97336,0.976511,0.978516,0.980521]
            },
            "type": "SMALL",
            "trainedTime": 1603957408
        },
        ...
    ]
}

// 大语义模型训练结果
{
    "taskId": "xxxx",
    "status": "FINISHED",
    "epochFinished": 4,
    "results": [  // 这里只保留当前最好的N个模型
        {
            "epoch": 1,
            "steps": 300,
            "modelPath": "/mnt/models/output/ep1-300",
            "eval": {
                "rate": [0.909195,0.940132,0.953595,0.960756,0.965053,0.967631,0.970496,0.973074,0.976797,0.979662]
            },
            "type": "BIG",
            "trainedTime": 1603957335
        },
        {
            "epoch": 1,
            "steps": 464,
            "modelPath": "/mnt/models/output/ep1-464",
            "eval": {
                "rate": [0.910914,0.940705,0.954741,0.962188,0.965626,0.969636,0.97336,0.975652,0.977943,0.980521]
            },
            "type": "BIG",
            "trainedTime": 1603957372
        },
        {
            "epoch": 3,
            "steps": 700,
            "modelPath": "/mnt/models/output/ep3-700",
            "eval": {
                "rate": [0.910627,0.941278,0.954741,0.961329,0.965912,0.968777,0.97336,0.976511,0.978516,0.980521]
            },
            "type": "BIG",
            "trainedTime": 1603957408
        },
        ...
    ]
}

// 训练失败
{
  "taskId": "xxxx",
  "status": "ERROR",
  "error": {
    "code": 102,
    "message": "xxxx"
  }
}

任务状态会保存24h，超时后当做 taskId 非法，访问时会返回 404 Not Found。但训练生成的N个模型会一直保留。

3.1.3 结束任务#

DELETE /model_train/<taskId>

如果任务尚未完成，则中止任务并清理所有结果。如果任务已结束，会主动清除任务结果（训练生成的N个模型会一直保留）。结束任务后，taskId 变为无效。

请求消息

无

响应消息

{
  "deleted": {
    "taskId": "xxxx"
  }
}

3.2 知识挖掘#

接口说明	接口	备注
发起知识挖掘任务	`POST /data_mining`	返回 `taskId`
查询任务状态和结果	`GET /data_mining/<taskId>`
结束任务	`DELETE /data_mining/<taskId>`

3.2.1 发起知识挖掘任务#

POST /data_mining

请求消息

参数	类型	必选	说明
recordsPath	String	是	对话记录txt文件，必选，用于新问题发现
overlookPath	String	否	忽略问题txt文件，可选，为空时不进行忽略问题过滤
kbPath	String	否	当前知识库文件mjsn文件，可选，为空时不进行现有知识点扩展问挖掘。
kbPath	String	否	当前知识库文件mjsn文件，可选，为空时不进行现有知识点扩展问挖掘。
config	Object	否	配置
config.weightPath	String	否	权重文件路径，为空表示使用系统默认
config.overlook	Integer	否	忽略问题相关配置
config.overlook.threshold	Float	否	忽略问题超参数，取值`(0,1]`，可使用默认值0.7。改大会减少过滤掉的问题比例，留下更多问题，反之则减少。


config.kbmining	Object	否	挖掘扩展问的相关配置
config.kbmining.discardThreshold	Float	否	挖掘扩展问的相似度上限，取值`(0,1]`，默认值0.95
config.kbmining.minKeepThreshold	Float	否	挖掘扩展问的相似度下限，取值`(0,1]`，默认值0.85
config.kbmining.maxKeepThreshold	Float	否	挖掘扩展问的抛弃相似度下限，取值`(0,1]`，默认值0.7，与知识库中问题相似度高于此值时，会在下一步前被抛弃。
config.kbmining.maxKeepThreshold	Float	否	挖掘扩展问的抛弃相似度下限，取值`(0,1]`，默认值0.7，与知识库中问题相似度高于此值时，会在下一步前被抛弃。
config.kbmining.minKeepCount	Integer	否	挖掘问题高于此数量才会被保留，取值`[1,+)`，默认值1
config.kmeans	Obejct	否	挖掘新知识点的相关配置
config.kmeans.minSentencePerCluster	Integer	否	新知识点最少问题数量，取值`[1,+∞)`，默认值10
config.kmeans.minAverageDistance	Float	否	新知识最小类内距离，取值`(0,1]`，默认值0.85，调高则值新知识类内相似度高，但类的数量会少。
config.kmeans.minAverageDistance	Float	否	新知识最小类内距离，取值`(0,1]`，默认值0.85，调高则值新知识类内相似度高，但类的数量会少。
config.kmeans.sentencePerCluster	Integer	否	新知识平均问题数量，取值`[1,+∞)`，默认值30，调高则新知识数量变少，调低则新知识数量变多。
config.kmeans.sentencePerCluster	Integer	否	新知识平均问题数量，取值`[1,+∞)`，默认值30，调高则新知识数量变少，调低则新知识数量变多。
config.kmeans.minBatchSize	Integer	否	知识挖掘算法超参数，取值`[1,+∞)`，默认值50000，调大会降低运行速度，但效果理论上略微上升。
config.kmeans.minBatchSize	Integer	否	知识挖掘算法超参数，取值`[1,+∞)`，默认值50000，调大会降低运行速度，但效果理论上略微上升。
config.notifyUrl	String	否	回调接口地址

{
  "recordsPath": "./test/xiamenyinhang_3000_records.txt",
  "kbPath": "./test/xiamenyinhang_knw.mjsn",
  "overlookPath":"./test/overlook.txt",

  "config": {
    "weightPath": "common_weight.h5",
    "overlook": {
      "threshold": 0.7
    },
    "kbmining": {
      "discardThreshold": 0.7,
      "minKeepThreshold": 0.85,
      "maxKeepThreshold": 0.95,
      "minKeepCount": 1
    },
    "kmeans": {
      "minSentencePerCluster": 10,
      "minAverageDistance": 0.85,
      "sentencePerCluster": 30,
      "minBatchSize": 50000
    },
    "notifyUrl": "http://10.0.3.10/post"
  }
}

注：回调接口发送body内容同“查询知识挖掘任务的状态和结果”接口的响应体内容，但 status 项只能为 FINISHED, ERROR。

响应消息

{
  "created": {
    "taskId": "xxxx",
  }
}

3.2.2 获取任务状态和结果#

GET /data_mining/<taskId>

请求消息

无

响应消息

参数	类型	说明
taskId	String	由创建知识挖掘接口返回的任务Id
status	String	任务状态，可以为 `WORKING`, `FINISHED`, `ERROR`
`status` 为 `FINISHED` 时
result	Object	知识挖掘结果
result.kb	Array Of Object	在提供了现有知识库时，有此项，表示针对现有知识库中的标准问挖掘出来的新扩展问。
result.kb	Array Of Object	在提供了现有知识库时，有此项，表示针对现有知识库中的标准问挖掘出来的新扩展问。
result.kb[#].q	String	现有知识库中的标准问
result.kb[#].i	String	现有知识库中的标准问Id
result.kb[#].e	Array of String	挖掘出来的扩展问
result.new_kb	Array Of Object	总有此项，表示挖掘出来的新标准问及其对应的扩展问
result.new_kb[#].q	String	挖掘出的新标准问
result.new_kb[#].e	Array of String	挖掘出来的扩展问
`status` 为 `ERROR` 时
error	Obejct	错误
error.code	Integer	错误代码
error.message	String	错误提示消息

{
  "taskId": "xxxx",
  "status": "WORKING",
}

{
  "taskId": "xxxx",
  "status": "FINISHED",
  "result":
  {
    "kb": [
      {
        "q": "xxxx",
        "i": "xxxx",
        "e":["xxx", "xxxx"],
      }
    ],
    "new_kb": [
      {
        "q":"xxxx",
        "e":["xxxx", "xxxx"],
      }
    ]
  }
}

{
  "taskId": "xxxx",
  "status": "ERROR",
  "error": {
    "code": 102,
    "message": "xxx"
  }
}

注：任务结果保存20分钟。超时则当做 taskId 非法，返回 404: Not Found。

3.2.3 结束任务#

DELETE /data_mining/<taskId>

如果任务尚未完成，则中止任务。如果任务已结束，会主动清除任务结果。结束任务后，taskId 变为无效。

请求消息

无

响应消息

{
  "deleted": {
    "taskId": "xxxx"
  }
}

3.3 文档拆分#

接口说明	接口	备注
发起文档拆分任务	`POST /doc_to_qa`	返回 `taskId`
查询任务状态和结果	`GET /doc_to_qa/<taskId>`
结束任务	`DELETE /doc_to_qa/<taskId>`

3.3.1 发起文档拆分任务#

POST /doc_to_qa

请求消息

参数	类型	必选	说明
type	String	是	`FILE` 或 `DIR`，表示单文档拆分还是多文档拆分
path	String	是	根据 `type` 不同分别表示一个文档文件的路径或者一个目录路径如果是目录路径，将会搜索此目录下的 `.txt` 文件进行处理
path	String	是
config	Object	否	配置
config.notifyUrl	String	否	回调接口地址，为空表示不进行回调

{
  "type": "FILE",
  "path": "/mnt/docs/1.txt",
  "config": {
    "notifyUrl": "http://10.0.3.16/notify/doc_to_qa"
  }
}

响应消息

{
  "created": {
    "taskId": "xxxx"
  }
}

注：回调地址发送body内容同“查询文档拆分任务状态和结果”接口的响应体结构，但status 只会为 FINISHED 或 ERROR。

3.3.2 查询任务状态和结果#

GET /doc_to_qa/<taskId>

请求消息

无

响应消息：

参数	类型	说明
taskId	String	任务Id
status	String	当前任务状态，可以为 `WORKING`, `FINISHED`, `ERROR`
当`status` 为 `FINISHED` 时
result	Array of Obejct	文档拆分结果，每个元素针对一篇文档
result[#].doc	String	文档名称
result[#].qa	Array of Object	拆分出的问答对列表
result[#].qa[#].q	String	拆分出的一个问答对的问题
result[#].qa[#].a	String	拆分出的一个问答对的答案
当`status` 为 `ERROR` 时
error	Obejct	错误
error.code	Integer	错误代码
error.message	String	错误提示消息

{
  "taskId": "xxxx",
  "status": 0,
  "result": [
    {
      "doc": "xxxx",
      "qa": [
        {
          "q": "xxxx",
          "a":"xxxx"
        },
        ...
      ]
    }
  ]
}

注：任务结果保存20分钟。超时则当做 taskId 非法，返回 404: Not Found。

3.3.3 结束任务#

DELETE /doc_to_qa/<taskId>

如果任务尚未完成，则中止任务。如果任务已结束，会主动清除任务结果。结束任务后，taskId 变为无效。

请求消息

无

响应消息

{
  "deleted": {
    "taskId": "xxxx"
  }
}

3.4 文档问答#

接口说明	接口	备注
发起文档问答会话	`POST /doc_reader`	返回 `sessionId`
文档问答	`POST /doc_reader/<sessionId>`
结束会话	`DELETE /doc_reader/<sessionId>`

3.4.1 发起文档问答会话#

POST /doc_reader

请求消息

参数	类型	必选	说明
type	String	是	`FILE` 或 `DIR`，文档问答所使用的业务文档或者业务文档目录
path	String	是	根据 `type` 不同分别表示一个文档文件的路径或者一个目录路径如果是目录路径，将会搜索此目录下的 `.txt` 文件进行处理
path	String	是
config	Object	否	配置
config.nbest	Integer	否	最大候选数量, 缺省10，取值范围`[1,+∞)`。调低此值可以提升回答速度，准确率可能下降。反之则速度变慢，准确率上升


config.maxAnswerLength	Integer	否	最终输出答案文本最大长度(字符数)，缺省500，取值范围`[1, +∞)`
config.docBufferLength	Integer	否	解码时最大保留值，缺省150，范围`[1,+∞)`

{
  "type": "FILE",
  "path": "/mnt/doc_reader/1.txt",
  "config": {
    "nbest": 10,  
    "maxAnswerLength": 500,
    "docBufferLength": 150,
  }
}

响应消息

{
  "created": {
    "sessionId": "xxxx"
  }
}

3.4.2 文档问答#

POST /doc_reader/<sessionId>

请求消息

参数	类型	必选	说明
query	String	是	用户输入的问题

{
  "query": "xxxx",
}

响应消息

参数	类型	说明
sessionId	String	会话Id
results	Array of Object	问答结果列表，有可能有多个候选结果
results[#].doc	String	命中的文档
results[#].answer	String	答案
results[#].docScore	Float	文档定位得分
results[#].answerScore	Float	答案得分

{
  "sessionId": "xxxx",
  "results": [
    {
      "doc": "/mnt/doc_reader/1.txt",
      "answer": "xxx",
      "docScore": 0.2,
      "answerScore": 0.6
    }
  ]
}

注意：会话的过期时间缺省为20分钟。如果20分钟中未使用此sessionId进行对话，则此 sessionId 会失效，再使用会返回错误 404 Not Found。

3.4.3 结束会话#

DELETE /doc_reader/<sessionId>

请求消息

无

响应消息

{
  "deleted": {
    "sessionId": "xxxx",
  }
}

3.5 扩展问生成#

接口说明	接口	备注
发起扩展问生成任务	`POST /generate_question`	返回 `taskId`
查询任务状态和结果	`GET /generate_question/<taskId>`
结束任务	`DELETE /generate_question/<taskId>`

3.5.1 发起扩展问生成任务#

POST /generate_question

请求消息

参数	类型	必选	说明
questions	Array of String	是	需要生成扩展问的标准问
config	Object	否	配置
config.notifyUrl	String	否	回调地址，缺省为空，表示不回调
config.topBeams	Integer	否	每个标准问生成的扩展问最大个数，取值`[1,+∞)`，缺省30
config.modelPath	String	否	模型目录路径，缺省为空，表示使用系统默认

{
  "questions": [
    "xxxxx"   // 无需按空格分割，内部填充空格
  ],
  "config": {
    "notifyUrl": "http://10.0.3.16/notify/generate_question", // 回调地址，为空则不回调
    "topBeams": 30,
    "modelPath": "/mnt/generate_questions/model"        // 模型目录路径，为空则使用系统默认
  }
}

注：回调接口发送body内容同“查询扩展问生成任务的状态和结果”接口的响应体内容，但 status 项只能为 FINISHED, ERROR。

响应消息

{
  "created": {
    "taskId": "xxxx"
  }
}

3.5.2 查询任务状态和结果#

GET /generate_question/<taskId>

请求消息

无

响应消息

参数	类型	说明
taskId	String	任务Id
status	String	当前任务状态，可以为 `WORKING`, `FINISHED`, `ERROR`
`status` 为 `FINISHED` 时
result	Array of Obejct	扩展问生成结果，每个元素针对输入的一个标准问
result[#].q	String	输入的一个标准问
result[#].e	Array of String	生成的扩展问列表
`status` 为 `ERROR` 时
error	Obejct	错误
error.code	Integer	错误代码
error.message	String	错误提示消息

{
  "taskId": "xxxx",
  "status": "WORKING",
}

{
  "taskId": "xxxx",
  "status": "FINISHED",
  "result": [
    {
      "q": "xxxxx",
      "e": ["xxxxxxxxx", "xxxxxxx" ]
    }
  ]
}

{
  "taskId": "xxxx",
  "status": "ERROR",
  "error": {
    "code": 102,
    "message":"错误提示"
  }
}

注：任务结果保存20分钟。超时则当做 taskId 非法，返回 404: Not Found。

3.5.3 结束任务#

DELETE /generate_question/<taskId>

如果任务尚未完成，则中止任务。如果任务已结束，则会主动清除任务结果。结束任务后，taskId 变为无效。

请求消息

无

响应消息

{
  "deleted": {
    "taskId": "xxxx"
  }
}

4. 版本记录#

接口版本	平台支持版本	组件及支持版本	修改内容
10.0.0	10D.1	aicp_nlu_train 10.0.0	初始版本