Embedding Android SDK 集成文档

1. Embedding

为开发者提供了文档向量化工具和用户问题向量化工具,方便开发者更好的向量化数据库,提高问题的匹配精确度,带给用户更好的使用体验。

2. 兼容性说明

类别 兼容范围
系统 支持armv7和armv8架构,兼容android 5.0及以上版本
开发环境 建议使用Android Studio 进行开发

3. 授权说明

车联AI认知大模型授权支持按照tokens授权和设备级授权两种方式。

tokens 授权:授权tokens总量,按照tokens 使用量计费,1 tokens 约等于1.5个中文汉字 或者 0.8个英文单词。

4. SDK集成包目录结构

将SDK zip包解压缩,得到如下文件:

├── Demo AutolinkChain的使用DEMO,DEMO中已经集成了SDK,您可以参考DEMO,集成SDK。集成前,请先测通DEMO,了解调用原理。

├── ReleaseNotes.txt SDK版本日志

├── SDK AutolinkChain SDK

│ └── AutolinkChain.aar

└── AutolinkChain Embedding Android SDK集成文档.pdf AutolinkChain集成指南

5. SDK工程配置

5.1 导入SDK库

复制AutolinkChain.aar到项目的libs目录下,然后在主Module的build.gradle文件中,增加如下配置:

implementation files('libs/AutolinkChain.aar')

5.2 配置权限

AutolinkChain SDK中默认配置了以下权限:

权限 使用说明
INTERNET 必须权限,SDK需要访问网络获取结果。
READ_EXTERNAL_STORAGE 必须权限,SDK需要判断日志路径是否存在。
WRITE_EXTERNAL_STORAGE 必须权限,SDK写本地日志需要用到该权限。
MANAGE_EXTERNAL_STORAGE 可选权限,安卓10以上设备用于动态授权弹出授权框需要用到该权限,安卓10以上设备必选。
READ_PHONE_STATE 可选权限,用于获取设备标识。

如果部分权限不需要,可通过如下配置去除,去除示例如下:

<!-- 移除SDK非必须权限示例 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" tools:node="remove" />

Android 10.0(API 29)及以上版本需要在application中做如下配置

<application android:requestLegacyExternalStorage="true"/>

5.3 混淆配置

AutolinkChain SDK 已做过混淆,如果您项目中也使用了混淆,请在 proguard-rules.pro文件中添加如下配置保持AutolinkChain SDK 不再被混淆。

-keep class com.iflytek.AutolinkChain.** {*;}
-keep class com.iflytek.AutolinkChain.**

6. SDK 初始化

在使用SDK功能前,需要先开通Autolink-AI授权并获取已开通授权的应用信息(appId、apiKey、apiSecret)。SDK全局只需要初始化一次。 初始化时,开发者需要构建一个AutolinkChainConfig实例config,把相关的appid信息以及日志设置等传入config中,然后再通过AutolinkChain.getInst().init方法把config实例设置到SDK中。具体初始化示例如下:

//配置应用信息 
AutolinkChainConfig config =  AutolinkChainConfig.builder()
    .appID("$appId")
    .apiKey("$apiKey")
    .apiSecret("$apiSecret");
int ret = AutolinkChain.getInst().init(getApplicationContext(), config);

初始化参数说明:

接口名称 含义 参数类型 限制 是否必填
appID 创建应用后,生成的应用ID String 与平台生成的appID完全一致
apiKey 创建应用后,生成的唯一应用标识 String 与平台生成的apiKey完全一致
apiSecret 创建应用后,生成的唯一应用秘钥 String 与平台生成的apiSecret完全一致
logLevel 日志等级 int 枚举,0:VERBOSE,1:DEBUG,2:INFO,3:WARN,4:ERROR,5:FATAL,100:OFF
logPath 日志存储路径(具体指定到文件名,如"/sdcard/iflytek/AutolinkChain.log"),设置则会把日志存在该路径下,不设置则会把日志打印在终端上。 String 设置的路径需要有读写权限
uid 用户自定义标识 String

初始化返回值:0:初始化成功,非0:初始化失败,请根据具体返回值参考错误码章节查询原因。

7. 文档向量化建模

开发者通过调用Embedding.getInst().embeddingP接口进行文档向量化,接口如下:

public class Embedding {
    public EmbeddingOutput embeddingP(String input, String uid) {
        ...
    }
    public EmbeddingOutput embeddingP(String input) {
        ...
    }
}

embeddingP接口说明:

参数名 类型 说明
input String 需要向量化的文本 限制:0-2048Token
uid String 请求用户服务返回的uid,用于应用端做用户区分 限制:length 0-50

EmbeddingOutput结构说明:

方法名 返回值类型 说明
getRaw() String 获取大模型返回的原始结果,格式为json。
getErrCode() int 获取请求结果,0:成功,非0:请求失败。
getErrMsg() String 获取错误信息,注意:如果调用成功,则此接口会返回空。
getSid() String 获取本次交互的sid。
getResultArray() ArrayList 获取本次请求文本的向量化结果。

具体示例如下:

/*********** * 文档向量化建模 * ***************/
private void startEmbeddingP(){
    EmbeddingOutput output = Embedding.getInst().embeddingP("这段话的内容变成向量化是什么样的?");
    int ret = output.getErrCode();
    if(ret == 0){
        //获取向量化结果    	
        ArrayList<Float> af = output.getResultArray();
        ...
    }else{
        showInfo("Embedding转换失败,错误码:" + ret);
    }
}

8. 用户问题向量化建模

开发者通过调用Embedding.getInst().embeddingQ接口进行用户问题向量化,接口如下:

public class Embedding {
    public EmbeddingOutput embeddingQ(String input, String uid) {
        ...
    }
    public EmbeddingOutput embeddingQ(String input) {
        ...
    }
}

embeddingQ接口说明:

参数名 类型 说明
input String 需要向量化的文本 限制:0-2048Token
uid String 请求用户服务返回的uid,用于应用端做用户区分 限制:length 0-50

EmbeddingOutput结构说明:

方法名 返回值类型 说明
getRaw() String 获取大模型返回的原始结果,格式为json。
getErrCode() int 获取请求结果,0:成功,非0:请求失败。
getErrMsg() String 获取错误信息,注意:如果调用成功,则此接口会返回空。
gitSid() String 获取本次交互的sid。
getResultArray() ArrayList 获取本次请求文本的向量化结果。

具体示例如下:

/*********** * 问题向量化建模 * ***************/
private void startEmbeddingQ(){
    EmbeddingOutput output = Embedding.getInst().embeddingQ("这段话的内容变成向量化是什么样的?");
    int ret = output.getErrCode();
    if(ret == 0){
        //获取向量化后的结果    	
        ArrayList<Float> af = output.getResultArray();
        ...
    }else{
        showInfo("Embedding转换失败,错误码:" + ret);
    }
}

9. 逆初始化

当SDK需要完整退出时,需调用逆初始化方法释放资源,示例代码如下:

AutolinkChain.getInst().unInit();

10. SDK API介绍

10.1 AutolinkChainConfig API

返回值类型 方法说明
AutolinkChainConfig public AutolinkChainConfig appID(String appID)
设置用户的appID
AutolinkChainConfig public AutolinkChainConfig apiKey(String apiKey)
设置用户的apiKey
AutolinkChainConfig public AutolinkChainConfig apiSecret(String apiSecret)
设置用户的apiSecret
AutolinkChainConfig public uid(String uid)
设置用户自定义标识
AutolinkChainConfig public AutolinkChainConfig workDir(String workDir)
设置SDK工作路径
AutolinkChainConfig public AutolinkChainConfig logLevel(int logLevel)
设置日志等级
AutolinkChainConfig public AutolinkChainConfig logPath(String logPath)
设置日志保存路径
AutolinkChainConfig public static AutolinkChainConfig builder()
构建AutolinkChain实例

10.2 AutolinkChain API

返回值类型 方法说明
AutolinkChain public static AutolinkChain getInst()
获取AutolinkChain实例
int public int init(Context context, AutolinkChainConfig config)
SDK初始化
int public int init(Context context)
SDK初始化
int public int unInit()
SDK逆初始化
int public int getInitCode()
获取SDK初始化结果码

10.3 Embedding API

返回值类型 方法说明
EmbeddingOutput public EmbeddingOutput embeddingP(String input, String uid)
文档向量化建模接口
EmbeddingOutput public EmbeddingOutput embeddingP(String input)
文档向量化建模接口
EmbeddingOutput public EmbeddingOutput embeddingQ(String input, String uid)
用户问题向量化建模接口
EmbeddingOutput public EmbeddingOutput embeddingQ(String input)
用户问题向量化建模接口
Embedding public static Embedding getInst()
获取Embedding实例对象

10.4 EmbeddingOutput API

返回值类型 方法说明
String String getRaw()
获取大模型返回的原始结果
int int getErrCode()
获取错误码
String String getErrMsg()
获取错误信息
String String getSid()
获取本次交互的sid
ArrayList ArrayList getResultArray()
获取向量化结果

11. 错误码

错误码 含义 自查指南
0 操作成功
18000 本地license文件不存在 检查工作目录下是否存在license文件,或者该目录是否有读写权限
18001 授权文件内容非法 授权文件存在问题,请联系技术支持询问
18002 授权文件解析失败 授权文件可能存在损坏,请联系技术支持询问
18003 payload内容缺失 授权文件存在问题,请联系技术支持询问
18004 signature内容缺失 授权文件存在问题,请联系技术支持询问
18005 授权已过期 授权时间过期,请检查系统时间是否是当前时间,并联系技术支持询问
18006 授权时间错误,比正常时间慢30分钟以上 请检查系统时间是否正确
18007 授权应用不匹配(apiKey、apiSecret) apiKey、apiSecret 配置有误,请核对项目中配置的 apiKey、apiSecret 。
18008 授权文件激活过期 授权文件已超过15天未激活,需要联系相关人员重新生成离线授权文件
18009 授权app信息指针为空
18010 离线授权激活文件指定平台与设备平台不匹配 授权文件里预置的平台架构与实际运行的设备的平台架构不一致
18011 离线授权激活文件指定架构与设备cpu架构不匹配 授权文件里预置的cpu架构与实际运行的设备的cpu架构不一致
18012 离线授权激活文件中包含License个数异常 离线授权文件异常,请联系相关人员重新生成离线授权文件
18013 离线授权激活文件中未找到当前设备 当前运行的设备的设备指纹不在离线授权文件中,请检查该设备的设备指纹是否在提供的指纹池中
18014 离线授权激活文件中设备指纹安全等级非法 请联系技术支持调整该appid的设备指纹等级
18015 硬件授权验证失败 硬件授权验证失败,请联系相关人员处理
18016 离线授权激活文件内容非法 离线授权文件被修改,请联系相关人员重新生成离线授权文件
18017 离线授权激活文件中协议头非法 离线授权文件被修改,请联系相关人员重新生成离线授权文件
18018 离线授权激活文件中指纹组成项个数为0 离线授权文件生成异常,请联系相关人员重新生成离线授权文件
18019 资源已过期 资源的时间校验已过期,请联系相关人员增加授权时间
18100 资源鉴权失败 资源鉴权失败,请联系相关人员处理
18101 资源格式解析失败 资源格式解析失败,请联系相关人员处理
18102 资源(与引擎)不匹配 资源(与引擎)不匹配,请检查资源是否用错,如果未用错,请联系相关人员处理
18103 资源参数不存在(指针为NULL) 资源参数不存在,请检查资源是否正确
18104 资源路径打开失败 资源路径打开失败,请检查工作目录下是否存在该资源,或者该资源是否存在读写权限
18105 资源加载失败,workDir内未找到对应资源 请检查workDir中是否存在此资源,或者resDir是否设置正确,或者app是否有改路径的读写权限
18106 资源卸载失败, 卸载的资源未加载过 资源卸载失败, 卸载的资源未加载过
18200 引擎鉴权失败 引擎鉴权失败,引擎存在问题。请联系技术支持询问
18201 引擎动态加载失败 引擎动态加载失败,请联系技术支持询问
18202 引擎未初始化 引擎在使用前,需要调用engineInit初始化
18203 引擎不支持该接口调用 引擎不支持该接口调用,请查询对应的能力文档,使用正确的方法调用
18204 引擎craete函数指针为空 引擎存在问题,请联系技术支持询问
18300 SDK不可用 SDK存在异常,请联系技术支持询问
18301 SDK未初始化 在使用大模型前请先初始化 SDK,如果有调用 uninit 方法,再次使用大模型交互时需要重新初始化。
18302 SDK初始化失败 请根据init接口回调中返回的错误码参考此文档做对应检查
18303 SDK 已经初始化 重复初始化导致,使用能力时,SDK 只需要初始化一次,请检查 SDK 初始化逻辑是否存在多次初始化。
18304 不合法参数 请参考demo及集成文档仔细检查所传参数是否正确。
18305 SDK会话handle为空 请检查代码逻辑,handle是否被释放
18306 SDK会话未找到 SDK会话未找到
18307 SDK会话重复终止 SDK会话重复终止,请检查代码逻辑
18308 超时错误 请求超时
18309 SDK正在初始化中 SDK正在初始化中,请检查代码逻辑
18310 SDK会话重复开启 SDK会话重复开启,请检查代码逻辑
18311 sdk同一能力并发路数超出最大限制 sdk同一能力并发路数超出最大限制
18312 此实例已处在运行态,禁止单实例并发运行 SDK同一能力单实例不支持并发
18400 工作目录无写权限 在设置 workDir 时,请确保该工作路径有读写权限。若无法设置读写权限,请修改为有读写权限的工作路径。
18401 设备指纹获取失败,设备未知 采集不到设备指纹
18402 文件打开失败 请检查 日志中所打印的文件是否存在,以及对应路径下是否有读权限。
18403 内存分配失败 请联系技术支持询问
18404 设备指纹比较失败 请联系技术支持询问
18500 未找到该参数 key 请参照demo或集成文档仔细检查参数名拼写
18501 参数范围溢出,不满足约束条件 请根据文档检查调用 SDK 方法时所传参数范围,需要确保所传参数符合协议约束要求
18502 SDK 初始化参数为空 请根据 SDK 集成文档检查 SDK 初始化代码,确保必填参数有值且合法
18503 SDK 初始化参数中 appId 为空 appId 为空值,请在 SDK 初始化时传入正确的 appId 值
18504 SDK 初始化参数中 apiKey为空 apiKey为空值,请在 SDK 初始化时传入正确的 apiKey值
18505 SDK 初始化参数中 apiSecret 为空 apiSecret 为空值,请在 SDK 初始化时传入正确的 apapiSecret 值
18506 ability参数为空 请检查代码逻辑,参数是否未传入
18507 input参数为空 请检查代码逻辑,参数是否未传入
18508 输入数据参数Key不存在 请检查代码逻辑,参数key是否不符合该引擎
18509 必填参数缺失 请参考demo或者文档检查是否漏传必填参数
18510 output参数缺失 引擎输出参数异常,请联系技术支持询问
18520 不支持的编解码类型 请检查送入的数据是否符合要求
18521 编解码handle指针为空 请检查代码逻辑,handle是否被释放
18522 编解码模块条件编译未打开 请联系技术支持询问
18523 编码错误 请联系技术支持询问
18524 解码错误 请联系技术支持询问
18600 协议中时间戳字段缺失 协议文件异常,请联系技术支持询问
18601 协议中未找到该能力ID 调用的能力不在该SDK中,请检查SDK是否使用错误,或者调用能力id是否写错
18602 协议中未找到该资源ID appid没有该资源的使用权限
18603 协议中未找到该引擎ID 协议存在问题,请联系技术支持询问
18604 协议中引擎个数为0 协议存在问题,请联系技术支持询问
18605 协议未被初始化解析 协议存在问题,请联系技术支持询问
18606 协议能力接口类型不匹配 协议存在问题,请联系技术支持询问
18607 预置协议解析失败 协议存在问题,请联系技术支持询问
18700 通用网络错误 请检查网络连接是否正常
18701 网络不通 请检查网络连接是否正常
18702 网关检查不过 检查设备时间是否正确; 请检查 SDK 初始化时所传 apiKey、apiScrect 是否正确;
18703 云端响应格式不对 请检查网络是否可以正常访问外网
18704 应用未注册 appid存在问题,请检查 appid 是否正确
18705 应用 ApiKey & ApiSecret 校验失败 请检查 apiKey、apiSecret 是否正确
18706 引擎不支持的平台架构 请检查运行的设备平台引擎是否支持
18707 授权已过期 请检查授权期限
18708 无可用授权 没有授权或者授权已满
18709 未找到该app绑定的能力 请检查该appid是否申请该能力
18710 未找到该app绑定的能力资源 该appid没有该资源的使用权限,请联系技术支持询问
18711 JSON操作失败 请联系技术支持询问
18712 网络请求 404 错误 请检查网络是否通畅
18713 设备指纹安全等级不匹配 设备指纹安全等级不符合要求
18714 应用信息有误 服务端无法查询到api_key,请检查api_key和api_secret信息是否填写正确
18715 未找到该SDK ID SDK异常,请联系技术支持询问
18716 未找到该组合能力集合 请检查使用的能力是否是该appid所申请的能力
18717 SDK授权不足 授权数量已满
18718 无效授权应用签名 应用签名异常,请联系技术支持询问
18719 应用签名不唯一 应用签名异常,请联系技术支持询问
18720 能力schema不可用 请联系技术支持询问
18721 竞争授权: 未找到能力集模板 请联系技术支持询问
18722 竞争授权: 能力不在模板能力集模板中 请联系技术支持询问
18801 连接建立出错 请检查网络是否通畅
18802 结果等待超时 请检查网络是否通畅
18803 连接状态异常 请检查网络是否通畅
18902 并发超过路数限制 不支持并发
18903 大模型规划步骤为空 请检查请求数据的意图是否明确
18904 插件未找到 请检查是否使用了未存在的插件
18906 与大模型交互次数超限制
18907 运行超限制时长
18908 大模型返回结果格式异常 可能是因为大模型结果太多,导致30秒内没有返回完,从而引起SDK内部认为超时,建议使用异步调用。
18951 同一流式大模型会话,禁止并发交互请求
18952 输入数据为空或异常
19001 设备级授权: 设备被禁用
19002 设备级授权: 协议解析失败
19003 设备级授权: 本地缓存获取失败
19004 设备级授权: 无网络
19005 设备级授权: 授权未找到
19006 设备级授权: 设备授权获取失败
19007 设备级授权: 当前设备处于黑名单
19008 设备级授权: 当前设备不在白名单
19010 设备级授权: 鉴权参数非法
20011 设备级授权: 不匹配的appid