通过集成
AIConversationKit
组件,您可为产品快速集成前沿的 AI 对话能力,实现流畅自然的智能交互体验,显著提升用户活跃度与满意度。 AI 倾听界面 | AI 对话界面 |
![]() | ![]() |
准备工作
开通服务
环境要求
Xcode:需使用 Xcode 15 或更高版本。
iOS 系统:支持 iOS 13.0 或更高版本的设备。
CocoaPods 环境:已安装 CocoaPods 环境。如果您尚未安装,请参见 CocoaPods 官网安装,或按以下步骤操作:
使用 gem 安装 CocoaPods:在终端中执行
sudo gem install cocoapods
命令进行安装。提示:
sudo gem install cocoapods
安装过程中可能需要输入电脑密码,按提示输入管理员密码即可。代码集成
获取 AIConversationKit 组件
1. 从 GitHub 下载 zip 文件,解压后,您会看到 AIConversationKit 目录、AIConversationKit.podspec 文件和 Resource 目录。

2. 复制上一步中解压得到的目录里的 AIConversationKit、podspec 和 Resource 到您的工程中。

3. 然后在
.xcodeproj
打开控制台,执行 pod init
。4. 在生成的 Podfile 里这样写:
pod 'AIConversationKit',:path => 'AIConversationKit.podspec'

5. 执行
pod install
。
6. 打开
.xcworkspace
:
7. 配置证书信息:

工程配置
使用 AI 对话,需要授权麦克风使用权限。在 App 的 Info.plist 中添加以下麦克风声明,对应麦克风系统弹出授权对话框时的提示信息。
<key>NSMicrophoneUsageDescription</key><string>此应用需要使用麦克风进行 AI 语音对话</string>

完成登录
在您的项目中添加登录代码,这是使用
AIConversationKit
各项功能的关键前提:import TUICoreimport AIConversationKit// 示例代码在 didFinishLaunchingWithOptions 完成登录,推荐您在自己登录业务完成后再调用登录服务func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {let userId = "denny" // 请替换为您的 UserIDlet sdkAppId = 1600000001 // 请替换为开通服务控制台的 SDKAppIDlet sdkSecretKey = "xxx" // 请替换为开通服务控制台的 SDKSecretKeylet userSig = GenerateTestUserSig.genTestUserSig(sdkAppId: sdkAppId, userId: userId, secrectkey: sdkSecretKey)TUILogin.login(Int32(sdkAppId), userID: userId, userSig:userSig){print("login success")} fail: { code, message inprint("login failed, code: \\(code), error: \\(message ?? "nil")")}return true}
登录接口参数说明
参数 | 类型 | 说明 |
SDKAppID | Int | |
UserID | String | 当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。 |
userSig | String | 用于腾讯云鉴权的票据。请注意: 开发环境:您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 UserSig 或者通过 UserSig 辅助工具 生成临时的 UserSig。生产环境:为了防止密钥泄露,请务必采用服务端生成 UserSig 的方式。详细信息请参见 服务端生成 UserSig。 |
开始您的第一次 AI 对话
登录成功后,使用以下代码发起 AI 对话:
let startParams = StartAIConversationParams()let sdkAppId = 1600000001 // 1、替换 sdkAppIdlet sdkSecretKey = "xxx" // 2、替换 sdkSecretKeylet aiRobotId = "robot_\\(TUILogin.getUserID() ?? "")"let aiRobotSig = GenerateTestUserSig.genTestUserSig(sdkAppId: sdkAppId, userId: aiRobotId, secrectkey: sdkSecretKey)startParams.agentConfig = AIConversationDefine.AgentConfig.generateDefaultConfig(aiRobotId: aiRobotId, aiRobotSig: aiRobotSig)startParams.secretId = "xxx" // 3、替换 secretIdstartParams.secretKey = "xxx" // 4、替换 secretKey// 5、替换 llmConfigstartParams.llmConfig = "{\\"LLMType\\":\\"openai\\",\\"Model\\":\\"hunyuan-turbo-latest\\",\\"SystemPrompt\\":\\"您是一个个人助手\\",\\"APIUrl\\":\\"https://hunyuan.cloud.tencent.com/openai/v1/chat/completions\\",\\"APIKey\\":\\"xxxx\\",\\"History\\":5,\\"Streaming\\":true}"// 6、替换 ttsConfigstartParams.ttsConfig = "{\\"TTSType\\":\\"tencent\\",\\"AppId\\":\\"xxx\\",\\"SecretId\\":\\"xxx\\",\\"SecretKey\\":\\"xxx\\",\\"VoiceType\\":\\"502001\\",\\"Speed\\":1.25,\\"Volume\\":5,\\"PrimaryLanguage\\":1,\\"FastVoiceType\\":\\"\\"}"let aiViewController = AIConversationViewController(aiParams: startParams)navigationController?.pushViewController(aiViewController, animated: true)
1. sdkAppId 和 sdkSecretKey 使用 完成登录 获取的数据即可。
2. 使用 Playground 配置 AI 对话参数,包括基础配置、STT、LLM、TTS;然后点击右下角的快速跑通,切换到 iOS,获取 SecretId、SecretKey 和 Config 参数。

3. 将云 API 的 SecretId 和 SecretKey 复制到
startParams.secretId
和startParams.secretKey
中。4. 将 Config 信息复制到 Json 解析工具中,如 JsonUtil,将 LLMConfig 对应的字符串值复制到
startParams.llmConfig
,将 TTSConfig 对应的字符串值复制到startParams.ttsConfig
中。说明:
开发环境:如果您正在本地开发调试阶段,可以采用上述方式快速集成 AI 对话。该方法中账号信息很容易被反编译逆向破解,一旦您的密钥泄露,攻击者就可以盗用您的腾讯云流量。
生产环境:如果您的项目要发布上线,请将上述账号信息保存到服务端中,避免流量被盗用;相关对话配置,也可以保存到服务端中,方便动态调整 AI 对话效果。
调节对话效果
为了在 AI 对话中获得最佳体验,清晰的声音采集至关重要。我们提供多种参数设置,帮助您在不同环境下都能获得清晰的语音交互效果。
vadLevel 远场人声抑制
在多人交谈的环境中,其他人声可能会干扰 AI 对您声音的识别。通过调整人声抑制级别,我们可以有效过滤环境中的其他人声干扰,让 AI 更准确地专注于您的语音;您可以通过设置 startParams 中的 sttConfig.vadLevel 参数来达到期望的效果。
级别 | 效果描述 | 使用场景 |
0 | 关闭远场人声抑制功能 | 在嘈杂环境下AI容易被噪声打断,可能导致无法正常对话。 |
1 | 开启轻度抑制模式 | 适合相对安静的环境使用,例如家庭、图书馆。 |
2 | 推荐默认设置 | 适用于大多数日常场景(默认值)。 |
3 | 开启强力抑制模式 | 适合嘈杂环境使用,如菜市场、车站。 |
代码配置示例
let startParams = StartAIConversationParams()startParams.sttConfig?.vadLevel = 3let aiViewController = AIConversationViewController(aiParams: startParams)navigationController?.pushViewController(aiViewController, animated: true)
interruptMode 打断模式
根据您的使用习惯,可以设置不同的打断方式,在 AI 说话时进行打断,使对话交互更加自然流畅;您可以通过设置 startParams 中的 agentConfig.interruptMode 参数来达到期望的效果。
模式 | 功能描述 | 适用场景 |
0 | 智能模式 | AI 正在说话时,可通过点击屏幕或用户说话打断;(默认值) |
1 | 手动打断 | AI 正在说话时,只能通过点击屏幕打断; |
代码配置示例
let startParams = StartAIConversationParams()startParams.agentConfig.interruptMode = 1let aiViewController = AIConversationViewController(aiParams: startParams)navigationController?.pushViewController(aiViewController, animated: true)
language 语言识别
根据说话者使用的语言进行设置,AI 才能准确地将语音转换成对应的文字内容;您可以通过设置 startParams 中的 sttConfig.language 参数来达到期望的效果。
语言代码 | 语言名称 | 说明 |
"zh" | 中文 | 支持普通话识别 (默认值) |
"en" | 英语 | 支持英语识别 |
代码配置示例
let startParams = StartAIConversationParams()startParams.sttConfig?.language = "en"let aiViewController = AIConversationViewController(aiParams: startParams)navigationController?.pushViewController(aiViewController, animated: true)
定制您的 UI
文案定制
AIConversationKit 用到的所有文案都存放于 Resource/en.lproj/AIConversationKitLocalized.strings 和 Resource/zh-Hans.lproj/AIConversationKitLocalized.strings 中,部分示例如下,您可以根据您的诉求来替换文件下的文案。
语言索引 | 中文 | 英文 | 详细描述 |
AIConversation.AIReply.listening | 我在听… | Listening… | 表示 AI 正在倾听您的问题 |
AIConversation.AIReply.thinking | 思考中… | Thinking… | 表示 AI 正在思考您的问题 |
AIConversation.Function.speakerOff | 关扬声器 | Turn off | 关闭扬声器播放 AI 语音 |
AIConversation.Function.mute | 静音 | Mute | 表示暂停倾听本地语音 |
AIConversation.Function.hangUp | 挂断 | Hang up | 表示结束和 AI 的对话 |
如果您需要修改中文界面文案,请在 Resource/zh-Hans.lproj/AIConversationKitLocalized.strings 文件中更新对应的文本内容即可。
"AIConversation.AIReply.thinking" = "让我想想...";"AIConversation.AIReply.listening" = "倾听中...";"AIConversation.Function.mute" = "闭麦";"AIConversation.Function.speakerOff" = "关免提";"AIConversation.Function.hangUp" = "结束";
最终效果:

图标定制
AIConversationKit 用到的所有图标都存放于
Resource/AIConversationKit.xcassets
目录下, 部分示例如下,您可以根据您的诉求来替换目录下的图标。图标路径 | 图标样式 | 详细描述 |
ai_default_avatar | ![]() | AI 机器人的头像 |
ai_human_avatar_default | ![]() | 本地用户的头像 |
speaker_off | ![]() | 手机外放声音不使用扬声器 |
audio_mute | ![]() | 本地 Mic 被静音时的图标 |
ai_hangup | ![]() | 结束和 AI 的对话 |
替换 AI 头像:

布局调整
AIConversationKit 主界面布局文件为 AIConversationViewController.swift,您可根据实际需求进行以下调整:
1. 灵活调整布局:支持自由修改各 View 的尺寸与位置,所有组件均为独立模块,可任意组合搭配。
2. 移除不需要的视图:若存在冗余 View,可直接删除以优化布局。
例如,可选择移除 AI 动画组件 AnimationAreaView,从而为 AI 字幕区域 AIReplyAreaView 释放更多显示空间。
// 1、删除 AI 动画组件 AnimationAreaView 的定义private let animationView: AnimationAreaView = {let view = AnimationAreaView(frame: .zero)return view}()// 2、在 constructViewHierarchy 函数中,删除对 animationView 的添加view.addSubview(animationView)// 3、在 activateConstraints 函数中,删除对 animationView 的布局约束animationView.snp.makeConstraints { make inmake.top.equalTo(view.safeAreaLayoutGuide).offset(62.scale375Height())make.left.right.equalToSuperview()make.bottom.equalTo(bottomContainerView.snp.top)}
最终效果:

常见问题
pod install 执行后本地安装找不到 AIConversationKit 最新版本?
如果无法安装 TUILiveKit 最新版本,请按以下步骤操作:
1. 在 Podfile 所在目录下删除
Podfile.lock
和 Pods
,您可以选择手动删除或终端执行以下命令// cd 到 Podfile 所在目录下rm -rf Pods/rmPodfile.lock
2. 在 Podfile 所在目录下执行
pod install --repo-update
// cd 到 Podfile 所在目录下pod install --repo-update
每次进房都需要调用登录吗?
不需要。通常您只需要完成一次
TUILogin.login
调用即可,我们建议您将 TUILogin.login
和 TUILogin.logout
与自己的登录业务关联。Podfile 文件有没有示例配置可以参考?
部署目标版本过低警告 ?
如果您遇到如下错误:
clang: error: SDK does not contain 'libarclite' at the path '/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/arc/libarclite_iphonesimulator.a'; try increasing the minimum deployment target部署目标版本过低警告:TXLiteAVSDK_Professional: iOS 8.0 → 需要 12.0+TXIMSDK_Plus_iOS_XCFramework: iOS 8.0 → 需要 12.0+TUICore: iOS 9.0 → 需要 12.0+
post_install do |installer|installer.pods_project.targets.each do |target|target.build_configurations.each do |config|config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'config.build_settings['ENABLE_BITCODE'] = 'NO'config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = 13.0endendend