Chuyển giọng nói thành văn bản theo thời gian thực

Chuyển giọng nói thành văn bản thời gian thực nhận âm thanh liên tục qua kết nối WebSocket lâu dài và trả về văn bản bổ sung cùng kết quả cuối cùng theo từng mục âm thanh. Phù hợp cho phụ đề trực tiếp, ghi nhanh cuộc họp, chuyển cuộc gọi thành văn bản và nhập liệu bằng giọng nói; nếu cần tải lên toàn bộ tệp ghi âm trong một lần, hãy dùng API chuyển giọng nói thành văn bản từ tệp.

gpt-live-transcribe phù hợp với văn bản bổ sung có độ trễ thấp; gpt-transcribe phù hợp để chuyển đổi chính xác cao sau khi gửi đoạn giọng nói đầy đủ và có thể trả về ngôn ngữ được phát hiện trong sự kiện cuối cùng. Mô hình trong kết nối và phiên phải giống nhau.

Xác thực và kết nối

Ứng dụng phía máy chủ nên dùng Bearer API Key trong bước bắt tay WebSocket:

API WebSocket của trình duyệt thông thường không cho tùy chỉnh Header Authorization, vì vậy không đưa API Key dài hạn vào HTML, JavaScript phía trình duyệt hoặc gói máy khách. Sản phẩm trình duyệt nên thiết lập kết nối qua backend đáng tin cậy hoặc cơ chế thông tin xác thực ngắn hạn có kiểm soát.

Yêu cầu âm thanh đầu vào

Âm thanh đầu vào trong tài liệu này sử dụng PCM16 little-endian, 24 kHz, đơn kênh, không có phần đầu tệp WAV hoặc định dạng chứa khác. audio trong input_audio_buffer.append là chuỗi Base64 của byte PCM thô.

Khi gửi theo thời gian thực, nên dùng đoạn âm thanh nhỏ với kích thước ổn định; mỗi sự kiện không nên vượt quá 15 MiB. Định dạng, tần số lấy mẫu hoặc xử lý định dạng chứa sai sẽ khiến chuyển giọng nói thành văn bản thất bại.

Cấu hình phiên

session.type trong session.update cố định là transcription. Cấu hình chuyển giọng nói thành văn bản nằm tại session.audio.input.transcription:

noise_reduction.type=near_field phù hợp với tai nghe có micrô; far_field phù hợp với phòng họp hoặc micrô máy tính xách tay. Đặt null để tắt khử nhiễu.

Gửi thủ công và VAD phía máy chủ

• turn_detection: null: sau khi gửi âm thanh, máy khách gọi input_audio_buffer.commit, phù hợp khi nghiệp vụ chủ động kiểm soát phân đoạn.
• VAD phía máy chủ: cấu hình ngưỡng, khoảng âm thanh đệm trước giọng nói và thời gian im lặng để máy chủ tự phát hiện giọng nói bắt đầu và kết thúc.

Trong chế độ thủ công, không gửi bộ đệm rỗng. Khi bật VAD, có thể cập nhật giao diện ghi âm theo speech_started và speech_stopped, nhưng kết quả cuối cùng vẫn phải dựa vào sự kiện completed.

Ví dụ kết nối

Các ví dụ sau giả định audio.pcm đã được chuyển sang âm thanh thô PCM16, 24 kHz, đơn kênh. Ứng dụng thời gian thực nên liên tục gửi các khối âm thanh nhỏ thay vì đọc toàn bộ bản ghi một lần.

import fs from 'node:fs';
import WebSocket from 'ws';

const ws = new WebSocket('wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID', {
  headers: {
    Authorization: 'Bearer your-api-key',
  },
});

ws.on('open', async () => {
  ws.send(JSON.stringify({
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "noise_reduction": { "type": "near_field" },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "Cuộc gọi hỗ trợ khách hàng bằng tiếng Trung",
          "keywords": ["AGTCloud", "Cổng API"],
          "languages": ["zh-cn", "en"]
        },
        "turn_detection": null
      }
    }
  }
}));

  const audio = fs.createReadStream('audio.pcm', { highWaterMark: 4800 });
  for await (const chunk of audio) {
    ws.send(JSON.stringify({
      type: 'input_audio_buffer.append',
      audio: chunk.toString('base64'),
    }));
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
  ws.send(JSON.stringify({ type: 'input_audio_buffer.commit' }));
});

ws.on('message', (message) => {
  const event = JSON.parse(message.toString());
  if (event.type.endsWith('.delta')) process.stdout.write(event.delta);
  if (event.type.endsWith('.completed')) console.log('\n', event.transcript);
});

Tham khảo sự kiện

Máy khách dùng sự kiện phiên và bộ đệm âm thanh để điều khiển đầu vào; máy chủ liên kết văn bản bổ sung, văn bản cuối cùng và lỗi bằng Item ID. Các mục âm thanh có thể hoàn tất theo thứ tự khác nhau, vì vậy nên tổng hợp văn bản theo item_id.

{
  "event_id": "evt_session_001",
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "noise_reduction": {
          "type": "near_field"
        },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "Cuộc gọi hỗ trợ khách hàng bằng tiếng Trung",
          "keywords": [
            "AGTCloud",
            "Cổng API"
          ],
          "languages": [
            "zh-cn",
            "en"
          ],
          "delay": "low"
        },
        "turn_detection": null
      }
    }
  }
}

Xử lý lỗi và khôi phục

Văn bản bổ sung có thể được sửa trong kết quả sau, nên không ghi vào bản ghi bất biến khi nhận delta; chỉ transcript trong completed mới là văn bản cuối cùng của mục âm thanh hiện tại.