开始使用 Soniox LangChain中的音频转录加载器。

设置

安装软件包：

pip install langchain-soniox

凭据

从 Soniox Console 获取您的Soniox API密钥，并将其设置为环境变量：

用法

基本转录

如何使用 SonioxDocumentLoader 转录音频文件并使用LLM生成摘要的示例。

from langchain_soniox import SonioxDocumentLoader
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

audio_file_url = "https://soniox.com/media/examples/coffee_shop.mp3"
loader = SonioxDocumentLoader(file_url=audio_file_url)

print(f"Transcribing {audio_file_url}...")
docs = loader.load()

transcript_text = docs[0].page_content
print(f"Transcript: {transcript_text}")

# Create a chain to summarize the transcript
prompt = ChatPromptTemplate.from_template(
    "Write a concise summary of the following speech:\n\n{transcript}"
)

chain = prompt | ChatOpenAI(model="gpt-5-mini") | StrOutputParser()
summary = chain.invoke({"transcript": transcript_text})
print(summary)

您也可以从本地文件或字节加载音频：

# Using a local file path
loader = SonioxDocumentLoader(file_path="/path/to/audio.mp3")

# Using binary data
with open("/path/to/audio.mp3", "rb") as f:
    audio_bytes = f.read()
loader = SonioxDocumentLoader(file_data=audio_bytes)

异步转录

对于异步操作，请使用 aload() or alazy_load():

from langchain_soniox import SonioxDocumentLoader

async def transcribe_async():
    loader = SonioxDocumentLoader(
        file_url="https://soniox.com/media/examples/coffee_shop.mp3"
    )

    docs = [doc async for doc in loader.alazy_load()]
    print(docs[0].page_content)

asyncio.run(transcribe_async())

高级用法

语言提示

Soniox会自动检测并转录 **60多种语言**中的语音。当您知道音频中可能出现哪些语言时，请提供 language_hints 以通过将识别偏向这些语言来提高准确性。

语言提示 **不会限制** 识别——它们只是 **偏向** 模型向指定语言的识别，同时仍然允许检测其他语言（如果存在）。

from langchain_soniox import (
    SonioxDocumentLoader,
    SonioxTranscriptionOptions,
)

loader = SonioxDocumentLoader(
    file_url="https://soniox.com/media/examples/coffee_shop.mp3",
    options=SonioxTranscriptionOptions(
        language_hints=["en", "es"],
    ),
)

docs = loader.load()

有关更多详细信息，请参阅 Soniox语言提示文档.

说话人分离

启用说话人识别以区分不同说话人：

from langchain_soniox import (
    SonioxDocumentLoader,
    SonioxTranscriptionOptions,
)

loader = SonioxDocumentLoader(
    file_url="https://soniox.com/media/examples/coffee_shop.mp3",
    options=SonioxTranscriptionOptions(
        enable_speaker_diarization=True,
    ),
)

docs = loader.load()

# Access speaker information in the metadata
current_speaker = None
output = ""
for token in docs[0].metadata["tokens"]:
    if current_speaker != token["speaker"]:
        current_speaker = token["speaker"]
        output += f"\nSpeaker {current_speaker}: {token['text'].lstrip()}"
    else:
        output += token["text"]
print(output)

# Analyze the conversation
prompt = ChatPromptTemplate.from_template(
    """
    Analyze the following conversation between speakers.
    Identify the intent of each speaker.

    Conversation:
    {conversation}
    """
)

chain = prompt | ChatOpenAI(model="gpt-5-mini") | StrOutputParser()
analysis = chain.invoke({"conversation": output})
print(analysis)

语言识别

启用自动语言检测和识别：

from langchain_soniox import (
    SonioxDocumentLoader,
    SonioxTranscriptionOptions,
)

loader = SonioxDocumentLoader(
    file_url="https://soniox.com/media/examples/coffee_shop.mp3",
    options=SonioxTranscriptionOptions(
        enable_language_identification=True,
    ),
)

docs = loader.load()

# Access language information in the metadata
current_language = None
output = ""
for token in docs[0].metadata["tokens"]:
    if current_language != token["language"]:
        current_language = token["language"]
        output += f"\n[{current_language}] {token['text'].lstrip()}"
    else:
        output += token["text"]
print(output)

提高准确性的上下文

提供特定领域的 上下文 以提高转录准确性。上下文帮助模型理解您的领域、识别重要术语并应用自定义词汇。

该 context 对象支持四个可选部分：

from langchain_soniox import (
    SonioxDocumentLoader,
    SonioxTranscriptionOptions,
    StructuredContext,
    StructuredContextGeneralItem,
    StructuredContextTranslationTerm,
)

loader = SonioxDocumentLoader(
    file_url="https://soniox.com/media/examples/coffee_shop.mp3",
    options=SonioxTranscriptionOptions(
        context=StructuredContext(
            # Structured key-value information (domain, topic, intent, etc.)
            general=[
                StructuredContextGeneralItem(key="domain", value="Healthcare"),
                StructuredContextGeneralItem(
                    key="topic", value="Diabetes management consultation"
                ),
                StructuredContextGeneralItem(key="doctor", value="Dr. Martha Smith"),
            ],
            # Longer free-form background text or related documents
            text="The patient has a history of...",
            # Domain-specific or uncommon words
            terms=["Celebrex", "Zyrtec", "Xanax"],
            # Custom translations for ambiguous terms
            translation_terms=[
                StructuredContextTranslationTerm(
                    source="Mr. Smith", target="Sr. Smith"
                ),
                StructuredContextTranslationTerm(source="MRI", target="RM"),
            ],
        ),
    ),
)

docs = loader.load()

有关更多详细信息，请参阅 Soniox上下文文档.

翻译

从任何检测到的语言翻译到目标语言：

from langchain_soniox import (
    SonioxDocumentLoader,
    SonioxTranscriptionOptions,
    TranslationConfig,
)

loader = SonioxDocumentLoader(
    file_url="https://soniox.com/media/examples/coffee_shop.mp3",
    options=SonioxTranscriptionOptions(
        translation=TranslationConfig(
            type="one_way",
            target_language="fr",
        ),
        language_hints=["en"],
    ),
)

docs = list(loader.lazy_load())

translated_text = ""
original_text = ""

for token in docs[0].metadata["tokens"]:
    if token["translation_status"] == "translation":
        translated_text += token["text"]
    else:
        original_text += token["text"]

print(original_text)
print(translated_text)

您也可以使用 two_way 翻译类型同时转录和翻译两种语言。欲了解更多信息，请参阅 异步翻译.

API参考

构造函数参数

\* 您必须指定 **恰好一个** of: file_path, file_data, or file_url.

[endpoints]: https://soniox.com/docs/stt/data-residency#regional-endpoints

转录选项

该 SonioxTranscriptionOptions 类支持以下参数：

浏览 API 文档 获取支持的完整选项列表。

[models]: https://soniox.com/docs/stt/models

返回值

该 lazy_load() 和 alazy_load() 方法返回一个 Document object:

Document(
    page_content=str,  # The transcribed text
    metadata={
        "source": str,  # File URL, path, or "file_upload"
        "transcription_id": str,  # Unique transcription ID
        "audio_duration_ms": int,  # Audio duration in milliseconds
        "model": str,  # Model used for transcription
        "created_at": str,  # ISO 8601 timestamp
        "tokens": list[dict],  # Detailed token-level information
    }
)

该 tokens 数组在元数据中包含每个转录单词的详细信息：

• - text：转录的文本
• - start_ms：起始时间（毫秒）
• - end_ms：结束时间（毫秒）
• - speaker：说话人 ID（如果启用了说话人分离），例如 "1", "2"等。
• - language：检测到的语言（如果启用了语言识别），例如 "en", "fr"等。
• - translation_status：翻译状态（"original", "translated" or "none")

了解更多关于 Soniox API 参考.

相关

• - Soniox API 文档
• - Soniox 控制台