# 星火知识库 API 文档

# 一、服务介绍

星火知识库是基于讯飞星火大模型的知识库问答方案，能够高效检索文档信息，准确回答专业问题，为大模型补充领域知识，让大模型助你高效了解文档内容。

该接口是通过 API 的方式给开发者提供一个通用的 HTTP 接口，基于该接口，开发者可以获取开放平台的星火文档知识库问答能力，方便开发者快速集成。

# 开通授权

您可在讯飞开放平台应用控制台 (opens new window)申请开通 API 权限并采购服务量。技术咨询可直接提交工单 (opens new window)

# 产品体验

基于星火知识库方案 API，我们搭建了星火文档问答 (opens new window)，供您快速体验功能和效果。

# 接口调用示例

部分开发语言Demo如下，其他开发语言请参照文档进行开发，欢迎大家到讯飞开放平台社区 (opens new window)交流集成经验。

星火知识库 DEMO - Java (opens new window)

星火知识库 DEMO - Python (opens new window)

# 接口要求

内容	说明
传输协议	https/wss
接口域名	chatdoc.xfyun.cn
接口鉴权	签名机制，详情请参照下方鉴权认证
字符编码	UTF-8
响应格式	统一采用 JSON 格式
开发语言	任意，只要可以向讯飞云服务发起 HTTP/WebSocket 请求的均可
文档格式	当前支持 doc/docx、pdf、md、txt 格式文档
文档大小	不超过 20M
文档长度	不超过 100W 字符

# 二、鉴权认证

在调用业务接口时，请求方需要对请求进行签名，服务端通过签名来校验请求的合法性。

# 鉴权方法

# 1、设置签名

在 HTTP 请求头 Header 或者 WebSocket 接口中设置参数：appId, timestamp, signature

示例：

文档上传接口：在 Http Request Header 中配置以下参数

String appId = "应用ID"；
String secret = "应用的秘钥"
Long timestamp = System.currentTimeMillis()/1000;
String signature = ApiAuthAlgorithm.getSignature(appId, secret, timestamp);

request.setHeader("appId",appId);
request.setHeader("timestamp",timestamp);
request.setHeader("signature",signature);

文档问答接口：通过在请求地址后面加上鉴权相关参数的方式

wss://chatdoc.xfyun.cn/openapi/chat?appId=xxx&timestamp=xxx&signature=xxxxxx

签名参数说明：

字段名	类型	描述	必须
appId	String	应用 ID	Y
timestamp	Long	时间戳，单位: s，与服务端时间相差五分钟之内	Y
signature	String	签名	Y

# 2、签名（signature）生成规则

首先，用应用 ID（appId）和时间戳（timestamp）通过 MD5 算法生成随机授权参数 auth
再使用授权参数 auth 和接口密钥（secret）基于 HmacSHA1 生产签名 signature

示例：

public class ApiAuthAlgorithm {

  private static final char[] MD5_TABLE = {
    '0',
    '1',
    '2',
    '3',
    '4',
    '5',
    '6',
    '7',
    '8',
    '9',
    'a',
    'b',
    'c',
    'd',
    'e',
    'f'
  };

  /**
   * 获取签名
   *
   * @param appId    签名的key
   * @param secret 签名秘钥
   * @return 返回签名
   */
  public String getSignature(String appId, String secret, long ts) {
    try {
      String auth = md5(appId + ts);
      return hmacSHA1Encrypt(auth, secret);
    } catch (SignatureException e) {
      return null;
    }
  }

  /**
   * sha1加密
   *
   * @param encryptText 加密文本
   * @param encryptKey  加密键
   * @return 加密
   */
  private String hmacSHA1Encrypt(String encryptText, String encryptKey)
    throws SignatureException {
    byte[] rawHmac;
    try {
      byte[] data = encryptKey.getBytes(StandardCharsets.UTF_8);
      SecretKeySpec secretKey = new SecretKeySpec(data, "HmacSHA1");
      Mac mac = Mac.getInstance("HmacSHA1");
      mac.init(secretKey);
      byte[] text = encryptText.getBytes(StandardCharsets.UTF_8);
      rawHmac = mac.doFinal(text);
    } catch (InvalidKeyException e) {
      throw new SignatureException("InvalidKeyException:" + e.getMessage());
    } catch (NoSuchAlgorithmException e) {
      throw new SignatureException(
        "NoSuchAlgorithmException:" + e.getMessage()
      );
    }
    return new String(Base64.encodeBase64(rawHmac));
  }

  private String md5(String cipherText) {
    try {
      byte[] data = cipherText.getBytes();
      // 信息摘要是安全的单向哈希函数，它接收任意大小的数据，并输出固定长度的哈希值。
      MessageDigest mdInst = MessageDigest.getInstance("MD5");

      // MessageDigest对象通过使用 update方法处理数据， 使用指定的byte数组更新摘要
      mdInst.update(data);

      // 摘要更新之后，通过调用digest（）执行哈希计算，获得密文
      byte[] md = mdInst.digest();

      // 把密文转换成十六进制的字符串形式
      int j = md.length;
      char[] str = new char[j * 2];
      int k = 0;
      for (byte byte0 : md) { // i = 0
        str[k++] = MD5_TABLE[byte0 >>> 4 & 0xf]; // 5
        str[k++] = MD5_TABLE[byte0 & 0xf]; // F
      }
      // 返回经过加密后的字符串
      return new String(str);
    } catch (Exception e) {
      return null;
    }
  }
}

# 鉴权结果

如果鉴权失败，则根据不同错误类型返回不同 HTTP Code 状态码，同时携带错误描述信息，详细错误说明如下：

HTTP Code	说明	错误描述信息	解决方法
401	鉴权参数为空	Invalid Param, Please check header	检查是否设置鉴权参数
401	签名参数解析失败	Signature cannot be verified	检查签名的各个参数是否有缺失是否正确，特别确认下复制的secret是否正确
401	签名校验失败	Signature required	签名验证失败，可能原因有很多。 1. 检查 appId、secret 是否正确。 2.检查计算签名的方法是否正确。 3. 检查时间戳是否正确等等
403	时钟偏移校验失败	Invalid time or time required	检查服务器时间是否标准，相差 5 分钟以上会报此错误
405	应用无效	Invalid Signature	检查该 appId 是否开通授权

# 三、基础功能

# 3.1、文档上传

# 接口描述

上传知识库文档数据，目前支持 doc/docx、pdf、md、txt 格式，单文件大小不超过 20MB，不超过 100W 字符。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/upload

# 请求参数说明

POST，multipart/form-data

字段名	类型	描述	必须	默认值
file	MultipartFile	文件	N
url	String	文件 url （文件和文件 url 必须有一个）	N
fileName	String	文件名称，带后缀。文件用 url 的方式，该字段必传；传 file 的话，该字段可不传	N
fileType	String	文件类型，目前传固定值"wiki"	Y	wiki
parseType	String	文件解析类型，"AUTO"-服务端智能判断是否需要走OCR， "TEXT"-直接读取文件文本内容，"OCR"-强制走OCR，目前仅pdf、word支持	Y	AUTO
stepByStep	Boolean	是否分步处理，true代表文件上传之后，服务只做了分片，这时候还不能去问答。需要业务做分片的确认，然后调用【文档向量化】接口，发起切片向量。待向量完成，即可问答。	N	false
callbackUrl	String	文件状态回调地址，文件状态有变动时服务会调用该 url。调用的时候会带上鉴权头，鉴权方式同【接口鉴权】，业务可根据需要是否做鉴权校验	N
extend	String	文件拆分扩展字段(转为JSONString)，也可在分步时，单独调用拆分接口重新发起拆分	N
extend.wikiSplitExtends	Object	WIKI拆分扩展（目前使用此方式）	N
extend.wikiSplitExtends.chunkSeparators	List	分段分隔符，支持多分隔符，base64编码	N	["DQo="]
extend.wikiSplitExtends.chunkSize	Int	分段最大长度，超过强行切分，默认2000	N	2000
extend.wikiSplitExtends.minChunkSize	Int	分段最小长度，小于这个长度的会聚合，默认256	N	256

# extend说明

字段名	类型	描述	必须	默认值
wikiSplitExtends	Object	WIKI拆分扩展（目前使用此方式）	N
wikiSplitExtends.chunkSeparators	List	分段分隔符，支持多分隔符，base64编码	N	["DQo="]
wikiSplitExtends.chunkSize	Int	分段最大长度，超过强行切分，默认2000	N	2000
wikiSplitExtends.minChunkSize	Int	分段最小长度，小于这个长度的会聚合，默认256	N	256

# callbackUrl说明

服务端在文件状态有变化的时候，即会调用该回调地址，调用方式为 - GET: callbackUrl?fileId=xxx&fileStatus=xxx，调用的时候会带上业务appId对应的鉴权头，鉴权方式同【接口鉴权】，业务可根据需要是否做鉴权校验。

字段名	类型	描述
fileId	String	文件id
fileStatus	String	文件状态

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Object	返回结果
data.fileId	String	返回上传的 fileId
data.quantity	Int	当前文件扣除多少页数使用量，PDF/DOC按自然页计算，若每页字数到2000也计算一页
data.parseType	String	文件解析使用的类型，TEXT/OCR；TEXT代表直接读文本内容，OCR代表走了OCR解析

# 返回参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": {
    "quantity": "12",
    "parseType": "TEXT",
    "fileId": "24c4109a57944997bc6b82661243ef67"
  }
}

# 3.2、文档状态查询

# 接口描述

查询文件状态，文件从上传到可问答，经历的状态如下（按顺序）：uploaded-已上传，texted-已文本化，ocring-对文档OCR识别中，spliting-切分中，splited-文本已切分，vectoring-向量中，vectored-已向量化（该状态时可问答），failed-失败。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/status

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
fileIds	String	上传的文件id列表，多个文档id用英文逗号分割	Y

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Array	返回结果
data.fileId	String	文件id
data.fileStatus	String	文件状态uploaded-已上传，texted-已文本化，spliting-切分中，splited-文本已切分， vectoring-向量中，vectored-已向量化，failed-失败

# 返回参数示例

{
  "code":0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc":"成功",
  "data":[
    {
      "fileId":"123",
      "fileStatus":"uploaded"
    }
  ]
}

# 3.3、文档问答

# 接口描述

对文档/知识库进行问答，流式返回注：仅文档状态为vectored的文件才可以进行问答

# 接口地址

wss://chatdoc.xfyun.cn/openapi/chat?appId=xxxx&timestamp=xxxxxxxx&signature=xxxxxx

# 请求参数说明

在请求 URL 上带上参数：appId, timestamp, signature 鉴权生成详情请参照上方鉴权认证建立连接时，服务端会校验鉴权

字段名	类型	描述	必须	默认值
repoId	String	知识库id，单个知识库最多包括100个文档 (repoId、repoIds、fileIds必传其一)	Y
repoIds	Array	知识库id列表，最大100 (repoId、repoIds、fileIds必传其一)	Y
fileIds	Array	文件id列表，最大200 (repoId、repoIds、fileIds必传其一)	Y
llmVersion	String	底层大模型版本,可选值generalv3.5、vdeepseekv3。 generalv3.5：星火大模型 Spark Max，vdeepseekv3：DeepSeek V3	N	generalv3.5
topN	Int	向量库文本段查询数量	N
messages	Array	问答内容列表，按时间正序，最后一条为最新提问	Y
messages.role	String	user 表示是用户的问题，assistant 表示 AI 的回复	Y
messages.content	String	用户和 AI 的对话内容	Y
chatExtends	Object	大模型对话自定义扩展字段	N
chatExtends.wikiPromptTpl	String	wiki 大模型问答模板，在某些场景服务默认的 prompt 回答效果不好时，业务可以考虑通过自定义 prompt 来改善。<wikiquestion>替换的问题标识，<wikicontent>替换的文本内容标识	N
chatExtends.retrievalFilterPolicy	String	检索过滤级别，STRICT-严格；REGULAR-正常；LENIENT-宽松；OFF-关闭；越严格，被过滤掉的文本片段越多，剩余文本段越少	N	0.82
chatExtends.spark	Boolean	用户问题未匹配到文档内容时，大模型兜底回答问题，该参数仅在wiki无内容匹配时生效	N
chatExtends.temperature	Float	大模型问答时的温度，取值范围 (0，1] ，temperature 越大，大模型回答随机度越高	N
chatExtends.qaMode	String	有QA对被检索到时，问答模式；QA_FIRST-qa对优先，让模型在检索到的qa对中选择一个最符合问题的答案原样返回；QA_SUMMARY-对检索到的qa对进行总结回答；MIX-混合模式，模型参考qa对和wiki文本内容混合回答；WIKI_ONLY-仅使用文本内容；	N	MIX

# 请求参数示例

WebSocket 建立成功后，即可发送问答消息，消息格式如下：

{
  "chatExtends": {
    "wikiPromptTpl": "请将以下内容作为已知信息：\n<wikicontent>\n请根据以上内容回答用户的问题。\n问题:<wikiquestion>\n回答:",
    "wikiFilterScore": 0.82,
    "temperature": 0.5
  },
  "fileIds": ["8b1b17171212121212114fd0806"],
  "messages": [
    {
      "role": "user",
      "content": "如何理赔"
    },
    {
      "role": "assistant",
      "content": "您好，根据您提供的信息，理赔操作指引如下：\n\n1. 登录小程序，点击“理赔申请”。\n2. 选择对应保单。\n3. 上传理赔相关资料。\n4. 填写发票总金额。\n5. 填写银行账户，需精确到支行。\n6. 点击“提交”成功后，返回“理赔服务”界面，点选“理赔查询”，查看理赔进度和申请记录。\n7. 如有需要，点击“查看详情”，查看理赔详情和金额。\n\n请注意，如有严重既往症员工还请和HR部门及时报备沟通，如未及时报备，保险公司不承担相关责任。同时，索赔资料不齐全导致延迟赔付等问题也需要注意。"
    },
    {
      "role": "user",
      "content": "家属有什么福利"
    }
  ]
}

# 返回参数说明

参数名	类型	描述
code	Int	错误码，0 标识成功
message	String	会话错误描述信息
content	String	回答内容
sid	String	会话唯一标识
status	Int	会话状态，取值为[0,1,2,99]；0 代表首次结果；1 代表中间结果；2 代表最后一个结果；99 代表引用的文档及文段
fileRefer	String	文档引用，status=99 的时候返回；结构是个 Map，key=文件 id，value=引用的文段列表（对应 fileTrunks 的 index）

若返回 fileRefer 为空，提示 "抱款，在文档中没有找到与提问相关的内容，请尝试换个问题问问吧。"表示提问未匹配到文档内容，可以降低chatExtends.wikiFilterScore以降低匹配阈值，也可以开启chatExtends.spark用大模型兜底。

# 返回参数实例

客户端发送消息后，服务端处理后会返回消息，格式如下

{
  "code": 0,
  "content": "和指南。在此之前，我可以为您",
  "fileRefer": "{\"b2de1116b590911111119d0f3dbfc8\":[3,7,8]}",
  "sid": "870b299a48ba46b6b5e4dfbd99fe4497",
  "status": 1
}

# 四、高级功能-文档萃取

# 4.1、提交萃取任务

# 接口描述

针对单个文档提交萃取任务。注：只有vectored 状态的文档才可以提交萃取任务。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/qa/extract

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
fileId	String	文件id	Y
chunkSize	Int	分片长度，根据这个长度将文件内容分块，然后根据每个分块抽取问题答案	Y
numPerChunk	Int	每个分片问题数（通过改该值限制抽取问题数，非100%准确）	Y
answerSize	Int	答案长度（通过改该值限制答案长度，非100%准确）	N
topicPreference	Array	主题偏好	N
includeAnswer	bool	是否包含答案，false的话仅有问题	N	true
notifyUrl	String	回调地址	N

# 请求参数示例

{
  "fileId": "af0823f307f04efa9ab4615052a2eb04",
  "chunkSize":2000,
  "numPerChunk": 2,
  "answerSize": 100
}

# 响应参数说明

字段名	类型	描述	必须	默认值
code	Int	错误码，成功=0	Y	0
sid	String	请求唯一id，用于问题定位	Y
desc	String	结果描述	Y
data	String	当前萃取任务的任务id，后续可根据该任务id获取萃取内容	Y

# 响应参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功",
  "data": "27805ef975654c01aa069f4e9aad0bb1"
}

# 4.2、文件萃取状态查询

# 接口描述

根据文件id，查询文件的萃取状态。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/qa/extract/status?fileId=xxx

# 请求参数说明

GET

字段名	类型	描述	必须	默认值
fileId	String	文件Id	N

# 响应参数说明

字段名	类型	描述	必须	默认值
code	Int	错误码，成功=0	Y	0
sid	String	请求唯一id，用于问题定位	Y
desc	String	结果描述	Y
data	String	文件萃取状态，UNSTARTED-未开始、EXTRACTING-萃取中、EXTRACTED-萃取完成、FAILED-萃取失败	Y

# 响应参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": "EXTRACTED"
}

# 4.3、获取萃取结果

# 接口描述

根据萃取任务id或者文件id，获取萃取结果。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/qa/extract/result?taskId=xxx

# 请求参数说明

GET

字段名	类型	描述	必须	默认值
taskId	String	任务Id，与fileId必须传一个	N
fileId	String	文件Id	N

# 响应参数说明

字段名	类型	描述	必须	默认值
code	Int	错误码，成功=0	Y	0
sid	String	请求唯一id，用于问题定位	Y
desc	String	结果描述	Y
data	array	返回结果	Y
data.id	String		Y
data.question	String	问题	Y
data.answer	String	答案	Y
data.chunkIndexReferences	String	问题引用分片索引列表	Y
data.answerChunkIndexReferences	String	答案引用分片索引列表	Y

# 响应参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": [{
    "id": "664d98e4e241e050529c74c7",
    "question": "在《鹧鸪天》中，“殷勤昨夜三更雨，又得浮生一日凉”这句诗的含义是什么？",
    "answer": "在《鹧鸪天》中，“殷勤昨夜三更雨，又得浮生一日凉”这句诗的含义是表达了作者对自然美景的欣赏和对生活的感悟。",
    "chunkIndexReferences": [1,2,3],
    "answerChunkIndexReferences": [1,2,3]
  }]
}

# 4.4、QA对应用

# 接口描述

将问题和答案作为QA对应用至文件或者知识库。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/qa/apply

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
fileId	String	文件id	Y
repoId	String	知识库id	Y
question	String	问题	Y
answer	String	答案	Y
embType	String	向量类型，Q-仅仅问题做向量、QA-问题和内容一起做向量	N	QA

# 请求参数示例

{
  "fileId": "af0823f307f04efa9ab4615052a2eb04",
  "repoId": "2e66ae9a1f7443248209d3bf85e89432",
  "question": "《醉落魄（忆别）》中提到‘旧交新贵音书绝’，请问这在表达什么情感或现象？",
  "answer": "《醉落魄（忆别）》中提到的“旧交新贵音书绝”表达了作者对过去友情的怀念和对现今与故友失去联系的感慨。这里的“旧交”指的是老朋友，而“新贵”可能指那些地位上升后改变了态度或生活方式的朋友。",
  "embType": "QA"
}

# 响应参数说明

字段名	类型	描述	必须	默认值
code	Int	错误码，成功=0	Y	0
sid	String	请求唯一id，用于问题定位	Y
desc	String	结果描述	Y
data	String	当前QA对的id，后续更新删除需要用	Y

# 响应参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功",
  "data": "5a5f57a52f834ae5b12888ebd282ea0a"
}

# 4.5、QA对更新

# 接口描述

根据QA对id更新QA对。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/qa/apply/update

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
id	String	QA对id	Y
fileId	String	文件id	Y
repoId	String	知识库id	Y
question	String	问题	Y
answer	String	答案	Y
embType	String	向量类型，Q-仅仅问题做向量、QA-问题和内容一起做向量	N	QA

# 请求参数示例

{
  "id": "8df4f13724a443b79612f853f9a8ae7b",
  "fileId": "af0823f307f04efa9ab4615052a2eb04",
  "repoId": "2e66ae9a1f7443248209d3bf85e89432",
  "question": "《醉落魄（忆别）》中提到‘旧交新贵音书绝’，请问这在表达什么情感或现象？",
  "answer": "《醉落魄（忆别）》中提到的“旧交新贵音书绝”表达了作者对过去友情的怀念和对现今与故友失去联系的感慨。这里的“旧交”指的是老朋友，而“新贵”可能指那些地位上升后改变了态度或生活方式的朋友。",
  "embType": "QA"
}

# 响应参数说明

字段名	类型	描述	必须	默认值
code	Int	错误码，成功=0	Y	0
sid	String	请求唯一id，用于问题定位	Y
desc	String	结果描述	Y

# 响应参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功"
}

# 4.6、QA对删除

# 接口描述

删除采用的QA对。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/qa/apply/delete

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
ids	String	需要删除的文件id，多个用英文逗号拼接，xxx,aaa,bbb	Y

# 响应参数说明

字段名	类型	描述	必须	默认值
code	Int	错误码，成功=0	Y	0
sid	String	请求唯一id，用于问题定位	Y
desc	String	结果描述	Y

# 响应参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功"
}

# 4.7、QA对查询

# 接口描述

查询文件或者知识库添加的问答对。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/qa/apply/page

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
fileId	String	文件id，和知识库id必传一个	N
repoId	String	知识库id	N
currentPage	Int	当前第几页	N	1
pageSize	Int	每页几条	N	10

# 请求参数示例

{
  "fileId": "af0823f307f04efa9ab4615052a2eb04"
}

# 响应参数说明

字段名	类型	描述	必须	默认值
code	Int	错误码，成功=0	Y	0
sid	String	请求唯一id，用于问题定位	Y
desc	String	结果描述	Y
data	Object	分页数据	Y
data.total	String	总数	Y
data.rows	Array	查询列表	Y
data.rows.id	String	QA对id	Y
data.rows.question	String	问题	Y
data.rows.answer	String	答案	Y
data.rows.embType	String	向量类型，Q-仅仅问题做向量、QA-问题和内容一起做向量	Y

# 请求参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功",
  "data": "5a5f57a52f834ae5b12888ebd282ea0a"
}

# 五、高级功能-文档处理

# 5.1、发起文档总结

# 接口描述

针对单个文档发起内容总结/概要。注：只有 splited、vectoring、vectored 状态的文档才可以发起总结。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/summary/start

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
fileId	String	文件 ID	Y

# 返回参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": null
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Object	返回结果

# 5.2、获取文档总结信息

# 接口描述

查询文档总结/概要信息

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/summary/query

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
fileId	String	文件 ID	Y

# 返回参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": null
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Object	返回结果
data.summaryStatus	String	文件总结状态，unsummary-未总结 summarying-总结中， done-总结完成，illegal-内容敏感，failed-总结失败
data.summary	String	总结内容

# 5.3、文档切分

# 接口描述

根据切分符对文档进行切分，上传文件之后会做一次切分，若切分效果不满意可调用此方法重新切分。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/split

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
fileIds	Array	文件列表	Y
isSplitDefault	Boolean	是否用默认切分策略，如果需要自定义切分符，该值需要设置为false	Y	true
splitType	String	按什么类型拆分，传固定 "wiki"	Y
wikiSplitExtends	String	WIKI拆分扩展	N
wikiSplitExtends.chunkSeparators	Array	分段分隔符，支持多分隔符，base64编码	N	["DQo="]
wikiSplitExtends.chunkSize	Int	分段最大长度，超过强行切分	N	2000
wikiSplitExtends.minChunkSize	Int	分段最小长度，小于该值的分段会向下段聚合，直至达到该值	N	200

# 请求参数示例

{
  "splitType": "wiki",
  "isSplitDefault":false,
  "fileIds": [
    "af0823f307f04efa9ab4615052a2eb04"
  ],
  "wikiSplitExtends":{
    "chunkSeparators": ["DQo="],
    "minChunkSize": 100,
    "chunkSize": 2000
  }
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Object	返回结果

# 返回参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功",
  "data": null
}

# 5.4、文档向量化

# 接口描述

对文档切分的文本块进行向量化操作（embedding），对于文件状态处于splited的文件，可以调用该方法进行向量处理。只有向量化之后的文件才可以发起问答。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/embedding

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
fileIds	String	上传的文件id列表，多个文档id用英文逗号分割	Y

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Object	返回结果

# 返回参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功",
  "data": null
}

# 5.5、文档内容相似度检测

# 接口描述

根据输入的文本，检索拆分后的相关原始文本块。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/vector/search

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
fileIds	Array	文件id列表，不传，查app下所有文件	N
topN	Int	向量库查询数量	N	5
content	String	用户的问题	Y
chatExtends	Object	自定义扩展字段	N
chatExtends.wikiFilterScore	Float	WIKI结果分数阈值，低于这个阈值的结果丢弃	N	0.82
chatExtends.esFilterScore	Float	进行全文检索时的es分数阈值，低于这个阈值的结果丢弃。	N	10

# 请求参数示例

{
  "fileIds": [
    "aa9efce4188b4025b6f9a3cd35e6de99"
  ],
  "content": "在哪下二维码",
  "chatExtends":{
    "wikiFilterScore": 0.90
  }
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Array	返回结果
data.content	String	wiki的文本分片内容
data.score	Float	查询结果分数
data.fileId	String	文件id，代表属于该文件的文段
data.index	Int	文本分片索引
data.type	String	检索类型，vector-向量检索
data.fileType	String	文件类型，wiki、qa

# 返回参数示例

{
  "code":0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc":"成功",
  "data":[
    {
      "content":"xxx",
      "score": 67.5,
      "fileId": "aa9efce4188b4025b6f9a3cd35e6de99"
    }]
}

# 5.6、文档分块内容获取

# 接口描述

获取文件分块内容

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/chunks

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
fileId	String	上传的文件id	Y

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Array	返回结果
data.dataType	String	文件类型 wiki
data.dataIndex	Int	分块索引
data.content	String	wiki分块内容

# 返回参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": [
    {
      "id": "f37203b9d39d4afb8816d30080047695",
      "question": null,
      "dataType": "wiki",
      "dataIndex": 0,
      "content": "名称:智能会议解决方案\n简介:讯飞听见智能会议系统是科大讯飞核心语音技术的集大成者，能将语音实时转成文字，经过个性化订制的标准普通话，转写准确率可达到95%以上，适用于各类会议。\n公司:科大讯飞股份有限公司\n价格:面议\n产品详情:讯飞听见智能会议系统是科大讯飞核心语音技术的集大成者，能将语音实时转成文字，经过个性化订制的标准普通话，转写准确率较高，适用于各类会议。\n链接:https://www.aifuwus.com/onstage/cmddetail?id=59"
    },
    {
      "id": "6567375c79c44f28badd1f0c62794a70",
      "question": null,
      "dataType": "wiki",
      "dataIndex": 1,
      "content": "\r\n名称:服务机器人解决方案\n简介:可提供各种场景不同外观的实体机器人定制及租赁服务，应用于展厅、机场、政务、银行、酒店、商超、医院等公共区域。您留下信息后我们将安排商务经理专人对接。\n公司:科大讯飞股份有限公司\n价格:面议\n产品详情:智能机器人可提供迎宾接待、智能交互、多媒体播放等服务，可同时采集用户线下的“交互式”行为数据。融合线下场景数据、CRM数据和讯飞DMP数据，对目标用户属性、需求偏好、内容消费趋势、潜在需求意图等进行全方位的分析，最终实现深刻理解和预测用户的需求意图。帮助品牌与消费者建立一对一的高效互动，提高营销效率，同时为用户减少信息噪音。\n面对不同行业客户个性化的需求，我们提供包括硬件、软件、云平台、PC端、移动端的完整解决方案，旨在构建一个“硬件+软件+服务+营销”的智能生态圈，致力于让每一个行业享受智慧科技。\n链接:https://www.aifuwus.com/onstage/cmddetail?id=67"
    }
  ]
}

# 5.7、文档详情

# 接口描述

查询文件详情。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/info

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
fileId	String	上传的文件id	Y

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	String	返回结果
data.fileId	String	文件id
data.fileName	String	文件名称
data.fileType	String	文件类型wiki
data.fileStatus	String	文件状态
data.extName	String	文件后缀
data.quantity	Int	文件计量数
data.expirationStatus	String	文件过期状态 active-正常，expired-已过期
data.createTime	String	文件创建时间
data.expireTime	Date	文件过期时间，pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8"

# 返回参数示例

{
  "flag": true,
  "code": 0,
  "desc": null,
  "data": {
    "fileId": "b0862da4c91147209434023c48665957",
    "fileName": "《科大讯飞文档知识库产品说明书》.pdf",
    "extName": "pdf",
    "fileType": "wiki",
    "fileStatus": "vectored",
    "quantity": 40,
    "createTime": "2024-01-10 09:50:19",
    "expireTime": "2024-04-09 23:59:59",
    "expirationStatus": "active"
  },
  "sid": "e01f951b14bb427286bbf6048e816745"
}

# 5.8、文档列表

# 接口描述

查询appId下的文件列表

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/list

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
fileName	String	文件名称，模糊查询	N
extName	String	文件后缀	N
fileStatus	String	文件类型	N
currentPage	Int	查询第几页	N	1
pageSize	Int	每页多少文件	N	10

# 请求参数示例

{
  "fileName": "产品白皮书",
  "extName": "pdf",
  "currentPage": 1,
  "pageSize": 10
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Array	返回结果
data.fileId	String	文件id
data.fileName	String	文件名称
data.fileType	String	文件类型wiki、qa
data.fileStatus	String	文件状态
data.extName	String	文件后缀
data.quantity	Int	文件计量数
data.expirationStatus	String	文件过期状态 active-正常，expired-已过期
data.createTime	String	文件创建时间
data.expireTime	Date	文件过期时间，pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8"

# 返回参数示例

{
  "flag": true,
  "code": 0,
  "desc": null,
  "data": {
    "total": 67,
    "rows": [
      {
        "fileId": "b59b99d4dbc34157b40d2106a32414ac",
        "fileName": "SFU实时音视频产品白皮书_v1.0.pdf",
        "extName": "pdf",
        "fileType": "wiki",
        "fileStatus": "splited",
        "quantity": 24,
        "createTime": "2024-01-11 19:19:35",
        "expireTime": "2024-04-10 23:59:59",
        "expirationStatus": "active"
      },
      {
        "fileId": "91d4cd682c3f4314b3642fb4d45336f8",
        "fileName": "AI中台产品白皮书_V1.0.pdf",
        "extName": "pdf",
        "fileType": "wiki",
        "fileStatus": "vectored",
        "quantity": 24,
        "createTime": "2023-11-14 18:53:14",
        "expireTime": "2024-02-12 23:59:59",
        "expirationStatus": "expired"
      }
    ]
  },
  "sid": "1a4000e8e1ae4edfbf29c0f63b391161"
}

# 5.9、文档删除

# 接口描述

删除文档，该操作会删除文件向量等相关信息。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/file/del

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
fileIds	String	上传的文件id列表，多个文档id用英文逗号分割	Y

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述

# 返回参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功",
  "data": null
}

# 六、高级功能-知识库

# 6.1、知识库创建

# 接口描述

创建一个新的知识库。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/repo/create

# 请求参数说明

POST，application/json

字段名	类型	描述	必须
repoName	String	知识库名称，唯一	Y
repoDesc	String	知识库简介	N
repoTags	String	知识库标签	N

# 请求参数实例

{
  "repoName":  "测试问答知识库",
  "repoDesc":"这是知识库简介",
  "repoTags":  "IT知识问答,AI"
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	String	知识库id，后续知识库操作使用

# 返回参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": "24c4109a57944997bc6b82661243ef67"
}

# 6.2、知识库添加文件

# 接口描述

向知识库中添加文件，每次操作最多可添加20个文件进知识库，文件较多时，需要分多次添加。且同一个文件最多可存在于10个不同知识库。注：仅文档状态为vectored的文件才可以进行问答

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/repo/file/add

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
repoId	String	知识库id	Y
fileIds	Array	文件id列表，最大20	Y

# 请求参数实例

{
  "repoId": "8b1b1717f6e14ed1bd8647cba4fd0806",
  "fileIds": [
    "5a5f57a52f834ae5b12888ebd282ea0a",
    "3a1668af97864f6ca0060d9eda0ffde4",
    "2e66ae9a1f7443248209d3bf85e89432"
  ]
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Object	返回结果
data.failedList	Array	失败文件id列表

# 返回参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": {
    "failedList": [
      "5a5f57a52f834ae5b12888ebd282ea0a"
    ]
  }
}

# 6.3、知识库移除文件

# 接口描述

从知识库中移除文件，一次最多操作20个文件。

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/repo/file/remove

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
repoId	String	知识库id	Y
fileIds	Array	文件id列表，最大20	Y

# 请求参数实例

{
  "repoId": "8b1b1717f6e14ed1bd8647cba4fd0806",
  "fileIds": [
    "5a5f57a52f834ae5b12888ebd282ea0a",
    "3a1668af97864f6ca0060d9eda0ffde4",
    "2e66ae9a1f7443248209d3bf85e89432"
  ]
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Object	返回结果
data.failedList	Array	失败文件id列表

# 返回参数示例

{
  "flag": true,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "code": 0,
  "desc": null,
  "data": {
    "failedList": [
      "5a5f57a52f834ae5b12888ebd282ea0a"
    ]
  }
}

# 6.4、知识库列表

# 接口描述

查询appid下知识库列表

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/repo/list

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
repoName	String	知识库名称，模糊查询	N
currentPage	Int	查询第几页	N	1
pageSize	Int	每页多少文件	N	10

# 请求参数示例

{
  "repoName": "产品说明",
  "currentPage": 1,
  "pageSize": 10
}

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	List	知识库列表
data.repoId	String	知识库id
data.repoName	String	知识库名称
data.repoDesc	String	知识库简介
data.repoTags	String	知识库tag
data.createTime	String	创建时间，pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8"

# 返回参数示例

{
  "flag": true,
  "code": 0,
  "desc": null,
  "data": [{
    "repoId": "9d1a5beea01e4b4a80f12f66f1ee23b0",
    "repoName": "云平台产品说明",
    "repoDesc": "云平台所有产品说明",
    "repoTags": "",
    "createTime": "2024-02-18 17:47:37"
  }],
  "sid": "0b953bd85e4c4675a8700ba705d69953"
}

# 6.5、知识库详情

# 接口描述

查询知识库详情

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/repo/info

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
repoId	String	知识库id	Y

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Object	返回结果
data.repoId	String	知识库id
data.repoName	String	知识库名称
data.repoDesc	String	知识库简介
data.repoTags	String	知识库tag
data.createTime	String	创建时间，pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8"

# 返回参数示例

{
  "flag": true,
  "code": 0,
  "desc": null,
  "data": [{
    "repoId": "9d1a5beea01e4b4a80f12f66f1ee23b0",
    "repoName": "云平台产品说明",
    "repoDesc": "云平台所有产品说明",
    "repoTags": "",
    "createTime": "2024-02-18 17:47:37"
  }],
  "sid": "0b953bd85e4c4675a8700ba705d69953"
}

# 6.6、知识库文件列表

# 接口描述

查询知识库下所有文件

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/repo/file/list

# 请求参数说明

POST，application/json

字段名	类型	描述	必须	默认值
repoId	String	知识库id	Y
fileName	String	文件名称，模糊查询	N
extName	Int	文件后缀	N
currentPage	Int	查询第几页	N	1
pageSize	Int	每页多少文件	N	20

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述
data	Array	返回结果
data.fileId	String	文件id
data.fileName	String	文件名称
data.fileType	String	文件类型wiki、qa
data.fileStatus	String	文件状态
data.extName	String	文件后缀
data.quantity	Int	文件计量数
data.expirationStatus	String	文件过期状态 active-正常 expired-已过期
data.createTime	String	文件创建时间
data.expireTime	Date	文件过期时间，pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8"

# 6.7、知识库删除

# 接口描述

删除知识库

# 接口地址

https://chatdoc.xfyun.cn/openapi/v1/repo/del

# 请求参数说明

POST，application/form-data

字段名	类型	描述	必须	默认值
repoId	String	知识库id	Y

# 返回参数说明

字段名	类型	描述
code	Int	错误码，成功=0
sid	String	请求唯一 id，用于问题定位
desc	String	结果描述

# 返回参数示例

{
  "code": 0,
  "sid": "9746244f046340e2869630e5f6fe8daa",
  "desc": "成功",
  "data": null
}

# 七、错误码

错误码	描述	处理方式
10019	问答的问题或引用文段可能涉政	检查问题或文件内容
10013	问答的问题或引用文段有敏感违规信息	检查问题或文件内容
10014	问答的输出有敏感违规信息	尝试换个问法
60001	文件类型不对	检查文件
60002	文件大小超限	检查文件
60003	文件上传失败	排查
60005	无文件权限	检查入参
60011	文件字数超限	检查文件
60012	文件无有校字符	检查文件
60014	问答的时候未传入文件 id	检查入参
62001	问答的时候，未找到相关文本段	检查提问问题
68003	操作太过频繁	自查
99999	内部错误	排查

# 八、常见问题

# 文档知识库的主要功能是什么？

答：让大模型根据文档内容回答问题，更可创建知识库聚合多文档，一次提问遍历领域知识；文档太多难以通读，快用文档总结，自动总结文档概要，快速了解文档内容等。

# 文档知识库现在支持哪些格式的文档？

答：目前支持 Word、PDF、Markdown、txt 格式的文档。

# 文档知识库支持什么应用平台？

答：目前支持 WebAPI 应用平台。

在这篇文章中：