AI-диалог

Запускайте голосовой AI-диалог по запросу поддерживаемого устройства, получайте данные диалога и намерения, а при необходимости передавайте декодированный PCM в активную сессию поставщика.

События AIChatEventType описаны в разделе «События AI-сессий», а проверка распознанных действий перед выполнением — в «AI-намерениях».

Интерактивная схема

Жизненный цикл AI-диалога по запросу устройства

Устройство запрашивает AI-диалог и указывает источник речи: Opus от устройства или SCO-запись на стороне приложения. Согласуйте состояния устройства и AI-сессии до получения итогового отчёта.

01Устройство → приложение

D

Получить запрос устройства

Устройство запрашивает новый AI-диалог и указывает канал речи SCO или Opus.

02Приложение

H

Подготовить запрошенный аудиоканал

Использовать указанный устройством канал: принимать пакеты Opus или подготовить SCO-запись в приложении.

03AIBudsAISDK

S

Запустить AI-диалог

Запустить сессию поставщика с подготовленной конфигурацией.

04Приложение ↔ устройство

✓

Подтвердить запуск

Сохранить сессию и при необходимости сообщить Opus-устройству результат запуска.

05Устройство → приложение → сессия

%

Записывать или передавать речь

SCO записывает микрофон устройства через приложение; Opus поступает от устройства, декодируется и добавляется в сессию.

аудио в реальном времени

06AI-сервис → приложение

%

Обрабатывать результаты AI

Обрабатывать данные диалога, намерения, голосовые данные, VAD и события сессии.

потоковые callbacks

07Приложение + аудиовыход

S

Выдать ответ

Показать текст и воспроизвести AI-речь по выбранному аудиоканалу согласно конфигурации.

08Приложение ↔ устройство

D

Согласовать остановку

Обработать завершение устройства, конфликт состояния, автоостановку, явную остановку или ошибку.

09Завершающий callback

✓

Завершить и освободить

Обработать итоговый отчёт, удалить сохранённую сессию и вернуть интерфейс в исходное состояние.

↳При ошибке запуска при необходимости сообщите о ней Opus-устройству. При завершении, конфликте состояния, автоостановке или невосстанавливаемой ошибке остановите сессию и освободите её после завершающего callback.

Предварительные условия

• AIBudsAISDK инициализирован, данные устройства настроены, зарегистрированный поставщик выбран и авторизован.
• Поставщик поддерживает AIChatServiceAPI.
• Устройство передаёт события AI-диалога, а для входа Opus соответствует DeviceAIChatAPI.
• Читайте запрошенный канал из события устройства, а не выбирайте его независимо в приложении.

Реализация с помощью AI

Разработка с AI

Реализуйте этот сценарий с AI

Используйте официальный навык «Реализация ИИ-чата AIBuds» и адаптируйте сценарий к приложению.

Прочитайте и выполните инструкции https://docs-aibuds.github.io/ru/skills/implement-aibuds-ai-chat. Используйте этот навык, чтобы реализовать «Реализация ИИ-чата AIBuds» в данном iOS-проекте и проверить результат.

Открыть официальный навык↗

API Reference

Framework

AIBudsAI.xcframework

Import

Swift

Swift

import AIBuds
import AIBudsAI
import AIBudsAIFoundation

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBudsAI/AIBudsAI-Swift.h>

Declaration

Swift

Swift

/// Starts an AI chat session.
/// - Parameters:
///   - config: The chat session configuration.
///   - onStartSuccess: Called with the active session.
///   - onStartFailure: Called when the session cannot start.
///   - onChatData: Called when new conversational data arrives.
///   - onIntent: Called when the provider detects an intent.
///   - onVoiceData: Called when voice data is produced.
///   - onEvent: Called for session-level events.
///   - onError: Called for runtime session errors.
///   - onFinish: Called with the final session report.
public static func startAIChat(_ config: AIChatSessionConfig = .default,
                         onStartSuccess: ((_ session: AIChatSessionConvertible) -> Void)? = nil,
                         onStartFailure: ((_ error: Error) -> Void)? = nil,
                             onChatData: ((_ chatData: AIChatDataModel) -> Void)? = nil,
                               onIntent: ((_ intent: AIChatIntentModel) -> Void)? = nil,
                            onVoiceData: ((_ voiceData: AIChatVoiceDataModel) -> Void)? = nil,
                                onEvent: ((_ event: AIChatEventModel) -> Void)? = nil,
                                onError: ((_ error: NSError) -> Void)? = nil,
                               onFinish: ((_ report: AIChatSessionReportModel) -> Void)? = nil) -> Void

/// Stops the active AI chat session. This is safe when no session is active.
public static func stopAIChat()

Objective-C

Objective-C

/// Starts an AI chat session.
/// - Parameters:
///   - config: The chat session configuration.
///   - onStartSuccess: Called with the active session.
///   - onStartFailure: Called when the session cannot start.
///   - onChatData: Called when new conversational data arrives.
///   - onIntent: Called when the provider detects an intent.
///   - onVoiceData: Called when voice data is produced.
///   - onEvent: Called for session-level events.
///   - onError: Called for runtime session errors.
///   - onFinish: Called with the final session report.
+ (void)startAIChatWithConfig:(AIBudsAIChatSessionConfig * _Nonnull)config
               onStartSuccess:(void (^ _Nullable)(id <AIBudsAIChatSessionConvertible> _Nonnull))onStartSuccess
               onStartFailure:(void (^ _Nullable)(NSError * _Nonnull))onStartFailure
                   onChatData:(void (^ _Nullable)(AIBudsAIChatDataModel * _Nonnull))onChatData
                     onIntent:(void (^ _Nullable)(AIBudsAIChatIntentModel * _Nonnull))onIntent
                  onVoiceData:(void (^ _Nullable)(AIBudsAIChatVoiceDataModel * _Nonnull))onVoiceData
                      onEvent:(void (^ _Nullable)(AIBudsAIChatEventModel * _Nonnull))onEvent
                      onError:(void (^ _Nullable)(NSError * _Nonnull))onError
                     onFinish:(void (^ _Nullable)(AIBudsAIChatSessionReportModel * _Nonnull))onFinish;

/// Stops the active AI chat session. This is safe when no session is active.
+ (void)stopAIChat;

См. startAIChat и stopAIChat.

Конфигурация

AIChatSessionConfig предоставляет настройки, используемые AIChatSettingsController:

Свойство	По умолчанию	Назначение
languageForSpeechInput	Язык приложения	Поддерживаемый поставщиком язык речи в формате с дефисом, например zh-CN.
audioChannel	.opusInA2dpOut	Аудиотранспорт сессии. Должен соответствовать событию устройства, запустившему сессию.
allowUserToInterruptAIResponse	true	Может ли пользователь прервать ответ AI, обычно голосовое воспроизведение.
maxPauseDurationBeforeAIResponds	0.8 секунды	Максимальная пауза речи до ответа AI.
autoEndSessionAfterNoInputDuration	15.0 секунд	Время бездействия до автоматического завершения сессии.
enableVoicePlayback	true	Включено ли воспроизведение сгенерированной речи.
shouldSaveVoiceForDebugging	false	Сохранять ли голосовые данные для диагностики. В production оставляйте выключенным, если политика явно не разрешает обратное.
additionalOptions	[:]	Параметры агента, голоса, плана, запроса, намерений или шумоподавления конкретного поставщика.
autoSelectAgentIfNotSpecified	true	Выбирает ли SDK агента, если агент поставщика не указан.

Используйте публичные константы AdditionalOptionKey..., а не фиксированные строки ключей поставщика.

Настройка сессии диалога

Demo отделяет выбор поставщика от настройки сессии. При смене поставщика сначала выберите его, получите поддерживаемые языки и завершите авторизацию, инициируемую приложением. ID агента и голоса, коды намерений, планы использования и начальные запросы выдаются поставщиком; не копируйте их из Demo как универсальные значения.

Swift

Swift

let vendor: AIServiceVendor = .starBurst
AIBudsAISDK.setAIServiceVendor(vendor)

let supportedLanguages = AIBudsAISDK.allSupportedLanguages(for: vendor)
let language = supportedLanguages.first?.languageCode

var options: [String: Any] = [:]
if let agentID = providerAgentID {
    options[AIChatSessionConfig.AdditionalOptionKeyStarburstAgentId] = agentID
}
if let speakerID = providerSpeakerID {
    options[AIChatSessionConfig.AdditionalOptionKeyStarburstSpeakerId] = speakerID
}

let config = AIChatSessionConfig(
    languageForSpeechInput: language,
    audioChannel: .opusInA2dpOut,
    allowUserToInterruptAIResponse: true,
    maxPauseDurationBeforeAIResponds: 0.8,
    autoEndSessionAfterNoInputDuration: 15,
    enableVoicePlayback: true,
    shouldSaveVoiceForDebugging: false,
    additionalOptions: options
)
config.autoSelectAgentIfNotSpecified = providerAgentID == nil

Objective-C

Objective-C

AIBudsAIServiceVendor vendor = AIBudsAIServiceVendorStarBurst;
[AIBudsAISDK setAIServiceVendor:vendor];

NSArray<AIBudsAIServiceLanguage *> *supportedLanguages =
    [AIBudsAISDK allSupportedLanguagesForVendor:vendor];
NSString *language = supportedLanguages.firstObject.languageCode;

NSMutableDictionary<NSString *, id> *options = [NSMutableDictionary dictionary];
if (self.providerAgentID.length > 0) {
    options[AIBudsAIChatSessionConfig.AdditionalOptionKeyStarburstAgentId] = self.providerAgentID;
}
if (self.providerSpeakerID.length > 0) {
    options[AIBudsAIChatSessionConfig.AdditionalOptionKeyStarburstSpeakerId] =
        self.providerSpeakerID;
}

AIBudsAIChatSessionConfig *config = [[AIBudsAIChatSessionConfig alloc]
        initWithLanguageForSpeechInput:language
                          audioChannel:AIBudsAIChatAudioChannelOpusInA2dpOut
        allowUserToInterruptAIResponse:YES
      maxPauseDurationBeforeAIResponds:0.8
    autoEndSessionAfterNoInputDuration:15.0
                   enableVoicePlayback:YES
           shouldSaveVoiceForDebugging:NO
                     additionalOptions:options];
config.autoSelectAgentIfNotSpecified = self.providerAgentID.length == 0;

Для .mltcloud используйте соответствующие константы AdditionalOptionKeyMltCloud.... План StarBurst или идентификатор поставщика задавайте только при наличии действительного значения в конфигурации.

Примеры использования

Обычно устройство инициирует диалог через .initiateWithSCO или .initiateWithOpus. До запуска AI-диалога перенесите запрошенный канал в конфигурацию сессии. Для Opus передавайте декодированный PCM от устройства. Для SCO запуск сессии .sco создаёт в приложении SCO-запись микрофона устройства.

Swift

Swift

let config = AIChatSessionConfig.default
config.audioChannel = .opusInA2dpOut
config.languageForSpeechInput = "en-US"

AIBudsAISDK.startAIChat(
    config,
    onStartSuccess: { session in
        currentSession = session
    },
    onStartFailure: { error in
        print("Chat start failed: \(error)")
    },
    onChatData: { chatData in
        conversation.append(chatData)
    },
    onIntent: { intent in
        handle(intent)
    },
    onVoiceData: { voiceData in
        handle(voiceData)
    },
    onEvent: { event in
        handle(event)
    },
    onError: { error in
        print(error.localizedDescription)
    },
    onFinish: { report in
        currentSession = nil
        save(report)
    }
)

Когда устройство передаёт декодированный 16-битный PCM для Opus-сессии, направляйте его в сохранённую сессию:

Swift

currentSession?.appendInt16PCM?(decodedPCMData)

Objective-C

Objective-C

AIBudsAIChatSessionConfig *config = [AIBudsAIChatSessionConfig defaultConfig];
config.audioChannel = AIBudsAIChatAudioChannelOpusInA2dpOut;
config.languageForSpeechInput = @"en-US";

[AIBudsAISDK startAIChatWithConfig:config
    onStartSuccess:^(id<AIBudsAIChatSessionConvertible> session) {
        self.currentSession = session;
    }
    onStartFailure:^(NSError *error) {
        NSLog(@"Chat start failed: %@", error);
    }
    onChatData:^(AIBudsAIChatDataModel *chatData) {
        [self recordChatData:chatData];
    }
    onIntent:^(AIBudsAIChatIntentModel *intent) {
        [self handleIntent:intent];
    }
    onVoiceData:^(AIBudsAIChatVoiceDataModel *voiceData) {
        [self handleVoiceData:voiceData];
    }
    onEvent:^(AIBudsAIChatEventModel *event) {
        [self handleEvent:event];
    }
    onError:^(NSError *error) {
        NSLog(@"%@", error.localizedDescription);
    }
    onFinish:^(AIBudsAIChatSessionReportModel *report) {
        self.currentSession = nil;
        [self saveReport:report];
    }];

При необходимости передавайте декодированный PCM:

Objective-C

[self.currentSession appendInt16PCM:decodedPCMData];

Остановка сессии

Когда устройство запрашивает завершение, при необходимости сообщите состояние остановки через DeviceAIChatAPI, затем вызовите:

Swift

Swift

AIBudsAISDK.stopAIChat()
currentSession = nil

Objective-C

Objective-C

[AIBudsAISDK stopAIChat];
self.currentSession = nil;

Примечания

• Это API аудиосессии, а не текстовый API sendMessage или истории сообщений.
• Сохраняйте AIChatSessionConvertible до onFinish, невосстанавливаемой ошибки или явной остановки.
• В SCO-сессии AIBuds AI SDK записывает микрофон устройства через SCO-канал приложения. В Opus-сессии устройство передаёт Opus приложению; декодированный PCM направляйте через appendInt16PCM(_:).
• Не включайте shouldSaveVoiceForDebugging в production, если политика конфиденциальности и хранения явно этого не разрешает.