CLI

从终端运行 EdgeSpeak 工作流。

安装

CLI 自带本机语音运行时，无需安装或启动桌面 App。请按操作系统选择命令。

macOS / Linux

在 Terminal 中运行。支持 macOS（Apple Silicon）与 Linux（x86_64）。Linux 安装器检测到 NVIDIA 驱动或 CUDA 环境时安装 CUDA 版，否则安装 CPU 版；若缺少 CUDA 12 运行库则会一并下载。使用 CUDA 版时，RTX 20 系列及更新的显卡需要 NVIDIA 驱动 570 或更高；GTX 900/10 系列、P100 和 V100 需要 575 或更高，驱动低于 575 时安装器会改为安装 CPU 版。

curl -fsSL https://edgespeak.com/install.sh | sh

如需手动指定安装版本，可传入 --device 参数，取值与 edgespeak-cli serve --device 相同：

curl -fsSL https://edgespeak.com/install.sh | sh -s -- --device cuda

--device 支持的取值（不区分大小写）：

sh ~/Downloads/install.sh

Windows

在 Windows x64 的 PowerShell 中运行。安装器默认安装 CPU 版，并把 edgespeak-cli 加入当前用户的 PATH，无需管理员权限。

irm https://edgespeak.com/install.ps1 | iex

CUDA 版在 RTX 20 系列及更新的显卡上需要 NVIDIA 驱动 570 或更高，GTX 900/10 系列、P100 和 V100 需要 575 或更高。如果需要在支持的 NVIDIA 显卡上启用 CUDA，请在同一个 PowerShell 窗口中显式选择 CUDA 版后再安装：

$env:EDGESPEAK_WINDOWS_ACCELERATOR = "cuda"
irm https://edgespeak.com/install.ps1 | iex

安装后可直接运行 edgespeak-cli login。如果其他已打开的终端仍找不到命令，请重新打开终端，让 PATH 更新生效。

激活

运行 edgespeak-cli login 通过浏览器登录：新账号开始 7 天试用，已购账号激活当前设备。无需账号和浏览器的设备匿名试用，可运行 edgespeak-cli trial。已有 License Key 可运行 edgespeak-cli activate "<LICENSE_KEY>"，传入 --stdin 可避免 Key 写入 Shell 历史。

edgespeak-cli login

edgespeak-cli trial            # instant device trial, no account or browser
edgespeak-cli activate "<LICENSE_KEY>"
edgespeak-cli activate --stdin   # paste the key, then Ctrl-D

购买、账户登录与设备激活

游客购买也会关联邮箱：付款成功后，License Key 归属于 Stripe 结账时填写的邮箱。用同一邮箱登录应看到已有的终身授权。购买不会自动设置账户密码。

密码是可选的：通过 Key 或邮箱链接登录后，可以在账户页的「安全设置」中设置密码。首次设置只需填写新密码和确认密码；修改已有密码时需要验证当前密码。

如果付款后登录只显示试用授权，请确认登录邮箱是否与结账邮箱一致，或直接在账户页使用购买的 License Key 登录。使用 Key 登录会进入所属账户，不会合并不同邮箱的账户。edgespeak-cli trial 申请的是匿名设备试用，不会查找邮箱下的购买记录；已有购买请使用 login 或 activate。

赠送邀请码可用于设备激活，但不能用于网站登录。邀请码不可用时，可购买 License Key后激活；若希望继续使用赠送码，请联系赠送方。License Key（软件激活）与下文用于 HTTP 认证的 API Key（接口认证）是两种不同的密钥。

激活网络排错与容器启动

edgespeak-cli activate 支持从环境变量 EDGESPEAK_LICENSE_KEY 读取 Key，也可使用 --stdin 输入，无需网站密码。HTTP 404 activation_code_unavailable 表示服务端拒绝该赠送码；network:dns、network:tls、network:tls_handshake、network:proxy、network:connect、network:timeout 为网络故障，不代表 Key 无效。

运行时将交互激活单次超时设为 30 秒，遇到网络故障时最多重试两次，间隔分别为 700 毫秒与 1800 毫秒；明确的证书校验错误（network:tls）与 HTTP 业务拒绝不会自动重试，TLS 握手中断（network:tls_handshake）仍会重试。重试最长约需 93 秒，CLI 会实时显示重试进度。后台刷新使用 5 秒超时。若因网络故障激活失败，保留原 Key 排查即可，无需重新购买。

CLI 为激活错误和进度提示提供简体中文、繁体中文、英文、德文、法文、日文与韩文。语言按 EDGESPEAK_CLI_LOCALE → LC_ALL → LC_MESSAGES → LANG 的优先级取第一个非空值；支持 zh_CN.UTF-8 等系统格式，遇到 C、POSIX、未支持语言或未设置时使用英文。可在容器中显式指定：

EDGESPEAK_CLI_LOCALE=zh-CN edgespeak-cli activate
EDGESPEAK_CLI_LOCALE=en edgespeak-cli activate

以上命令从已设置的 EDGESPEAK_LICENSE_KEY 读取 Key。语言设置只影响激活错误和进度，不改变错误码、退出码、--json 数据或音频的 --language 参数；其他 CLI 文案目前仍以英文为主。未知运行时错误保留原始诊断，不根据未知错误推荐购买。

在出错的同一个容器内运行以下无凭据探测：

getent ahosts api.edgespeak.com
curl -sS --connect-timeout 10 --max-time 30 -o /dev/null \
  -w 'http=%{http_code} dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} total=%{time_total}\n' \
  https://api.edgespeak.com/api/health

健康探测成功仅说明当前网络路径可达，不代表激活请求已成功。排查时请记录时间、CLI 版本、错误类别与探测结果，切勿分享 License Key 或包含凭据的代理配置。中国大陆跨境链路可能影响连接，但单条发送失败日志不足以归因于 Cloudflare。请分别排查容器 DNS、系统时间、代理设置与出站 HTTPS 连接，并保持 TLS 证书校验开启。

容器启动时切勿重复执行 deactivate && activate：这会先撤销本机授权，使服务启动依赖网络激活。首次在目标设备激活后，应持久化 EDGESPEAK_DATA_DIR 目录，后续重启直接运行 serve。Linux 默认数据目录为 $XDG_DATA_HOME/EdgeSpeak 或 $HOME/.local/share/EdgeSpeak；请保持设备标识稳定，不要在不同节点间跨机共用同一个授权数据卷。

License Key 应通过环境变量或 Secret 传入运行时，切勿写入 Dockerfile ENV 或镜像中。对外提供服务时请设置独立的 EDGESPEAK_API_KEY。推荐的容器入口配置：

ENTRYPOINT ["edgespeak-cli"]
CMD ["serve", "--host", "0.0.0.0", "--port", "1118", "--allow-remote"]

工作流

支持转录与说话人标注、文稿对齐、语义分句、播报、声音与模型管理，以及启动 Realtime Demo。桌面 App 未运行时，大多数一次性命令会自动启动随附的本机引擎；serve 命令则持续运行 Headless 服务，供 API 客户端反复调用。

edgespeak-cli transcribe meeting.m4a -o meeting.json   # word-level timing in JSON
edgespeak-cli transcribe meeting.m4a --diarize -o speakers.json
edgespeak-cli transcribe meeting.m4a -o transcript.srt
edgespeak-cli align meeting.m4a --text-file transcript.txt -o aligned.json
edgespeak-cli segment --file transcript.txt -o sentences.json
edgespeak-cli speech "Read this aloud" -o speech.wav
edgespeak-cli voices list
edgespeak-cli models list
edgespeak-cli status
edgespeak-cli demo
edgespeak-cli update

transcribe、align、speech、voices add 的 --language 与 HTTP API 使用同一套代码，例如 --language yue，见语言代码。transcribe --language 需要能连上网关。

更新模型

CLI 0.6.0 起提供。 更早的 CLI 没有 models update，也不会自动刷新已安装模型。

# 只检查已安装模型，不下载、不改写本地模型文件
edgespeak-cli models update --check
edgespeak-cli models update --check --json

# 更新全部已安装模型，或指定一个已安装模型
edgespeak-cli models update
edgespeak-cli models update EdgeSpeak/Lattice-2
edgespeak-cli models update EdgeSpeak/Lattice-2-Flash

# 安装尚未下载的模型
edgespeak-cli models download EdgeSpeak/Lattice-2

不指定 ID 时，models update 只检查 CLI 支持的已安装模型，不会下载整个模型目录。指定的模型尚未安装时返回 not_installed，请用 models download 安装。共享模型包只处理一次。更新前请退出桌面 App、停止 serve 和 MCP 会话；网关运行时仍可使用 --check。

EdgeSpeak/Lattice-2-Lite、EdgeSpeak/Lattice-2-Flash 和 EdgeSpeak/Lattice-2-Pro 各自包含同档位已安装的转录模型（Transcriber.ES）和翻译模型（Translator.ES）。只安装翻译模型也会被识别；只装了一种能力时，更新不会顺带安装另一种。每个档位汇总一条状态，任一已安装能力更新失败时报告 failed。不指定 ID 时，三档也按这一规则检查。EdgeSpeak/Lattice-2 单独更新对齐模型；EdgeSpeak/Lattice-1 更新对齐、语义断句和说话人分离模型包。

Lattice 模型读取远端 manifest 检查更新。TTS 和语言模型以当前 CLI 内置目录中的兼容版本为准，因此发现新版模型前应先更新 CLI。语言模型保留已安装的量化档位；只有本地资产、没有公开下载的模型返回 unsupported。每种能力的模型包内，变更文件下载并校验成功后才替换，下载失败会保留该包的已安装文件。各能力分别更新，后续失败不会撤销此前已成功的更新。

已安装的 Lattice-2 Preview 会被识别为可升级模型。兼容客户端下载正式声学文件，复用校验通过的 tokenizer，并保留旧版客户端所需的 Preview 文件。

edgespeak-cli update 安装最新独立运行时后，由安装器调用新运行时的 models update；即使重新安装的是同一兼容客户端版本，也会检查模型。如果某个平台暂时仍提供不含此命令的旧 CLI，安装器会明确提示已跳过模型更新。随桌面 App 分发的 CLI 由 App 更新软件，此命令只更新模型。Windows 上，CLI 启动独立 PowerShell 窗口后退出，让出被占用的可执行文件；请在该窗口查看最终结果。Windows 原命令的即时退出状态只表示更新程序已启动。在已激活的设备上直接重新运行安装命令，也会更新已安装的模型；模型更新失败不影响安装结果，安装器会提示重试 edgespeak-cli models update。

--json 返回 check 标记和 models 数组，每项含 id、status，失败时可含 error。状态为 updated、up_to_date、update_available、not_installed、unsupported 或 failed。检查成功时即使存在更新也返回退出码 0；不支持自动更新的本地模型会明确报告并跳过；失败或显式指定未安装模型时返回 1。macOS/Linux 上，运行时更新失败返回 1；运行时已装好但模型更新失败时，update 返回 3。停止运行中的服务后重试 edgespeak-cli models update 即可，无需重装运行时。

API 复用与段落切分

连接到运行中的本地网关或桌面网关时，CLI 通过 HTTP 调用同一组 API。transcribe --diarize 对应 /v1/audio/transcriptions 的 response_format=diarized_json，会执行说话人分离与转录；diarize 对应 /v1/speaker/diarizations，仅返回说话人时间线。在相同的输入、模型和处理配置下，计算流程完全一致；但桌面模式与独立运行模式的默认配置可能不同。

edgespeak-cli transcribe meeting.m4a --diarize --base-url http://127.0.0.1:1117/v1 -o speakers.json
edgespeak-cli diarize meeting.m4a -o timeline.json
edgespeak-cli segment --file transcript.txt --paragraph-threshold 0.5 -o paragraphs.json
edgespeak-cli segment --transcript aligned.json -o resegmented.json

segment --file 读取纯文本；--transcript 读取含 segments[].words[] 的转录或对齐 JSON，重新切句并映射词级时间戳。--text、--file 与 --transcript 三种输入参数互斥。

--paragraph-threshold 启用段落切分，对应 API 的 paragraph_threshold 参数。返回结果中每个 segments[] 元素为一个段落，不含时间戳；省略该参数时默认按句切分。完整参数与文本归一化接口见 API 文档。

Headless API 服务

无需桌面 App，即可持续运行 HTTP 服务。以下命令使用 Bash / zsh（Windows 可使用 WSL 或 Git Bash）；PowerShell 的环境变量写法见下文。

在本机启动并验证

未设置 EDGESPEAK_API_KEY 时，直接启动默认无需认证。以下命令在启动时清除继承的变量，确保本例关闭认证：

env -u EDGESPEAK_API_KEY edgespeak-cli serve

服务默认监听 127.0.0.1:1118，在前台持续运行。保留该终端，在另一个终端发起健康检查请求：

export EDGESPEAK_BASE_URL=http://127.0.0.1:1118/v1
curl --fail-with-body "$EDGESPEAK_BASE_URL/health"

输出示例：

{"status":"ok","license":"active"}

license 的取值与含义见检查服务状态。/health 与 /v1/health 始终无需认证，HTTP 200 仅表示服务进程可达。要验证认证机制，请调用下文的受保护接口。执行推理前还需要登录或激活，并下载与加载模型；服务启动成功不代表模型已就绪。按 Ctrl-C 可停止服务。

从命令行控制认证

非回环地址始终需要 --allow-remote。--allow-unauthenticated-loopback 是仅回环的旧别名，不能与 --allow-remote 同时使用。非回环地址关闭认证仅适用于隔离的测试环境。

开启认证：停止已有服务后，在服务端设置 API Key 并重新启动（请替换示例中的占位符）：

export EDGESPEAK_API_KEY="your-long-random-secret"
edgespeak-cli serve

在调用端终端设置相同的 Key，调用受保护接口验证：

export EDGESPEAK_BASE_URL=http://127.0.0.1:1118/v1
export EDGESPEAK_API_KEY="your-long-random-secret"
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/downloads" \
  -H "Authorization: Bearer $EDGESPEAK_API_KEY"

输出示例（尚无下载任务记录）：

{"object":"list","data":[]}

Key 缺失或错误时返回 HTTP 401。请求头也支持用 x-api-key: $EDGESPEAK_API_KEY 替代 Bearer 格式。

关闭认证：停止服务后传入 --allow-unauthenticated 参数启动。该参数优先级高于环境变量：

edgespeak-cli serve --allow-unauthenticated

在 PowerShell 中，开启认证的命令如下；若需移除环境变量，可运行 Remove-Item Env:EDGESPEAK_API_KEY -ErrorAction SilentlyContinue 后再启动服务。--allow-unauthenticated 在各平台含义相同。

$env:EDGESPEAK_API_KEY = "your-long-random-secret"
edgespeak-cli serve

上述环境变量属于服务端配置，不随 API 页面上的请求示例开关变化。客户端子命令的 --api-key 参数仅用于发出请求；serve 通过环境变量配置 Key，不支持使用该参数设置服务密钥。

保存密钥与主动轮换

serve 只在启动时读取一次 EDGESPEAK_API_KEY，不会生成、保存、过期或刷新密钥；运行中修改环境变量不影响已启动的进程，桌面 App 的认证开关与「重新生成」也不会影响它。请使用自行保管的随机长密钥。轮换步骤：停止服务，导出新值，重新启动，并把新密钥同步到各调用端；旧密钥随后返回 HTTP 401。

export EDGESPEAK_API_KEY="your-long-random-secret"
edgespeak-cli serve

CLI 不要求 sk-edgespeak- 前缀。它与桌面 App 自动生成的 Key 格式相似，但两者的值相互独立。API Key 的保存与更换。

允许另一台机器访问

在服务端配置密钥，并显式开启非回环监听：

export EDGESPEAK_API_KEY="your-long-random-secret"
edgespeak-cli serve --host 0.0.0.0 --port 1118 --allow-remote

客户端发起请求时需替换为服务端的实际 IP 与相同密钥，不要使用 0.0.0.0。远程访问完整示例。

模型与运行选项

通过 --context-tokens 参数在服务启动时指定语言模型上下文窗口。默认值为 8192 token，应用于当前进程启动的本机语言模型 Worker。Headless 服务不读取桌面 App 保存的上下文设置。

edgespeak-cli serve --context-tokens 32768

原生视频请求的采样率由模型目录自动决定，无需也不支持配置视频 FPS 参数。上下文长度与视频采样帧共享同一份内存和 token 预算。请求格式、运行依赖与资源开销见原生视频输入与上下文窗口。

并发参数

这些 serve 参数取值范围为 1..64；0 不代表无限制。

edgespeak-cli serve --speech-concurrency 2 --transcription-concurrency 2

转录与文稿对齐属于独立能力，可并发执行，不再共用单一执行槽，但仍共享全局上传与原生内存预算。同类请求超出并发限制时会进入队列。HTTP 播报、转录与底层 ASR / TTS 队列会有限度优先复用已加载的模型：最早等待的请求最多被插队两次，等待超过 1 秒后不再允许插队。这不是 1 秒内必定开始执行的保证，当前正在执行的任务和长连接仍需先完成。

并发数并不等同于模型实例数。同款 ASR 模型可由批量任务与 Realtime 会话复用，切换模型规格时需等待旧模型会话清理完毕；TTS 任务共用一个模型执行槽；LLM 则由原生运行时调度，当前同一时间最多加载一个模型且独占推理槽。调大并发参数不会复制模型副本，也不保证提升吞吐量；内存不足、模型不支持的配置和原生故障仍会报错。

客户端配置请求超时时，应计入排队等待、模型加载和实际推理三部分耗时，Realtime 握手同理。取消排队中的请求会直接移除等待登记；若请求已进入推理执行阶段，需等待任务完成或清理后才会释放模型资源。查看等待和执行状态。

模型休眠与常驻

CLI 服务默认在模型空闲 300 秒（5 分钟）后释放内存或显存，下次调用时重新加载。正在执行的任务与持有租约的会话不会因超时被强制中断，HTTP 服务也会持续监听。--preload 仅在启动服务时预加载指定模型。

调整方式：

edgespeak-cli serve --preload transcribe --no-model-sleep
# 或指定空闲秒数：
edgespeak-cli serve --model-idle-seconds 600

--no-model-sleep 用于禁止因空闲自动卸载。--model-idle-seconds 接受 0..86400 秒：0 表示空闲后尽快释放，86400 为约定值，表示「从不因空闲卸载」（并非 24 小时）。这两个参数互斥，不能同时使用。也可以通过环境变量 EDGESPEAK_ENGINE_IDLE_TTL_SECS 设置，命令行参数优先级更高；桌面 App 的设置不会同步至独立 CLI。

该策略覆盖 ASR、LLM、TTS、强制对齐、语义分句、说话人识别与声纹等全部模型。禁止休眠仍允许按请求切换模型、显式卸载以及进程退出时清理，但不会绕过硬件资源限制，无法保证所有模型同时常驻。若需复用模型，请保持 serve 进程持续运行；一次性 CLI 命令执行完毕后会直接退出并释放模型。

Agent

通过 EdgeSpeak Skill 让 Agent 调用，或把本地网关与 MCP 接入自动化和 CI 环境。

隐私

语音工作流与已安装的本机模型让源音频、声音、生成音频、转录稿、提示词与图片留在当前设备。只有在你明确选择 execution_location=remote 的模型时，才会把发给该模型的请求传给对应供应商。

使用本机模型生成

启动桌面网关或 CLI 服务，并将环境变量 EDGESPEAK_BASE_URL 指向对应地址。通过模型目录下载并加载模型后即可调用：

edgespeak-cli models load Qwen/Qwen3.5-4B
edgespeak-cli generate "Summarize the meeting" --model Qwen/Qwen3.5-4B
edgespeak-cli generate "Describe this image" --image screenshot.png --json