跳到正文
openrouter blog(openrouter.ai)·· 13 天前精選品質評分71

OpenRouter 教學:如何用 Python 建置語音 AI 助理

How to Build a Voice AI Agent

重點導讀

OpenRouter 示範如何用 Python 建置餐廳訂位語音AI 助理,串接語音轉文字、LLM 工具呼叫與文字轉語音,並逐句產生語音回覆。

AI 伴隨問答

自備 Key 深度分析

針對這篇報導有疑問?可直接點選快捷問題或向 AI 追問背景脈絡與技術細節:

推薦理由

文章以餐廳訂位流程示範語音AI 助理的建置,並比較延遲、成本與轉錄表現,呈現串接工具時的實作取捨。

正文 · 中文翻譯

語音代理必須做到的不只是產生好的回答。它還必須理解對方說了什麼、判斷該怎麼做、呼叫所需工具,並在停頓變得尷尬之前再次開口。

在這篇教學中,我們會用 Python 建立完整流程。我們的範例是一個餐廳訂位代理,能轉錄來電者的語音、使用工具查詢座位空位,並將回覆轉成語音。語音轉文字、LLM 和文字轉語音都透過同一個 OpenRouter API 金鑰執行;我們會將每個已完成的句子串流送至 TTS,而不是等整段回覆全部產生完畢。

在三段測試對話的全部 12 個回合中,伺服器端首次產生音訊的整體中位數為 1.9 秒;以我們 10 月 8 日測試時的促銷價格計算,一段四回合的對話每分鐘處理語音約需 $0.013。

重點整理

  • 文字轉語音約佔測得模型成本的 90%,因此語音回覆長度是這個代理的重要成本因素。

  • 在我們的測試中,伺服器端首次產生音訊的估計時間,純文字回合為 1.4 秒,使用工具的回合為 2.4 秒;每回合計算一次 LLM 請求。範例程式碼會額外發出 LLM 請求,而網路傳輸與音訊播放也會增加等待時間。

  • 姓名比電話號碼更難轉錄。採取行動前,請先讓來電者確認重要資訊。

  • 將已完成的句子送至文字轉語音(TTS)可以縮短等待語音輸出的時間,但即時播放與處理插話還需要額外的流程協調。

語音 AI 代理如何處理一個回合

語音代理會接收來電者的語音、將其轉成文字、交由 LLM 判斷該如何處理,再將回覆轉成語音。流程如下:

Diagram of one voice AI agent turn: caller audio goes to speech-to-text, then the LLM, a sentence splitter, text-to-speech and agent audio. The LLM can call the booking tools check_availability and book_table and continue with the tool result.

例如,當有人打電話到我們的餐廳訂位時,LLM 可能需要先呼叫 check_availability,再作出回覆。你的應用程式會執行這個函式,將可預訂時段傳回模型,並等待模型產生回覆。這趟額外的往返會增加來電者的等待時間。

為了縮短等待時間,我們可以在 LLM 尚未產生完整回覆前,就開始生成語音。我們不會等整段文字完成,而是串流接收回覆、切分成句子,並在模型繼續生成後續內容時,將每個已完成的句子送至 TTS。

在這個實作中,我們會使用語音轉文字 API轉錄來電者的語音、使用支援工具呼叫的 Chat Completions處理對話與訂位,並使用文字轉語音 API產生語音回覆。

轉錄 API 會以 JSON 傳迴文字,語音 API 則會傳迴音訊位元組。我們的 Python 範例會將產生的音訊儲存為 WAV 檔案,稍後再使用 LiveKit 處理即時音訊與插話。

用 Python 建立語音代理

我們來用三個模型建立餐廳訂位代理:elevenlabs/scribe-v2 負責轉錄,openai/gpt-6-luna 負責對話與工具呼叫,elevenlabs/eleven-flash-v2.5 負責語音生成。

你需要 Python 3.10 或更新版本,以及一組 OpenRouter API 金鑰。請安裝 requests 程式庫,並將 API 金鑰設為環境變數:

python -m pip install requests
export OPENROUTER_API_KEY="your-api-key"

為了讓範例容易重現,我們會使用第二個 TTS 語音模擬四個來電者回合,而不連線麥克風。我們也會使用模擬訂位資料,讓代理能查詢空位並提供訂位詳情,而不必連線真實的訂位系統。

將以下程式碼儲存為 voice_agent.py:

import base64
import io
import json
import os
import re
import wave
from concurrent.futures import ThreadPoolExecutor
from datetime import date

import requests

API = "https://openrouter.ai/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"}

STT = "elevenlabs/scribe-v2"
LLM = "openai/gpt-6-luna"
TTS = "elevenlabs/eleven-flash-v2.5"
PCM_RATE = 24000

def system_prompt():
    today = date.today()  # read per call, so a long-running agent stays on the right day
    return (
        "You are the phone receptionist for Luigi's restaurant. "
        f"Today is {today:%A, %B} {today.day}, {today.year}. Keep answers short and spoken: "
        "no markdown, and say times in words. Check availability before "
        "offering a table. Only book after the caller agrees and provides a name. "
        "Do not claim to send confirmation texts."
    )

def tool(name, description, properties):
    return {
        "type": "function",
        "function": {
            "name": name,
            "description": description,
            "parameters": {
                "type": "object",
                "properties": properties,
                "required": list(properties),
            },
        },
    }

DATE = {"type": "string", "description": "YYYY-MM-DD"}
TIME = {"type": "string", "description": "HH:MM, 24-hour"}
PARTY = {"type": "integer", "minimum": 1}

TOOLS = [
    tool(
        "check_availability",
        "Find open tables near the requested time",
        {"date": DATE, "time": TIME, "party_size": PARTY},
    ),
    tool(
        "book_table",
        "Book only after the caller accepts a time and gives a name",
        {
            "date": DATE,
            "time": TIME,
            "party_size": PARTY,
            "name": {"type": "string"},
        },
    ),
]

def run_tool(name, args):
    # Mock booking service; replace with a real reservation backend.
    if name == "check_availability":
        return {
            "open_times": (
                ["17:45", "20:15"]
                if args["party_size"] >= 5
                else [args["time"]]
            )
        }

    if name == "book_table":
        allowed = (
            ["17:45", "20:15"]
            if args["party_size"] >= 5
            else [args["time"]]
        )
        return (
            {"booked": True, "reference": "XJ47Q"}
            if args["time"] in allowed
            else {"booked": False, "error": "Time unavailable"}
        )

    return {"error": f"Unknown tool: {name}"}

def to_wav(pcm, rate):
    if len(pcm) % 2:
        raise ValueError("PCM audio must contain whole 16-bit samples")
    output = io.BytesIO()
    with wave.open(output, "wb") as wav:
        wav.setnchannels(1)
        wav.setsampwidth(2)
        wav.setframerate(rate)
        wav.writeframes(pcm)
    return output.getvalue()

def speak(text, voice="sarah"):
    if not text.strip():
        return b"", PCM_RATE

    with requests.post(
        f"{API}/audio/speech",
        headers=AUTH,
        stream=True,
        timeout=60,
        json={
            "model": TTS,
            "input": text,
            "voice": voice,
            "response_format": "pcm",
            "provider": {
                "options": {
                    "elevenlabs": {"output_format": "pcm_24000"}
                }
            },
        },
    ) as response:
        response.raise_for_status()
        if not response.headers.get("Content-Type", "").startswith("audio/pcm"):
            raise ValueError("Expected raw PCM audio from TTS")
        pcm = b"".join(response.iter_content(4096))
        if not pcm:
            raise ValueError("TTS returned no audio")
        return pcm, PCM_RATE

def transcribe(wav):
    response = requests.post(
        f"{API}/audio/transcriptions",
        headers=AUTH,
        timeout=60,
        json={
            "model": STT,
            "language": "en",
            "input_audio": {
                "data": base64.b64encode(wav).decode("ascii"),
                "format": "wav",
            },
        },
    )
    response.raise_for_status()
    return response.json()["text"].strip()

def choose_tool_calls(messages):
    # Resolve possible tools before starting any paid TTS requests.
    response = requests.post(
        f"{API}/chat/completions",
        headers=AUTH,
        timeout=60,
        json={
            "model": LLM,
            "messages": messages,
            "tools": TOOLS,
            "tool_choice": "auto",
            "reasoning": {"effort": "none"},
            "max_tokens": 300,
        },
    )
    response.raise_for_status()
    message = response.json()["choices"][0]["message"]
    return message.get("tool_calls") or []

def stream_reply(messages):
    # This request has no tools, so sentences can safely go to TTS.
    pending, finish = "", None
    with requests.post(
        f"{API}/chat/completions",
        headers=AUTH,
        stream=True,
        timeout=60,
        json={
            "model": LLM,
            "messages": messages,
            "reasoning": {"effort": "none"},
            "max_tokens": 300,
            "stream": True,
        },
    ) as response:
        response.raise_for_status()
        response.encoding = "utf-8"

        for line in response.iter_lines(decode_unicode=True):
            if not line or not line.startswith("data: {"):
                continue

            chunk = json.loads(line[6:])
            if chunk.get("error"):  # a provider error mid-stream, after some text may have arrived
                raise RuntimeError(f"stream error: {chunk['error']}")
            choices = chunk.get("choices")
            if not choices:
                continue

            finish = choices[0].get("finish_reason") or finish
            pending += (choices[0].get("delta") or {}).get("content") or ""
            # Wait for whitespace; a buffer ending in "3." may still become "3.14".
            while match := re.search(r"[.!?]\s", pending):
                sentence = pending[:match.end()].strip()
                if sentence:
                    yield sentence
                pending = pending[match.end():]

    if finish == "length":  # hit max_tokens, so don't speak the clipped tail or save the reply as a full answer
        raise RuntimeError("reply cut off at max_tokens")
    if pending.strip():
        yield pending.strip()

def run_turn(caller_wav, messages):
    heard = transcribe(caller_wav)
    messages.append({"role": "user", "content": heard})

    # Tool selection can repeat when the model needs several tool results.
    for _ in range(4):
        calls = choose_tool_calls(messages)
        if not calls:
            break

        messages.append({"role": "assistant", "content": None, "tool_calls": calls})
        for call in calls:
            try:
                args = json.loads(call["function"]["arguments"])
                result = run_tool(call["function"]["name"], args)
            except (ValueError, TypeError, KeyError) as exc:
                result = {"error": str(exc)}
            messages.append({
                "role": "tool",
                "tool_call_id": call["id"],
                "content": json.dumps(result),
            })
    else:
        raise RuntimeError("Too many tool calls")

    sentences, jobs = [], []
    with ThreadPoolExecutor(max_workers=3) as pool:
        for sentence in stream_reply(messages):
            sentences.append(sentence)
            jobs.append(pool.submit(speak, sentence))
        audio = [job.result() for job in jobs]

    if not sentences:
        raise RuntimeError("LLM returned no spoken response")

    rates = {rate for _, rate in audio}
    if rates != {PCM_RATE}:
        raise ValueError("Inconsistent TTS sample rates")

    spoken = " ".join(sentences)
    messages.append({"role": "assistant", "content": spoken})
    pcm = b"".join(chunk for chunk, _ in audio)
    return heard, spoken, to_wav(pcm, PCM_RATE)

if __name__ == "__main__":
    caller_lines = [
        "Hi, do you have a table for six this Saturday at seven thirty?",
        "Eight fifteen works. The name is Siobhan Okafor.",
        "Can you text the confirmation to four one five, "
        "five five five, zero one eight two?",
        "No, that's everything. Thanks, bye.",
    ]

    messages = [{"role": "system", "content": system_prompt()}]
    for turn, line in enumerate(caller_lines, 1):
        pcm, rate = speak(line, voice="george")
        heard, said, reply = run_turn(to_wav(pcm, rate), messages)
        with open(f"agent_{turn}.wav", "wb") as file:
            file.write(reply)
        print(f"caller: {heard}\nagent:  {said}\n")

這個指令碼透過 run_turn() 串接三個 API。它會轉錄每位來電者的訊息、將逐字稿傳給 LLM,並處理回應。如果 LLM 要求使用工具,函式就會執行該工具、將結果加入對話記錄,再發出另一個請求,讓模型繼續處理。

看看 stream_reply() 如何處理工具呼叫。模型會分段串流傳送函式名稱和引數,因此我們會先將它們組合起來,再執行工具。對於語音回覆,我們會透過執行緒集區將完整句子傳送給 TTS,讓語音生成作業能與剩餘的 LLM 輸出同步進行。

接著,我們會依句子順序合併音訊,並將它儲存為 WAV 檔案。等介紹 LiveKit 時,我們再處理實際播放和中斷。

你可以使用這個指令執行指令碼:

python voice_agent.py

它應該會建立四個音訊檔案,從 agent_1.wav 到 agent_4.wav,並輸出對話內容。以下是其中一次測試執行的節錄。來電者的訊息顯示的是轉錄後的音訊,因此數字可能與實際說出的內容不同。

caller: Hi, do you have a table for six this Saturday at 7:30?

agent:  We don't have seven-thirty available for six,
        but I can offer five forty-five or eight fifteen.
        Would either work for you?

caller: 815 works. The name is Siobhan Okafor

agent:  You're booked for six at eight fifteen this
        Saturday under Siobhan Okafor.
        Your reference is XJ47Q.

caller: Can you text the confirmation to 415-555-0182?

agent:  I can't send texts from here, but your
        reservation is confirmed under Siobhan Okafor
        for six at eight fifteen this Saturday,
        reference XJ47Q.

這個範例顯示,代理程式會先確認是否有空位,再提供其他時間;來電者接受後,代理程式便呼叫 book_table。由於我們尚未提供傳送簡訊的工具,因此它也不會承諾傳送簡訊確認。

這種設計為何有效,以及哪些情況會讓它失效

在聊天視窗中看起來完全沒問題的回覆,唸出來時可能會很奇怪。時間、電話號碼和 Markdown 都是很好的例子。因此,我們在系統提示中要求 LLM 保持回覆簡短、避免格式化,並以口語文字寫出時間,例如用「eight fifteen」取代 8:15。

反過來也可能發生同樣的問題。在我們的測試中,語音轉文字將「eight fifteen」轉成 815,但 LLM 依據先前的對話內容,正確理解了來電者的回覆。我們會將對話記錄儲存在 messages 中,並隨每次請求一併傳送,因為 Chat Completions 不會自動保留先前的對話輪次。因此,提示詞長度從第一輪約 290 個 token 增加到第四輪約 490 個 token。

另一項重要考量是確保代理程式只確認實際完成的操作。在先前尚未加入 book_table 的版本中,即使應用程式根本沒有建立預約,代理程式仍可能告訴來電者預約已確認。

因此,預約工具不能只回傳一則回應。連線到實際的預約系統時,它應該確認是否有空位、儲存預約,並且只在操作成功時回傳確認訊息。

語音 AI 代理程式有多快?

在全部 12 輪對話中,伺服器端首次產生音訊的中位時間為 1.9 秒。依對話輪次型別來看,不使用工具時的中位時間為 1.4 秒,代理程式需要呼叫工具時則為 2.4 秒。

我們測量了三段完整對話,共 12 輪,並使用我們的 生成中繼資料估算各階段的伺服器端延遲。如此一來,我們便能將模型處理時間與測試環境中的額外網路延遲區分開來。

以下是各項結果的比較:

階段使用工具呼叫不使用工具
語音轉文字(Scribe v2)549 ms391 ms
LLM 選擇工具736 ms—
LLM 回答,第一個 token685 ms706 ms
文字轉語音,第一個位元組262 ms208 ms
預估首次音訊所需時間2.4 s1.4 s

多出的 LLM 請求是造成大部分差異的原因。代理程式需要確認是否有空位時,必須等工具傳回結果後才能產生回答。

這些資料反映的是伺服器端處理時間,而非呼叫者實際經歷的完整時間。網路傳輸、偵測呼叫者何時說完,以及播放音訊都會增加延遲。各個階段的延遲中位數加總後,也不一定等於整體延遲中位數。這些估算也以每一輪對話呼叫一次 LLM 為前提。下方範例程式碼每一輪會呼叫兩次:先以非串流方式確認是否有工具呼叫,再以串流方式產生回覆;若該輪需要呼叫工具,工具執行後還會再呼叫一次,因此實際耗時預期會比這些資料更長。

下方的模型比較採用不同的測試執行和輸入內容,因此回報的延遲與此處顯示的完整對話測量結果不同。

語音 AI 代理程式的成本是多少?

在五次測試中,我們與餐廳進行的四輪對話成本介於 $0.0069 到 $0.0087 之間。每通電話約有 38 秒語音;以 2026 年 10 月 8 日的價格計算,每分鐘處理語音的估計成本為 $0.013。

大部分成本來自產生代理程式的語音。

階段佔總成本比例測試期間價格
文字轉語音(Eleven Flash v2.5)90%每百萬個字元 $20
語音轉文字(Scribe v2)6%每小時音訊 $0.11
LLM(GPT-6 Luna)4%每百萬個輸入/輸出 token 分別為 $0.10/$0.50

上述 ElevenLabs 價格包含 50% 的上市折扣,該折扣於 2026 年 10 月 19 日結束。依照標準牌價,Eleven Flash v2.5 每百萬個字元 $40,而 Scribe v2 每小時音訊約 $0.22。假設用量相同,我們的對話每分鐘處理語音成本約為 $0.025。這是根據 2026 年 10 月 8 日測量結果所做的計算,並非另一項帳單測試。

這份成本明細仍然很有參考價值。在這段對話中,TTS 約佔我們支出的 90%,因此縮短代理程式的口語回覆,比小幅減少 LLM token 用量更能降低成本。

你也可以追蹤個別請求的實際成本。轉錄回應會包含 usage.cost,而語音回應會提供 X-Generation-Id 標頭,你可以使用它透過我們的 生成中繼資料 API 查詢成本。

應該使用哪種語音轉文字模型?

對餐廳訂位代理程式來說,當來電者提到代理程式需要採取行動的細節時,轉錄準確度最為重要,例如姓名、日期、電話號碼和訂位時間。

為了比較模型,我們使用三種合成語音產生九句來電者臺詞,再為每段錄音製作清晰版和電話音質版。總共得到 54 段音訊片段,測試中每個模型評分 90 項事實。

我們評估了十種 STT 模型。下表列出五種模型,呈現我們觀察到的準確度和延遲範圍。

模型保留的事實(共 90 項)伺服器延遲中位數測試日期的每小時成本
microsoft/mai-transcribe-2891,740 毫秒$0.11
elevenlabs/scribe-v288379 毫秒$0.11
openai/whisper-large-v388517 毫秒$0.17
x-ai/grok-stt-1.086264 毫秒$0.10
deepgram/nova-38383 毫秒$0.26

MAI-Transcribe 2 保留的事實最多,但 Scribe v2 的速度快得多,而且只少保留一項事實。Whisper Large V3 的分數與 Scribe 相同,但回應時間較長。對我們的預約代理而言,Scribe v2 在準確度與速度之間取得良好平衡,因此我們在 Python 實作中選用它。

即使正確保留了電話號碼,所有辨識器仍會弄錯少見的人名。例如,「Siobhan Okafor」在逐字稿中被寫成「Shioban Okafor」、「Siobhan O’Keefe」和「Siobhan Akhefer」。

不要假設轉錄出來的人名正確;請讓代理向來電者確認,或請對方拼出姓名,再完成預約。

請記住,這些結果來自合成的英文錄音,並非不同口音與環境下的實際客戶通話。你可以探索可用的轉錄模型,但建議使用能反映自身使用情境的音訊測試入選模型。

應該使用哪種 LLM 和文字轉語音模型?

在評估 LLM 時,我們考量了工具呼叫準確度、回應時間,以及產生的文字是否適合自然朗讀。

我們比較的每個 LLM 在五次測試中都呼叫了預期的預約工具。差異主要在回應速度和答案格式。

模型將時間寫成數字首次回答 token 所需時間(中位數)每回合成本
DeepSeek V4.1 Flash0/51.9 s(不使用推理時為 1.4 s)$0.00017
GPT-6 Luna0/52.3 s(不使用推理時為 1.6 s)$0.00008
Claude Haiku 5.55/52.6 s$0.00026
Gemini 3.8 Flash0/54.0 s$0.00129
MiMo V2.6 Flash2/56.4 s$0.00006

其中一項差異在於模型如何處理口語時間。Claude Haiku 5.5 在每次測試中都寫成 7:30,而非指定的口語形式;其中一種設定還在可見回應中附上日期計算結果。如果回應會直接送交 TTS,這兩種行為都值得留意。

這些結果來自另一組模型比較,每個模型測試五次,並非上述完整對話測量結果。測量的是在測試模型設定下,首次產生回答 token 所需的時間。

推理功能也會影響延遲。在我們對 GPT-6 Luna 的比較中,停用推理後,在測試的工具呼叫回閤中,首次產生回答 token 的時間從 2.3 秒降至 1.6 秒。對於相對單純的預約任務,這很有幫助,前提是模型仍能正確呼叫工具。

選擇文字轉語音模型

在 TTS 測試中,我們著重比較各模型開始回傳音訊的速度。我們向 12 個模型傳送相同的 101 字元回應,每個模型重複測試五次。

以下列出六項具代表性的結果:

模型伺服器端回傳首位元組的中位時間測試日期的每百萬字元成本
Grok Voice TTS 1.080 ms$15
Kokoro 82M98 ms$0.62
Deepgram Aura-2236 ms$30
Eleven Flash v2.5275 ms$20 促銷價
Eleven v4 Turbo1,245 ms$20 促銷價
Gemini 3.8 Flash TTS2,561 ms無法直接比較(按 token 計價)

Gemini 採用不同的計費單位,因此我們未將其納入每字元成本比較,以免把估算換算值當成報價。

以伺服器端測量結果來看,Grok Voice 和 Kokoro 回傳第一個音訊位元組的速度最快,Eleven Flash v2.5 的表現也不錯。

不過,伺服器回報的時間不一定等同於應用程式實際體驗的時間。Kokoro 的伺服器延遲中位數低於 100 毫秒,但音訊傳到我們的測試環境卻花了三到八秒。

這就是為什麼你應該在自己的應用程式中測量延遲,尤其是在建置對話式應用程式時。只依據速度選擇模型之前,也要聽聽生成的語音並確認發音。

這個實作使用 Eleven Flash v2.5。你可以瀏覽可用的語音模型,並使用模型代稱(slug)將它替換成其他選項。

使用 LiveKit Agents 執行相同的代理程式

我們的 Python 指令碼會處理轉錄、工具呼叫和語音生成,但不支援與代理程式進行即時對話。若要做到這一點,我們還需要處理麥克風輸入、偵測來電者何時說完,以及管理中斷。

我們可以使用 LiveKit Agents 來處理這些工作。它會處理即時音訊連線和對話流程,同時讓我們繼續透過 OpenRouter 使用相同的三個模型。

首先,安裝 LiveKit Agents 和 OpenAI 外掛程式:

python -m pip install "livekit-agents[openai]~=1.8"

你也需要從 LiveKit 專案取得 LIVEKIT_URL、LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET,以及我們稍早設定的 OPENROUTER_API_KEY。如果尚未設定專案,請參閱 LiveKit 快速入門指南。

將以下內容存成 livekit_agent.py,並放在 voice_agent.py 旁邊。我們會重用上一個範例中的餐廳指示和訂位函式。

import os

from livekit import agents
from livekit.agents import (
    Agent,
    AgentServer,
    AgentSession,
    function_tool,
    inference,
)
from livekit.plugins import openai

from voice_agent import run_tool, system_prompt

API = "https://openrouter.ai/api/v1"
KEY = os.environ["OPENROUTER_API_KEY"]

class Luigis(Agent):
    def __init__(self):
        super().__init__(instructions=system_prompt())

    @function_tool
    async def check_availability(
        self, date: str, time: str, party_size: int
    ) -> dict:
        """Check available tables for a date, time, and party size."""
        return run_tool(
            "check_availability",
            {"date": date, "time": time, "party_size": party_size},
        )

    @function_tool
    async def book_table(
        self, date: str, time: str, party_size: int, name: str
    ) -> dict:
        """Book a table after the caller agrees and gives a name."""
        return run_tool(
            "book_table",
            {
                "date": date,
                "time": time,
                "party_size": party_size,
                "name": name,
            },
        )

server = AgentServer()

@server.rtc_session(agent_name="luigis")
async def luigis_session(ctx: agents.JobContext):
    session = AgentSession(
        vad=inference.VAD(model="silero"),
        stt=openai.STT(
            model="elevenlabs/scribe-v2",
            base_url=API,
            api_key=KEY,
        ),
        llm=openai.LLM.with_openrouter(
            model="openai/gpt-6-luna",
            api_key=KEY,
            reasoning_effort="none",
        ),
        tts=openai.TTS(
            model="elevenlabs/eleven-flash-v2.5",
            voice="sarah",
            response_format="pcm",
            base_url=API,
            api_key=KEY,
        ),
    )

    await session.start(room=ctx.room, agent=Luigis())

if __name__ == "__main__":
    agents.cli.run_app(server)

AgentSession 會連線這三個模型,而 Silero 語音活動偵測(VAD)則協助判斷來電者何時停止說話,讓 LiveKit 可以傳送音訊進行轉錄。LiveKit 也會管理語音播放和中斷。

請注意,訂位函式並未變更。LiveKit 的 @function_tool 裝飾器會讓 LLM 使用這些函式,而每個函式都會將來電者的詳細資料傳送給相同的模擬訂位服務。

你可以使用自己的麥克風在本機測試代理程式:

python livekit_agent.py console

若要將它連線到 LiveKit 專案,並透過 Agent Console 進行測試,請執行:

python livekit_agent.py dev

試著要求預訂六人座,時間是七點半,然後接受八點十五分。在先前以文字驅動的 LiveKit 測試中,產生了以下工具呼叫:

check_availability(
    date="2026-10-10",
    time="19:30",
    party_size=6
)

book_table(
    date="2026-10-10",
    time="20:15",
    party_size=6,
    name="Siobhan Okafor"
)

這項設定會將訂位工具連線到 LiveKit 音訊工作階段,讓你使用麥克風測試相同的對話。你也可以參閱我們的 LiveKit 整合指南,進一步瞭解模型備援和供應商路由。

你可能會遇到的錯誤

測試期間,我們遇到幾個因缺少引數或模型設定不受支援而造成的錯誤。三個錯誤都回傳了 HTTP 400 回應:

問題API 回應修正方式
使用 ElevenLabs TTS 模型時未指定 voice此 TTS 供應商要求明確指定 voice。指定支援的 voice,例如 sarah。
將 data:audio/wav;base64,… URI 傳送給 STT供應商無法處理音訊輸入(音訊格式不受支援或格式錯誤)。以正確的音訊格式傳送原始 base64 資料。
在必須啟用推理的情況下停用了推理此端點必須啟用推理,且無法停用。移除不受支援的推理設定。

我們的語音轉文字 API要求將音訊位元組以 base64 編碼後放在 input_audio.data,不要加上 data:audio/…;base64, 字首。你也必須指定音訊格式,例如 wav 或 mp3。

不同供應商支援的語音名稱也各不相同。例如,OpenAI 的語音(如 alloy)不會自動適用於 ElevenLabs。你可以在我們的文字轉語音檔案或 models API 中檢視各模型支援的語音。

我們遇到的另一個問題是,空白的 TTS 輸入會產生一段很短的音訊。傳送語音請求前,最好先篩除空字串。

你需要語音轉語音模型嗎?

這個範例不需要。我們建置的語音轉文字、LLM 和文字轉語音獨立流程,已足以處理餐廳訂位作業。

我們也測試了將來電者的音訊直接傳送給四種支援音訊的 LLM:Gemini 3.8 Flash、Qwen3.8 Omni Flash、MiMo V2.6 Flash 和 GPT Audio Mini。在全部 12 次測試中,它們都選擇了預期的訂位工具。

這表示在我們的範例中,這些模型可以處理工具呼叫,不必另外提出轉錄請求。不過,我們沒有測量完整的語音對語音對話,因此這些結果無法說明這種做法是否能加快速度,或產生更好的語音回覆。

採用三階段流程時,我們可以檢視轉錄文字、找出錯誤發生的位置,並分別更換轉錄、語言或語音模型。能直接處理音訊輸入與輸出的模型或許可以簡化流程,但在選擇之前,最好先比較完整回應時間、音訊品質和中斷處理能力。

結論

我們的 Python 範例只是起點。將代理程式連線到實際來電者之前,請將模擬訂位函式替換成自己的後端,並使用真實語音進行測試。只有系統提示會讓代理程式等候來電者同意後才呼叫 book_table,因此請讓後端在寫入訂位資料前先確認訂位。請測量完整回應時間,包括網路傳送和播放時間,而不要只依據伺服器端延遲。

如果需要即時音訊和中斷處理,可以使用 LiveKit,並透過 OpenRouter 繼續使用相同的模型。

常見問題

如何將語音 AI 代理程式連線到實際電話號碼?

你可以使用 LiveKit 的電話整合功能,將語音 AI 代理程式連線到電話號碼。LiveKit 支援透過其電話號碼服務或 SIP 供應商接聽來電。設定必要的中繼線和派送規則,將來電轉送至 LiveKit 房間,讓代理程式加入對話。設定步驟請參閱 LiveKit 電話整合檔案。

語音 AI 代理程式能處理中斷嗎?

可以。LiveKit 之類的框架可以偵測有人在代理程式回覆時開始說話,暫停代理程式的語音,並根據新的輸入繼續對話。

請注意,中斷語音不會自動取消已在執行的工具。對於訂位或付款等操作,應由應用程式妥善處理取消和確認。

我可以在 AI 語音代理程式中使用自己的聲音嗎?

可以,只要選擇支援聲音複製的文字轉語音模型即可。OpenRouter 上有些模型接受透過 input_references 引數傳入的參考音訊,並使用該聲音產生語音,不需要另外進行聲音訓練。

各模型和供應商端點對聲音複製的支援程度不一,選擇模型前請檢視 TTS 檔案。只能使用你有權複製的錄音。

我可以將語音代理程式連線到實際訂位系統或其他 API 嗎?

可以。我們範例中的 check_availability 和 book_table 函式使用模擬資料,你可以將其實作替換為向訂位 API 或資料庫傳送請求。

LLM 仍會決定何時呼叫各個函式,而你的應用程式會執行實際操作並傳回結果。對於預訂餐桌或傳送確認訊息等操作,請先確認操作成功,再告知呼叫者已完成。

來源: openrouter blog (openrouter.ai)
開啟原文

讀者討論

理性交流 · 即時討論