PersonaPlex /api/chat WebSocket API 参考：全参数完整文档
【免费下载链接】personaplexPersonaPlex code.项目地址: https://gitcode.com/GitHub_Trending/pe/personaplex
PersonaPlex 是一个实时、全双工的语音对话大模型（基于 Moshi 架构），你可以对着麦克风与它"自然说话"，它还能被打断、能抢话、能同步输出文字。本文以/api/chat WebSocket 接口为核心，用表格和流程图讲清楚：连接参数、16 种音色、二进制消息协议和常见问题，帮新手快速接入自己的语音对话客户端。
一分钟看懂 PersonaPlex 架构
一句话理解数据流向：
- 浏览器（或你的客户端）通过WebSocket把Opus 编码的音频流发给服务器；
- 服务器上的 Mimi 编码器把音频变成 token，LM（语言模型）结合角色 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.md）：
SSL_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.py）；seed为-1或省略时不固定随机性。
采样参数（客户端会发送，当前服务端暂未启用）
官方 Web 客户端还会发送以下采样参数（定义见 useModelParams.ts），服务端对应解析代码目前处于注释状态（server.py）。了解它们的默认值和取值范围，便于阅读源码和后续对接：
| 参数 | 默认值 | 取值范围 | 含义 |
|---|---|---|---|
text_temperature | 0.7 | 0.2 – 1.2 | 文本 token 采样温度，越高越发散 |
text_topk | 25 | 10 – 500 | 文本候选集大小 |
audio_temperature | 0.8 | 0.2 – 1.2 | 音频 token 采样温度 |
audio_topk | 250 | 10 – 500 | 音频候选集大小 |
pad_mult | 0 | -4 – 4 | 静音帧概率调节 |
repetition_penalty | 1.0 | 1.0 – 2.0 | 重复惩罚系数，调大可减少"复读机" |
repetition_penalty_context | 64 | 0 – 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.txt：
You 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 内容 |
|---|---|---|---|
0x00 | handshake 握手 | 服务端 → 客户端 | 版本 + 模型标识（各 1 字节，均为 0） |
0x01 | audio 音频 | 双向 | Opus 音频字节流（客户端发麦克风，服务端回说话声） |
0x02 | text 文字 | 服务端 → 客户端 | UTF-8 编码的逐词转写文本 |
0x03 | control 控制 | 客户端 → 服务端 | 1 字节：start / endTurn / pause / restart |
0x04 | metadata | 双向 | JSON 序列化的元数据 |
0x05 | error | 服务端 → 客户端 | UTF-8 错误信息 |
0x06 | ping | 客户端 → 服务端 | 无 payload，保活用 |
控制帧的具体动作位（types.ts）：start=0b00、endTurn=0b01、pause=0b10、restart=0b11。
连接生命周期：一次完整会话的流程
客户端 服务器 │ GET /api/chat?voice_prompt=NATF0.pt&text_prompt=...&seed=42 ├─────────────────────────────►│ │ │ ① 加载音色 + 编码角色 Prompt │ │ ② 模型跑完 system prompt 预热 │ ◄────────── 0x00 握手帧 ────│ ③ 发送握手（可开始说话） │ 0x01 Opus 音频（麦克风流） │ ├─────────────────────────────►│ │ ◄──── 0x01 回复音频 ────────│ ④ 全双工：边听边说，可被打断 │ ◄──── 0x02 逐词文字 ────────│ ⑤ 同步文字转写 │ 0x06 ping 保活（10s 无消息客户端主动断开） ├─────────────────────────────►│关键细节（server.py）：
- 握手帧
0x00之前别发音频——此时服务器正在加载音色与角色 Prompt； - 音频为Opus 编码、24kHz 单声道流式分片，客户端侧解码见 decoderWorker.ts；
- 客户端侧 10 秒收不到任何消息会判定断线（useSocket.ts），所以空闲时记得发
0x06ping 或保持音频流发送； - 会话结束（任一方关闭连接）后服务器会复位流式状态，可立即开启下一轮会话。
常见问题 FAQ
Q1：连接立刻断开？多半是voice_prompt文件名写错（注意带.pt后缀）或text_prompt参数缺失。对照 server.py 的服务端校验逻辑排查。
Q2：GPU 显存不够怎么办？启动时加--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/chat，Query 传voice_prompt+text_prompt（+可选seed） |
| 选音色 | NAT 系自然、VAR 系多变，共 16 个.pt文件 |
| 收发数据 | 二进制帧，首字节 0x00–0x06 定类型 |
| 保活 | 空闲 10 秒内发0x06ping |
掌握以上参数与协议，你就能脱离 Web UI，用任意语言写一个属于自己的全双工语音对话客户端了。
【免费下载链接】personaplexPersonaPlex code.项目地址: https://gitcode.com/GitHub_Trending/pe/personaplex
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
