TAISDK集成文档

TAISDK是一款封装了腾讯云教育AI能力的SDK，通过集成SDK，用户可以快速接入相关产品功能，如数学作业批改、智玲口语评测等。

一、获取密钥

secretId和secretKey是使用SDK的安全凭证，通过以下方式获取

获取到秘钥后到tencentcloud-sdk-android-soe/TAIDemo/app/src/main/java/com/tencent/taidemo/PrivateInfo.java填入对应的appId ,secretId ,secretKey. soeAppId 和hcmAppId根据需要填写.需要到控制台新建.
soe控制台:https://console.cloud.tencent.com/soe/index/setting_en
hcm控制台:https://console.cloud.tencent.com/hcm/app
token 不需要填写.

二、SDK集成

1、导入SDK

1.源码方式导入

Demo源码下载

从Demo获取SDK并导入到工程

2.CocoaPods集成

1. 安装 CocoaPods

sudo gem install cocoapods

2. 创建 Podfile 文件
   进入项目所在路径，输入以下命令行之后项目路径下会出现一个 Podfile 文件。

pod init

3. 编辑 Podfile 文件
   编辑 Podfile 文件，支持选择版本号
   进入项目所在路径，输入以下命令行之后项目路径下会出现一个 Podfile 文件。

platform :ios, '8.0'
target 'TAIDemo' do
 pod 'TAISDK_iOS'
end

4. 更新并安装sdk
   在终端窗口中输入如下命令以更新本地库文件，并安装 TAI SDK：

pod install 

或使用以下命令更新本地库版本：

pod update

pod 命令执行完后，会生成集成了 SDK 的 .xcworkspace 后缀的工程文件，双击打开即可。

2、接口调用

数学作业批改

//一、声明并定义对象
@property (strong, nonatomic) TAIMathCorrection *mathCorrection;
self.mathCorrection = [[TAIMathCorrection alloc] init];

//二、初始化参数
TAIMathCorrectionParam *param = [[TAIMathCorrectionParam alloc] init];
param.sessionId = [[NSUUID UUID] UUIDString];
param.appId = @"";
param.imageData = UIImageJPEGRepresentation(_imageView.image, 0);
param.secretId = @"";
param.secretKey = @"";
//三、作业批改
[self.mathCorrection correction:param callback:^(TAIError *error, TAIMathCorrectionRet *result) {
    //成功返回TAIMathCorrectionRet
}];

智玲口语评测

//一、声明并定义对象
@property (strong, nonatomic) TAIOralEvaluation *oralEvaluation;
self.oralEvaluation = [[TAIOralEvaluation alloc] init];
self.oralEvaluation.delegate = self;

//二、数据回调
- (void)oralEvaluation:(TAIOralEvaluation *)oralEvaluation onEvaluateData:(TAIOralEvaluationData *)data result:(TAIOralEvaluationRet *)result error:(TAIError *)error
{
    //数据和结果回调（只有data.bEnd为YES，result有效）
}

• 内部录制（SDK内部录制音频并传输，推荐）

//三、初始化参数
TAIOralEvaluationParam *param = [[TAIOralEvaluationParam alloc] init];
param.sessionId = [[NSUUID UUID] UUIDString];
param.appId = @"";
param.workMode = TAIOralEvaluationWorkMode_Once;
param.evalMode = TAIOralEvaluationEvalMode_Sentence;
param.storageMode = TAIOralEvaluationStorageMode_Disable;
param.serverType = TAIOralEvaluationServerType_English;
param.scoreCoeff = 1.0;
param.fileType = TAIOralEvaluationFileType_Mp3;
param.refText = @"";
param.secretId = @"";
param.secretKey = @"";
//四、开始录制
[self.oralEvaluation startRecordAndEvaluation:param callback:^(TAIError *error) 
    //结果返回
}];

//五、结束录制
[self.oralEvaluation stopRecordAndEvaluation:^(TAIError *error) {
    //结果返回
}];

• 外部录制（SDK外部录制音频数据作为Api调用参数）

//三、初始化参数
TAIOralEvaluationParam *param = [[TAIOralEvaluationParam alloc] init];
param.sessionId = [[NSUUID UUID] UUIDString];
param.appId = @"";
param.workMode = TAIOralEvaluationWorkMode_Once;
param.evalMode = TAIOralEvaluationEvalMode_Sentence;
param.storageMode = TAIOralEvaluationStorageMode_Disable;
param.serverType = TAIOralEvaluationServerType_English;
param.scoreCoeff = 1.0;
param.fileType = TAIOralEvaluationFileType_Mp3;
param.refText = @"hello guagua";
param.secretId = @"";
param.secretKey = @"";

NSString *mp3Path = [[NSBundle mainBundle] pathForResource:@"hello_guagua" ofType:@"mp3"];
TAIOralEvaluationData *data = [[TAIOralEvaluationData alloc] init];
data.seqId = 1;
data.bEnd = YES;
data.audio = [NSData dataWithContentsOfFile:mp3Path];
__weak typeof(self) ws = self;  

//评测结束后是否重置AVAudioSession  true:重置  false:否
[self.oralEvaluation resetAvAudioSession:true];  

//四、传输数据
[self.oralEvaluation oralEvaluation:param data:data callback:^(TAIError *error) {
    //接口调用结果返回
}];

注意事项

外部录制三种格式目前仅支持16k采样率16bit编码单声道，如有不一致可能导致评估不准确或失败

• 静音检测

//在开始调用`startRecordAndEvaluation`前设置录制参数
TAIRecorderParam *recordParam = [[TAIRecorderParam alloc] init];
recordParam.fragEnable = YES;
recordParam.fragSize = 1024;
recordParam.vadEnable = YES;
recordParam.vadInterval = 5000;
[self.oralEvaluation setRecorderParam:recordParam];

当检测到静音或者录音分贝变化时，通过TAIOralEvaluationListener通知上层。

//检测到静音
- (void)oralEvaluation:(TAIOralEvaluation *)oralEvaluation  onEndOfSpeechInOralEvaluation:(BOOL)isSpeak;
{
    //这里可以根据业务逻辑处理，如停止录音或提示用户
}

//音量发生变化
- (void)oralEvaluation:(TAIOralEvaluation *)oralEvaluation onVolumeChanged:(NSInteger)volume
{
    //回调录音分贝大小[0-120]
}

TAIRecorderParam参数说明

参数	类型	说明
fragEnable	BOOL	是否开启分片，默认YES
fragSize	NSInteger	分片大小，默认1024，建议为1024的整数倍，范围【1k-10k】
vadEnable	BOOL	是否开启静音检测，默认NO
vadInterval	NSInteger	静音检测时间间隔，单位【ms】
db	NSInteger	静音检测分贝阈值

3、签名

secretKey属于安全敏感参数，线上版本一般由业务后台生成临时secretKey或者SDK外部签名返回到客户端。

（1）内部签名：sdk内部通过用户提供的secretKey和secretId计算签名，用户无需关心签名细节

（2）外部签名：sdk外部调用getStringToSign获取签名字符串，然后根据签名规则（参考步骤三） 进行签名。口语评测时需提供secretId、timestamp和signature参数

//获取签名所需字符串
- (NSString *)getStringToSign:(NSInteger)timestamp;

注意事项

时间戳timestamp必须和TAIEvaluationParam参数的timestamp一致

4、参数说明

公共参数

• TAICommonParam参数说明

参数	类型	必填	说明
appId	NSString	是	appId
timeout	NSInteger	否	超时时间，默认30秒
secretId	NSString	是	密钥Id
secretKey	NSString	内部签名：必填	密钥Key
signature	NSString	外部签名：必填	签名
timestamp	NSInteger	外部签名：必填	秒级时间戳

• TAIError参数说明

参数	类型	说明
code	TAIErrCode	错误码
desc	NSString	错误描述
requestId	NSString	请求id，定位错误信息

数学作业批改

• TAIMathCorrectionParam参数说明

参数	类型	必填	说明
sessionId	NSString	是	一次批改唯一标识
imageData	NSData	是	图片数据

• TAIMathCorrectionRet参数说明

参数	类型	说明
sessionId	NSString	一次批改唯一标识
formula	NSString	算式
items	NSArray<TAIMathCorrectionItem *>	算式结果

• TAIMathCorrectionItem参数说明

参数	类型	说明
result	BOOL	算式结果
rect	CGRect	算式坐标
formula	NSString	算式字符串

智玲口语评测

• TAIOralEvaluationParam参数说明

参数	类型	必填	说明
sessionId	NSString	是	一次批改唯一标识
workMode	TAIOralEvaluationWorkMode	是	传输方式
evalMode	TAIOralEvaluationEvalMode	是	评测模式
isFixOn	BOOL	否	true:开启单词映射,false:关闭单词映射
fileType	TAIOralEvaluationFileType	是	数据格式
storageMode	TAIOralEvaluationStorageMode	式	是否存储音频文件
serverType	TAIOralEvaluationServerType	是	语言类型
hostType	TAIOralEvaluationHostType	否	host类型 0:国内 1:海外
scoreCoeff	float	是	苛刻指数，取值为[1.0 - 4.0]范围内的浮点数，用于平滑不同年龄段的分数，1.0为小年龄段，4.0为最高年龄段
refText	NSString	是	被评估语音对应的文本

• TAIOralEvaluationData参数说明

参数	类型	说明
seqId	NSInteger	分片序列号(从1开始)
bEnd	BOOL	是否最后一个分片
audio	NSData	音频数据

• TAIMathCorrectionRet参数说明

参数	类型	说明
sessionId	NSString	一次批改唯一标识
pronAccuracy	float	发音精准度，取值范围[-1, 100]，当取-1时指完全不匹配
pronFluency	float	发音流利度，取值范围[0, 1]，当为词模式时，取值无意义
pronCompletion	float	发音完整度，取值范围[0, 1]，当为词模式时，取值无意义
audioUrl	NSString	保存语音音频文件的下载地址（TAIOralEvaluationStorageMode_Enable有效）
words	NSArray<TAIOralEvaluationWord *>	详细发音评估结果
suggestedScore	float	建议评分，取值范围[0,100]

• TAIOralEvaluationPhoneInfo参数说明

参数	类型	说明
beginTime	int	当前单词语音起始时间点，单位为ms
endTime	int	当前单词语音终止时间点，单位为ms
pronAccuracy	float	音节发音准确度，取值范围[-1, 100]，当取-1时指完全不匹配
detectedStress	BOOL	当前音节是否检测为重音
phone	NSString	当前音节
stress	BOOL	当前音节是否应为重音
referencePhone	NSString	标准音素
rLetter	NSString	音素映射的字母

• TAIOralEvaluationWord参数说明

参数	类型	说明
beginTime	int	当前单词语音起始时间点，单位为ms
endTime	int	当前单词语音终止时间点，单位为ms
pronAccuracy	float	单词发音准确度，取值范围[-1, 100]，当取-1时指完全不匹配
pronFluency	float	单词发音流利度，取值范围[0, 1]
word	NSString	当前词
matchTag	int	当前词与输入语句的匹配情况，0:匹配单词、1：新增单词、2：缺少单词
phoneInfos	NSArray<TAIOralEvaluationPhoneInfo *>	音节评估详情