Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:SDK HarmonyOS do Qwen-Audio-Realtime

Última atualização: Nov 20, 2026

Use o SDK HarmonyOS do Qwen-Audio-Realtime para implementar entrada de áudio em tempo real e saída de voz ou texto.

Para conexão e autenticação, consulte Acesso por WebSocket. Para campos de eventos e exemplos JSON, consulte Eventos do cliente e Eventos do servidor.

Guia do usuário: Para a apresentação do modelo e sugestões de seleção, consulte Conversa por voz em tempo real.

Pré-requisitos

  1. Obtenha e configure uma chave de API. Não insira chaves de API de longa duração diretamente no código de aplicativos móveis. Recomendamos que o servidor do seu aplicativo gere uma chave de API temporária e a entregue ao cliente.

Instalar o SDK

  • Baixe o pacote de integração do SDK mais recente.
  • Extraia o pacote de integração do SDK no formato .tar.gz. Obtenha o SDK no formato HAR no diretório entry/libs e adicione-o às dependências do projeto. Para integração em C++, use native/libs e native/include no pacote para obter as bibliotecas dinâmicas e os arquivos de cabeçalho.

Início rápido

Abra o projeto no DevEco Studio. O código de exemplo está localizado em DashQwenAudioChatPage.ets. Substitua a chave de API e, em seguida, teste os recursos.

Procedimento

  1. Inicialize o SDK.
  2. Defina os parâmetros de acordo com os requisitos do negócio: defina os parâmetros de conexão e controle por meio do parâmetro parameters da interface initialize; defina os parâmetros de efeito da conversa por voz por meio da interface setParams.
  3. Chame startDialog para iniciar a conversa.
  4. No callback onNuiAudioStateChanged, habilite o dispositivo de gravação com base no estado do áudio.
  5. Forneça continuamente os dados de gravação no callback onNuiNeedAudioData ou envie continuamente os dados de gravação por meio de updateAudio.
  6. Receba continuamente os dados de voz retornados pela IA no callback onNuiAssistEventCallback.
  7. Escute os eventos e obtenha as informações de eventos no callback onNuiEventCallback.
  8. Chame stopDialog para encerrar a conversa e confirme que a conversa foi encerrada escutando o evento EVENT_TRANSCRIBER_COMPLETE.
  9. Quando o recurso de conversa não for mais usado, chame release para liberar os recursos do SDK.

Parâmetros da solicitação

Parâmetros de conexão e controle

Configure passando uma string JSON para o parâmetro parameters da interface initialize.

Exemplo de parâmetros: A seguir está uma string JSON de exemplo que não lista todos os parâmetros. Adicione parâmetros conforme necessário durante a codificação:

Este exemplo usa qwen-audio-3.1-realtime-plus. Ao alterar o modelo, atualize model na URL e nls_config.model nos parâmetros de efeito da conversa por voz de forma correspondente.

{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
Descrição dos parâmetros
ParâmetroTipoObrigatórioDescrição

url

String

Sim

Endereço do serviço:

  • wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • China (Pequim) 2: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Ao chamar a API, substitua {WorkspaceId} pelo seu ID do Workspace real.

apikey

String

Sim

Chave de API.

service_mode

String

Sim

Modo de execução. Para conversas por voz em tempo real, o valor é fixado como "1".

device_id

String

Sim

Uma string exclusiva usada para identificar o usuário final. Você pode defini-la como o ID do usuário no seu aplicativo ou um identificador de dispositivo exclusivo gerado pelo cliente. Esse ID é usado principalmente para rastreamento de logs e solução de problemas.

audio_update_manually

String

Não

Se deve habilitar o modo de envio ativo de dados de áudio. Valor padrão: "false".
Quando este parâmetro é definido como "true" para habilitar o modo de envio ativo de dados de áudio e a versão do SDK oferece suporte a recursos de áudio no dispositivo (como AEC e VAD), os recursos de áudio no dispositivo são habilitados por padrão.

workspace

String

Não

Quando o parâmetro audio_update_manually é definido como "true" e os recursos de áudio no dispositivo (como AEC e VAD) estão habilitados, você deve definir workspace, que é o caminho onde os arquivos de recursos no dispositivo são armazenados.

debug_path

String

Não

O caminho de armazenamento dos arquivos de log. Este parâmetro só entra em vigor quando save_log é definido como true ao chamar a API initialize. Nesse caso, você deve definir o caminho do arquivo de log; caso contrário, um erro será relatado. Um máximo de dois arquivos de log é retido localmente.

save_wav

String

Não

Se deve salvar arquivos de áudio para depuração. Os arquivos de áudio são salvos em debug_path.
Valor padrão: "false".
Valores válidos:

  • "true": Sim
  • "false": Não
Este parâmetro só entra em vigor quando save_log é definido como true ao chamar a API initialize. Além disso, debug_path também deve ser definido.

max_log_file_size

int

Não

O número máximo de bytes de um arquivo de log.
Este parâmetro só entra em vigor quando save_log é definido como true ao chamar a API initialize.
Valor padrão: 104857600 (100 × 1024 × 1024 bytes, ou seja, 100MiB).

log_track_level

int

Não

Controla o nível de filtragem do conteúdo de log enviado externamente por meio do callback de log (onNuiLogTrackCallback).
Valor padrão: 2.
Valores válidos:

  • 0: LOG_LEVEL_VERBOSE
  • 1: LOG_LEVEL_DEBUG
  • 2: LOG_LEVEL_INFO
  • 3: LOG_LEVEL_WARNING
  • 4: LOG_LEVEL_ERROR
  • 5: LOG_LEVEL_NONE (desativa este recurso)
Observação: log_track_level e level (definido por meio da API initialize) determinam em conjunto os logs que são finalmente retornados. Um log só é retornado se o seu valor de nível for maior ou igual tanto a log_track_level quanto a level. Por exemplo, se log_track_level for definido como 2 (INFO) e level como 3 (WARNING), apenas os logs de nível WARNING e superior (valor >= 3) são retornados.

aec_params

object

Não

Objeto de configuração avançada dos recursos de AEC no dispositivo. Este objeto de configuração só é habilitado quando o parâmetro audio_update_manually é definido como "true".

aec_params.enable_aec

boolean

Não

Se deve habilitar o recurso de cancelamento de eco AEC no dispositivo.
Quando o parâmetro audio_update_manually é definido como "true" e a versão do SDK oferece suporte aos recursos de áudio AEC no dispositivo, ele é habilitado por padrão.

aec_params.save_audio

boolean

Não

Se deve habilitar o recurso de armazenamento de áudio do módulo de cancelamento de eco AEC no dispositivo. Quando save_wav é "true" e debug_path está definido, ele é habilitado por padrão, e os dados de áudio de execução do AEC são armazenados em debug_path.

aec_params.enable_aec_data_callback

boolean

Não

Se deve enviar os dados pós-AEC ao usuário. Valor padrão: false. Depois que este recurso é habilitado, os dados são recebidos em EVENT_AEC_DATA de onNuiAssistEventCallback.

vad_params

object

Não

Objeto de configuração avançada dos recursos de VAD no dispositivo.
Este objeto de configuração só é habilitado quando o parâmetro audio_update_manually é definido como "true".

vad_params.enable_vad

boolean

Não

Se deve habilitar o recurso de detecção de voz VAD no dispositivo.
Quando o parâmetro audio_update_manually é definido como "true" e a versão do SDK oferece suporte aos recursos de áudio VAD no dispositivo, ele é habilitado por padrão.

vad_params.save_audio

boolean

Não

Se deve habilitar o recurso de armazenamento de áudio do módulo de detecção de voz VAD no dispositivo.
Quando save_wav é "true" e debug_path está definido, ele é habilitado por padrão, e os dados de áudio de execução do VAD são armazenados em debug_path.

Parâmetros de efeito da conversa por voz

Configurado passando uma string JSON no parâmetro params da API setParams.

Exemplo de parâmetros: A seguir está uma string JSON de exemplo que não lista todos os parâmetros. Adicione parâmetros conforme necessário durante a codificação:

{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.1-realtime-plus",
        "sr_format": "pcm"
    }
}
Descrição dos parâmetros
Parâmetros de primeiro nívelTipoObrigatórioDescrição

service_type

int

Sim

Tipo de serviço de voz. Para conversas por voz em tempo real, é fixado em 4.

nls_config

object

Sim

Objeto de configuração principal da conversa por voz, contendo parâmetros-chave como seleção de modelo e controle do efeito da conversa.

nls_config.model

string

Sim

Especifica o nome do modelo. Oferece suporte aos modelos das séries qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.

nls_config.sr_format

string

Sim

Formato de áudio de entrada. Atualmente, apenas pcm (16kHz 16bit mono) é suportado, que é o valor padrão.

nls_config.modalities

string

Não

Uma string em formato de matriz, que especifica as configurações de modalidade de saída do modelo. Valores válidos:

  • ["text"]: Gera apenas texto.
  • ["audio", "text"] (valor padrão): Gera tanto texto quanto áudio.

nls_config.voice

string

Não

Nome da voz TTS. O valor padrão para 3.1 Plus/Flash é longanqian_v3.1, e o valor padrão para 3.0 Plus/Flash é longanqian. Só pode ser definido no primeiro session.update; valores passados posteriormente serão ignorados.

  • Vozes do sistema 3.1 Plus/Flash: Os valores válidos incluem longanqian_v3.1 e todas as vozes da lista de vozes 3.1 TTS Plus/Flash. Para a lista completa, consulte Configuração de voz.
  • Vozes do sistema 3.0 Plus/Flash: longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
  • Vozes de clonagem de voz: Criadas por meio da API de clonagem de voz. Preencha o voice_id retornado neste parâmetro. Para mais informações, consulte Configuração de voz.

nls_config.enable_speech_emotion

boolean

Não

Se deve habilitar o recurso de aprimoramento de emoção. Quando habilitado, as mudanças emocionais da voz de resposta são mais pronunciadas. Valor padrão: true. Valores válidos: true, false.

nls_config.instructions

string

Não

Instrução do sistema usada para definir a identidade do papel do modelo, o estilo de resposta e as preferências comportamentais. Tem efeito durante toda a sessão.

nls_config.max_history_turns

int

Não

Número máximo de turnos históricos de perguntas e respostas permitidos por solicitação. O intervalo de valores é 1-50, e o valor padrão é 20.

nls_config.tools

string

Não

String em formato de matriz. Lista de definições de ferramentas de Function Calling. Quando configurada, o modelo pode decidir autonomamente se chama ferramentas com base na entrada do usuário.
Descrição dos parâmetros internos:
typestring(obrigatório)
Fixado como function.
function.namestring(obrigatório)
Nome da função da ferramenta.
function.descriptionstring(opcional)
Descrição da funcionalidade da função da ferramenta, com base na qual o modelo determina se deve chamar a ferramenta.
function.parametersobject(opcional)
Descrição dos parâmetros de entrada da função da ferramenta, com base na qual o modelo extrai os parâmetros necessários. Se a função não exigir parâmetros de entrada, isto pode ser omitido.
Exemplo:

[
 {
 "type": "function",
 "function": {
 "name": "get_weather",
 "description": "查询指定城市的天气信息。",
 "parameters": {
 "type": "object",
 "properties": {
 "city": {
 "type": "string",
 "description": "城市"
 }
 },
 "required": [
 "city"
 ]
 }
 }
 }
]

nls_config.turn_detection

string

Não

As descrições de campos de detecção de turno a seguir se aplicam a qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.

String em formato de objeto JSON. Configuração de detecção de turno. Se não for definida, muda para o modo push-to-talk (enviar áudio e acionar a inferência manualmente). Caso contrário, o modo de conversa duplex é habilitado.

nls_config.turn_detection.type

string

Não

Tipo de VAD. Valores válidos:

  • server_vad (padrão): Detecta o início e o fim da fala com base em características acústicas, acionando a inferência automaticamente.
  • smart_turn: Detecção de turno inteligente que combina percepção acústica com compreensão semântica, determinando os limites de turno por meio de julgamento acústico e semântico duplo. Sons não semânticos (como "hã" e "é") não acionarão um turno de diálogo nem interromperão a reprodução do modelo.
  • smart_turn_v2 (recomendado): Aprimora a compreensão do contexto da conversa sobre o smart_turn, determinando melhor a intenção de interação em cenários com múltiplos locutores. Reduz as respostas falsas e as interrupções falsas causadas pela fala de pessoas próximas ou inserções irrelevantes.

nls_config.turn_detection.threshold

float

Não

Sensibilidade do VAD. Aplica-se a server_vad, smart_turn e smart_turn_v2. Quanto menor o valor, mais facilmente sons fracos (incluindo ruído de fundo) são reconhecidos como fala; quanto maior o valor, mais clara e alta deve ser a fala necessária para acionar a detecção.
O intervalo de valores é [-1.0, 1.0], e o valor padrão é 0.5.

nls_config.turn_detection.silence_duration_ms

int

Não

Duração mínima de silêncio (em milissegundos) após o fim da fala. Só tem efeito no modo server_vad (não tem efeito nos modos smart_turn e smart_turn_v2). Assim que o silêncio atinge essa duração, a resposta do modelo é acionada. Quanto menor o valor, mais rápida a resposta, mas pausas breves também podem causar acionamentos falsos.
O intervalo de valores é [200, 6000], e o valor padrão é 800. Para cenários de conversa, recomenda-se 400-800.

nls_config.turn_detection.voiceprint_audio_urls

string

Não

String em formato de matriz. Efetivo nos modos smart_turn e smart_turn_v2. Lista de URLs publicamente acessíveis do áudio pré-gravado do usuário-alvo, usada para aprimoramento do locutor. O modelo usa esses arquivos de áudio para focar no locutor-alvo em conversas duplex, ignorando vozes de pessoas próximas e ruído de fundo. Há suporte a até 5 URLs. Requisitos de formato de áudio: PCM ou WAV de 16kHz.

Referência da API

Gerenciamento de dispositivos de áudio

Ao contrário do Android, que usa AudioRecord / AudioTrack, o HarmonyOS fornece capacidades de captura e reprodução de áudio por meio de @kit.AudioKit, usando AudioCapturer (gravação) e AudioRenderer (reprodução), respectivamente. O exemplo deste produto já os encapsulou em duas classes utilitárias, AudioRecorder.ets e AudioPlayer.ets, que podem ser reutilizadas diretamente.

Gravação (AudioCapturer)

  • Criar: Criado de forma assíncrona por meio de audio.createAudioCapturer(capturerOptions), com taxa de amostragem fixa de 16kHz, 16 bits, mono (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW).
  • Fonte de áudio (audio.SourceType):
    • SOURCE_TYPE_MIC: Fonte de áudio bruta do microfone, usada quando o AEC interno do SDK está habilitado (os dados são enviados ao SDK por meio de updateAudio).
    • SOURCE_TYPE_VOICE_COMMUNICATION: Fonte de áudio de chamada de voz, com cancelamento de eco já aplicado pelo sistema durante a captura, usada quando o AEC interno do SDK está desabilitado (o áudio é obtido por meio de onNuiNeedAudioData).
  • Eventos de dados: Receba continuamente os dados de gravação por meio de capturer.on('readData', (buffer: ArrayBuffer) => void).
  • Eventos de estado: Monitorados por meio de capturer.on('stateChange', (state: audio.AudioState) => void); STATE_RUNNING indica que a gravação foi iniciada, STATE_STOPPED indica que foi interrompida.
  • Controle: start() para iniciar, stop() para parar, release() para liberar.
import { audio } from '@kit.AudioKit';

const audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_16000,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
const audioCapturerInfo: audio.AudioCapturerInfo = {
  source: audio.SourceType.SOURCE_TYPE_MIC,
  capturerFlags: 0
};
const options: audio.AudioCapturerOptions = { streamInfo: audioStreamInfo, capturerInfo: audioCapturerInfo };

audio.createAudioCapturer(options).then((capturer) => {
  capturer.on('readData', (buffer: ArrayBuffer) => {
    // 将录音数据送入SDK
    nuiInstance.updateAudio(buffer, false);
  });
  capturer.start();
});

Nota: O AudioCapturer do HarmonyOS é criado de forma assíncrona, e start() só pode ser chamado após a criação ser concluída. Portanto, não crie e inicie imediatamente o gravador em STATE_OPEN — crie-o primeiro e, em seguida, chame start() no callback STATE_OPEN (o exemplo o cria no estágio doInit e o inicia no estágio onNuiAudioStateChanged).

Reprodução (AudioRenderer)

  • Criar: Criado de forma assíncrona por meio de audio.createAudioRenderer(rendererOptions).
  • Taxa de amostragem: O áudio de resposta de voz sintetizado pelo DashScope realtime é de 24kHz (passado ao construir AudioPlayer).
  • Eventos de dados: Obtenha o áudio a ser reproduzido por meio de renderer.on('writeData', (data: ArrayBuffer): audio.AudioDataCallbackResult => ...); retornar AudioDataCallbackResult.VALID indica que os dados foram preenchidos, INVALID indica que não há dados.
  • Eventos de estado: Monitore o início e o fim da reprodução por meio de renderer.on('stateChange', (state: audio.AudioState) => void).
  • Controle: start() para iniciar, stop() para parar, pause() para pausar (pausar preserva os dados em buffer).
import { audio } from '@kit.AudioKit';

const audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_24000,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
const audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_VOICE_ASSISTANT,
  rendererFlags: 0
};
const options: audio.AudioRendererOptions = { streamInfo: audioStreamInfo, rendererInfo: audioRendererInfo };

audio.createAudioRenderer(options, (err, renderer) => {
  renderer.on('writeData', (data: ArrayBuffer): audio.AudioDataCallbackResult => {
    // 从队列取出AI返回的音频填入data, 返回VALID/INVALID
    return audio.AudioDataCallbackResult.VALID;
  });
  renderer.start();
});

Sinal de referência AEC: Quando o AEC interno do SDK está habilitado, o áudio reproduzido pelo player deve ser enviado ao SDK como sinal de referência, chamando nuiInstance.pushReferenceData(data, false) (correspondente ao updateRefAudio do Android).

Declaração de permissão

Para usar o recurso de gravação, declare a permissão do microfone em module.json5:

{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}

NativeNui

initialize · Inicializar o SDK

Inicializa a instância do SDK de conversa por voz. O SDK é um singleton; não o inicialize novamente antes de chamar release.

Esta interface é bloqueante e deve ser chamada em uma thread que não seja de UI.

Assinatura do método
public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number
Descrição dos parâmetros
ParâmetroTipoDescrição

callback

INativeNuiCallback

Implementação das interfaces de callback de eventos e dados.

parameters

string

String JSON contendo parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle.

level

number

Controla o nível de log do próprio SDK.

save_log

boolean

Se deve salvar logs locais. Se true, você deve especificar o caminho por meio de debug_path em Parâmetros de conexão e controle, e pode definir o tamanho do arquivo por meio de max_log_file_size.

setParams

Define os parâmetros de efeito da conversa por voz no formato JSON. Chame isto antes de startDialog.

Assinatura do método
public setParams(params: string): number
Descrição dos parâmetros
ParâmetroTipoDescrição

params

string

Parâmetros de efeito da conversa por voz.

startDialog

Inicia a conversa.

Assinatura do método
public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number
Descrição dos parâmetros
ParâmetroTipoDescrição

vad_mode

Constants.VadMode

Modo VAD. Fixado em Constants.VadMode.TYPE_P2T.

dialog_params

string

Se o parâmetro apikey em Parâmetros de conexão e controle usar uma chave de API temporária, você pode atualizá-la aqui quando expirar.
O conteúdo está no formato JSON:

{
 "apikey": "st-****"
}

stopDialog

Encerra a conversa. Depois que você chama esta API, o servidor retorna o resultado final da conversa e encerra a tarefa.

Assinatura do método
public stopDialog(): number

cancelDialog

Encerra a conversa imediatamente. Depois que você chama esta API, a tarefa termina imediatamente, sem esperar o servidor retornar o resultado final da conversa.

Assinatura do método
public cancelDialog(): number

dialogAction

Envia comandos de ação de diálogo durante a interação, usados para atualizar comportamentos em tempo de execução, como o contexto da conversa.

Assinatura do método
public dialogAction(params: string): number
Descrição dos parâmetros
ParâmetroTipoDescrição

params

string

Uma string em formato JSON, usada para atualizar comportamentos em tempo de execução, como o contexto da conversa.

params.type

String

Fixado como "action".

params.command

String

O comando em tempo de execução específico. Atualmente suporta "function_call", "play_start" e "play_over".

  • function_call: O comando para atualizar uma solicitação de chamada de função.
  • play_start: Quando o AEC no dispositivo é usado, este comando notifica o player do AEC interno do SDK para começar a reproduzir áudio.
  • play_over: Quando o AEC no dispositivo é usado, este comando notifica o player do AEC interno do SDK de que a reprodução terminou.

params.context

String

Quando command é "function_call", atualiza a solicitação de chamada de função.

params.context.type

String

O tipo de evento. Obrigatório quando command é "function_call".

  • conversation.item.create: Insere manualmente um item de conversa no contexto da conversa. Pode ser usado para injetar contexto histórico, complementar informações de texto ou gravar de volta os resultados de execução de ferramentas do Function Calling.
  • response.create: Após o envio do comando conversation.item.create, este comando aciona uma segunda rodada de inferência.

params.context.item

object

Obrigatório quando params.context.type é conversation.item.create, indicando o item de conversa a criar. Consulte a seguir para obter detalhes.

params.context.response

object

Opcional quando params.context.type é response.create, indicando a configuração de sessão padrão usada para substituir a rodada atual de inferência. Se não for especificado, a configuração da sessão atual é usada. Consulte a seguir para obter detalhes.

Parâmetros de context.item:

ParâmetroTipoDescrição

id

String

Opcional. O identificador exclusivo do item de conversa. Se não for especificado, é gerado automaticamente pelo servidor. Se o ID especificado já existir na conversa, um erro será retornado.

type

String

Obrigatório. O tipo do item de conversa. Valores válidos:

  • message: Uma mensagem de conversa comum.
  • function_call: Uma solicitação de chamada de função. Geralmente gerada pelo servidor; o cliente também pode usá-la para complementar o contexto histórico.
  • function_call_output: Resultados de execução de ferramentas. O cliente executa a ferramenta após receber function_call e grava o resultado de volta com este tipo.

role

String

Obrigatório para o tipo message. O papel da mensagem. Valores válidos: system, user, assistant.

content

array

Obrigatório para o tipo message. A lista de conteúdo da mensagem. Cada elemento contém type e o campo de dados correspondente.
Tipos de conteúdo suportados por cada papel:
system
input_text: Mensagem do sistema, com o campo obrigatório text.
user

  • input_text: Entrada de texto do usuário, campo obrigatório text.
  • input_audio: Entrada de áudio do usuário, campo obrigatório audio (codificado em Base64).
assistant
output_text: Saída de texto do assistente, campo obrigatório text.

call_id

String

(Obrigatório para o tipo function_call / function_call_output )
O identificador exclusivo da chamada de função, usado para correlacionar a solicitação e o resultado.

name

String

(Obrigatório para o tipo function_call )
O nome da função a ser chamada.

arguments

String

function_call tipo obrigatório)
Os parâmetros da chamada de função, no formato de string JSON.

output

String

(Obrigatório para o tipo function_call_output )
Resultados da ferramenta, no formato de string JSON.

Parâmetros de context.response:

ParâmetroTipoDescrição

modalities

array

Uma string em formato de matriz, que especifica as configurações de modalidade de saída do modelo. Valores válidos:

  • ["text"]: Gera apenas texto.
  • ["audio", "text"] (valor padrão): Gera tanto texto quanto áudio.

voice

string

Substitui a voz TTS desta rodada.

Exemplo:

{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"杭州\",\"condition\":\"晴\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": [
        "text",
        "audio"
      ]
    },
    "type": "response.create"
  }
}

updateAudio

Quando o parâmetro audio_update_manually é definido como "true", os dados de gravação não são mais preenchidos por meio de onNuiNeedAudioData; em vez disso, são enviados ativamente por meio desta API.

Assinatura do método
public updateAudio(data: ArrayBuffer, first_pack: boolean): number
Descrição dos parâmetros
ParâmetroTipoDescrição

data

ArrayBuffer

Os dados de áudio a enviar (PCM).

first_pack

boolean

Se é o primeiro pacote. O SDK calcula internamente o número de bytes com base em data.byteLength.

pushReferenceData (correspondente ao updateRefAudio do Android)

Quando o parâmetro audio_update_manually é definido como "true" e o recurso de cancelamento de eco AEC no dispositivo está habilitado, você deve usar esta API para enviar os dados de áudio reproduzidos pelo player como sinal de referência.

Assinatura do método
public pushReferenceData(data: ArrayBuffer, first_pack: boolean): number
Descrição dos parâmetros
ParâmetroTipoDescrição

data

ArrayBuffer

Os dados de áudio a enviar (PCM).

first_pack

boolean

Se é o primeiro pacote. O SDK calcula internamente o número de bytes com base em data.byteLength.

release · Liberar os recursos do SDK

Libera todos os recursos internos do SDK. Depois que este método é chamado, a instância do SDK fica indisponível; para usá-la novamente, você deve chamar initialize novamente para reinicializá-la.

Assinatura do método
public release(): number

GetVersion

Obtém as informações da versão atual do SDK.

Assinatura do método
public GetVersion(): string
Descrição do valor de retorno

As informações da versão atual do SDK.

INativeNuiCallback: Escutar callbacks

onNuiEventCallback: Escutar informações de eventos

Assinatura do método
onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;
Descrição dos parâmetros
ParâmetroTipoDescrição

event

Constants.NuiEvent

O evento de callback.

resultCode

number

Válido apenas quando o evento EVENT_ASR_ERROR ocorre.

arg2

number

Parâmetro reservado.

asrResult

AsrResult

O resultado do reconhecimento de fala.

kwsResult

KwsResult

Recurso de despertar por voz. Você pode ignorar este parâmetro.

onNuiAudioStateChanged: Escutar mudanças de estado do áudio

O SDK usa este callback para notificar quando iniciar ou parar a gravação.

Assinatura do método
onNuiAudioStateChanged: (state: Constants.AudioState) => void
Descrição dos estados de AudioState
EstadoDescrição

STATE_OPEN

A interação começa. Você pode ligar o dispositivo de gravação para gravar áudio.

STATE_PAUSE

A interação para. Você pode parar a gravação.

STATE_CLOSE

A instância do SDK foi liberada. Você pode fechar completamente o dispositivo de gravação.

onNuiAudioRMSChanged: Escutar o volume da gravação

Escuta o volume dos dados de áudio gravados, que pode ser usado para exibição na UI.

Assinatura do método
onNuiAudioRMSChanged: (val: number) => number
Descrição dos parâmetros
ParâmetroTipoDescrição

val

number

O valor do volume dos dados de áudio gravados.

onNuiNeedAudioData: Preencher os dados de áudio a serem processados

Depois que a conversa começa, este callback é acionado continuamente, e você deve fornecer nele os dados de áudio a serem processados. Você pode ignorar este callback quando o parâmetro audio_update_manually estiver definido como "true".

Assinatura do método
onNuiNeedAudioData: (buffer: ArrayBuffer) => number
Descrição dos parâmetros
ParâmetroTipoDescrição

buffer

ArrayBuffer

Os dados de áudio a preencher. O SDK obtém o número esperado de bytes a ler com base em buffer.byteLength.

Descrição do valor de retorno

O número real de bytes preenchidos.

onNuiAssistEventCallback: Dados auxiliares e resultados de informações

Este callback é usado para receber eventos auxiliares e dados relacionados de dentro do SDK.

Assinatura do método
onNuiAssistEventCallback?: (event: Constants.NuiEvent, info: string, infoLen: number,
                            data: ArrayBuffer) => void;
Descrição dos parâmetros
ParâmetroTipoDescrição

event

Constants.NuiEvent

Evento NuiEvent.

info

string

Informações adicionais, geralmente uma string JSON.

infoLen

number

O comprimento das informações adicionais.

data

ArrayBuffer

Os dados binários adicionais, como o áudio TTS retornado pela IA.

Nota: No HarmonyOS, este callback é opcional (?) e pode ficar sem implementação se você não precisar dele.

onNuiLogTrackCallback: Escutar logs de rastreamento

Este callback é usado para receber logs detalhados de dentro do SDK, facilitando a solução de problemas e a depuração.

onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

NuiEvent: Tipos de evento

No SDK do HarmonyOS, os tipos de evento são definidos pela enumeração Constants.NuiEvent. A tabela a seguir lista os eventos relacionados a conversas por voz em tempo real:

EventoDescrição

EVENT_TRANSCRIBER_STARTED

A tarefa foi iniciada com sucesso.

EVENT_VAD_START

Este evento é acionado imediatamente após o início da tarefa. Ele não indica que o início da fala humana foi detectado.

EVENT_VAD_END

O fim da fala humana foi detectado.

EVENT_ASR_PARTIAL_RESULT

Resultados intermediários de reconhecimento de fala.

EVENT_ASR_RESULT

O resultado completo do reconhecimento de fala.

EVENT_ASR_ERROR

Ocorreu um erro durante a conversa por voz.

EVENT_MIC_ERROR

Acionado quando nenhum dado de áudio é recebido por 2 segundos consecutivos.

EVENT_SENTENCE_START

O início de uma frase foi detectado.

EVENT_SENTENCE_END

O fim de uma frase foi detectado; nesse momento, um resultado de reconhecimento completo é retornado.

EVENT_TRANSCRIBER_COMPLETE

A conversa por voz termina.

EVENT_AUDIO_TRANSCRIPTION

Evento incremental de legendas de texto no modo de áudio, que retorna fragmentos de legendas de forma contínua (streaming).

EVENT_AUDIO_TRANSCRIPTION_COMPLETED

Evento de conclusão da saída de legendas no modo de áudio.

EVENT_OTHER_RESULT

Outras informações de eventos não classificados, como os resultados retornados de function_call.

EVENT_ASR_TTS_START

A IA começa a retornar dados TTS.

EVENT_ASR_TTS_DATA

Os dados TTS retornados pela IA.

EVENT_ASR_TTS_COMPLETE

A IA termina de retornar dados TTS.

EVENT_RESULT_TRANSLATED

Resultados intermediários de tradução.

EVENT_RESULT_TRANSLATED_END

A saída do resultado da tradução está concluída.

EVENT_AEC_DATA

Os dados de áudio após o cancelamento de eco do AEC.