EdgeSpeak
中文
语言
English中文

Python SDK

首版 Python SDK 仍在开发，尚未发布到 PyPI。需要支持 serve --sdk 的配套 CLI；账号 API KEY 还需要配套账号后端。本文说明未发布实现的用法。

从源码安装

需要 Python 3.10 或更新版本。在公开 EdgeSpeak 仓库目录执行：

Shell
python -m pip install ./sdk/python

SDK 自动发现 CLI，要求 CLI ≥ 0.6.3 且支持 edgespeak-sdk-v2（最低版本见 edgespeak.MIN_CLI_VERSION）。兼容的本地安装直接复用，不联网检查；缺失或不兼容时，自动调用官方稳定版安装器，完成后再次验证。安装需要联网，使用 ~/.edgespeak/sdk/ 下的独立目录，保留原 CLI 入口和 PATH，单独限时 20 分钟。如果官方 CLI 或安装器版本仍不支持 SDK，会明确报错。Python 包不包含模型和原生引擎。自动安装支持 macOS Apple Silicon、Linux x86_64 和 Windows x64。

转录与对齐

Python
import os
from edgespeak import EdgeSpeak

with EdgeSpeak(api_key=os.environ["EDGESPEAK_API_KEY"]) as client:
    transcript = client.transcribe("meeting.wav", language="zh", diarize=True)
    alignment = client.align("speech.wav", text="这里填写音频中实际说出的文字。", language="zh")
    print(transcript["text"])
    print(alignment)

SDK 会启动自己的 CLI 服务，使用随机本机端口。无需也不提供 CLI 路径配置。未提供账号 API KEY 时，CLI 沿用已有的本地激活流程。

说话人分析

Python
with EdgeSpeak() as client:
    turns = client.diarize("meeting.wav", num_speakers=2)
    first = client.speaker_embedding("alice.wav")
    second = client.speaker_embedding("bob.wav")
    comparison = client.speaker_similarity(first["data"][0]["embedding"], second["data"][0]["embedding"])

方法返回网关的 JSON 对象。字段见转录与说话人分析和对齐。音频时间戳以秒为单位。对齐文本应是音频中实际说出的原文，不能用译文替代。

账号 API KEY

从顶部账户菜单打开独立的 API KEY页面，填写名称并创建密钥。完整密钥只显示一次，请当场复制保存；列表只保留前缀。可选择有效期，撤销不再使用的密钥。

通过 api_key 参数传入，或设置 EDGESPEAK_API_KEY 后让 EdgeSpeak() 自动读取。SDK 内部转换为 CLI 的账号凭据。接入已有网关使用独立的 gateway_key；这里的示例用 EDGESPEAK_GATEWAY_KEY 保存网关令牌。账号密钥沿用账号已有的设备和用量额度，不能用于网页登录或离线授权。

同一机器上的 SDK 和桌面端共用设备名额。关闭 SDK 或撤销密钥不会移除设备；不再使用的机器可在账号页的设备管理中移除，以释放名额。密码重置后，账号密钥仍然有效，直到到期或手动撤销。

SDK 通过子进程环境传入账号密钥，不放入命令行参数。CLI 将会话凭据保留在内存中，保留桌面账号身份并共享用量账本。撤销后服务端拒绝新请求；此前签发的凭据最多有效五分钟。已经开始的推理不会被中断。

服务生命周期

推荐使用 with。close() 可重复调用，只释放该客户端启动的服务。垃圾回收提供清理兜底，但无法保证何时发生。服务同时监听父进程输入管道，Python 异常退出时也会触发退出。

未能正常完成关闭的服务会被强制停止。HTTP 端口关闭不能单独证明原生工作进程已经退出。Windows 回收和加载模型后的进程回收，需要通过发布验收后才能发布此开发版 SDK。

每个工作进程应创建自己的客户端。Python 多进程推荐 spawn；通过 fork 创建的子进程不能使用父进程的客户端。

接入已有网关

Python
with EdgeSpeak(
    base_url="http://127.0.0.1:1118/v1",
    gateway_key=os.environ["EDGESPEAK_GATEWAY_KEY"],
) as client:
    result = client.transcribe("meeting.wav")

附加模式关闭客户端不会停止外部服务。此模式不接受账号 api_key。远程地址要求 HTTPS；不跟随重定向，也不读取环境代理和环境 CA 覆盖配置。

错误与超时

EdgeSpeakError 提供 code 和 status_code，不原样显示服务端错误正文。RuntimeStartError 表示 CLI 启动或握手失败。请求超时默认是每个 HTTP I/O 阶段 600 秒，并非整个任务的总时限；startup_timeout 默认 30 秒。请求超时不代表服务端推理已经停止。

语音方法

各方法保留 API 返回的 JSON；transcribe(response_format="text") 返回字符串。时间单位为秒。模型要求和参数约束见音频 API、对齐 API和文本 API。

方法参数与行为
transcribe(audio, ...)model、language、diarize、response_format、prompt、timestamp_granularities、word_timestamp_enabled、candidates、semantic_sentence_enabled、min_chars、max_chars、start_margin、end_margin、stream
align(audio, ...)text 或 text_file、text_format、model、language、search_effort、threshold、start + end、protected_terms、text_normalization、audio_track、audio_channel、semantic_sentence_enabled、min_chars、max_chars、start_margin、end_margin、progress
segment(text, ...)纯文本或 segments，以及 threshold、paragraph_threshold、min_chars、max_chars、start_margin、end_margin、options
diarize(audio, ...)独立说话人分离，可用 num_speakers 指定 1–32 位说话人
speaker_embedding(audio, ...)单个路径或路径列表，可指定 model；批量结果保持输入顺序
speaker_similarity(a, b, ...)比较同一模型生成的两个声纹向量，可指定 model

转录中 diarize=True 选择 diarized_json，不能同时选择其他响应格式。人数设置属于独立的 diarize()；转录和对齐 API 不接受 num_speakers。对齐 API 目前不执行说话人分离。

参考文件与对齐

Python
with EdgeSpeak() as client:
    aligned = client.align(
        "speech.wav", text_file="captions.ass", language="zh",
        search_effort="auto", semantic_sentence_enabled=True,
        min_chars=10, max_chars=40,
    )
    from_json = client.align(
        "speech.wav", text={"segments": [{"text": "音频中实际说出的原文。"}]}
    )

text_file 读取本地 UTF-8 文件，支持 BOM，上限为 64 MiB。支持 .txt、.json、.srt、.ass 和 .ssa，也可用 text_format 覆盖扩展名。JSON 使用包含 segments[].text 的字幕结构，或回退到顶层 text。直接传字幕内容时，使用 text=contents, text_format="srt"，格式也可为 json、ass 或 ssa。text 和 text_file 必须且只能提供一个。

SDK 上传文件内容，不发送本地 text_path。CLI 共用解析器提取原文，忽略字幕原有时间，以及 ASS 样式、注释和绘图；对齐根据音频重新计算时间。这需要配套的未发布 CLI/API text_format 支持。

语义分句与分段

Python
with EdgeSpeak() as client:
    sentences = client.segment("这是第一句。这是第二句。", max_chars=40)
    paragraphs = client.segment("一段较长的原文。", paragraph_threshold=0.6)
    transcript = client.transcribe("meeting.wav", diarize=True)
    captions = client.segment(segments=transcript["segments"], min_chars=10, max_chars=40)

纯文本模式生成句子；带时间的 segments 模式通过 API 的重新分句行为保留时间和说话人信息。段落模式仅接受纯文本，不能同时设置时间片段、长度限制或边距。转录、对齐也可设置 semantic_sentence_enabled=True 直接分句；未传参数沿用运行时默认设置。

进度与流式结果

Python
with EdgeSpeak() as client:
    with client.align("speech.wav", text="音频中实际说出的原文。", progress=True) as events:
        for event in events:
            print(event)

对齐依次返回进度、阶段事件和最终对齐对象；进度达到 1 不等于收到最终结果。transcribe(stream=True) 返回 SSE 事件，目前需要连接桌面端网关，Headless CLI 不支持流式转录。流式转录要求 response_format="json"，不支持说话人分离或时间粒度参数；不兼容组合会由 API 拒绝。

提前停止读取时使用流的上下文管理器。关闭客户端也会关闭其流。连接结束却没有终止事件时，抛出错误码为 incomplete_stream 的 EdgeSpeakError。关闭流会释放连接和上传文件，但不保证已开始的推理被取消。

可运行示例

Python SDK 示例覆盖转录、对齐、语义分句与分段、带时间字幕、说话人分离、批量声纹和相似度。各文件用 --help 查看参数。传 --base-url 连接已有网关，否则示例自行启动并关闭 CLI 服务。

Shell
python sdk/python/examples/transcribe.py meeting.wav --diarize --semantic
python sdk/python/examples/align.py speech.wav --text-file captions.srt --progress
python sdk/python/examples/segment.py --text "这是第一句。这是第二句。" --max-chars 40
python sdk/python/examples/segment.py --segments-file transcript.json --max-chars 40
python sdk/python/examples/speakers.py meeting.wav alice.wav bob.wav --num-speakers 2

密钥可选择永久有效，仅表示密钥不设到期日；账号授权、订阅额度、在线验证和撤销仍然生效。临时授权凭据仍最多有效五分钟。

SDK 用 exception.code 保留网关原始错误码，用 exception.reason 区分 api_key_expired（密钥过期）、api_key_revoked（密钥已撤销）、usage_exhausted（本期额度耗尽）。服务器提供下次重置时间时，可读取经过验证的 exception.resets_at；额度响应的既有网关错误码仍是 license_required。异常不会原样输出任意服务器错误文本。

API KEY 与桌面端共享账号订阅额度及其计费周期。创建或切换密钥不重置用量，进入下一个订阅周期才按账号套餐恢复额度。

本页目录