deepgram-python-conversational-stt

使用 Deepgram 对话式 STT / Flux（Python SDK）

在 /v2/listen 上进行感知轮次的流式 STT — 针对对话音频进行了优化（轮次结束检测、提前 EOT、抢话场景）。

何时使用此产品

• 你正在构建对话式 UI，需要明确的轮次边界。
• 你想使用 Flux 模型（针对人与人或人与 Agent 的对话进行了优化）。
• 与 v1 utterance_end 相比，你希望获得延迟更低的轮次信号。

以下情况请使用其他技能：

• 你需要通用转录（字幕、批处理、非对话场景）→ deepgram-python-speech-to-text。
• 你需要完整的交互式 Agent（STT + LLM + TTS）→ deepgram-python-voice-agent。
• 你需要分析（摘要/情感分析）→ deepgram-python-audio-intelligence。

身份验证

import os
from dotenv import load_dotenv
load_dotenv()

from deepgram import DeepgramClient
client = DeepgramClient(api_key=os.environ["DEEPGRAM_API_KEY"])

标头：Authorization: Token <api_key>。仅支持 WSS — v2 没有 REST 路径。

快速入门

import threading, time
from pathlib import Path
from deepgram.core.events import EventType
from deepgram.listen.v2.types import (
    ListenV2CloseStream,
    ListenV2Connected,
    ListenV2FatalError,
    ListenV2TurnInfo,
)

with client.listen.v2.connect(
    model="flux-general-en",
    encoding="linear16",
    sample_rate="16000",
) as conn:

    def on_message(m):
        if isinstance(m, ListenV2TurnInfo):
            print(f"turn {m.turn_index} [{m.event}] {m.transcript}")
        elif isinstance(m, dict):                     # untyped fallback
            if m.get("type") == "TurnInfo":
                print(f"turn {m.get('turn_index')} [{m.get('event')}] {m.get('transcript')}")
        else:
            print(f"event: {getattr(m, 'type', type(m).__name__)}")

    conn.on(EventType.OPEN,    lambda _: print("open"))
    conn.on(EventType.MESSAGE, on_message)
    conn.on(EventType.CLOSE,   lambda _: print("close"))
    conn.on(EventType.ERROR,   lambda e: print(f"err: {type(e).__name__}: {e}"))

    def send_audio():
        for chunk in mic_chunks():                     # 80ms recommended
            conn.send_media(chunk)
            time.sleep(0.01)
        conn.send_close_stream(ListenV2CloseStream(type="CloseStream"))

    threading.Thread(target=send_audio, daemon=True).start()
    conn.start_listening()

关键参数

参数	说明
model	flux-general-en（英语）或 flux-general-multi（多语言）— 必填，必须是 Flux 模型
encoding	linear16、mulaw 等。对于容器化音频可省略
sample_rate	SDK 签名中的字符串，例如 "16000"
eager_eot_threshold	在达到此置信度时提前触发轮次结束
eot_threshold	主要的轮次结束置信度；设置为 "1.0" 可禁止基于置信度的结束
eot_timeout_ms	基于时间的轮次结束回退；即使 eot_threshold="1.0"，此设置仍然生效
keyterm	用于提升领域关键词识别效果
mip_opt_out, tag	元数据 / 隐私标记
language_hint	仅适用于 flux-general-multi
authorization, request_options	覆盖身份验证或请求选项

v2 没有 language 参数 — 语言由模型决定（flux-general-en），或通过多语言模型的 language_hint 指定。

对于由应用程序控制的轮次，请使用 eot_threshold="1.0"，并设置足够大的 eot_timeout_ms，然后调用 conn.send_force_end_turn() 来结束当前轮次。ForceEndTurn 需要启用部署支持；请参阅 examples/16-transcription-force-end-turn.py。

事件（服务端 → 客户端）

• ListenV2Connected — 已建立连接
• ListenV2ConfigureSuccess / ListenV2ConfigureFailure — 会话中配置变更
• ListenV2TurnInfo — 每轮转录文本 + 事件（Update、EndOfTurn、EagerEndOfTurn 等）+ turn_index
• ListenV2FatalError — 致命错误

客户端消息：ListenV2Media、ListenV2Configure、ListenV2ForceEndTurn、ListenV2CloseStream。

异步版本

from deepgram import AsyncDeepgramClient
client = AsyncDeepgramClient()

async with client.listen.v2.connect(model="flux-general-en", ...) as conn:
    # same .on(...) handlers, then:
    await conn.start_listening()

API 参考（分层）

1. 仓库内参考文档：reference.md — “Listen V2 Connect”。
2. AsyncAPI（WSS）：https://developers.deepgram.com/asyncapi.yaml
3. Context7：库 ID /llmstxt/developers_deepgram_llms_txt。
4. 产品文档：
   • https://developers.deepgram.com/reference/speech-to-text/listen-flux
   • https://developers.deepgram.com/docs/flux/quickstart
   • https://developers.deepgram.com/docs/flux/language-prompting

注意事项

1. 使用 /v2/listen，而非 /v1/listen。 路由不同，客户端路径也不同（listen.v2 与 listen.v1）。
2. 仅支持 Flux 模型。 nova-3、base 等模型会被拒绝。请使用 flux-general-en 或 flux-general-multi。
3. 没有 language 参数。 语言由模型选择决定。对于 flux-general-multi，请使用 language_hint。
4. SDK 中的 sample_rate 是字符串（例如 "16000"）。
5. 每次发送约 80ms 的音频块，以获得最佳的轮次检测延迟。
6. 使用 send_close_stream(ListenV2CloseStream(type="CloseStream")) 关闭流，不要使用 send_finalize（这是 v1 的做法）。
7. 收到的消息可能是类型化对象，也可能是原始 dict——SDK 使用带有 construct_type 的标记联合处理未知消息。请处理这两种情况（参见 .fernignore 中的 socket_client.py 补丁）。
8. socket_client.py 已修补并冻结（参见 .fernignore → src/deepgram/listen/v2/socket_client.py）。重新生成时不要覆盖此手动补丁；除非重新生成工作流另有说明，否则请将其他 listen/v2 文件视为生成文件。
9. 对于容器化音频（WAV、OGG 等），省略 encoding/sample_rate——服务器会从容器中检测这些参数。

此仓库中的示例文件

• examples/14-transcription-live-websocket-v2.py
• tests/manual/listen/v2/connect/main.py

相关技能

• deepgram-python-speech-to-text — v1 通用语音转文本（REST + WSS）
• deepgram-python-voice-agent — 完整的交互式助手

核心产品技能

如需跨语言的 Deepgram 产品知识——包括整合后的 API 参考、文档查找器、可运行的专项示例、第三方集成示例和 MCP 设置——请安装核心技能：

npx skills add deepgram/skills

此 SDK 提供符合语言惯例的代码技能；deepgram/skills 提供跨语言产品知识（参见 api、docs、recipes、examples、starters、setup-mcp）。