TTX-Bench

TTX-Bench 是一个本地运行的 FastAPI 评测台，用来测试一条完整语音链路里的三段能力：

• ASR 识别速度和结果
• LLM 首字延迟和输出内容
• TTS 首帧延迟和合成结果

当前页面已经改成录音主工作台，参数通过 ASR / LLM / TTS 三个设置弹窗维护，配置可以自动保存在浏览器本地，也可以导入导出为 JSON。

每个会话还会在本地写一份结构化日志到 reports/sessions/<session_id>/logs.jsonl，方便直接排查 WebSocket、Provider 和阶段返回数据。

首页还会根据当前 Provider 存量和 /info 运行时信息显示一段“首次启动检查”提示：

• 当前没有任何 Provider 时，提示你先填一套配置或配置 PROVIDER_BOOTSTRAP_FILE
• 只保存了部分能力时，提示你还缺哪一段 Provider
• 三段能力都已具备时，这块提示会自动收起

运行边界

• 这是一个本地自托管工具，不内置任何 ASR / LLM / TTS 凭据。
• 实际运行前，需要用户自己提供对应 provider 的 provider / model / base_url / api_key。
• Provider 实例和 Lab 实验快照会落到本地 reports/ 目录，便于复用和追踪。
• Lab 实验定义只保存脱敏后的 provider 快照；运行实验时会按 provider_id 重新读取当前 Provider 配置。
• REST API 不会回传已保存的真实 API Key；Provider 编辑页里 API Key 也不会回显，留空保存会保持原值。
• reports/providers/providers.json 只保存公开配置和元数据；真实 API Key 单独保存在本地 reports/providers/provider_secrets.json。
• 以上本地文件都只适合单机自托管使用，不适合多用户共享部署。

当前内置实现与模板

按代码里的注册关系，当前内置 Provider 实现是：

• ASR
  • ali：DashScope Recognition 实时语音识别
• LLM
  • openai：对应 app/providers/llm/openai_compatible.py
• TTS
  • ali：DashScope QwenTtsRealtime 实时语音合成
  • edge_tts：本地 Edge TTS，无需远程 base_url 和 api_key

按模板定义，当前内置 Provider 模板是：

• aliyun_asr_realtime
  • provider_options: ali
• openai_compatible
  • provider_options: openai / deepseek / ali
• aliyun_tts_realtime
  • provider_options: ali
• edge_tts_local
  • provider_options: edge_tts

快速开始

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python run.py

如果你希望保留热重载：

UVICORN_RELOAD=1 python run.py

常用运行时环境变量：

• APP_NAME
• APP_HOST
• APP_PORT
• REPORTS_DIR
• PROVIDER_BOOTSTRAP_FILE
• LOG_LEVEL

.env.example 当前只保留运行时环境变量；实际 ASR / LLM / TTS 连接参数应通过 Provider 页面保存，或者通过 PROVIDER_BOOTSTRAP_FILE 指向的本地 JSON 文件导入。

打开 http://localhost:8000。

如果你希望首次启动就自动导入本地 Provider 配置文件，推荐把 examples/providers.bootstrap.example.json 复制成根目录下的 providers.bootstrap.local.json，填入你自己的真实 base_url / api_key / model，并在 .env 里保留：

PROVIDER_BOOTSTRAP_FILE=./providers.bootstrap.local.json

应用启动时会按 name + service + template_key 幂等导入这些 Provider：

• 同名同模板已存在时更新配置，不会重复创建
• 真实 API Key 仍只会写入本地 reports/providers/provider_secrets.json
• GET /info 会返回本次 bootstrap 是否已加载

验证基础功能：

make verify

执行一轮完整的本地基础检查：

make preflight

输出本地运行诊断摘要：

make doctor

浏览器级 smoke test：

npm install
npx playwright install chromium
make browser-smoke

统一配置约定

所有服务统一使用这四个字段：

• provider
• model
• base_url
• api_key

另外每一段能力都支持一个 params JSON。

对阿里云 provider 来说，项目内部仍然保留统一映射：

• model -> 阿里云模型或应用标识
• api_key -> 阿里云 API Key
• base_url -> 阿里云服务入口 URL

这不是阿里云原生控制台字段命名，而是为了让 ASR / LLM / TTS 三段配置结构统一。

录音链路

前端录音现在直接采集单声道 PCM，并在浏览器端下采样到 16000 Hz，再通过 WebSocket 发送给后端，避免依赖 MediaRecorder 的 webm 容器格式。

文档拆分

• ASR 配置文档
• LLM 配置文档
• TTS 配置文档
• Provider 模板说明
• 浏览器烟测清单
• 发布说明
• 使用示例
• 架构说明
• 安全说明
• 行为准则

系统入口

• GET /health
  • 最小健康检查
• GET /info
  • 返回当前实例版本、运行边界、已注册 Provider 和 Provider 模板摘要

目录结构

app/
  api/              FastAPI 路由
  core/             pipeline / session / telemetry
  providers/        ASR / LLM / TTS provider 封装
  schemas/          Pydantic 模型
  services/         业务服务
  templates/        单页前端
docs/
  asr.md
  llm.md
  tts.md