星火知识库 API 文档

一、服务介绍

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

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

#开通授权

您可在讯飞开放平台应用控制台 申请开通 API 权限，申请后将即时开通并通过邮件通知。

#产品体验

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

#接口 Demo

示例 Demo请点击 调用示例 下载。

Demo 覆盖部分语言，其他语言请参照下方接口文档进行开发。

欢迎热心的开发者到讯飞开放平台社区 分享你们的 demo。

#接口要求

内容	说明
传输协议	https/wss
请求地址	1、文档上传：https://chatdoc.xfyun.cn/openapi/fileUpload 2、文档问答：wss://chatdoc.xfyun.cn/openapi/chat 3、发起文档总结：https://chatdoc.xfyun.cn/openapi/startSummary 4、获取文档总结/概要内容：https://chatdoc.xfyun.cn/openapi/fileSummary
接口鉴权	签名机制，详情请参照下方鉴权认证
字符编码	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 是否开通授权

高级功能

星火知识库服务还提供 自定义切分、OCR 识别、文档内容查询、内容相似度检索等功能，如有需要请联系cbg_open_ml@iflytek.com

#四、错误码

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

#五、调用示例

文档知识库 demo java 语言

文档知识库 demo python 语言

文档知识库 demo go 语言

注： 也欢迎热心的开发者到 讯飞开放平台社区 分享你们的 demo。

#六、常见问题

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

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

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

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

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

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