deepgram-python-audio-intelligence

使用 Deepgram Audio Intelligence（Python SDK）

应用于 /v1/listen 转录的分析叠加功能：摘要、主题、意图、情感、语言检测、说话人分离、脱敏、实体识别。使用同一端点和同一客户端方法进行 STT——通过参数启用功能。

何时使用此产品

• 你有音频（文件、URL 或实时流），并希望在获取转录文本的同时进行分析。
• REST 是主要使用方式——大多数分析功能仅支持 REST。

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

• 你只需要纯转录文本，不需要分析 → deepgram-python-speech-to-text。
• 输入已经是转录文本 → deepgram-python-text-intelligence（/v1/read）。
• 你需要对话轮次管理 → deepgram-python-conversational-stt。
• 你需要完整的交互式 Agent → deepgram-python-voice-agent。

功能支持情况：REST 与 WSS

功能	REST	WSS
diarize	是	是
redact	是	是
punctuate、smart_format	是	是
实体检测	是	是
summarize	是	否
topics	是	否
intents	是	否
sentiment	是	否
detect_language	是	否
custom_topic / custom_intent	是	否

对于仅支持 WSS 的功能子集，代码路径与 deepgram-python-speech-to-text 相同。

身份验证

from dotenv import load_dotenv
load_dotenv()

from deepgram import DeepgramClient
client = DeepgramClient()

请求头：Authorization: Token <api_key>。

快速开始 — 使用 REST 进行完整分析

response = client.listen.v1.media.transcribe_url(
    url="https://dpgr.am/spacewalk.wav",
    model="nova-3",
    smart_format=True,
    punctuate=True,
    diarize=True,              # speaker separation
    summarize="v2",            # "v2" for the current model; True also accepted on /v1/listen
    topics=True,
    intents=True,
    sentiment=True,
    detect_language=True,
    redact=["pci", "pii"],     # or Sequence[str]
    language="en-US",
)

r = response.results
print("transcript:", r.channels[0].alternatives[0].transcript)
print("summary:",    r.summary)
print("topics:",     r.topics)
print("intents:",    r.intents)
print("sentiments:", r.sentiments)
print("detected_language:", r.channels[0].detected_language)

# Speaker diarization
for word in r.channels[0].alternatives[0].words or []:
    speaker = getattr(word, "speaker", None)
    if speaker is not None:
        print(f"Speaker {speaker}: {word.word}")

快速开始 — REST 文件

with open("call.wav", "rb") as f:
    audio = f.read()

response = client.listen.v1.media.transcribe_file(
    request=audio,
    model="nova-3",
    diarize=True,
    redact=["pii"],
    summarize="v2",
    topics=True,
)

快速开始 — 带词级时间戳的说话人分离

在一次请求中启用说话人分离和词级时间戳，然后遍历逐词对象，构建带时间信息的说话人标注转录文本。

response = client.listen.v1.media.transcribe_url(
    url="https://dpgr.am/spacewalk.wav",
    model="nova-3",
    diarize=True,        # tag each word with a speaker id
    smart_format=True,   # punctuated_word for cleaner output
    punctuate=True,
)

words = response.results.channels[0].alternatives[0].words or []

# Per-word: speaker, timestamps, confidence
for w in words:
    speaker = getattr(w, "speaker", None)
    text = w.punctuated_word or w.word
    print(f"[speaker {speaker}] {text}  ({w.start:.2f}s–{w.end:.2f}s, conf={w.confidence:.2f})")

# Group consecutive words by speaker into utterances
from itertools import groupby
for speaker, group in groupby(words, key=lambda w: getattr(w, "speaker", None)):
    text = " ".join((w.punctuated_word or w.word) for w in group)
    print(f"Speaker {speaker}: {text}")

每个条目提供以下逐词字段：

字段	类型	描述
word	str	小写词元
punctuated_word	str | None	带有智能格式化大小写和标点的词元（当 smart_format=True 时）
start、end	float	音频时间戳，单位为秒
confidence	float	0.0–1.0 的置信度
speaker	int | None	说话人 ID（当 diarize=True 时）；禁用说话人分离时为 None
speaker_confidence	float | None	说话人 ID 的置信度

如需更高层级的细分，请设置 utterances=True，以在 response.results.utterances 获取预先分组的说话人轮次。设置 paragraphs=True 可获取按说话人轮次边界组织的 paragraphs 视图。

快速开始 — WSS 子集（仅说话人分离 / 脱敏 / 实体识别）

import threading
from deepgram.core.events import EventType

with client.listen.v1.connect(model="nova-3", diarize=True, redact=["pii"]) as conn:
    conn.on(EventType.MESSAGE, lambda m: print(m))
    threading.Thread(target=conn.start_listening, daemon=True).start()
    for chunk in audio_chunks:
        conn.send_media(chunk)
    conn.send_finalize()

关键参数

summarize、topics、intents、sentiment、detect_language、diarize、redact、custom_topic、custom_topic_mode、custom_intent、custom_intent_mode、detect_entities，以及所有标准 STT 参数（model、language、encoding、sample_rate 等）。

当前生成的 SDK 中，redact 的类型为 Optional[str]（src/deepgram/listen/v1/media/client.py）。传入一种脱敏模式即可，例如 "pci"、"pii"、"numbers" 或 "phi"。传输层支持通过重复查询参数发送多个脱敏模式——请查看 src/deepgram/types/listen_v1redact.py 了解当前类型；如果需要多种模式，请改用原始查询参数构造方式（或发起多次调用）。此前的 Union[str, Sequence[str]] 覆盖配置已不再保留于 .fernignore。

API 参考（分层）

1. 仓库内参考：reference.md — “Listen V1 Media”（REST 参数包含所有分析标志）、“Listen V1 Connect”（支持 WSS 的子集）。
2. OpenAPI（REST）：https://developers.deepgram.com/openapi.yaml
3. AsyncAPI（WSS）：https://developers.deepgram.com/asyncapi.yaml
4. Context7：库 ID /llmstxt/developers_deepgram_llms_txt。
5. 产品文档：
   • https://developers.deepgram.com/docs/stt-intelligence-feature-overview
   • https://developers.deepgram.com/docs/summarization
   • https://developers.deepgram.com/docs/topic-detection
   • https://developers.deepgram.com/docs/intent-recognition
   • https://developers.deepgram.com/docs/sentiment-analysis
   • https://developers.deepgram.com/docs/language-detection
   • https://developers.deepgram.com/docs/redaction
   • https://developers.deepgram.com/docs/diarization

注意事项

1. /v1/listen 上的 summarize 接受布尔值或字符串 "v2"。 使用 "v2" 可指定当前的摘要模型；True 也有效（映射到默认模型）。/v1/read 则相反——它只接受布尔值。如果要对已转录的文本进行摘要，请参阅 deepgram-python-text-intelligence。
2. Sentiment / topics / intents / summarize / detect_language 仅支持 REST。 不要在 WSS 上传入这些参数——它们会被忽略或拒绝。
3. Sentiment / topics / intents / summarize 仅支持英语。
4. 并非所有模型都支持所有附加功能。 Flux / Base 模型存在限制。除非有特殊原因，否则请使用 nova-3。
5. Redaction 的取值包括 pci、pii、phi、numbers 等，而不是任意字符串。
6. custom_topic / custom_intent 需要指定模式（"extended" 或 "strict"）。
7. 短音频或低质量音频的说话人分离效果不稳定。 对于时长不足 30 秒的片段，预期会出现说话人切换。

此仓库中的示例文件

• examples/15-transcription-advanced-options.py — smart_format、punctuate、diarize
• tests/wire/test_listen_v1_media.py — 覆盖智能参数的线协议测试

相关技能

• deepgram-python-speech-to-text — 相同端点，纯转录
• deepgram-python-text-intelligence — 相同分析功能，文本输入
• deepgram-python-conversational-stt — 用于轮流对话的 Flux
• deepgram-python-voice-agent — 交互式助手

中央产品技能

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

npx skills add deepgram/skills

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