如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

即時轉錄

在 Realtime 工作階段中轉錄即時音訊。

如果應用程式需要將麥克風、通話或其他即時音訊串流轉成文字,而且不需要助理以語音回覆,就可以使用即時轉錄。建議使用的模型會隨著語音輸入逐步傳回新增的轉錄文字,並在應用程式提交每個語音回合時傳回該回合的最終轉錄結果。

建議先使用 gpt-live-transcribe。如果音訊已經錄好,請使用檔案轉錄。如需比較不同的工作流程,請參閱轉錄概覽。

建立轉錄工作階段

若要使用標準 API 金鑰,在伺服器端透過 WebSocket 進行轉錄,請連線至 wss://api.openai.com/v1/realtime?intent=transcription。請使用 WebSocket 指南中的驗證標頭,但不要在 URL 中加入 model。該指南中指定模型的 URL 會建立對話工作階段,無法接受下方的轉錄設定更新。

建立連線後,請傳送 session.update,在工作階段設定中指定 type: "transcription",並選擇 gpt-live-transcribe。如需處理瀏覽器音訊,請參閱 WebRTC。

{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "gpt-live-transcribe"
        },
        "turn_detection": null
      }
    }
  }
}

這個範例使用 24 kHz PCM 音訊。在 gpt-live-transcribe 轉錄工作階段中,請省略 audio.input.turn_detection,或將其設為 null。模型不支援 server_vad 或 semantic_vad。如需完整的工作階段設定,請參閱 Realtime 工作階段參考文件。

串流傳送音訊

使用 input_audio_buffer.append 分段傳送音訊:

ws.send(
  JSON.stringify({
    type: "input_audio_buffer.append",
    audio: base64Pcm16,
  })
);

在每個語音回合結束時傳送 input_audio_buffer.commit,即可收到該回合的最終轉錄結果:

ws.send(
  JSON.stringify({
    type: "input_audio_buffer.commit",
  })
);

請在用戶端使用語音活動偵測(VAD)判斷說話者何時停止說話,再傳送 input_audio_buffer.commit。

處理轉錄事件

監聽轉錄文字的增量事件和完成事件:

ws.on("message", (data) => {
  const event = JSON.parse(data);

  if (event.type === "conversation.item.input_audio_transcription.delta") {
    process.stdout.write(event.delta);
  }

  if (event.type === "conversation.item.input_audio_transcription.completed") {
    console.log("\nFinal transcript:", event.transcript);
  }
});

增量事件包含最新產生的轉錄文字:

{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "item_003",
  "content_index": 0,
  "delta": "Hello,"
}

完成事件包含已提交項目的最終轉錄結果:

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "item_003",
  "content_index": 0,
  "transcript": "Hello, how are you?"
}

不同語音回合的完成事件不一定會依回合順序抵達。請使用 item_id 將轉錄事件對應到已提交的輸入項目。

設定好轉錄工作階段後,可使用下列 Go 函式傳送 24 kHz 的單聲道 PCM16 音訊、提交該回合,並將最終轉錄結果對應到已提交的項目:

func transcribeTurn(ctx context.Context, conn *realtime.RealtimeConnection, audio []byte) error {
	for start := 0; start < len(audio); start += 9600 {
		end := min(start+9600, len(audio))
		if err := conn.Send(ctx, realtime.RealtimeClientEventParamOfInputAudioBufferAppend(base64.StdEncoding.EncodeToString(audio[start:end]))); err != nil {
			return err
		}
	}
	if err := conn.Send(ctx, realtime.RealtimeClientEventUnionParam{
		OfInputAudioBufferCommit: &realtime.InputAudioBufferCommitEventParam{},
	}); err != nil {
		return err
	}
	// Match the final transcript to the committed item, not event arrival order.
	var itemID string
	for {
		event, err := conn.Recv(ctx)
		if err != nil {
			return err
		}
		switch event.Type {
		case "input_audio_buffer.committed":
			itemID = event.OfInputAudioBufferCommittedEvent.ItemID
		case "conversation.item.input_audio_transcription.delta":
			delta := event.OfConversationItemInputAudioTranscriptionDeltaEvent
			if itemID != "" && delta.ItemID == itemID {
				fmt.Fprintf(os.Stderr, "Partial transcript (%s): %s\n", delta.ItemID, delta.Delta)
			}
		case "conversation.item.input_audio_transcription.completed":
			completed := event.OfConversationItemInputAudioTranscriptionCompletedEvent
			if itemID == "" || completed.ItemID != itemID {
				continue
			}
			fmt.Println("Final transcript:", completed.Transcript)
			return nil
		case "conversation.item.input_audio_transcription.failed":
			if itemID != "" && event.OfConversationItemInputAudioTranscriptionFailedEvent.ItemID == itemID {
				return fmt.Errorf("transcription failed")
			}
		case "error":
			return fmt.Errorf("Realtime API error: %s", event.OfRealtimeErrorEvent.Error.Message)
		}
	}
}

加入轉錄上下文

如果音訊中含有專業詞彙,或預期會出現多種語言,請提供上下文。在工作階段進行期間,可以再次傳送 session.update 事件來變更轉錄設定。

{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "gpt-live-transcribe",
          "prompt": "A customer support call about a premium plan and account AC-42.",
          "keywords": ["premium plan", "AC-42", "billing"],
          "languages": ["en", "fr"],
          "delay": "low"
        },
        "turn_detection": null
      }
    }
  }
}
  • 使用 prompt 描述錄音內容或錄音情境。
  • 使用 keywords 列出音訊中可能出現的產品名稱、縮寫及其他特定詞語的確切寫法。
  • 使用 languages 指定預期的輸入語言。

支援的語言代碼格式包括:

  • ISO 639-1 代碼,例如 en、es 和 fr。
  • 部分 ISO 639-3 代碼,例如 eng、spa、yue 和 cmn。
  • 含地區標記的 zh 語系代碼,例如 zh-cn、zh-tw 和 zh-hk。

Realtime API 會拒絕不支援或格式錯誤的語言代碼。

關鍵字只供模型參考,不一定會出現在轉錄結果中。每個關鍵字都必須寫在同一行,不得包含 <、>、歸位字元或換行字元。如果任一關鍵字包含上述任一字元,或 prompt 超過模型的長度限制,Realtime API 就會拒絕更新工作階段。

gpt-live-transcribe 使用 languages 欄位,而非單數形式的 language 欄位。請勿同時傳送這兩個欄位。

轉錄已提交的回合

只有在需要等到語音回合提交後才開始轉錄,或需要模型傳回偵測到的語言時,才在 Realtime 工作階段中使用 gpt-transcribe。這個工作流程需要使用 WebSocket 連線。

當 gpt-transcribe 在 Realtime API 工作階段中轉錄輸入音訊,或在專用轉錄工作階段中執行時,模型會自動使用先前回合的轉錄結果作為上下文。

{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "gpt-transcribe"
        },
        "turn_detection": null
      }
    }
  }
}

將音訊附加到緩衝區後,傳送 input_audio_buffer.commit。模型接著可以在送出最終完成事件前,逐步傳回新增的轉錄文字。完成事件也會包含偵測到的語言:

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "item_003",
  "content_index": 0,
  "transcript": "Bonjour, pouvez-vous m'entendre ?",
  "languages": [{ "code": "fr" }]
}

當 gpt-transcribe 無法可靠地判斷語言時,languages 會是空陣列。gpt-live-transcribe 不會傳回語言偵測結果。

調整延遲與準確度

串流轉錄需要在延遲與轉錄品質之間取得平衡。較低的延遲設定可讓部分轉錄文字更早出現。較高的延遲設定則讓模型在輸出文字前取得更多音訊上下文,有助於降低詞錯誤率。

請先設定 audio.input.transcription.delay,再使用實際音訊測試。可依使用情境選擇起始設定:

  • minimal 適合對延遲最敏感的互動。
  • low 適合需要低延遲的即時字幕。
  • medium 適合需要兼顧延遲與準確度的情境。
  • high 適合準確度比即時顯示更重要的情境。
  • xhigh 適合能容許最長延遲,讓模型取得更多上下文的工作流程。

實際延遲的毫秒數會隨模型設定而異。請使用具代表性的音訊測量延遲,不要假設每個等級都對應固定的延遲時間。

請勿只根據合成音訊選擇設定。測試時,請使用能反映實際情境的麥克風和電話音訊,並涵蓋不同口音、背景噪音、說話時切換語言、專業詞彙及長時間工作階段。

處理信心分數、時間戳記與說話者標籤

gpt-live-transcribe 不會傳回逐詞時間戳記、說話者標籤或轉錄信心分數。如果應用程式需要時間戳記或說話者標籤,請使用支援所需功能的檔案轉錄模型,或在應用程式中加入替代處理機制。

正式環境檢查清單

  • 調整設定前,先訂定目標延遲與準確度門檻。
  • 使用正式環境中的實際音訊測試,不要只使用沒有雜訊的樣本。
  • 測試每一種目標語言。
  • 在評估資料集中納入數字、日期、貨幣、電子郵件地址、產品名稱和專業術語。
  • 除了詞錯誤率,也要分別追蹤轉錄結果為空、遭截斷或延遲送達的情況。
  • 決定後續增量事件修正先前的文字時,使用者介面應如何更新已顯示的部分轉錄文字。
  • 使用 item_id 將最終轉錄結果排序,並與對應的輸入項目核對。
  • 如果模型不支援時間戳記、說話者標籤或信心分數欄位,請備妥替代處理機制。

相關指南

Realtime 與音訊概覽

比較語音智慧體、翻譯與轉錄工作階段。

即時翻譯

使用專用翻譯工作階段即時翻譯語音。

WebSocket 連線

透過伺服器端的媒體處理管線串流傳送原始音訊。

語音活動偵測

為即時音訊串流設定回合偵測功能。