1 line
29 KiB
JSON
1 line
29 KiB
JSON
{"repo": "carl-ai-lab/ai-accent-coach", "files": {"README.md": {"59e3eaaeed5a004ecd3a800a6997dc807c907486": {"t": 1785747352.5585701, "n": 5119, "h": "0c4e59690cb418b5", "c": "<p align=\"center\">\n <img src=\"assets/logo.png\" alt=\"Accent Coach\" width=\"480\"/>\n</p>\n\n# AI Accent Coach — AI 美式英语口语教练\n\n自部署的 AI 口语练习工具，By **卡尔AI工坊**\n\n支持实时对话、发音纠正、生词本和间隔重复复习\n\nA self-hosted AI speaking coach for American English learners — real conversation practice, pronunciation coaching, vocabulary notebook, and spaced-repetition review.\n\n\n\n---\n\n## 功能 / Features\n\n- **实时对话** — 与 AI 教练进行流式对话（streaming LLM）\n- **语音识别** — 本地运行 [faster-whisper](https://github.com/SYSTRAN/faster-whisper)，支持 GPU / CPU，零额外 API 费用\n- **语音合成** — 通过 [edge-tts](https://github.com/rany2/edge-tts) 免费朗读，无需 API Key\n- **点击查词** — 点击教练回复中的任意单词，即时查看释义并自动存入生词本\n- **选中查短语** — 选中一段文本获取上下文翻译\n- **间隔重复复习** — 基于 Leitner Box 的生词本复习系统\n- **6 种对话场景** — 日常聊天 / 商务 / 旅行 / 面试 / 讨论 / 故事\n- **3 个难度等级** — 入门 / 中级 / 高级\n- **单文件前端** — 无构建步骤，不依赖 Node.js\n\n## 架构 / Architecture\n\n```text\n┌───────────────────────────────────┐\n│ Browser (index.html) │\n│ mic → WebM → /api/transcribe │\n│ text → /api/chat (SSE stream) │\n│ audio ← /api/tts │\n└──────────────┬────────────────────┘\n │ HTTPS（自签名证书 / self-signed）\n┌──────────────▼────────────────────┐\n│ FastAPI backend │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ Whisper │ │ OpenAI-compat │ │\n│ │ (本地) │ │ LLM API │ │\n│ └──────────┘ └───────────────┘ │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ edge-tts │ │ JSON 存储 │ │\n│ └──────────┘ └───────────────┘ │\n└───────────────────────────────────┘\n```\n\n## 目录结构 / Directory Structure\n\n```text\nai-accent-coach/\n├── app.py # FastAPI 后端（所有 API）\n├── coach.sh # 服务管理脚本（start/stop/restart/status/log）\n├── requirements.txt\n├── .env.example # ← 复制为 .env 并填写配置\n├── static/\n│ └── index.html # 单文件前端\n└── assets/\n └── logo.png\n```\n\n## 快速开始 / Quick Start\n\n```bash\ngit clone https://github.com/Carl-AI-Lab/ai-accent-coach.git\ncd ai-accent-coach\n\npython3 -m venv venv && source venv/bin/activate # 推荐使用虚拟环境\npip install -r requirements.txt\n\ncp .env.example .env\n# 编辑 .env —— 至少填写 OPENAI_API_KEY\n# 没有 GPU？把 WHISPER_DEVICE 改为 cpu\n```\n\n启动服务 / Start：\n\n```bash\nbash coach.sh start # 后台运行，日志输出到 accent-coach.log\n# 或\npython app.py # 前台运行，实时输出\n```\n\n> **首次启动说明：** Whisper 模型（distil-large-v3 约 1.5 GB）会在首次使用时自动从 HuggingFace 下载，请耐心等待。国内用户可在 `.env` 中取消 `HF_ENDPOINT` 的注释以使用镜像加速。\n\n打开浏览器访问 **https://localhost:8443**。\n\n> 由于使用自签名证书，浏览器会显示安全警告——点击 **\"高级\"→\"继续前往\"**（Chrome）或 **\"接受风险并继续\"**（Firefox）即可。\n\n停止服务 / Stop：\n\n```bash\nbash coach.sh stop\n```\n\n## 环境变量 / Configuration\n\n所有配置项均在 **`.env`** 文件中（参考 [.env.example](.env.example)）：\n\n| 变量 Variable | 默认值 Default | 说明 Description |\n|---|---|---|\n| `OPENAI_API_KEY` | *（必填 required）* | 任意 OpenAI 兼容服务的 API Key |\n| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | LLM 接口地址，支持 OpenAI / DeepSeek / Ollama 等 |\n| `LLM_MODEL` | `gpt-4.1-mini` | 模型名称 |\n| `WHISPER_DEVICE` | `cpu` | `cuda` = GPU，`cpu` = 仅 CPU |\n| `WHISPER_MODEL` | `distil-large-v3` | Whisper 模型大小 |\n| `WHISPER_UNLOAD_TIMEOUT` | `120` | 空闲多少秒后自动卸载模型（节省显存） |\n| `TTS_VOICE` | `en-US-AndrewMultilingualNeural` | edge-tts 语音名称 |\n| `PORT` | `8443` | HTTPS 监听端口 |\n\n### 切换 LLM 服务商 / Using a Different LLM Provider\n\n支持任意 OpenAI 兼容接口：\n\n```bash\n# OpenAI（默认）\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=gpt-4.1-mini\n\n# DeepSeek\nOPENAI_BASE_URL=https://api.deepseek.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=deepseek-chat\n\n# Ollama（本地运行，免费）\nOPENAI_BASE_URL=http://localhost:11434/v1\nOPENAI_API_KEY=ollama\nLLM_MODEL=llama3.1\n```\n\n## GPU 与 CPU 对比 / GPU vs CPU\n\nWhisper 在本地运行语音识别，可选 GPU 或 CPU 模式。\n\n### GPU 模式（推荐）\n\n```bash\nWHISPER_DEVICE=cuda\n```\n\n需要 NVIDIA GPU + **cuBLAS** + **cuDNN**（CUDA 12）。\n\n先安装 CUDA 运行时库（如果系统未自带）：\n\n```bash\npip install nvidia-cublas-cu12 nvidia-cudnn-cu12\n```\n\n然后设置 `LD_LIBRARY_PATH`，让 `faster-whisper` 能找到它们：\n\n```bash\n# 查找 pip 安装的库路径\npython3 -c \"import nvidia.cublas.lib, nvidia.cudnn.lib; print(nvidia.cublas.lib.__path__[0]); print(nvidia.cudnn.lib.__path__[0])\"\n\n# 输出示例：\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cublas/lib\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cudnn/lib\n\n# 启动前设置（或取消 coach.sh 中对应行的注释）：\nexport LD_LIBRARY_PATH=\"/home/you/venv/.../nvidia/cublas/lib:/home/you/venv/.../nvidia/cudnn/lib\"\n```\n\n### CPU 模式\n\n```bash\nWHISPER_DEVICE=cpu\n```\n\n无需 GPU，任何机器都能运行，但速度明显更慢——见下方性能对比。\n\n> **提示：** 在 CPU 上建议使用较小的模型以加快响应速度：\n> ```bash\n> WHISPER_MODEL=base # 最快，准确率较低\n> WHISPER_MODEL=small # 速度与准确率平衡\n> WHISPER_MODEL=medium # 准确率更高，速度更慢\n> ```\n\n### 性能实测 / Benchmark\n\n在同一台机器上测试，10 秒音频片段，`distil-large-v3` 模型，`beam_size=5`，`vad_filter=True`：\n\n| | 设备 Device | 计算类型 | 模型加载 | 转录耗时（3 次平均） |\n|---|---|---|---|---|\n| **GPU** | NVIDIA RTX 4060 Laptop (8 GB) | float16 | 16.5 s | **0.51 s** |\n| **CPU** | Intel i7-12700H (20 threads) | int8 | 5.7 s | **5.52 s** |\n\n> **CPU 转录速度约慢 11 倍**，但模型加载反而快 3 倍（跳过 CUDA 初始化）。日常练习时 CPU 延迟（~5 秒/句）可以接受；追求流畅对话体验建议使用 **GPU**。\n\n## 环境要求 / Requirements\n\n- Python ≥ 3.9\n- 一个 OpenAI 兼容的 API Key（用于 LLM）\n- *（GPU 模式）* NVIDIA GPU + CUDA 12 + cuBLAS + cuDNN 9\n- *（CPU 模式）* 无额外硬件要求，x86_64 或 ARM 均可\n\n## 许可证 / License\n\n[Apache License 2.0](LICENSE)\n"}, "21a9201672a4c02b1ede5295a85e60b20b3ded26": {"t": 1785772712.9456112, "n": 4867, "h": "19ff02eeec07b3a5", "c": "<p align=\"center\">\n <img src=\"assets/logo.png\" alt=\"Accent Coach\" width=\"480\"/>\n</p>\n\n# AI Accent Coach — AI 美式英语口语教练\n\n自部署的 AI 口语练习工具，By **卡尔AI工坊**\n\n支持实时对话、发音纠正、生词本和间隔重复复习\n\nA self-hosted AI speaking coach for American English learners — real conversation practice, pronunciation coaching, vocabulary notebook, and spaced-repetition review.\n\n\n\n---\n\n## 功能 / Features\n\n- **实时对话** — 与 AI 教练进行流式对话（streaming LLM）\n- **语音识别** — 本地运行 [faster-whisper](https://github.com/SYSTRAN/faster-whisper)，支持 GPU / CPU，零额外 API 费用\n- **语音合成** — 通过 [edge-tts](https://github.com/rany2/edge-tts) 免费朗读，无需 API Key\n- **点击查词** — 点击教练回复中的任意单词，即时查看释义并自动存入生词本\n- **选中查短语** — 选中一段文本获取上下文翻译\n- **间隔重复复习** — 基于 Leitner Box 的生词本复习系统\n- **6 种对话场景** — 日常聊天 / 商务 / 旅行 / 面试 / 讨论 / 故事\n- **3 个难度等级** — 入门 / 中级 / 高级\n- **单文件前端** — 无构建步骤，不依赖 Node.js\n\n## 架构 / Architecture\n\n```text\n┌───────────────────────────────────┐\n│ Browser (index.html) │\n│ mic → WebM → /api/transcribe │\n│ text → /api/chat (SSE stream) │\n│ audio ← /api/tts │\n└──────────────┬────────────────────┘\n │ HTTPS（自签名证书 / self-signed）\n┌──────────────▼────────────────────┐\n│ FastAPI backend │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ Whisper │ │ OpenAI-compat │ │\n│ │ (本地) │ │ LLM API │ │\n│ └──────────┘ └───────────────┘ │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ edge-tts │ │ JSON 存储 │ │\n│ └──────────┘ └───────────────┘ │\n└───────────────────────────────────┘\n```\n\n## 目录结构 / Directory Structure\n\n```text\nai-accent-coach/\n├── app.py # FastAPI 后端（所有 API）\n├── coach.sh # 服务管理脚本（start/stop/restart/status/log）\n├── requirements.txt\n├── .env.example # ← 复制为 .env 并填写配置\n├── static/\n│ └── index.html # 单文件前端\n└── assets/\n └── logo.png\n```\n\n## 快速开始 / Quick Start\n\n```bash\ngit clone https://github.com/Carl-AI-Lab/ai-accent-coach.git\ncd ai-accent-coach\n\npython3 -m venv venv && source venv/bin/activate # 推荐使用虚拟环境\npip install -r requirements.txt\n\ncp .env.example .env\n# 编辑 .env —— 至少填写 OPENAI_API_KEY\n```\n\n启动服务 / Start：\n\n```bash\nbash coach.sh start # 后台运行，日志输出到 accent-coach.log\n# 或\npython app.py # 前台运行，实时输出\n```\n\n打开浏览器访问 **https://localhost:8443**（接受自签名证书即可）。\n\n停止服务 / Stop：\n\n```bash\nbash coach.sh stop\n```\n\n## 环境变量 / Configuration\n\n所有配置项均在 **`.env`** 文件中（参考 [.env.example](.env.example)）：\n\n| 变量 Variable | 默认值 Default | 说明 Description |\n|---|---|---|\n| `OPENAI_API_KEY` | *（必填 required）* | 任意 OpenAI 兼容服务的 API Key |\n| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | LLM 接口地址，支持 OpenAI / DeepSeek / Ollama 等 |\n| `LLM_MODEL` | `gpt-4.1-mini` | 模型名称 |\n| `WHISPER_DEVICE` | `cuda` | `cuda` = GPU，`cpu` = 仅 CPU |\n| `WHISPER_MODEL` | `distil-large-v3` | Whisper 模型大小 |\n| `WHISPER_UNLOAD_TIMEOUT` | `120` | 空闲多少秒后自动卸载模型（节省显存） |\n| `TTS_VOICE` | `en-US-AndrewMultilingualNeural` | edge-tts 语音名称 |\n| `PORT` | `8443` | HTTPS 监听端口 |\n\n### 切换 LLM 服务商 / Using a Different LLM Provider\n\n支持任意 OpenAI 兼容接口：\n\n```bash\n# OpenAI（默认）\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=gpt-4.1-mini\n\n# DeepSeek\nOPENAI_BASE_URL=https://api.deepseek.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=deepseek-chat\n\n# Ollama（本地运行，免费）\nOPENAI_BASE_URL=http://localhost:11434/v1\nOPENAI_API_KEY=ollama\nLLM_MODEL=llama3.1\n```\n\n## GPU 与 CPU 对比 / GPU vs CPU\n\nWhisper 在本地运行语音识别，可选 GPU 或 CPU 模式。\n\n### GPU 模式（推荐）\n\n```bash\nWHISPER_DEVICE=cuda\n```\n\n需要 NVIDIA GPU + **cuBLAS** + **cuDNN**（CUDA 12）。\n\n如果通过 pip 安装了 CUDA 库（`nvidia-cublas-cu12`、`nvidia-cudnn-cu12`），需要设置 `LD_LIBRARY_PATH`，让 `faster-whisper` 能找到它们：\n\n```bash\n# 查找 pip 安装的库路径\npython3 -c \"import nvidia.cublas.lib, nvidia.cudnn.lib; print(nvidia.cublas.lib.__path__[0]); print(nvidia.cudnn.lib.__path__[0])\"\n\n# 输出示例：\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cublas/lib\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cudnn/lib\n\n# 启动前设置（或取消 coach.sh 中对应行的注释）：\nexport LD_LIBRARY_PATH=\"/home/you/venv/.../nvidia/cublas/lib:/home/you/venv/.../nvidia/cudnn/lib\"\n```\n\n### CPU 模式\n\n```bash\nWHISPER_DEVICE=cpu\n```\n\n无需 GPU，任何机器都能运行，但速度明显更慢——见下方性能对比。\n\n> **提示：** 在 CPU 上建议使用较小的模型以加快响应速度：\n> ```bash\n> WHISPER_MODEL=base # 最快，准确率较低\n> WHISPER_MODEL=small # 速度与准确率平衡\n> WHISPER_MODEL=medium # 准确率更高，速度更慢\n> ```\n\n### 性能实测 / Benchmark\n\n在同一台机器上测试，10 秒音频片段，`distil-large-v3` 模型，`beam_size=5`，`vad_filter=True`：\n\n| | 设备 Device | 计算类型 | 模型加载 | 转录耗时（3 次平均） |\n|---|---|---|---|---|\n| **GPU** | NVIDIA RTX 4060 Laptop (8 GB) | float16 | 16.5 s | **0.51 s** |\n| **CPU** | Intel i7-12700H (20 threads) | int8 | 5.7 s | **5.52 s** |\n\n> **CPU 转录速度约慢 11 倍**，但模型加载反而快 3 倍（跳过 CUDA 初始化）。日常练习时 CPU 延迟（~5 秒/句）可以接受；追求流畅对话体验建议使用 **GPU**。\n\n## 环境要求 / Requirements\n\n- Python ≥ 3.9\n- 一个 OpenAI 兼容的 API Key（用于 LLM）\n- *（GPU 模式）* NVIDIA GPU + CUDA 12 + cuBLAS + cuDNN 9\n- *（CPU 模式）* 无额外硬件要求，x86_64 或 ARM 均可\n\n## 许可证 / License\n\n[Apache License 2.0](LICENSE)\n"}, "606c378ba7d454f11d95f596a699809a49d64c99": {"t": 1785772715.4630685, "n": 4834, "h": "ee8c909d5d1420f7", "c": "<p align=\"center\">\n <img src=\"assets/logo.png\" alt=\"Accent Coach\" width=\"480\"/>\n</p>\n\n# AI Accent Coach — AI 美式英语口语教练\n\n自部署的 AI 口语练习工具，支持实时对话、发音纠正、生词本和间隔重复复习。\n\nA self-hosted AI speaking coach for American English learners — real conversation practice, pronunciation coaching, vocabulary notebook, and spaced-repetition review.\n\n---\n\n## 功能 / Features\n\n- **实时对话** — 与 AI 教练进行流式对话（streaming LLM）\n- **语音识别** — 本地运行 [faster-whisper](https://github.com/SYSTRAN/faster-whisper)，支持 GPU / CPU，零额外 API 费用\n- **语音合成** — 通过 [edge-tts](https://github.com/rany2/edge-tts) 免费朗读，无需 API Key\n- **点击查词** — 点击教练回复中的任意单词，即时查看释义并自动存入生词本\n- **选中查短语** — 选中一段文本获取上下文翻译\n- **间隔重复复习** — 基于 Leitner Box 的生词本复习系统\n- **6 种对话场景** — 日常聊天 / 商务 / 旅行 / 面试 / 讨论 / 故事\n- **3 个难度等级** — 入门 / 中级 / 高级\n- **单文件前端** — 无构建步骤，不依赖 Node.js\n\n## 架构 / Architecture\n\n```text\n┌───────────────────────────────────┐\n│ Browser (index.html) │\n│ mic → WebM → /api/transcribe │\n│ text → /api/chat (SSE stream) │\n│ audio ← /api/tts │\n└──────────────┬────────────────────┘\n │ HTTPS（自签名证书 / self-signed）\n┌──────────────▼────────────────────┐\n│ FastAPI backend │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ Whisper │ │ OpenAI-compat │ │\n│ │ (本地) │ │ LLM API │ │\n│ └──────────┘ └───────────────┘ │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ edge-tts │ │ JSON 存储 │ │\n│ └──────────┘ └───────────────┘ │\n└───────────────────────────────────┘\n```\n\n## 目录结构 / Directory Structure\n\n```text\nai-accent-coach/\n├── app.py # FastAPI 后端（所有 API）\n├── coach.sh # 服务管理脚本（start/stop/restart/status/log）\n├── requirements.txt\n├── .env.example # ← 复制为 .env 并填写配置\n├── static/\n│ └── index.html # 单文件前端\n└── assets/\n └── logo.png\n```\n\n## 快速开始 / Quick Start\n\n```bash\ngit clone https://github.com/Carl-AI-Lab/ai-accent-coach.git\ncd ai-accent-coach\n\npython3 -m venv venv && source venv/bin/activate # 推荐使用虚拟环境\npip install -r requirements.txt\n\ncp .env.example .env\n# 编辑 .env —— 至少填写 OPENAI_API_KEY\n```\n\n启动服务 / Start：\n\n```bash\nbash coach.sh start # 后台运行，日志输出到 accent-coach.log\n# 或\npython app.py # 前台运行，实时输出\n```\n\n打开浏览器访问 **https://localhost:8443**（接受自签名证书即可）。\n\n停止服务 / Stop：\n\n```bash\nbash coach.sh stop\n```\n\n## 环境变量 / Configuration\n\n所有配置项均在 **`.env`** 文件中（参考 [.env.example](.env.example)）：\n\n| 变量 Variable | 默认值 Default | 说明 Description |\n|---|---|---|\n| `OPENAI_API_KEY` | *（必填 required）* | 任意 OpenAI 兼容服务的 API Key |\n| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | LLM 接口地址，支持 OpenAI / DeepSeek / Ollama 等 |\n| `LLM_MODEL` | `gpt-4.1-mini` | 模型名称 |\n| `WHISPER_DEVICE` | `cuda` | `cuda` = GPU，`cpu` = 仅 CPU |\n| `WHISPER_MODEL` | `distil-large-v3` | Whisper 模型大小 |\n| `WHISPER_UNLOAD_TIMEOUT` | `120` | 空闲多少秒后自动卸载模型（节省显存） |\n| `TTS_VOICE` | `en-US-AndrewMultilingualNeural` | edge-tts 语音名称 |\n| `PORT` | `8443` | HTTPS 监听端口 |\n\n### 切换 LLM 服务商 / Using a Different LLM Provider\n\n支持任意 OpenAI 兼容接口：\n\n```bash\n# OpenAI（默认）\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=gpt-4.1-mini\n\n# DeepSeek\nOPENAI_BASE_URL=https://api.deepseek.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=deepseek-chat\n\n# Ollama（本地运行，免费）\nOPENAI_BASE_URL=http://localhost:11434/v1\nOPENAI_API_KEY=ollama\nLLM_MODEL=llama3.1\n```\n\n## GPU 与 CPU 对比 / GPU vs CPU\n\nWhisper 在本地运行语音识别，可选 GPU 或 CPU 模式。\n\n### GPU 模式（推荐）\n\n```bash\nWHISPER_DEVICE=cuda\n```\n\n需要 NVIDIA GPU + **cuBLAS** + **cuDNN**（CUDA 12）。\n\n如果通过 pip 安装了 CUDA 库（`nvidia-cublas-cu12`、`nvidia-cudnn-cu12`），需要设置 `LD_LIBRARY_PATH`，让 `faster-whisper` 能找到它们：\n\n```bash\n# 查找 pip 安装的库路径\npython3 -c \"import nvidia.cublas.lib, nvidia.cudnn.lib; print(nvidia.cublas.lib.__path__[0]); print(nvidia.cudnn.lib.__path__[0])\"\n\n# 输出示例：\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cublas/lib\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cudnn/lib\n\n# 启动前设置（或取消 coach.sh 中对应行的注释）：\nexport LD_LIBRARY_PATH=\"/home/you/venv/.../nvidia/cublas/lib:/home/you/venv/.../nvidia/cudnn/lib\"\n```\n\n### CPU 模式\n\n```bash\nWHISPER_DEVICE=cpu\n```\n\n无需 GPU，任何机器都能运行，但速度明显更慢——见下方性能对比。\n\n> **提示：** 在 CPU 上建议使用较小的模型以加快响应速度：\n> ```bash\n> WHISPER_MODEL=base # 最快，准确率较低\n> WHISPER_MODEL=small # 速度与准确率平衡\n> WHISPER_MODEL=medium # 准确率更高，速度更慢\n> ```\n\n### 性能实测 / Benchmark\n\n在同一台机器上测试，10 秒音频片段，`distil-large-v3` 模型，`beam_size=5`，`vad_filter=True`：\n\n| | 设备 Device | 计算类型 | 模型加载 | 转录耗时（3 次平均） |\n|---|---|---|---|---|\n| **GPU** | NVIDIA RTX 4060 Laptop (8 GB) | float16 | 16.5 s | **0.51 s** |\n| **CPU** | Intel i7-12700H (20 threads) | int8 | 5.7 s | **5.52 s** |\n\n> **CPU 转录速度约慢 11 倍**，但模型加载反而快 3 倍（跳过 CUDA 初始化）。日常练习时 CPU 延迟（~5 秒/句）可以接受；追求流畅对话体验建议使用 **GPU**。\n\n## 环境要求 / Requirements\n\n- Python ≥ 3.9\n- 一个 OpenAI 兼容的 API Key（用于 LLM）\n- *（GPU 模式）* NVIDIA GPU + CUDA 12 + cuBLAS + cuDNN 9\n- *（CPU 模式）* 无额外硬件要求，x86_64 或 ARM 均可\n\n## 许可证 / License\n\n[Apache License 2.0](LICENSE)\n"}, "28d17577028823df064d8030a56eb2338d9504f4": {"t": 1785772717.6429486, "n": 5879, "h": "40d8e7d18490b8a5", "c": "<p align=\"center\">\n <img src=\"assets/logo.png\" alt=\"AccentCoach\" width=\"480\"/>\n</p>\n\n<p align=\"center\">\n <b>Self-hosted AI speaking coach for American English learners.</b><br/>\n Real conversation practice · Pronunciation coaching · Vocabulary notebook · Spaced-repetition review\n</p>\n\n---\n\n## Features\n\n- **Real-time conversation** with an AI coach (streaming LLM)\n- **Speech-to-text** via local [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (GPU or CPU)\n- **Text-to-speech** via [edge-tts](https://github.com/rany2/edge-tts) (free, no API key)\n- **Tap-to-lookup** — click any word in coach replies for instant meaning + auto-save to notebook\n- **Phrase selection** — select a phrase for contextual translation\n- **Spaced-repetition notebook** with Leitner box review\n- **6 conversation scenarios** (Daily Chat, Business, Travel, Interview, Discussion, Stories)\n- **3 difficulty levels** (Beginner / Intermediate / Advanced)\n- **Zero external STT API cost** — Whisper runs 100% locally\n- **Single-file frontend** — no build step, no Node.js\n\n## Architecture\n\n```text\n┌───────────────────────────────────┐\n│ Browser (index.html) │\n│ mic → WebM → /api/transcribe │\n│ text → /api/chat (SSE stream) │\n│ audio ← /api/tts │\n└──────────────┬────────────────────┘\n │ HTTPS (self-signed)\n┌──────────────▼────────────────────┐\n│ FastAPI backend │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ Whisper │ │ OpenAI-compat │ │\n│ │ (local) │ │ LLM API │ │\n│ └──────────┘ └───────────────┘ │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ edge-tts │ │ JSON storage │ │\n│ └──────────┘ └───────────────┘ │\n└───────────────────────────────────┘\n```\n\n## Directory Structure\n\n```text\nai-accent-coach/\n├── app.py # FastAPI backend (all APIs)\n├── coach.sh # Service manager (start/stop/restart/status/log)\n├── requirements.txt\n├── .env.example # ← copy to .env and fill in\n├── static/\n│ └── index.html # Single-file frontend\n└── assets/\n └── logo.png\n```\n\n## Quick Start\n\n```bash\ngit clone https://github.com/Carl-AI-Lab/ai-accent-coach.git\ncd ai-accent-coach\n\npython3 -m venv venv && source venv/bin/activate # recommended\npip install -r requirements.txt\n\ncp .env.example .env\n# Edit .env — at minimum set OPENAI_API_KEY\n```\n\nStart the server:\n\n```bash\nbash coach.sh start # background, logs to accent-coach.log\n# or\npython app.py # foreground with live output\n```\n\nOpen **https://localhost:8443** in your browser (accept the self-signed certificate).\n\nStop:\n\n```bash\nbash coach.sh stop\n```\n\n## Configuration\n\nAll settings live in **`.env`** (see [.env.example](.env.example)):\n\n| Variable | Default | Description |\n|---|---|---|\n| `OPENAI_API_KEY` | *(required)* | API key for any OpenAI-compatible service |\n| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | LLM endpoint. Works with OpenAI, DeepSeek, Ollama, etc. |\n| `LLM_MODEL` | `gpt-4.1-mini` | Model name |\n| `WHISPER_DEVICE` | `cuda` | `cuda` for GPU, `cpu` for CPU-only |\n| `WHISPER_MODEL` | `distil-large-v3` | Whisper model size |\n| `WHISPER_UNLOAD_TIMEOUT` | `120` | Seconds idle before auto-unloading the model from memory |\n| `TTS_VOICE` | `en-US-AndrewMultilingualNeural` | edge-tts voice name |\n| `PORT` | `8443` | HTTPS listen port |\n\n### Using a Different LLM Provider\n\nAccentCoach works with any OpenAI-compatible API:\n\n```bash\n# OpenAI (default)\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=gpt-4.1-mini\n\n# DeepSeek\nOPENAI_BASE_URL=https://api.deepseek.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=deepseek-chat\n\n# Ollama (local, free)\nOPENAI_BASE_URL=http://localhost:11434/v1\nOPENAI_API_KEY=ollama\nLLM_MODEL=llama3.1\n```\n\n## GPU vs CPU\n\nWhisper runs locally for speech-to-text. You can choose GPU or CPU mode.\n\n### GPU Mode (recommended)\n\n```bash\nWHISPER_DEVICE=cuda\n```\n\nRequires NVIDIA GPU with **cuBLAS** and **cuDNN** for CUDA 12.\n\nIf you installed CUDA libraries via pip (`nvidia-cublas-cu12`, `nvidia-cudnn-cu12`), you need to set `LD_LIBRARY_PATH` so that `faster-whisper` can find them:\n\n```bash\n# Find the library paths installed by pip\npython3 -c \"import nvidia.cublas.lib, nvidia.cudnn.lib; print(nvidia.cublas.lib.__path__[0]); print(nvidia.cudnn.lib.__path__[0])\"\n\n# Example output:\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cublas/lib\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cudnn/lib\n\n# Set before starting (or uncomment the line in coach.sh):\nexport LD_LIBRARY_PATH=\"/home/you/venv/.../nvidia/cublas/lib:/home/you/venv/.../nvidia/cudnn/lib\"\n```\n\n### CPU Mode\n\n```bash\nWHISPER_DEVICE=cpu\n```\n\nNo GPU required. Works on any machine. Significantly slower — see benchmark below.\n\n> **Tip:** On CPU, consider using a smaller model for faster response:\n> ```bash\n> WHISPER_MODEL=base # fastest, lower accuracy\n> WHISPER_MODEL=small # good balance\n> WHISPER_MODEL=medium # better accuracy, slower\n> ```\n\n### Benchmark (actual measurements)\n\nTested on the same machine with a 10-second audio clip, `distil-large-v3` model, `beam_size=5`, `vad_filter=True`:\n\n| | Device | Compute Type | Model Load | Transcription (avg of 3) |\n|---|---|---|---|---|\n| **GPU** | NVIDIA RTX 4060 Laptop (8 GB) | float16 | 16.5 s | **0.51 s** |\n| **CPU** | Intel i7-12700H (20 threads) | int8 | 5.7 s | **5.52 s** |\n\n> **CPU is ~11× slower for transcription**, but model loading is actually 3× faster since it skips CUDA initialization. For casual practice the CPU latency (~5 s per utterance) is acceptable. For fluid conversation, **GPU is strongly recommended**.\n\n## Requirements\n\n- Python ≥ 3.9\n- An OpenAI-compatible API key (for the LLM)\n- *(GPU mode)* NVIDIA GPU + CUDA 12 + cuBLAS + cuDNN 9\n- *(CPU mode)* No extra hardware — works on any x86_64 or ARM machine\n\n## License\n\n[Apache License 2.0](LICENSE)\n"}}}} |