遷移至 GPT-Live

從 Realtime API 遷移

先閱讀 GPT-Live 提示詞指南。將既有提示詞拆分給語音模型和後端，不要整份複製到 session.instructions。在語音提示詞中保留對話風格和委派指引，將詳細工作流程和工具使用指示移至後端。

遷移前： Realtime 模型負責語音，並選擇 check_availability 和 book_appointment 等函式。應用程式負責執行函式並傳回結果。

遷移後： GPT-Live 負責語音，並將任務工作委派出去。後端負責選擇相同的函式，應用程式仍負責驗證和執行。此處的步驟使用 Responses 委派。如果你保留外部智慧體，請改用用戶端配接器。

Responses 委派的運作方式

在 delegation.responses 中設定後端模型、指示和工具。當 GPT-Live 判斷某個請求需要後端處理時，Live 服務會呼叫該 Responses 模型，並提供相關對話上下文。後端會針對任務進行推理並選擇工具。應用程式仍負責執行自訂函式、強制執行權限檢查，以及傳回函式結果。

以預約助理為例：

1. 使用者詢問星期五有哪些可預約時段，GPT-Live 便將此請求委派出去。
2. Responses 後端請求呼叫 check_availability。
3. 應用程式執行函式、傳回結果，並讓後端繼續產生回應。
4. GPT-Live 根據後端的回答，與使用者討論可預約時段。

後端執行工作時，GPT-Live 可以繼續對話。後端工作完成並不代表助理已經說完。組態與完整事件流程請參閱委派與工具。

保留依賴音訊的決策

檢查既有的工具使用決策是否依賴聲音線索，例如語音信箱的提示音，或預錄問候語的節奏。GPT-Live 能聽到傳入的音訊，但其語音前端會委派工作，而非發出一般的結構化函式呼叫。在用戶端模式下，session.delegation.created 只包含中繼資料和時間資訊，不含原始音訊、任務文字或已剖析的工具引數。受委派的後端不會自動收到波形資料。

若要偵測答錄機，請明確將傳入音訊導向支援音訊的偵測器。你可以評估一種由應用程式管理的架構：在通話的部分期間，讓獨立的 Realtime 工作階段與 GPT-Live 同時運作：

1. 將傳入的通話音訊各複製一份，傳送至兩個工作階段。
2. 讓偵測器透過結構化函式呼叫回報分類結果。依據結構描述檢查每個結果，拒絕過時的結果，並在證據不足時維持未知狀態。允許根據後續證據修正判斷。
3. 將相關且可信任的上下文傳送至 GPT-Live，並依照應用程式政策控制輸出音訊的播放。

將「真人或機器」的分類與「是否已可開始錄音」分開判斷。辨識出語音信箱，不代表問候語和提示音已結束，也不代表可以開始錄音。分類器結果或上下文接收確認，也不代表已獲准播放音訊。請參考調整防護機制和播放控制，在應用程式控制的音訊路徑中強制落實播放決策。

測試以下情境：簡短的「喂」之後接續語音信箱問候語、來電篩選提示，以及語音信箱運作期間有人接聽。如果你在通話結束前停止偵測器，請測試偵測器停止後才有人接聽的情況。根據這些測試和偵測器增加的成本，決定何時停止偵測。僅憑首次判定為真人，無法確定後續已不需要偵測。

調整連線與音訊生命週期

將 Realtime 工作階段設定流程替換為 GPT-Live 連線程序。重新檢查所用傳輸方式的啟動流程和音訊格式。WebRTC 透過媒體軌道傳輸音訊，並透過資料通道傳輸 JSON 事件。主要 WebSocket 連線則將音訊放在 JSON 事件中傳輸。

如果你的 Realtime 應用程式使用伺服器連線監控通話或強制執行防護機制，請將其調整為 GPT-Live 側頻連線。對話檢查和播放方式所需的變更，請依照調整防護機制處理。

生成與播放：在 Realtime 中，response.output_audio.done 標記音訊生成結束，response.done 則標記回應串流結束。回應中斷或未成功時，也可能發生這些事件；請檢查 response.done 中的 response.status。這兩個事件都無法確認緩衝音訊是否已播放完畢。例如，伺服器可能已完成生成，但用戶端仍有一秒的音訊尚待播放。請依據播放狀態控制「說話中」指示器。

字幕：輸入轉錄對應使用者的語音，輸出轉錄則對應助理生成的語音。啟用輸入轉錄後，Realtime 會透過 conversation.item.input_audio_transcription.delta 傳送更新，並透過 conversation.item.input_audio_transcription.completed 傳送最終轉錄文字。delta 是新增的文字片段。在 GPT-Live 中，由於聆聽和說話可能同時進行，請將每個片段分別附加至對應說話者的字幕。單一片段不代表完整回合，也不能確認播放狀態。顯示方式的實作範例請參閱顯示字幕。

在 GPT-Live 中，response.create 會啟動或繼續已委派的 Responses 工作，並不會授予語音模型說話的權限。如需瞭解啟動、問候、打斷對話及關閉工作階段的處理方式，請參閱管理工作階段。

分開設定對話與後端指示

將對話風格與委派指引移至 session.instructions，並將業務規則與工具使用指示移至 delegation.responses.instructions。如果後端由你自行執行，請將這些規則保留在後端現有的提示詞中。

遷移前：單一 Realtime 提示詞

Help callers book appointments. Speak briefly. Check availability with the tool,
ask the caller to confirm a slot, then book it. Never claim an unverified booking.

遷移後：GPT-Live 對話指示

Help callers book appointments. Keep spoken replies brief. Delegate availability
checks and booking requests. Ask the caller to confirm the proposed slot.
Only announce a booking when the backend reports that it succeeded.

遷移後：後端指示

Use the appointment tools to check current availability. Before booking, verify
that the caller confirmed the exact slot and still has permission to book it.
Apply the latest correction. Return verified availability, booking, or failure
status with the date, time, and time zone.

執行工具前，請在應用程式中強制執行確認與權限檢查。提示詞中的指示能引導模型，但無法強制執行這些檢查。如需提示詞設計資訊，請參閱為語音模型撰寫提示詞。

調整函式處理常式

保留 check_availability 和 book_appointment 的實作。將其定義從 Realtime 的 session.tools 或 response.tools 移至 delegation.responses.tools，並使用 Responses 函式結構描述。將工具選擇設定移至 delegation.responses.tool_choice 和 delegation.responses.parallel_tool_calls。請參閱設定 Responses 委派。

函式仍會針對原始的 call_id 傳回結果。改變的是處理常式接收呼叫與傳送結果的位置：

例如，在 check_availability 傳回一個已驗證的時段後，結果的傳送方式會變更如下。這些訊息是在已連線的工作階段中傳送；call_availability 代表你收到的實際呼叫 ID。

遷移前：Realtime 結果

12345678{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_availability",
    "output": "{\"available\":true,\"slot_id\":\"slot_friday_14\",\"booked\":false}"
  }
}

遷移後：GPT-Live 結果

1
2
3
4
5
6
7
8
9
10
11export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "availability_result_1",
    item: {
      type: "function_call_output",
      call_id: "call_availability",
      output: '{"available":true,"slot_id":"slot_friday_14","booked":false}',
    },
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.responses.response_input_item_param import ResponseInputItemParam


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    item: ResponseInputItemParam = {
        "type": "function_call_output",
        "call_id": "call_availability",
        "output": '{"available":true,"slot_id":"slot_friday_14","booked":false}',
    }
    await connection.response.item.create(
        event_id="availability_result_1",
        item=item,
    )

提交所有必要的函式結果後，讓後端繼續執行：

1
2
3
4
5
6export function sendUpdate(connection) {
  connection.send({
    type: "response.create",
    event_id: "continue_availability_1",
  });
}

1
2
3
4
5
6
7
8
9
10from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    await connection.response.create(
        event_id="continue_availability_1",
    )

初次遷移時，將 parallel_tool_calls 設為 false 可簡化結果處理。即使生命週期終止時的快照包含 output: []，仍應從輸出項目完成事件中收集呼叫。僅靠引數完成事件，無法取得函式名稱與 call_id。請遵循完整的函式結果處理程序，處理呼叫收集、輸出提交與錯誤。

保留上下文並套用修正

Responses 委派會將相關的語音對話上下文提供給後端。請在應用程式中保存作為準據的預約狀態，包括已選時段、已確認時段、權限、進行中的操作及結果。Live 對話記錄可能會經過壓縮，不能當作預約紀錄。

如果星期四的查詢尚未完成，使用者就說「其實，改成星期五好了」，請更新任務的修訂版本，並使先前的時段確認失效。執行預約前，請檢查引數是否仍符合目前的任務與確認內容。對於應用程式拒絕執行的任何待處理函式呼叫，請如實傳回已被取代或已取消的結果，接著完成所需的整批輸出後再繼續。如果預約已成功，請先核對該結果與使用者要求的變更，再採取其他動作。

逐字稿片段可能延遲送達，或與助理的語音重疊。請原樣附加收到的每個 delta，並使用 start_ms 和 end_ms 將顯示內容分組。這些時間戳記並非明確的回合界線，也不是逐字播放時間戳記。當意圖不明確時，請釐清重要的日期、名稱與數字。如需逐字稿與上下文的處理方式，請參閱管理工作階段。

圖像與螢幕上下文：如果你的 Realtime 應用程式接受圖像，請將圖像傳送至具備視覺能力的後端，並將相關文字傳回 GPT-Live。用戶端委派與 Responses 委派都支援此模式。請參閱新增圖像與視覺上下文。

從文字智慧體或串接式流程遷移

遷移前：文字智慧體會接收文字請求，並使用其工具與已儲存的狀態。串接式（亦稱級聯式）語音流程會在智慧體之前加入語音轉文字步驟，並在其後加入文字轉語音步驟。

遷移後： GPT-Live 提供語音介面，並將任務工作委派給現有的智慧體。對於串接式流程，GPT-Live 會取代原本獨立的語音轉文字與文字轉語音階段。後端中仍適合該任務的模型、指示、工具、工作流程與持久狀態，都應保留。

連接現有的智慧體

在設定工作階段時，將 delegation 設為 {"type":"client"}。應用程式會收到如下通知：

123456789{
  "type": "session.delegation.created",
  "offset_ms": 1000,
  "delegation": {
    "id": "item_appointment_1",
    "type": "delegation",
    "target": "client"
  }
}

通知包含中繼資料，不包含請求文字、工具引數或完整逐字稿。請保持實際的 delegation.id 不變。使用近期附有角色標籤的逐字稿片段，以及已驗證的應用程式狀態，組成智慧體的輸入；其中應包含進行中的任務與最新修正。委派可能在逐字稿出現完整句子之前送達。如果現有上下文不足以確定請求內容，請先收集更多上下文或要求釐清，再採取行動。

在文字應用程式中，你可能會直接將使用者的最新訊息傳給智慧體。使用 GPT-Live 時，請加入轉接器，提供該上下文並傳回簡潔且經過驗證的結果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25async function handleDelegation(event, app) {
  if (
    event.type !== "session.delegation.created" ||
    event.delegation?.target !== "client"
  )
    return;

  const context = app.readContext();
  if (!context) return; // Retain the notice; resolve the request before acting.

  const summary = await app.runAgent({
    revision: context.revision,
    recentConversation: context.recentConversation,
    task: context.task,
  });

  if (app.currentRevision() !== context.revision) return;

  app.send({
    type: "session.commentary.append",
    event_id: crypto.randomUUID(),
    delegation_id: event.delegation.id,
    content: summary,
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from uuid import uuid4

from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.live.server_event import ServerEvent


@dataclass(frozen=True)
class Context:
    revision: int
    recent_conversation: str
    task: str


async def handle_delegation(
    event: ServerEvent,
    connection: AsyncLiveConnection | AsyncSidebandConnection,
    *,
    read_context: Callable[[], Context | None],
    run_agent: Callable[[Context], Awaitable[str]],
    current_revision: Callable[[], int],
) -> None:
    if (
        event.type != "session.delegation.created"
        or event.delegation.target != "client"
    ):
        return
    context = read_context()
    if context is None:
        return  # Retain the notice; resolve the request before acting.
    summary = await run_agent(context)
    if current_revision() != context.revision:
        return
    await connection.session.commentary.append(
        event_id=str(uuid4()),
        delegation_id=event.delegation.id,
        content=summary,
    )

轉接器會使用應用程式的回呼函式來讀取上下文、執行智慧體及檢查目前的任務修訂版本；這些並非 SDK 方法。上下文回呼函式會傳回包含近期對話與目前任務的就緒快照；如果請求仍不明確，則不傳回快照。智慧體回呼函式會呼叫現有的智慧體，並傳回經過驗證且不超過 500 個 Token 的摘要。在 JavaScript 中，應用程式提供的 send 回呼函式會透過 Live 連線傳送 JSON 事件。在 Python 中，轉接器則直接透過 SDK 的 connection 傳送更新。

如果上下文尚未就緒，請保留通知，並在釐清請求後再次呼叫轉接器。呼叫此轉接器前，請先在應用程式中認領該委派，避免通知重複送達時，同一操作被啟動兩次。請在後端管理授權、確認、操作 ID 與重試決策。修訂版本檢查可防止此轉接器告知使用者過時的結果；後端在執行預約等會產生副作用的操作前，也必須檢查目前的修訂版本。

對預約助理而言，上下文應明確指出使用者要求的日期與時區、先前提供的時段、任何已確認的時段，以及最新修正。可預約時段的查詢結果應說明該時段可供預約，且尚未建立預約。只有在預約成功後，才能傳回預約確認。如需完整設定與結果處理流程，請參閱用戶端委派。

傳送更新與修正

將結構化工具輸出與工作流程細節保留在後端。向 GPT-Live 傳回簡短、符合事實的更新：

• 使用 session.thinking.append 提供背景進度，例如查詢仍在執行中。
• 使用 session.commentary.append 提供使用者應聽到的已驗證結果。
• 使用 session.instructions.append 提供由應用程式撰寫的行為指引。

這三者都接受不超過 500 個 Token 的純字串 content，且都需要 delegation_id。相關工作請使用原始的用戶端委派 ID；一般工作階段上下文則使用 null。請透過 client_event_id 比對附加操作的確認回覆。更新已被接受，不代表語音已產生或播放。請參閱傳送適當類型的更新。

當使用者說「其實，改成星期五好了」，請更新進行中的任務及其修訂版本，使所有星期四的確認失效，並指示現有的智慧體處理修正後的請求。請決定要取消、變更，還是讓待處理的查詢完成。過時的結果應予以捨棄，不要傳回 GPT-Live。語音遭到打斷不會取消後端操作，而提出取消請求也不代表動作已被取消。

語音工作階段結束後，後端工作可能仍會持續。請在應用程式中持久保存其狀態。之後再次進行語音互動時，請使用已儲存的相關上下文啟動新的工作階段；請參閱管理工作階段。

調整文字與語音防護措施

文字智慧體可以先完成並驗證回覆，再顯示給使用者。串接式流程可能會先驗證完整回覆，再送至文字轉語音階段。GPT-Live 可以在後端工作仍在執行時說話，因此暫不提供工具結果或暫停後端的後續執行，並不能阻止所有語音輸出。

請依照調整防護機制保留現有檢查，並將持續語音輸出的情況納入考量。

讓鍵入的文字輸入繼續連接至現有後端。將鍵入的修正視為同一任務的更新，並將已驗證的相關上下文傳送至語音工作階段。請參閱接受鍵入的文字輸入與確保更新準確且實用。