語音智慧體

語音智慧體讓使用者透過與你的應用程式交談來提問並完成任務。設計時的關鍵選擇，在於如何將語音與推理和工具連接起來：採用搭配獨立後端的持續對話、單一語音模型，或由你逐一控制各階段的管線。

選擇合適的架構

建構全雙工語音智慧體

GPT-Live 可以同時聆聽與說話，這項能力稱為 全雙工。即時模型負責語音互動，並將推理與工具使用委派給獨立的後端。後端執行工作時，使用者仍可繼續交談。

你可以保留現有的文字工作流程，包括其中的業務邏輯與工具，並加入 GPT-Live 作為語音介面。 委派模式 決定由誰執行後端工作，以及提供所需的對話上下文：

• 用戶端委派： 連接你自己的智慧體或工作流程，使用你選擇的後端模型與供應商。由你的應用程式執行工作，並將結果傳回 GPT-Live。
• Responses 委派： 選擇由 OpenAI 託管的 Responses 模型來執行後端推理與工具使用。GPT-Live 提供對話上下文，並管理對該模型的呼叫；自訂函式仍由你的應用程式執行。

在這兩種模式下，權限與業務紀錄都由你的應用程式掌控。請在即時模型的提示詞中設定說話行為，並在後端提示詞中設定業務規則。

請先閱讀開始使用 GPT-Live。後端設定請參閱委派與工具，說話行為的設定則請參閱為語音模型撰寫提示詞。

建構語音到語音智慧體

使用 Realtime API 時，可以從 RealtimeAgent 與 RealtimeSession 著手，以瀏覽器為主要執行環境。工作階段會處理音訊對話輪次、工具、中斷與交接。完整的入門範例現已收錄於開始使用 Realtime API。

建構串接式語音工作流程

若想在語音辨識、智慧體與語音生成之間檢查或轉換文字，請採用串接式架構。你的應用程式會管理三個階段：

1. 語音轉文字
2. 智慧體工作流程本身
3. 文字轉語音

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
32import asyncio
import numpy as np

from agents import Agent, function_tool
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline


@function_tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    return f"The weather in {city} is sunny."


agent = Agent(
    name="Assistant",
    instructions="You are a helpful voice assistant.",
    model="gpt-6-astra",
    tools=[get_weather],
)


async def main() -> None:
    pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
    audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16))
    result = await pipeline.run(audio_input)
    async for event in result.stream():
        if event.type == "voice_stream_event_audio":
            print("Received audio bytes", len(event.data))


if __name__ == "__main__":
    asyncio.run(main())

若需要查看或替換每個階段，請採用此方式。例如，你可以儲存轉錄內容，在文字智慧體回覆前執行政策檢查、呼叫內部系統，然後等工作流程產生經核准的答案後才生成語音。

評估你的語音智慧體

請分別測試對話品質與任務結果。回覆聽起來自然，並不代表工具已執行，也不代表應用程式狀態已改變。

1. 選擇具代表性的情境，並明確訂定預期結果、工具呼叫與權限。
2. 儲存驗證各項結果所需的音訊、事件、工具結果與應用程式狀態。請區分評估執行本身失敗，以及評估有效執行但智慧體未能完成任務這兩種情況。
3. 重複執行情境，比較任務完成情況、聽到回覆前的延遲、中斷與不必要的靜默。比較變更前後的表現時，請保持來電者、模型組態、工具與傳輸方式一致。

針對 GPT-Live，請分別衡量以下面向：

• 任務與工具結果： 檢查意圖是否保留、委派的工作、工具引數、權限與最終應用程式狀態。驗證語音確認內容是否與實際完成的動作相符。
• 對話時序： 衡量聽到回覆的時間、不必要的靜默、同時說話的情況，以及被打斷時是否讓出發言機會，包括後端工作執行期間使用者提出更正的情況。
• 語音與語言： 測試不同口音、背景雜音、語言切換、姓名與數字等情況下的輸入辨識能力。除了辨識能力之外，也要分別評估輸出語音是否容易聽懂，以及語言選擇是否適當。
• 工作階段可靠性： 將連線失敗、音訊遺失、逾時與未完成的工作階段和任務分數分開追蹤。

依循 起步、進階、實戰 三個階段，逐步增加複雜度：

1. 起步： 使用合成語音，在受控條件下測試單輪請求。固定生成的音訊、應用程式上下文與預期結果，以便重複比較。
2. 進階： 重播具代表性的真人單輪請求錄音，測試不同人聲、麥克風、停頓與聲學條件如何影響行為。
3. 實戰： 使用獨立的模擬來電者，進行持續的多輪對話。當對話與後端工作同時進行時，測試釐清問題、需求變更、中斷與恢復的處理情況。

除了自動評分，也要搭配人工聆聽，評估發音、自然度，以及對話節奏是否合宜。

如需 GPT-Live 的評估任務執行框架，請參閱語音智慧體評估 Cookbook。

如需 Realtime 的評估任務執行框架與實作範例，請參閱 OpenAI Cookbook 中的 Realtime 評估指南。可執行的評估範例由 Cookbook 維護；本頁提供共用的測試檢查清單。

衡量延遲

為每項延遲指標定義可觀測的起始與結束事件。首次聽到回覆、開始委派、被打斷後讓出發言機會、後端完成工作， 以及任務經驗證完成所需的時間，各自衡量不同的起訖範圍。請使用同一條單調遞增的 時間軸，並報告符合納入條件的樣本群體、中位數與尾端延遲。請勿 以僅涵蓋後端的計時結果取代端對端回應時間。

比較前端模型時，請固定來電者、錄音、後端模型、提示詞、傳輸方式、音訊傳送節奏與 評分器。

針對 GPT-Live，請記錄應用程式可觀測的各階段：收到委派、 開始後端請求、取得第一個有用的結果、工具開始與結束執行、提交結果、 音訊抵達，以及用戶端播放。用戶端委派讓你的應用程式 直接觀測其後端請求；Responses 委派則會提供巢狀 回應事件，以及應用程式所執行自訂工具的相關資訊。

利用各階段的時間間隔，找出連線建立、模型處理、工具、 應用程式緩衝與播放過程中的延遲。請將第一個有用的語音答案 與「我正在查詢」這類回應確認分開衡量。較早 給出回應確認，並不代表使用者要求的結果也更早送達。

每次只變更一個因素，並重複執行相同情境。比較收到有用語音回覆所需時間的中位數與 尾端延遲，同時比較任務成功情況、工具執行的正確性 與中斷情況。實作指引請參閱降低後端延遲 。

語音智慧體仍使用相同的智慧體核心構成要素

語音介面改變了傳輸方式與音訊處理迴圈，但核心工作流程的設計決策仍相同：

• 語音智慧體需要外部能力時，請參閱使用工具。
• 語音工作流程需要串流、接續執行或持久保存狀態時，請參閱執行智慧體。
• 語音工作流程需要分流至不同專業智慧體時，請參閱編排與交接。
• 語音工作流程需要安全檢查或核准時，請參閱防護機制與人工審查。
• 需要透過 MCP 提供的能力，或想檢視語音工作流程的執行行為時，請參閱整合與可觀測性。

實務原則是：先選擇音訊架構，再以設計文字智慧體的方式，設計智慧體工作流程的其餘部分。

後續步驟