PersonaPlex /api/chat WebSocket API 参考全参数完整文档【免费下载链接】personaplexPersonaPlex code.项目地址: https://gitcode.com/GitHub_Trending/pe/personaplexPersonaPlex 是一个实时、全双工的语音对话大模型基于 Moshi 架构你可以对着麦克风与它自然说话它还能被打断、能抢话、能同步输出文字。本文以/api/chat WebSocket 接口为核心用表格和流程图讲清楚连接参数、16 种音色、二进制消息协议和常见问题帮新手快速接入自己的语音对话客户端。一分钟看懂 PersonaPlex 架构一句话理解数据流向浏览器或你的客户端通过WebSocket把Opus 编码的音频流发给服务器服务器上的 Mimi 编码器把音频变成 tokenLM语言模型结合角色 Prompt与音色 Prompt实时生成回复 token回复音频以 Opus 流返回同时逐词推送文字转写实现边说边打字的效果。核心服务端逻辑位于 moshi/moshi/server.py接口注册在 server.py 一行/api/chat是唯一需要掌握的端点。接口基础信息如何连接到 /api/chat项目说明端点GET /api/chat握手后升级为 WebSocket协议ws://本地 HTTP或wss://启用 SSL 时默认端口8998消息类型纯二进制帧binary frame首字节标识消息类型并发能力服务器用全局锁串行化会话同一时刻只服务一个活跃会话启动服务后详见 README.mdSSL_DIR$(mktemp -d); python -m moshi.server --ssl $SSL_DIR客户端如何拼装 URL参考 Conversation.tsx 中的buildURL函数先取协议ws或wss再向/api/chat追加全部查询参数。连接参数详解Query 参数全表所有参数都通过URL 查询字符串传递连接建立前就生效对话中途不可修改。核心参数服务器端实际读取参数必填默认值说明voice_prompt✅ 必填NATF0.pt音色文件文件名如NATF2.pt、VARM3.pt必须在服务器音色目录中存在text_prompt✅ 必填可为空串见下方示例角色设定文本服务端会自动包裹system ... /system标签seed❌ 可选随机随机种子-1表示每次随机相同种子可复现对话⚠️ 注意voice_prompt与text_prompt若缺失会直接导致连接报错server.pyseed为-1或省略时不固定随机性。采样参数客户端会发送当前服务端暂未启用官方 Web 客户端还会发送以下采样参数定义见 useModelParams.ts服务端对应解析代码目前处于注释状态server.py。了解它们的默认值和取值范围便于阅读源码和后续对接参数默认值取值范围含义text_temperature0.70.2 – 1.2文本 token 采样温度越高越发散text_topk2510 – 500文本候选集大小audio_temperature0.80.2 – 1.2音频 token 采样温度audio_topk25010 – 500音频候选集大小pad_mult0-4 – 4静音帧概率调节repetition_penalty1.01.0 – 2.0重复惩罚系数调大可减少复读机repetition_penalty_context640 – 200重复惩罚作用的上下文长度worker_auth_id/email——演示环境排队系统使用本地部署可忽略16 种预置音色怎么选音色文件随模型仓库分发服务器首次启动自动下载解压逻辑见 server.py。命名规则NAT 自然对话感VAR 多样风格F 女声M 男声。类别音色编号推荐场景Natural(female)NATF0 – NATF3默认NATF0适合助手类对话Natural(male)NATM0 – NATM3客服、讲解类角色Variety(female)VARF0 – VARF4角色扮演、个性化音色Variety(male)VARM0 – VARM4角色扮演、个性化音色角色 Prompt 怎么写3 类模板示例text_prompt决定模型扮演谁。以下是官方推荐的三种写法 助手角色默认You are a wise and friendly teacher. Answer questions or provide advice in a clear and engaging way. 客服角色把公司名、你的名字、要查询的信息写进一句 Prompt例如仓库自带的示例 prompt_service.txtYou work for SwiftPlex Appliances which is a appliance repair company and your name is Farhod Toshmatov. ...☕ 闲聊角色开放式对话以You enjoy having a good conversation.开头可追加话题与人物设定如你在波士顿的前面包师 David Green。更多示例见 README.md 的 Prompting Guide 章节——官方甚至放了一个火星宇航员抢修反应堆的角色试试效果相当惊艳。二进制消息协议6 种帧类型连接建立后双向都走二进制帧首字节即消息类型。协议定义见 types.ts编解码实现见 encoder.ts首字节类型方向Payload 内容0x00handshake 握手服务端 → 客户端版本 模型标识各 1 字节均为 00x01audio 音频双向Opus 音频字节流客户端发麦克风服务端回说话声0x02text 文字服务端 → 客户端UTF-8 编码的逐词转写文本0x03control 控制客户端 → 服务端1 字节start / endTurn / pause / restart0x04metadata双向JSON 序列化的元数据0x05error服务端 → 客户端UTF-8 错误信息0x06ping客户端 → 服务端无 payload保活用控制帧的具体动作位types.tsstart0b00、endTurn0b01、pause0b10、restart0b11。连接生命周期一次完整会话的流程客户端 服务器 │ GET /api/chat?voice_promptNATF0.pttext_prompt...seed42 ├─────────────────────────────►│ │ │ ① 加载音色 编码角色 Prompt │ │ ② 模型跑完 system prompt 预热 │ ◄────────── 0x00 握手帧 ────│ ③ 发送握手可开始说话 │ 0x01 Opus 音频麦克风流 │ ├─────────────────────────────►│ │ ◄──── 0x01 回复音频 ────────│ ④ 全双工边听边说可被打断 │ ◄──── 0x02 逐词文字 ────────│ ⑤ 同步文字转写 │ 0x06 ping 保活10s 无消息客户端主动断开 ├─────────────────────────────►│关键细节server.py握手帧0x00之前别发音频——此时服务器正在加载音色与角色 Prompt音频为Opus 编码、24kHz 单声道流式分片客户端侧解码见 decoderWorker.ts客户端侧 10 秒收不到任何消息会判定断线useSocket.ts所以空闲时记得发0x06ping 或保持音频流发送会话结束任一方关闭连接后服务器会复位流式状态可立即开启下一轮会话。常见问题 FAQQ1连接立刻断开多半是voice_prompt文件名写错注意带.pt后缀或text_prompt参数缺失。对照 server.py 的服务端校验逻辑排查。Q2GPU 显存不够怎么办启动时加--cpu-offload参数需先pip install accelerate把 LM 层卸载到 CPU详见 README.md。Q3一次能开多个会话吗服务端通过全局锁串行处理server.py同一时间只能有一个活跃对话第二个连接需等第一个结束。Q4如何复现某次有趣的对话连接时传seed固定整数并保持text_prompt/voice_prompt一致即可复现。Q5本地运行需要装什么安装 Opus 开发库如sudo apt install libopus-dev然后pip install moshi/.完整步骤见 README.md。小结你要做的事记住这一点发起连接GET /api/chatQuery 传voice_prompttext_prompt可选seed选音色NAT 系自然、VAR 系多变共 16 个.pt文件收发数据二进制帧首字节 0x00–0x06 定类型保活空闲 10 秒内发0x06ping掌握以上参数与协议你就能脱离 Web UI用任意语言写一个属于自己的全双工语音对话客户端了。【免费下载链接】personaplexPersonaPlex code.项目地址: https://gitcode.com/GitHub_Trending/pe/personaplex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
