迁移到 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，并对输出音频的播放应用您的应用策略。

将真人或机器的分类判断与是否可以开始录音的判断分开。识别出语音信箱，并不能证明问候语和提示音已经结束，也不能证明可以开始录音。分类器结果或上下文确认也不代表已获准播放音频。请参考调整护栏和播放控制，在您的应用所控制的音频路径中强制执行播放许可决策。

测试以下情形：一句简短的“您好”随后变成语音信箱问候语、来电筛选提示，以及语音信箱播放过程中有人接听。如果您在通话结束前停止检测器，还应测试检测器停止后才有人接听的情况。根据这些测试和检测器增加的成本，选择何时停止检测器。仅凭首次判定为真人，并不能确定后续检测已无必要。

调整连接和音频生命周期

用 GPT-Live 连接流程替换 Realtime 会话设置流程。重新检查所用传输方式的启动流程和音频格式。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 的实现。使用 Responses 函数模式，将其定义从 Realtime 的 session.tools 或 response.tools 移至 delegation.responses.tools。将工具选择设置移至 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 提供语音界面，并将任务工作委派给您现有的智能体。对于链式流水线，它会替代独立的语音转文本和文本转语音阶段。后端中仍适用于任务的模型、指令、工具、工作流程和持久化状态均予以保留。

连接现有智能体

在设置会话时，将 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 可以在后端工作仍在进行时说话，因此暂不返回工具结果或暂不让后端继续执行，并不能暂停所有语音。

请按照调整护栏中的指导，保留现有检查，并应对持续的语音输出。

继续将键入的输入连接到现有后端。将键入的更正视为对同一任务的更新，并向语音会话发送经过验证的相关上下文。请参阅接受键入的输入和确保更新准确且有用。