车联AI知识库 API 文档
一、服务介绍
车联AI知识库是基于车联Autolink-AI的知识库问答方案,能够高效检索文档信息,准确回答专业问题,为大模型补充领域知识,让大模型助你高效了解文档内容。
该接口是通过 API 的方式给开发者提供一个通用的 HTTP 接口,基于该接口,开发者可以获取开放平台的车联AI文档知识库问答能力,方便开发者快速集成。
开通授权
您可在车联AI-Saas平台应用控制台 申请开通 API 权限并采购服务量。
产品体验
基于车联AI知识库方案 API,我们搭建了车联AI文档问答 ,供您快速体验功能和效果。
接口 Demo
示例 Demo请点击 调用示例 下载。
Demo 覆盖部分语言,其他语言请参照下方接口文档进行开发。
欢迎热心的开发者到车联AI-Saas平台社区
分享你们的 demo。
接口要求
内容 | 说明 |
---|---|
传输协议 | https/wss |
请求地址 | 1、文档上传:https://chatdoc.xfyun.cn/openapi/v1/file/upload 2、文档问答:wss://chatdoc.xfyun.cn/openapi/chat 3、发起文档总结:https://chatdoc.xfyun.cn/openapi/v1/file/summary/start 4、获取文档总结/概要内容:https://chatdoc.xfyun.cn/openapi/v1/file/summary/query |
接口鉴权 | 签名机制,详情请参照下方鉴权认证 |
字符编码 | 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×tamp=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 是否开通授权 |
三、接口列表
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 |
callbackUrl | String | 文件状态回调地址,文件状态有变动时服务会调用该 url。调用的时候会带上鉴权头,鉴权方式同【接口鉴权】,业务可根据需要是否做鉴权校验 | N |
返回参数示例
{
"flag": true,
"sid": "9746244f046340e2869630e5f6fe8daa",
"code": 0,
"desc": null,
"data": {
"fileId": "24c4109a57944997bc6b82661243ef67"
}
}
返回参数说明
字段名 | 类型 | 描述 |
---|---|---|
code | Int | 错误码,成功=0 |
sid | String | 请求唯一 id,用于问题定位 |
desc | String | 结果描述 |
data | Object | 返回结果 |
data.fileId | String | 返回上传的 fileId |
2、文档问答
接口描述
对文档/知识库进行问答,流式返回
接口地址
wss://chatdoc.xfyun.cn/openapi/chat?appId=xxxx×tamp=xxxxxxxx&signature=xxxxxx
请求参数说明
在请求 URL 上带上参数:
appId
,timestamp
,signature
鉴权生成详情请参照上方鉴权认证 建立连接时,服务端会校验鉴权
发送消息格式
- 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": "家属有什么福利"
}
]
}
- 参数说明:
字段名 | 类型 | 描述 | 必须 | 默认值 |
---|---|---|---|---|
fileIds | Array | 提问问题检索的文件 id 列表,必传 | Y | |
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.wikiFilterScore | Float | wiki 结果分数阈值,低于这个阈值的结果丢弃。取值范围为(0,1] 参考值为:0.80非常宽松 0.82宽松 0.83标准 0.84严格 0.86非常严格。服务会根据问题检索文件列表中内容相关的文段,该值设置的越高,可能丢弃的内容越多,但保留下来的内容越准确;但过高也可能导致无匹配内容 | N | 0.82 |
chatExtends.temperature | Float | 大模型问答时的温度,取值范围 (0,1] ,temperature 越大,大模型回答随机度越高 | N |
返回消息格式
- 客户端发送消息后,服务端处理后会返回消息,格式如下
{
"code": 0,
"content": "和指南。在此之前,我可以为您",
"fileRefer": "{\"b2de1116b590911111119d0f3dbfc8\":[3,7,8]}",
"sid": "870b299a48ba46b6b5e4dfbd99fe4497",
"status": 1
}
返回参数说明
参数名 | 类型 | 描述 |
---|---|---|
code | Int | 错误码 ,0 标识成功 |
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.sparkWhenWithoutEmbedding用大模型兜底。
3、文档总结
接口描述
针对单个文档发起内容总结/概要
接口地址
https://chatdoc.xfyun.cn/openapi/v1/file/summary/start
请求参数说明
POST,multipart/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 | 返回结果 |
4、获取文档总结/概要信息
接口描述
查询文档总结/概要信息
接口地址
https://chatdoc.xfyun.cn/openapi/v1/file/summary/query
请求参数说明
POST,multipart/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、高级功能
车联AI知识库服务还提供 自定义切分、OCR 识别、文档内容查询、内容相似度检索等功能,请参考详细文档:车联AI知识库API V2.0
四、错误码
错误码 | 描述 | 处理方式 |
---|---|---|
10019 | 问答的问题或引用文段可能涉政 | 检查问题或文件内容 |
10013 | 问答的问题或引用文段有敏感违规信息 | 检查问题或文件内容 |
10014 | 问答的输出有敏感违规信息 | 尝试换个问法 |
60001 | 文件类型不对 | 检查文件 |
60002 | 文件大小超限 | 检查文件 |
60003 | 文件上传失败 | 排查 |
60005 | 无文件权限 | 检查入参 |
60011 | 文件字数超限 | 检查文件 |
60012 | 文件无有校字符 | 检查文件 |
60005 | 无文件权限 | 检查入参 |
60014 | 问答的时候未传入文件 id | 检查入参 |
62001 | 问答的时候,未找到相关文本段 | 检查提问问题 |
68003 | 操作太过频繁 | 自查 |
99999 | 内部错误 | 排查 |
五、调用示例
注: 也欢迎热心的开发者到 车联AI-Saas平台社区 分享你们的 demo。
六、常见问题
文档知识库的主要功能是什么?
答:让大模型根据文档内容回答问题,更可创建知识库聚合多文档,一次提问遍历领域知识;文档太多难以通读,快用文档总结,自动总结文档概要,快速了解文档内容等。
文档知识库现在支持哪些格式的文档?
答:目前支持 Word、PDF、Markdown、txt 格式的文档。
文档知识库支持什么应用平台?
答:目前支持 WebAPI 应用平台。