Skip to main content

SDK C# untuk Qwen-LiveTranslate-Realtime

Gunakan C# SDK untuk memanggil Qwen-LiveTranslate-Realtime melalui WebSocket dan menerjemahkan ucapan menjadi teks serta audio dalam bahasa tujuan.

Prasyarat

Dapatkan kunci API dan simpan nilainya di variabel lingkungan DASHSCOPE_API_KEY. Gunakan kunci API dari wilayah yang sama dengan workspace Anda.

Instal SDK

Unduh dan ekstrak Bailian.DashScope-1.1.0.zip. Untuk menggunakan SDK dalam proyek C#, instal dari sumber lokal NuGet.

Mulai cepat

Menjalankan contoh bawaan

  1. Buat proyek konsol .NET 10 dan instal SDK seperti dijelaskan di atas.
  2. Simpan input.pcm di direktori proyek. Gunakan PCM mentah 16 kHz, mono, 16-bit little-endian. Konversikan berkas WAV ke PCM mentah terlebih dahulu.
Atur endpoint WebSocket untuk workspace di wilayah Singapura. Ganti WorkspaceId dengan ID workspace Anda. Untuk daftar wilayah dan endpoint yang didukung, lihat Akses WebSocket.
export DASHSCOPE_REALTIME_URL="wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"

Memanggil SDK dalam proyek

Program ini mengalirkan rekaman raw PCM secara real time, menunggu hingga respons selesai, lalu menulis audio ke output.pcm. Ganti Program.cs dengan kode berikut.
using DashScope.Qwen;

if (args.Length < 2)
    throw new ArgumentException("Usage: <input.pcm> <model> [voice]");

using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(60));
var ct = timeout.Token;
await using var client = new QwenLiveTranslator(new QwenLiveTranslateOptions
{
    Model = args[1],
    Voice = args.Length > 2 ? args[2] : null,
    Url = Environment.GetEnvironmentVariable("DASHSCOPE_REALTIME_URL")
        ?? throw new InvalidOperationException("Set DASHSCOPE_REALTIME_URL to your workspace WebSocket endpoint."),
    Modalities = ["text", "audio"],
    SourceLanguage = "zh",
    TargetLanguage = "en",
    SampleRate = 16000,
});

using var output = File.Create("output.pcm");
var completed = new TaskCompletionSource<string?>(TaskCreationOptions.RunContinuationsAsynchronously);
client.TranslationCompleted += (_, e) => Console.WriteLine(e.Text);
client.TranslatedAudioChunk += (_, e) => output.Write(e.Pcm);
client.ResponseCompleted += (_, e) => completed.TrySetResult(e.Status);
client.ErrorOccurred += (_, e) => completed.TrySetException(
    new InvalidOperationException($"{e.ServerErrorCode}: {e.ServerErrorMessage}"));

await client.ConnectAsync(ct);
using var input = File.OpenRead(args[0]);
var frame = new byte[640];
int size;
while ((size = await input.ReadAsync(frame.AsMemory(), ct)) > 0)
{
    await client.AppendAudioAsync(frame.AsMemory(0, size), ct);
    await Task.Delay(20, ct);
}

Array.Clear(frame);
for (var i = 0; i < 60; i++)
{
    await client.AppendAudioAsync(frame, ct);
    await Task.Delay(20, ct);
}

await client.FinishAsync(ct);
var status = await completed.Task.WaitAsync(ct);
if (status != "completed" || output.Length == 0)
    throw new InvalidOperationException($"Status: {status}, audio bytes: {output.Length}");
Tempatkan file raw PCM dari panduan cepat di direktori proyek Anda dan jalankan contohnya.
dotnet run -- input.pcm qwen3.8-livetranslate-flash-realtime Serena

Parameter permintaan

OpsiTipeDefaultDeskripsi
ApiKeystring?nullKunci API Model Studio. Jika diabaikan, SDK membaca DASHSCOPE_API_KEY.
Urlstringwss://dashscope.aliyuncs.com/api-ws/v1/realtimeEndpoint WebSocket. SDK menambahkan Model sebagai parameter query model.
WorkspaceIdstring?nullID workspace yang dikirim dalam header X-DashScope-WorkSpace. Untuk menggunakan endpoint khusus workspace, atur alamat lengkap di Url.
ConnectTimeoutTimeSpan10 sWaktu tunggu pembukaan koneksi WebSocket.
StartTimeoutTimeSpan10 sWaktu tunggu penerimaan session.created.
StopTimeoutTimeSpan10 sWaktu tunggu penerimaan session.finished saat mode selesai menunggu peristiwa tersebut.
FinishModeQwenRealtimeFinishMode?nullJika diabaikan, SDK memilih mode selesai berdasarkan model. Baca FinishMode pada instance untuk melihat mode apa yang digunakan.
Modelstringqwen3.5-livetranslate-flash-realtimeID model.
ModalitiesIList<string>["text", "audio"]Moda output. Gunakan ["text"] jika hanya ingin teks terjemahan.
Voicestring?nullSuara untuk audio terjemahan. Jika diabaikan, server akan memilih suara default. Saat menghasilkan audio dengan versi 3.8, tentukan suara yang didukung oleh model tersebut.
EnableVoiceClonebool?nullMengaktifkan kloning suara untuk audio yang diterjemahkan.
VoiceCloneFrequencystringonceonce mengkloning suara di awal sesi, always mengkloningnya untuk setiap kalimat, dan never menggunakan ID suara yang sudah dikloning. Periksa mode mana yang didukung oleh model Anda.
SampleRateint16000Laju sampel input dalam Hz. Pilih laju sampel yang didukung oleh model Anda.
InputAudioFormatstringpcmFormat audio input. Opsi SDK menerima pcm atau opus. Periksa referensi acara klien untuk format yang didukung oleh model Anda.
OutputAudioFormatstring?nullFormat audio output, seperti pcm. Jika dilewatkan, server menggunakan nilai default-nya.
TranscriptionModelstring?qwen3-asr-flash-realtimeModel untuk pengenalan ucapan sumber. Dengan qwen3.5-livetranslate-flash-realtime, atur kedua opsi ini dan SourceLanguage ke null agar menghilangkan input_audio_transcription. Pengenalan ucapan sumber selalu aktif pada versi 3.8.
SourceLanguagestring?nullKode bahasa sumber, seperti zh. Jika dilewatkan, server akan mendeteksi bahasanya.
TargetLanguagestringenKode bahasa tujuan, seperti en.
SkipSameLanguageTextbool?nullMelewatkan teks terjemahan ketika bahasa sumber dan tujuan sama. Periksa apakah versi model Anda mendukung opsi ini.
SkipSameLanguageAudiobool?nullMelewatkan audio terjemahan ketika bahasa sumber dan tujuan sama. Periksa apakah versi model Anda mendukung opsi ini.
CorpusPhrasesIDictionary<string, string>?nullGlosarium terjemahan yang memetakan istilah sumber ke istilah tujuan dalam translation.corpus.phrases.
VadThresholddouble?0.5Ambang VAD server dari -1,0 hingga 1,0.
VadSilenceMsint1000Durasi keheningan dalam milidetik sebelum server mendeteksi akhir ucapan.
EnableDebugInfobool?nullMeminta informasi debug dari server.
Untuk terjemahan audio dan video dengan 3.8, pertama atur session.input_modalities ke ["audio", "video"] seperti yang ditunjukkan di WebSocket akses, lalu kirim frame gambar bersamaan dengan audio. AppendImageAsync mengirim frame gambar. Gunakan SendRawEventAsync untuk mengirim acara klien lengkap untuk bidang tanpa opsi SDK khusus.

Referensi API

Gunakan DashScope.Qwen.QwenLiveTranslator bersama QwenLiveTranslateOptions. Beberapa pengaturan sesi dan bidang peristiwa berbeda antara versi 3.5 dan 3.8. Lihat referensi acara klien untuk model Anda.

Metode

Metode di bawah ini mengembalikan Task, kecuali DisposeAsync. ct adalah token pembatalan opsional.
MetodeDeskripsi
ConnectAsync(CancellationToken ct = default)Membuka koneksi, menunggu session.created, dan mengirim session.update.
AppendAudioAsync(ReadOnlyMemory<byte> pcm, CancellationToken ct = default)Mengirim frame audio. SDK mengenkripsi byte secara Base64 dan mengirim acara input_audio_buffer.append.
AppendImageAsync(string imageBase64, CancellationToken ct = default)Mengirim frame gambar Base64 dalam input_image_buffer.append. Pilih model yang mendukung input gambar dan aktifkan input audio dan gambar terlebih dahulu.
SendRawEventAsync(string frameJson, CancellationToken ct = default)Mengirim JSON acara klien lengkap seperti yang diberikan. Gunakan metode ini untuk acara tanpa metode SDK khusus.
FinishAsync(CancellationToken ct = default)Mengakhiri sesi menggunakan FinishMode aktif.
AbortAsync()Menutup koneksi secara langsung dan membuang hasil yang belum diproses.
DisposeAsync()Melepaskan sumber daya secara asinkron dan mengembalikan ValueTask.

Acara

AcaraArgumen acaraKapan acara dipicu
SessionReadystring?Sesi siap. Nilainya adalah session.id.
SourceTranscriptUpdatedQwenTranscriptEventArgsTranskrip sumber saat ini. Dikembalikan ketika pengenalan ucapan sumber diaktifkan.
SourceTranscriptCompletedQwenTranscriptEventArgsTranskrip akhir dari ucapan sumber.
TranslationTextDeltaQwenTextDeltaEventArgsDelta terjemahan. Baca TranslationCompleted untuk terjemahan akhir.
TranslationCompletedQwenTranscriptEventArgsTerjemahan lengkap untuk ucapan tersebut.
TranslatedAudioChunkQwenAudioChunkEventArgsBagian audio terjemahan. Format dan laju sampel tergantung pada konfigurasi sesi dan respons model.
TranslatedAudioCompletedEventArgsSemua audio terjemahan untuk giliran telah tiba.
ResponseCompletedQwenResponseSummaryresponse.done tiba dengan status dan penggunaan.
RawServerEventQwenServerEventArgsAcara server mentah dengan jenisnya dan objek JSON-nya.
ErrorOccurredDashScopeErrorEventArgsTerjadi kesalahan server atau kegagalan koneksi.
Lihat tipe hasil C# SDK untuk bidang-bidang argumen acara. Penggunaan terjemahan bersifat kumulatif selama sesi.

Mengakhiri sesi

Setelah mengirim semua audio, panggil FinishAsync untuk mengakhiri sesi dan menerima sisa terjemahan serta audio terjemahan. Secara default, LiveTranslate menggunakan FinishAndWait, yang mengirim session.finish dan menunggu session.finished.