Alibaba Cloud Model Studio:Connecting to models and applications

Conecte-se a modelos e aplicativos da Realtime API pelos protocolos AOQ, WebRTC e WebSocket. Este tópico aborda o fluxo de conexão, diagramas de sequência e exemplos de código para cada protocolo.

Pré-requisitos

• Antes de se conectar, verifique Supported models and applications
• Saiba mais sobre Token authentication

Experimente a demonstração

Use a demonstração para Android do Alibaba Cloud Model Studio para verificar rapidamente a conectividade AOQ. Baixe o APK e configure a chave de API e o workspaceId para testar os modelos selecionados.

Escaneie o QR code a seguir para baixar a demonstração:

Conexão AOQ

O protocolo AOQ é uma personalização avançada baseada no QUIC. Ele é ideal para aplicativos móveis nativos, suporta transmissão mista de áudio, vídeo e dados e possui resiliência integrada para redes instáveis. O exemplo a seguir usa a demonstração iOS Real-time omni (Omni) para detalhar o fluxo de conexão AOQ. Para obter detalhes sobre a API do SDK AOQ, consulte AOQ client SDK.

Diagrama de sequência geral

Crie o engine e defina os callbacks

let config = AoqCreateConfig()
config.workDir = workDir
config.enableDumpAudio = false
engine = AoqClientEngine.createEngine(config, delegate: self)

Implemente o protocolo AoqEngineDelegate para escutar callbacks como onConnectionStatusChange, onDataMsg e onError.

Inicie a captura e a reprodução de áudio

// Audio capture
let capCfg = AoqAudioCaptureConfig()
capCfg.channel = 1; capCfg.isExternal = false
engine.startAudioCapture(capCfg)

// Audio playback
let playCfg = AoqAudioPlaybackConfig()
playCfg.channel = 1; playCfg.isExternal = false
engine.startAudioPlayer(playCfg)

// Video capture (optional)
let vidCfg = AoqVideoCaptureConfig()
vidCfg.width = 720; vidCfg.height = 1280; vidCfg.fps = 15
engine.startVideoCapture(vidCfg)

Obtenha as credenciais de conexão

O AppServer do aplicativo atua como proxy da solicitação para o Model Studio. Consulte Token authentication.

Configure os codecs e estabeleça a conexão

Configure os parâmetros do codec e chame connect:

// Audio codec configuration
let encCfg = AoqAudioCodecConfig()
encCfg.codecType = .audioPCM; encCfg.sampleRate = 16000; encCfg.channel = 1
engine.setAudioEncoderConfig(encCfg)
engine.setAudioDecoderConfig(encCfg)

// Disable media sending before connect; enable it after session.updated
engine.enableSendMediaStream(.audio, enable: false)

let config = AoqConnectConfig()
config.token = token
config.sid = sid
config.certFingerprint = certificate
config.relayEndpoints = relayEndpoints
config.workspaceIdHash = workspaceIdHash
config.publishTracks = [audioTrack, dataTrack]
config.subscribeTracks = [audioTrack, dataTrack]
engine.connect(config)

Configure a sessão de IA

Após estabelecer a conexão com sucesso, envie um evento session.update. Para mais detalhes, consulte Client events:

func onConnectionStatusChange(_ status: AoqConnectionStatus) {
    if status == .connected { sendSessionUpdate() }
}

private func sendSessionUpdate() {
    let json = """
    {
      // The ID of this event, generated by the client
      "event_id": "event_ToPZqeobitzUJnt3QqtWg",
      // Event type, fixed to session.update
      "type": "session.update",
      // Session configuration
      "session": {
          // Output modalities. Set to ["text"] (text only) or ["text","audio"] (text and audio).
          "modalities": [
              "text",
              "audio"
          ],
          // Voice for the output audio
          "voice": "Ethan",
          // Input audio format. Only pcm is supported. The input audio is a PCM audio stream with a 16 kHz sample rate.
          "input_audio_format": "pcm",
          // Output audio format. Only pcm is supported. The output audio is a PCM audio stream with a 24 kHz sample rate.
          "output_audio_format": "pcm",
          // System message that sets the model's goal or role.
          "instructions": "You are an AI customer service agent at a five-star hotel. Accurately and courteously answer customer questions about room types, facilities, prices, and booking policies. Always respond in a professional and helpful manner, and never provide unverified information or information beyond the scope of the hotel's services.",
          // Whether to enable voice activity detection. To enable it, pass a configuration object; the server then automatically detects when speech starts and stops.
          // Set to null to let the client decide when to trigger a model response.
          "turn_detection": {
              // VAD type: server_vad or semantic_vad. semantic_vad is recommended for qwen3.5-omni-realtime series models.
              "type": "semantic_vad",
              // VAD detection threshold. Increase it in noisy environments and decrease it in quiet environments.
              "threshold": 0.5,
              // Silence duration for detecting the end of speech. A model response is triggered after this duration is exceeded
              "silence_duration_ms": 800
          }
      }
    }
    """
    let msg = AoqDataMsg()
    msg.data = json.data(using: .utf8)!
    engine.send(msg)
}

Ative o envio de mídia após receber session.updated

O exemplo a seguir processa a resposta session.updated do modelo. Para mais detalhes, consulte Server events:

func onDataMsg(_ msg: AoqDataMsg) {
    guard let obj = try? JSONSerialization.jsonObject(with: msg.data) as? [String: Any],
          let type = obj["type"] as? String else { return }
    if type == "session.updated" {
        engine.enableSendMediaStream(.audio, enable: true)
        engine.enableSendMediaStream(.video, enable: true)
    }
}

Desconecte e destrua o engine

engine.disconnect()
AoqClientEngine.destroy()

Conexão WebRTC

O WebRTC não possui um SDK dedicado. Na web, conecte-se diretamente pela API JavaScript nativa do navegador. Em outros clientes, use uma biblioteca WebRTC open source ou um service RTC de terceiros compatível com o protocolo WebRTC padrão. O exemplo a seguir usa JavaScript na web.

Diagrama de fluxo geral

Estabeleça a conexão

# pip install aiortc aiohttp certifi
import asyncio, aiohttp, ssl, certifi
from aiortc import RTCPeerConnection, RTCConfiguration, RTCSessionDescription
from aiortc.mediastreams import AudioStreamTrack

API_KEY = "your-api-key"
MODEL = "target-model"
SIGNALING_URL = f"https://{{endpoint}}/api/v1/webrtc/realtime?model={MODEL}"

async def connect():
    pc = RTCPeerConnection(RTCConfiguration(iceServers=[]))

    # Add an audio track so that the Offer SDP contains m=audio (required by the server)
    pc.addTrack(AudioStreamTrack())

    # Create a DataChannel to trigger SDP negotiation (the name is customizable; the server pushes events through a channel named "txt")
    pc.createDataChannel("oai-events")

    # SDP exchange: create an Offer and send it to the server
    offer = await pc.createOffer()
    await pc.setLocalDescription(offer)

    async with aiohttp.ClientSession() as session:
        async with session.post(
            SIGNALING_URL,
            ssl=ssl.create_default_context(cafile=certifi.where()),
            data=offer.sdp.encode("utf-8"),
            headers={
                "Content-Type": "application/sdp",
                "Authorization": f"Bearer {API_KEY}",
            },
        ) as resp:
            if not resp.ok:
                raise Exception(f"SDP exchange failed: {resp.status} {await resp.text()}")
            answer_sdp = await resp.text()

    print("=== Offer SDP ===")
    print(offer.sdp)
    print("=== Answer SDP ===")
    print(answer_sdp)

    # ICE connection setup completes automatically
    await pc.setRemoteDescription(RTCSessionDescription(sdp=answer_sdp, type="answer"))
    print("WebRTC connection established")
    return pc

Configure os parâmetros do modelo

Monitore as mensagens retornadas pelo modelo via DataChannel para manter a sequência correta da interação:

pc.ondatachannel = (event) => {
  const ch = event.channel;
  ch.onmessage = (e) => {
    let obj;
    try { obj = JSON.parse(e.data); }
    catch (err) {
      return;
    }
    if (obj?.type === "session.created") {
      sendUpdate(event.channel);
      // Start pushing audio and video
      audioSender?.replaceTrack(audioTrack);
      videoSender?.replaceTrack(videoTrack);
    }
  };
};

Envie e receba dados de mídia

As faixas de áudio e vídeo adicionadas durante a configuração da conexão (os canais de mídia RTP) transmitem dados automaticamente para o servidor.

• Áudio: transmitido diretamente pela faixa de áudio (RTP). Não são necessários eventos input_audio_buffer.append.
• Imagens: os quadros são enviados pela faixa de vídeo (RTP). Eventos input_image_buffer.append não são suportados.

Código-fonte da demonstração

Pré-requisitos

• Um navegador moderno com suporte a WebRTC (como Chrome, Edge, Firefox ou Safari).
• Permissão de microfone concedida ao navegador.
• Devido às políticas de segurança de origem cruzada, o navegador não consegue enviar a solicitação de conexão diretamente ao servidor. Execute o comando curl em um terminal para estabelecer a conexão.

Execute a demonstração

Crie um arquivo HTML chamado webrtc_demo.html e copie o seguinte código para ele:

webrtc_demo.html.

Abra o arquivo em um navegador e siga estas etapas:

1. Clique em Start session. A página gera automaticamente o Offer SDP e o comando curl correspondente.
2. Clique em Copy curl command e execute o comando em um terminal. O comando retorna o Answer SDP.
3. Cole o Answer SDP na caixa de texto Answer SDP da página e clique em Set Answer para estabelecer a conexão e iniciar a conversa por voz.

Conexão WebSocket

O método e o fluxo de conexão variam conforme o modelo. Para mais detalhes, consulte:

• Real-time omni
• Real-time audio translation
• Real-time speech recognition
• Real-time speech synthesis
• Real-time voice conversation