QA 问答对管理

QA 把标准问题、相似问和答案组织为可检索知识。适合 FAQ、标准服务话术等内容。使用平台 API Key，读取模板要求 knowledge_file=READ，写入要求 WRITE。

QA 同样属于知识库资源。新增接口不返回完整资源对象，需要通过资源列表回查并保存数字 id；已有 QA 可用资源删除接口删除。

新增 QA

POST /openapi/paas/v1/knowledge/qa/add

创建一条标准问答对。

权限：knowledge_file=WRITE。

请求参数

参数	JSON/表单类型	必填	说明
`containerId`	string	是	所属知识库 code
`question`	string	是	非空标准问题，最长 255 字符
`answer`	string	建议填写	答案内容
`similar`	array[string]	否	相似问题，最多 100 条，每条最长 1000 字符，不传逗号拼接字符串
`parentCode`	string	建议填写	父目录 code，顶级填写 0
`neverExpire`	integer	否	默认 1 永久有效；0 使用有效期
`startTime`	string	条件必填	neverExpire=0 时，yyyy-MM-dd HH:mm:ss
`endTime`	string	条件必填	neverExpire=0 时，yyyy-MM-dd HH:mm:ss
`originContent`	string	否	原始内容，按富文本来源需要提供

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/qa/add" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "containerId": "partner_kb_001",
  "question": "产品支持哪些部署方式？",
  "answer": "支持按项目约定进行部署。",
  "similar": [
    "可以私有化部署吗？"
  ],
  "parentCode": "0",
  "neverExpire": 1
}'

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	string	操作结果；成功时可以为空字符串，不包含新资源对象

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": ""
}

成功 data 是结果字符串，不是 QA code。创建结果未知时先回查目标知识库，不盲目重放新增请求。

更新 QA

PUT /openapi/paas/v1/knowledge/qa/update

按数字主键更新 QA，提交需要保留的完整问题、答案及相似问集合。

权限：knowledge_file=WRITE。

请求参数

参数	JSON/表单类型	必填	说明
`id`	integer	是	QA 资源数字主键
`containerId`	string	是	所属知识库 code
`question`	string	是	非空标准问题，最长 255 字符
`answer`	string	建议填写	答案内容
`similar`	array[string]	否	相似问题，最多 100 条，每条最长 1000 字符，不传逗号拼接字符串
`parentCode`	string	建议填写	父目录 code，顶级填写 0
`neverExpire`	integer	否	默认 1 永久有效；0 使用有效期
`startTime`	string	条件必填	neverExpire=0 时，yyyy-MM-dd HH:mm:ss
`endTime`	string	条件必填	neverExpire=0 时，yyyy-MM-dd HH:mm:ss
`originContent`	string	否	原始内容，按富文本来源需要提供

请求示例

curl --request PUT "${BASE_URL}/openapi/paas/v1/knowledge/qa/update" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "id": 1003,
  "containerId": "partner_kb_001",
  "question": "产品支持哪些部署方式？",
  "answer": "支持按项目约定进行部署。",
  "similar": [
    "可以私有化部署吗？"
  ],
  "parentCode": "0",
  "neverExpire": 1
}'

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	string	操作结果；成功时可以为空字符串，不包含新资源对象

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": ""
}

不是追加相似问接口。省略既有业务内容可能改变资源，应先读取再更新。成功后可通过检索与资源查询验证。

下载批量导入模板

GET /openapi/paas/v1/knowledge/qa/downloadExcelTemplate

获取当前部署版本的 Excel 模板，填写后调用批量导入。请使用 HTTP 客户端下载到文件；命令行可为下方请求增加 --output qa-template.xlsx。

权限：knowledge_file=READ。

请求参数

无请求参数。

请求示例

curl --request GET "${BASE_URL}/openapi/paas/v1/knowledge/qa/downloadExcelTemplate" \
  --header "Authorization: Bearer ${AIS_API_KEY}"

响应字段

成功返回 Excel 文件流，不返回 JSON data。客户端依据 Content-Type 和 Content-Disposition 保存文件；下载失败时仍可能返回 JSON 错误。

不要手工猜测表头顺序或删除模板说明行。文件流无 JSON 响应示例；响应头与文件内容即为下载结果。

批量导入 QA

POST /openapi/paas/v1/knowledge/qa/batchAdd

上传已填写的 xlsx 模板。当前服务端限制最多 5000 行、100 MB，网关可能有更低限制。

权限：knowledge_file=WRITE。

请求参数

参数	JSON/表单类型	必填	说明
`file`	file	是	xlsx 文件流
`containerId`	string	是	目标知识库 code
`parentCode`	string	否	父目录 code，默认 0

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/qa/batchAdd" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --form "file=@/path/to/qa.xlsx" \
  --form "containerId=partner_kb_001" \
  --form "parentCode=0"

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data.success`	integer	本次可写入的 QA 数量
`data.errorSize`	integer	校验失败条数
`data.errorMsg`	array[string]	失败条目的标题列表；有失败时才返回，标题可为空
`data.errorReason`	string	校验失败原因提示，有失败时返回；不依赖固定语言

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "success": 1,
    "errorSize": 1,
    "errorMsg": [
      "超出长度限制的示例问题"
    ],
    "errorReason": "存在未通过校验的条目，请修正后重新提交。"
  }
}

外层 8200 不代表整批无失败，必须同时检查 errorSize。只修正并重交失败条目；不要把含已成功数据的完整原批次直接重发，以免重复创建。日期转换或文件格式异常可能直接返回错误而不是批量结果。

QA 接入验收

验证标准问与相似问都能命中预期知识；答案更新后等待相应处理完成，再核对检索内容。填写有限有效期时核对起止时间及目标环境时区。

模板下载、上传体积、业务校验和权限错误的响应形式不同，统一处理入口见错误处理。

新增 QA​

请求参数​

请求示例​

响应字段​

响应示例​

更新 QA​

请求参数​

请求示例​

响应字段​

响应示例​

下载批量导入模板​

请求参数​

请求示例​

响应字段​

批量导入 QA​

请求参数​

请求示例​

响应字段​

响应示例​

QA 接入验收​

新增 QA

请求参数

请求示例

响应字段

响应示例

更新 QA

请求参数

请求示例

响应字段

响应示例

下载批量导入模板

请求参数

请求示例

响应字段

批量导入 QA

请求参数

请求示例

响应字段

响应示例

QA 接入验收