Riffn：为AI Agent与本地模型搭建实时语音交互链路

这次我们来看一个比较有意思的方向把 AI Agent 和本地模型的交互从“打字”直接变成“说话”。项目叫Riffn核心定位一句话概括给 AI Agent 和本地模型建立一条即时语音链路。简单说你在浏览器里打开页面、按一下说话语音转成文本送给本地模型或 Agent 处理再把回复合成语音播出来。整个链路是实时的不需要先把音频文件转出来再手动导入。这篇文章不打算只讲概念。我会从项目定位、核心能力速览、环境准备、部署启动、功能验证、接口调用、性能观察、常见问题、最佳实践这几个维度展开。如果你平时主要用 Ollama、Open WebUI、ComfyUI、AnythingLLM 这类本地 AI 工具同时对语音交互有需求那这篇文章可以直接收藏。先说清楚三件事第一这个项目解决的是“语音管道”问题不是某个具体的大模型。它更接近一个中间层把 ASR、LLM、TTS 串起来让你的本地 Agent 具备“随时开口说话”的能力。第二它的门槛取决于你用什么模型。如果你已经有本地模型服务比如 Ollama 或 LM Studio 的 API那 Riffn 的重点就是配置连接如果你希望全链路语音都由本地模型完成那就需要额外的 ASR 和 TTS 模型显存和内存要求会明显上升。第三落地验证的核心指标有三个延迟、稳定性和扩展性。延迟决定对话体验稳定性决定能不能长时间挂着用扩展性决定能不能接入你现有的 Agent 工具链。下面进入正文先给出一份能力速览再逐步展开。需要说明的是由于项目处于早期版本阶段部分功能细节、端口和启动参数可能随版本变化。文中所有配置均为通用示例实际使用时以仓库 README 和启动日志为准。1. Riffn 核心能力速览能力项说明项目类型本地语音交互中间层连接 AI Agent 与本地大模型核心功能语音输入转文本、调用 Agent/LLM、文本回复转语音输出启动方式本地服务模式浏览器访问交互页面服务形态HTTP/WebSocket 本地服务可接入其他应用支持模型取决于配置的 ASR、LLM、TTS 服务常见为本地 Ollama/LM Studio/OpenAI 兼容 API推荐硬件需要 GPU 的场景建议 8GB 以上显存纯 CPU 长文本对话实时性会明显下降适合读者本地 AI 玩家、Agent 开发者、语音交互产品原型验证者开源情况开源项目早期版本是否支持批量任务取决于后端模型/Agent 是否支持Riffn 本身定位是实时语音会话不建议当作离线批处理工具主要优势实时语音链路、本地优先、可与现有 AI Agent 工具组合从材料看这个项目最核心的价值不是“生成语音”这一个环节而是把“语音输入Agent 处理语音输出”整个流程串起来。所以后面所有测试都应该围绕这条主链路来设计而不是只测语音转录或只测 TTS。2. 适用场景与使用边界先聊适用场景。Riffn 这类工具最舒服的场景有三类。第一类是本地 AI 语音助手。你本地跑着 Ollama平时靠命令行或 WebUI 打字交互。接入 Riffn 之后可以把说话变成输入方式适合做家庭语音助手、桌面语音助手。第二类是 Agent 工具链的语音入口。你的 AI Agent 已经能调用工具、查询资料、生成内容但缺一个自然的交互入口。通过 Riffn可以让用户用语音触发 Agent 任务比如“帮我总结一下今天的日志”“给某个人发一段会议提醒”。第三类是产品原型验证。如果你想快速验证“语音 大模型”的产品想法用现成组件把它串起来会比从零开发 ASR、LLM、TTS 整合快很多。再说不适合的场景。不适合把 Riffn 当离线批量转写工具。虽然语音输入会经过 ASR但它的定位是实时交互不是高吞吐量的音频批处理。不适合对延迟极其敏感的生产环境。本地 ASR、LLM、TTS 全链路每一环都会产生耗时。追求百毫秒级语音响应需要做大量工程优化不是这个项目当前的重点。不适合直接商用的场景。项目处于早期阶段接口、协议、稳定性都可能变化。商用前需要自己加固服务安全、日志、权限控制。然后是使用边界这里必须强调合规问题。Riffn 涉及语音采集、传输、处理和 TTS 声音输出。使用时要特别注意以下几点录制或实时采集他人声音必须获得明确授权。使用某个音色进行 TTS 合成如果该音色来自真人嗓音需要确认授权范围。不要把 Riffn 服务暴露在公网除非你做好了身份认证、HTTPS 和流量限制。本地模型处理用户语音内容时如果涉及隐私信息要确认模型部署环境的数据安全策略。Agent 如果具备外部工具调用能力语音触发的操作同样要有权限边界和操作确认机制。这些不是套话。语音交互天然让人降低警惕用户容易把不该说的信息说出口。作为部署者你有责任控制数据流向和工具权限。3. Riffn 本地部署环境准备在动手之前先确认基础环境。Riffn 本身是一个本地服务应用对系统依赖不算复杂但你需要先准备好“被接入的模型层”。3.1 操作系统与运行时支持主流桌面系统Windows 10/11、macOS、Linux。建议使用较新的 LTS 系统版本避免系统库太老导致依赖装不上。运行时方面需要确认 Node.js 和 Python 的版本。这类语音链路项目通常用 Node.js 写服务层、Python 跑模型层或者反过来。不管哪种组合建议按仓库 README 要求的版本安装不要用太旧的版本。常见的检查命令node -v npm -v python --version3.2 模型层准备Riffn 的定位是“语音链接”所以你需要先有一个能用的模型服务。三种常见选择第一种Ollama。本机跑模型最方便默认 API 地址是http://localhost:11434。如果你的 Agent 只负责对话这种方案最轻量。第二种LM Studio。提供兼容 OpenAI 的本地 API便于切换不同模型厂商的权重文件适合玩 AGENTS 场景。第三种OpenAI 兼容 API。不管本地还是远程只要是兼容 OpenAI 格式的接口理论上都可以接入。需要注意使用远程 API 时语音文本和回复内容会经过第三方服务涉及敏感信息要谨慎。3.3 语音组件准备Riffn 的语音链路包含两块语音识别ASR负责把你的话变成文本。可以用本机 Whisper 服务比如 faster-whisper 或 whisper.cpp也可以用云 ASR但本地优先更符合项目定位。语音合成TTS负责把 Agent 回复变成语音。本地常见选择有 edge-tts、piper、GPT-SoVITS、ChatTTS 等。具体接哪个看 Riffn 支持的配置项。如果你手头没有这些组件也可以先让 Riffn 只输出文本用浏览器自带的语音播报能力做临时验证。这个在测试阶段很实用。3.4 硬件与磁盘如果你打算全链路本地化推荐配置内存16GB 起步32GB 更稳。显存ASR 和 LLM 同时常驻时8GB 显存属于入门12GB 以上体验更好。磁盘预留 20GB 以上模型权重文件随随便便就是几个 GB。如果你用 CPU 推理不是不能跑但要放低预期。语音交互对延迟敏感CPU 跑 7B 级模型做流式对话会比较吃力。3.5 端口预留本地服务需要端口。默认常见端口是 8000、7860、3000。启动前先检查端口是否被占用# 查看某个端口是否被占用 lsof -i :3000如果有冲突直接用环境变量或启动参数改端口。4. Riffn 安装部署与启动方式因为 Riffn 是早期项目不同版本启动方式可能有差异。下面给一个通用部署流程步骤以仓库 README 为准。4.1 获取代码git clone https://github.com/riffn/riffn.git cd riffn如果仓库名或路径不对直接到 GitHub 搜索Riffn找到对应仓库。4.2 安装依赖npm install如果项目同时包含 Python 端还需要pip install -r requirements.txt如果出现依赖安装失败优先检查 Node.js 或 Python 版本其次看网络源配置。国内环境可以把 npm 源切成淘宝源npm config set registry https://registry.npmmirror.comPython 包同理切到清华源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple4.3 配置模型链接这是最关键的步骤。Riffn 需要知道你本地模型服务跑在哪里。一般通过.env文件或配置文件指定# 示例配置实际变量名以项目 README 为准 LOCAL_LLM_BASE_URLhttp://localhost:11434 LOCAL_LLM_MODELllama3.1:8b ASR_SERVICEwhisper TTS_SERVICEedge-tts PORT3000注意不同版本的变量名可能不同。如果服务启动后无法识别模型优先回仓库确认配置项。4.4 启动顺序建议按这个顺序启动第一步启动本地 LLM 服务ollama serve第二步确认模型已拉取ollama pull llama3.1:8b第三步启动 ASR / TTS 服务。比如用 edge-tts 做 TTS 时先确认命令行可用edge-tts --text test --write-media test.mp3第四步启动 Riffnnpm start启动后看到类似Server listening on http://localhost:3000的日志说明服务起来了。4.5 访问交互页面打开浏览器访问 http://localhost:3000或你配置的端口。页面应该包含麦克风按钮用于开始/停止语音输入。对话区域展示识别文本和 Agent 回复。语音播报状态显示 TTS 是否工作。如果页面打开但没有声音先回到浏览器检查是否自动播放被拦截。浏览器通常要求用户先点击页面才能自动播放音频。这是语音交互项目最常见的坑之一。5. Riffn 功能测试与效果验证部署完成后不要急着把这个服务丢给用户。先按下面的流程测一轮功能确认整条链路是通的。测试1确认本地模型层可用先不经过语音链路直接用 curl 测试 LLM 服务curl http://localhost:11434/api/chat \ -H Content-Type: application/json \ -d { model: llama3.1:8b, messages: [{role: user, content: 你好请简单介绍一下你自己}] }预期输出流式返回一段正常对话回复。如果这一步失败说明问题在模型层跟 Riffn 无关。测试2测试文本输入链路在 Riffn 页面里找到文本输入框如果支持输入同样的问题。预期结果Agent 返回回复文本页面正常展示日志无报错。这个测试的意义在于把“语音识别”从链路中剥离出来。文本输入能通说明 LLM 调用和对话管理没问题文字能通但语音不通问题就在 ASR 或 TTS 环节。测试3测试语音输入点击麦克风按钮说“今天天气怎么样”然后观察页面是否出现识别文本。识别文本是否正确。Agent 是否基于识别文本产生了回复。判断标准识别文本准确率可接受对话连贯。如果识别失败常见原因浏览器麦克风权限未开启。ASR 服务没有正确启动。ASR 模型加载时间过长导致超时。测试4测试语音输出Agent 回复后页面应该自动播放或显示播放按钮。打开浏览器控制台注意是否有音频自动播放被拦截的提示。如果需要手动点击按钮才能播放说明浏览器自动播放策略拦截。解决方法是让用户进入页面后先做一次点击交互或者到浏览器设置里允许该站点自动播放声音。测试5多轮对话测试连续说三轮以上内容例如第一轮“帮我写一个 Python 快速排序。” 第二轮“解释一下第一行代码的作用。” 第三轮“换一种写法用列表推导式实现。”判断标准三轮对话上下文连贯回复不串台语音输入和输出持续稳定。这里最能暴露出上下文管理问题。很多语音交互工具在单轮表现不错多轮就开始丢上下文。测试6中断与重试测试在 Agent 回复语音播放过程中再次点击麦克风输入新指令。判断标准系统能够处理打断逻辑不会卡死或产生双重回复。如果项目不支持打断这个测试也会告诉你当前交互的局限在哪里。测试7长文本回复测试故意输入一个需要大段输出的问题例如“用 1000 字介绍量子计算的发展史”。观察点语音输出是否会截断。浏览器是否卡顿。TTS 是否能够完整合成。长文本是语音链路最容易出问题的场景。模型生成时间、语音合成时间、播放队列任何一个环节处理不好都会让体验明显下降。6. Riffn 接口 API 与工具链接入除了页面交互Riffn 如果暴露了 API 接口就可以很方便地接入到其他工具里。假设本地服务启动在http://localhost:3000一个通用的会话接口可能是POST /api/chat。实际路径需要以项目 README 为准下面是常见风格的调用示例curl -X POST http://localhost:3000/api/chat \ -H Content-Type: application/json \ -d { message: 帮我把这段文字翻译成英文, session_id: test-001 }预期返回一个包含回复文本的 JSON{ reply: Here is the translation..., session_id: test-001, audio_url: /api/audio/test-001.mp3 }如果你要写一个最简单的 Python 客户端可以这样import requests url http://localhost:3000/api/chat payload { message: 你好请介绍一下你自己, session_id: demo-session } response requests.post(url, jsonpayload, timeout120) data response.json() print(Agent 回复:, data.get(reply)) print(语音地址:, data.get(audio_url))需要注意不同项目对输入输出字段的定义差异很大。上面的reply、session_id、audio_url都是示例字段真实字段名以接口文档为准。6.1 接入自己的 Agent 工具Riffn 的价值在于它可以充当 Agent 的前端语音入口。比如你已经有自己的 Agent 框架可以通过两种方式接方式一Riffn 直接调用 Agent 的 API。在配置里将 LLM Base URL 指向你的 Agent 服务并确保接口格式兼容。方式二Riffn 提供中间层你写一个适配服务。Riffn 收到语音后转成文本转发给你的 Agent再把 Agent 的结果转成文本返回给 Riffn 做 TTS。这种方式更适合已有复杂 Agent 逻辑、不想被 Riffn 的配置选项局限的情况。缺点是中间多一跳延迟会升高。6.2 批量任务说明这里先给一个判断Riffn 本身定位是实时语音交互不是批量处理工具。批量推理主要受限于后端服务能力。如果你的后端 Agent 支持批量任务理论上可以在 Riffn 里通过脚本触发多轮请求。但语音链路天然不适合高并发。建议的做法是用 API 方式批量发送文本请求绕过 ASR 和 TTS。批处理完成后再对结果统一合成语音。如果你确实需要“一批文本 - 一批语音”的能力建议直接调用 TTS 服务而不是通过 Riffn 交互层。下面给一个通用的批量 TTS 思路import os texts [第一段内容, 第二段内容, 第三段内容] os.makedirs(./outputs, exist_okTrue) for idx, text in enumerate(texts): output_path f./outputs/tts_{idx}.mp3 # 这里调用你配置的 TTS 命令行或 API os.system(fedge-tts --text {text} --write-media {output_path}) print(f已完成: {output_path})这个脚本不依赖 Riffn可以作为批量语音生成的后备方案。7. 资源占用与性能观察语音交互项目性能就是体验。这部分重点讲清楚资源占用怎么看以及如何定位卡顿环节。7.1 观察显存和内存如果你的 ASR、LLM、TTS 都在本地建议打开任务管理器或nvidia-smi实时观察。watch -n 1 nvidia-smi观察重点LLM 加载后显存占用。ASR 模型加载是否常驻显存。TTS 合成时内存是否暴涨。实际占用会因模型大小和量化程度明显不同。7B 量化模型大概会占用几个 G 显存Whisper small 模型又有额外占用。如果你跑的是 13B 或更大模型8G 显存会非常紧张。7.2 延迟拆解一次完整的语音交互延迟由四部分构成语音识别时间你说话停顿后ASR 返回文本的时间。大模型生成时间从文本进入模型到回复完成的时间。语音合成时间TTS 把回复文本变成语音的时间。播放排队时间音频进入浏览器播放队列前的时间。建议在 Riffn 日志里分别记录这四段时间。如果没有现成日志可以用请求开始和结束时间估算总延迟再单独 curl 测试 LLM 的延迟来粗粒度拆分。例如你按一下麦克风到听到回复总共耗时 10 秒其中LLM 生成回复耗时 6 秒。TTS 合成耗时 2 秒。网络和逻辑耗时 1 秒。ASR 识别耗时 1 秒。优化优先级很明确先优化 LLM 生成速度其次换更快的 TTS。如果 LLM 生成时间占大头换小模型或量化版本效果最明显不需要折腾 TTS。7.3 如何降低资源占用一个很实用的技巧给 ASR 和 LLM 使用不同服务不要让它们抢显存。如果你只有一块显卡更稳妥的策略是ASR 优先用 CPU 推理的轻量模型比如 faster-whisper 的 tiny 或 base 版本。LLM 用 GPU 推理保持生成速度。TTS 优先用非 GPU 方案比如 edge-tts 请求云服务或 piper 的 CPU 推理。这种组合可以避免多个模型同时竞争显存虽然牺牲一点 ASR 精度但整体可用性明显提升。7.4 进程残留与端口清理服务反复重启时容易产生监听占用问题。如果你改了端口仍然提示占用先查一下是否老进程没有退出。Linux / macOSkill -9 $(lsof -t -i :3000)Windows PowerShellGet-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force8. Riffn 常见问题与排查方法整理了一份高频问题排查表覆盖从启动到交互的大部分坑。问题现象可能原因排查方式解决方案启动后页面打不开端口被占用或服务未成功启动查看终端日志检查端口监听更换端口或重启服务页面能打开但麦克风不可用浏览器权限未开启检查地址栏麦克风权限图标在浏览器设置中允许麦克风权限说话后没有识别文本ASR 服务未启动或路径配置错误单独调用 ASR 接口测试确认 ASR 服务地址重启 ASR识别文本存在但 Agent 不回复LLM 服务地址或模型名错误curl 直接调用 LLM 接口核对 LLM Base URL 和模型名Agent 回复文本正常但没有语音TTS 服务不可用或浏览器禁音浏览器控制台查看报错检查 TTS 配置允许页面自动播放多轮对话上下文丢失会话管理逻辑异常观察请求中是否携带 session_id重置会话或检查上下文处理配置显存不足导致崩溃LLM 和 ASR 同时占用显存查看 nvidia-smi 确认占用调小模型或切分设备执行长文本回复被截断TTS 合成超时查看日志中的 TTS 报错换更快的 TTS 或分段合成首次说话延迟特别高模型冷加载观察模型加载日志提前发送一条唤醒消息预热这里再单独说一下模型文件缺失问题。很多语音链路工具启动时不报错运行时才出问题。如果你遇到 ASR 或 TTS 调用失败先确认模型文件是否真正下载完成。Whisper 模型、TTS 音色文件都有可能因为网络中断下载不完整表现为第一次可用、第二次失败或者随机失败。9. Riffn 最佳实践与使用建议9.1 先跑通最小链路不要一上来就追求最复杂的 Agent 多模态语音体验。第一次部署建议先用最小链路验证本地 LLM 固定文本输入 MP3 文件播放跑通后再加上麦克风输入最后再加 Agent 工具调用。最小链路的好处是出问题时你永远知道问题出在哪个环节。9.2 建立一套可复用的启动脚本语音链路涉及多个服务手动启动很容易漏。建议写成一个启动脚本以start.sh为例#!/bin/bash # 1. 启动 LLM 服务 nohup ollama serve logs/ollama.log 21 # 2. 启动 ASR 服务示例 # nohup python -m faster_whisper_server logs/asr.log 21 # 3. 启动 Riffn npm start echo Riffn 已启动访问 http://localhost:3000Windows 用户可以写成同思路的.bat脚本。9.3 日志与目录管理不要把模型权重、输入材料、输出结果混在同一个目录里。建议目录结构riffn/ ├── models/ # 放置模型文件 ├── inputs/ # 测试音频文件 ├── outputs/ # 生成结果 ├── logs/ # 服务日志 └── scripts/ # 启动与测试脚本日志要按日期滚动避免单个日志文件无限增长。服务长时间挂机时这个习惯能帮你省去很多排查时间。9.4 安全与权限控制语音交互服务不能裸奔在公网上。至少要保证服务监听在 127.0.0.1 而不是 0.0.0.0。如果需要局域网访问控制好网段和防火墙。如果接口暴露在公网必须加认证和 HTTPS。另外如果你的 Agent 具备工具调用能力比如可以发邮件、操作文件、控制智能家居语音触发要格外谨慎。语音指令容易被误触发建议为高风险操作增加二次确认。9.5 合规使用提醒关于声音和隐私这里有必要再强调一次使用真实人物的声音进行 TTS 合成必须获得本人授权。录制语音对话内容前要告知参与方。敏感信息不要通过不安全的链路传输。商用前检查模型、音色、代码仓库的开源许可证。10. 总结与下一步Riffn 这类项目的价值不在某个单独的模型而在于把语音识别、大模型对话、语音合成串成一条可用的实时链路。从项目定位看它最有亮点的地方是本地优先、面向 Agent 交互设计、扩展方式灵活。这意味着它可以作为你本地 AI 工具链里的一块新拼图。第一次部署这个项目最先应该验证的是三件事第一模型层是否已经可用。先证明本地 LLM 能正常返回结果再接入语音层否则一切问题都会显得像 Riffn 的问题。第二语音转文本和文本转语音这两条路是否分别可通。建议先用文本输入测一遍再测麦克风再测播放逐个确认。第三多轮对话是否稳定。语音交互只用单轮演示意义不大连续对话不丢上下文才是可用的起点。最容易踩的坑有两个一个是浏览器音频自动播放被拦截表现形式为“有文字回复但没有声音”另一个是显存不足导致 LLM 和 ASR 互相抢资源表现为服务不稳定、时好时坏。后续扩展方向可以考虑把 Riffn 接入你已有的 Agent 流程比如让语音指令触发搜索、总结、日程管理等操作或者替换 TTS 引擎让回复声音更有辨识度更远一步可以做流式 TTS让语音输出和大模型生成同时进行肉眼可见地降低等待时间。建议收藏备用。等你手头的本地模型环境稳定后抽一个下午时间按上面的流程跑一遍最小链路会对语音交互的工程复杂度有更具体的感觉。