远程主机

一台机器有 GPU、另一台机器上是你日常使用的 Mizuoto 时，可以让某个引擎在有 GPU 的机器上运行。有 GPU 的一方运行 mizuoto agent（下文称 agent），日常使用的一方（下文称 主机）把它添加为远程主机，再把引擎的设备设为 <主机名>/<设备>，例如 gpu-box/cuda:0。之后合成、流式播放和取消都与在本机运行时一样，只是引擎以及它加载的模型在 agent 上运行。

# 在 GPU 机器上（与这里相同的 Mizuoto 版本，装好 torch；它有自己的模型）：
mizuoto doctor
mizuoto model download qwen3tts/1.7b-base
mizuoto agent --host 0.0.0.0                 # 打印它生成的令牌

# 在本机：
mizuoto remote add gpu-box 192.168.1.20 --token <令牌>
mizuoto remote use qwen3tts gpu-box --device cuda:0
mizuoto speak "你好，世界。" -m qwen3tts/1.7b-base -v "我的音色"

什么在哪里运行复制锚点链接

• 模型状态来自 agent。 对设备指向远程主机的引擎，模型是否“已安装”取决于 agent 上已安装的模型列表（主机每 15 秒左右重新询问一次），而不是本机的模型文件夹。模型要在 agent 上用它自己的 mizuoto 命令安装。
• 两台机器运行相同的 Mizuoto 版本。 Mizuoto 0.2 使用第 2 版 agent 协议，以“已加载的引擎”为单位工作（加载、准备音色、合成、转换、编辑）。协议版本不同的主机和 agent 会在握手时互相拒绝，并提示在两台机器上安装相同版本的 Mizuoto。
• 文件按内容传送。 请求里用到的文件（参考音频、情感参考音频等）按 SHA-256 发送：agent 已经有的不再发送，没有的分块（每块 8 MB）上传一次。agent 启动时删除一个月内没有被任何主机用到的文件。
• 音色缓存会传回本机。 引擎为音色准备的缓存（第一次使用某个音色时生成）写在 agent 上，随结果逐个文件传回，保存在本机音色的缓存文件夹里；之后使用同一音色时直接读取。
• 流式输出、流式文本输入和取消都可用。 音频片段一生成就从 agent 传回；取消请求会转发给 agent 上的引擎。
• 训练留在本机。 引擎在远程主机上时，训练方法会说明原因：<engine> runs on <host>, and training runs on this machine: mizuoto remote use <engine> --local。

agent：提供引擎的机器复制锚点链接

mizuoto agent [--host 地址] [--port 端口] [--token 令牌] [--ssl-certfile 证书] [--ssl-keyfile 私钥]

• agent 使用这台机器自己的数据文件夹（设置、模型、缓存），和这台机器上的 mizuoto webui 一样；要让它用另一个文件夹，设置环境变量 MIZUOTO_DATA_DIR。引擎运行在 agent 自己的进程里。

• 第一次启动且没有令牌时，agent 生成一个随机令牌，保存为 remote.agent.token，并在终端上打印：

  复制文字

  Made a token and saved it (remote.agent.token): <令牌>
  Mizuoto agent on 0.0.0.0:7870: asr, qwen3tts
  On the host: mizuoto remote add <name> <this machine>:7870 --token …

  第二行列出在那里可用的引擎。之后再启动会沿用保存的令牌；想查看它，打开那台机器的 settings.toml（mizuoto config path）。

• 监听非本机地址又没有 TLS 时，agent 会警告：

  复制文字

  warning: without TLS, requests and audio cross the network unencrypted; use a private network or a tunnel

• agent 在前台运行，直到 Ctrl+C。它自己的空闲卸载、显存处理等遵循那台机器的设置（compute.*、engines.<id>.*）。端口被占用时启动失败，提示换一个 --port。

• 需要接受许可的引擎（Fish Speech、IndexTTS）：在 agent 上安装它们的包（mizuoto-fishspeech、mizuoto-indextts），并在下载模型前在 agent 上接受许可（mizuoto engine accept-licence <id>）；在主机上合成前，主机上也要接受。

主机：使用远程引擎的机器复制锚点链接

添加主机复制锚点链接

mizuoto remote add gpu-box 192.168.1.20 --token <令牌>
mizuoto remote add gpu-box gpu.example.com:7870 --token <令牌> --tls --ca-file ./agent.pem

把引擎放到主机上复制锚点链接

mizuoto remote use qwen3tts gpu-box --device cuda:0   # 等于 engines.qwen3tts.device = "gpu-box/cuda:0"
mizuoto remote use qwen3tts gpu-box                   # 设备 auto：由 agent 选择
mizuoto remote use qwen3tts --local                   # 回到本机运行（device = "auto"）

引擎在远程主机上时，引擎卡片和模型行标注 在 gpu-box 上（主机名），并提示：引擎 其依赖由 gpu-box 管理：在那里运行 mizuoto doctor qwen3tts；模型 这些是 gpu-box 上的模型：请在那里用 mizuoto model download 下载。

查看与移除复制锚点链接

mizuoto remote list          # 名称、地址、状态、版本、设备、已安装的引擎、使用它的引擎
mizuoto remote remove gpu-box

remote list 会重新连接每台主机。移除主机时，设备指向它的引擎改回 auto，回到本机运行。

出错时复制锚点链接

超时：

安全复制锚点链接

• 每个连接先发送令牌，agent 用恒定时间比较；令牌错误的连接立即关闭。
• 不开 TLS 时，请求、参考音频和合成的音频以明文经过网络。只在可信的局域网里这样用，或者经过 VPN、SSH 隧道，或者给 agent 配置证书（--ssl-certfile）并在主机上加 --tls。
• agent 使用自签名证书时，在主机上用 --ca-file 给出这份证书；这种情况下不检查证书中的主机名。不给 --ca-file 时使用系统的 CA。
• 令牌不会出现在 mizuoto config show 和接口返回的设置里，只显示是否已设置。

HTTP 接口复制锚点链接

接口的通用约定见 HTTP 接口，相关设置见 配置与环境变量。