安装前先确认使用方式

Fish Audio 常用于AI语音生成、音色实验、文本转语音和语音工作流集成。

macOS 用户在配置前应先确认目标：如果只是偶尔生成语音，网页端或接口调用更省事；如果希望在本机调试项目、批量处理素材、接入自己的脚本，则需要搭建本地运行环境。

两种方式并不冲突，建议新手先用在线控制台熟悉参数，再决定是否安装本地依赖。

macOS 设备主要分为 Apple Silicon 芯片机型和 Intel 芯片机型。

前者包括 M1、M2、M3、M4 系列，适合使用 arm64 原生环境，并可尝试调用 Metal 后端进行推理加速；后者通常以 CPU 运行为主，速度会慢一些，适合轻量测试、接口调用或较短文本处理。

安装前可点击左上角苹果图标，进入“关于本机”查看芯片类型和内存容量。

语音模型对内存较敏感，建议至少16GB内存，若需要处理较长音频或多任务运行，32GB以上更稳。

基础工具准备

本地配置通常需要 Homebrew、Git、Python 环境和 FFmpeg。

Homebrew 用于安装命令行工具，Git 用于获取项目文件，Python 用于运行推理脚本，FFmpeg 用于音频格式转换。

安装 Homebrew 后，可在终端执行 brew --version 检查是否可用；执行 git --version 检查 Git；执行 ffmpeg -version 检查音频工具是否安装成功。

Python 版本建议选择 3.10 或 3.11，优先使用 Miniforge、Mambaforge 或 pyenv 创建独立环境，避免与系统自带 Python 混用。

很多安装失败并不是项目问题，而是依赖被装进了错误的解释器。终端中可通过 which python、python --version、pip --version 确认路径是否指向当前环境。若输出路径位于项目专用环境目录中，说明环境隔离基本正确。

Apple Silicon 电脑配置步骤

Apple Silicon 机型建议全程使用 arm64 原生终端和 arm64 Python，不要混用旧架构依赖。

• 第一步：安装 Homebrew，确认路径通常为 /opt/homebrew/bin/brew。
• 第二步：安装基础组件，依次准备 git、ffmpeg、cmake 等工具。
• 第三步：创建独立 Python 环境，例如 conda create -n fishaudio python=3.10，随后执行 conda activate fishaudio 进入环境。
• 第四步：获取 Fish Audio 相关项目文件。若使用官方开放项目，可通过 Git 获取仓库；若使用官方服务接口，则按文档安装对应 SDK 或请求库。
• 第五步：安装 Python 依赖，通常执行 pip install -r requirements.txt。安装大模型框架时要特留意 Apple Silicon 兼容性，PyTorch 建议使用官方适配 macOS 的版本。安装后可在 Python 中检查 torch.backends.mps.is_available()，返回 True 代表可尝试使用 MPS 后端。
• 第六步：准备模型文件或接口凭据。本地模型应放在项目文档指定目录，路径不要包含特殊符号和过长中文目录名，减少读取异常。若使用接口方式，应把密钥写入环境变量或本地配置文件，不要直接写进公开脚本。
• 第七步：运行示例命令，先用一句短文本生成几秒钟音频，确认流程能跑通，再逐步提高文本长度、采样参数和并发数量。

Intel Mac 配置步骤

Intel 机型的安装思路类似，但重点是稳定而不是加速。

• 第一步：确认终端、Homebrew 和 Python 均为 x86_64 架构。
• 第二步：创建独立环境并安装依赖。
• 第三步：优先选择 CPU 可运行的推理参数，不要照搬 Apple Silicon 的 MPS 配置。
• 第四步：先测试短文本和低负载任务，观察内存、温度和运行时间。

Intel Mac 尤其是较早年份设备，运行大型语音模型可能出现速度慢、风扇长时间高转、内存占用过高等情况。此时更建议使用在线接口，把本机作为脚本调度和音频后处理环境。

若必须本地运行，可降低批量大小，缩短单次输入文本，关闭不必要的软件，并把输出格式统一为 wav 或 mp3 后再做后期处理。

常见参数与目录建议

目录结构

项目目录建议放在用户目录下的 Developer、Projects 或 AI 文件夹中，例如 ~/Projects/fish-audio，避免放在系统保护目录或云同步目录内。

模型文件、输入文本、输出音频最好分开放置，便于备份和排错。

音频素材建议统一采样率和格式，常见做法是用 FFmpeg 转成 wav，再进入后续处理流程。

API 调用与协作

如果使用 API 调用，建议把密钥放入 .env 文件或系统环境变量，并在版本管理中忽略该文件。

批量任务应加入失败重试、日志记录和输出文件命名规则，避免生成结果互相覆盖。

对团队协作而言，还应记录 Python 版本、依赖版本、模型版本和关键参数，后续升级或复现结果会方便很多。

安装失败与排查方法

依赖安装报错

依赖安装报错时，先看报错位置。

• 如果是 command not found，多半是 Homebrew、Git 或 FFmpeg 未安装，或环境变量未生效。
• 如果是 Python 版本不匹配，应重新创建指定版本环境。
• 如果是某个包编译失败，可先升级 pip、setuptools、wheel，再重试安装。
• Apple Silicon 上遇到架构不一致，可通过 arch 命令确认当前终端架构，必要时重新安装对应版本环境。

运行时报错

运行时报模型找不到，通常是路径配置错误、文件未下载完整或目录层级不符合项目要求。

音频无输出时，应检查输出目录是否有写入权限、文本是否为空、参数是否超出范围。

生成速度过慢不一定是故障，可能是模型较大或设备算力有限。

若使用接口方式，失败原因还可能包括额度不足、请求过于频繁、网络连接不稳定或参数格式不符合文档。

升级、回退与备份建议

AI语音工具迭代较快，升级前不要直接覆盖可用环境。

稳妥做法：先记录当前项目提交版本、依赖清单和模型文件版本，再新建一个测试环境验证。

若升级后输出质量变化明显或脚本报错，可切回旧环境继续工作。

对已经投入生产的语音流程，建议把“可运行版本”和“测试版本”分开，避免临时升级影响交付。

备份时不必复制整个环境目录，通常保留项目配置、依赖清单、关键脚本、提示参数、音色授权说明和输出样例即可。

大型模型文件可单独存放，并记录来源、版本和校验信息。这样即使重装系统，也能较快恢复。

安全边界与合规提醒

使用 Fish Audio 处理语音时，应确保文本、音频样本和音色素材来源清晰。

不要使用未获许可的个人声音进行商业发布，也不要把生成内容用于误导他人、冒充身份或制造虚假证明。

企业场景下，建议建立素材登记表，注明来源、授权范围、使用期限和负责人。

本地项目不要随意运行来历不明的脚本，尤其是要求输入账号密钥、读取全盘文件或修改系统设置的内容。

安装依赖时优先参考官方文档和可信仓库，密钥不要提交到公开代码平台。

生成结果发布前应人工审核，重点检查读音、语气、敏感表达和版权归属，必要时加入明确的合成语音提示。

实用建议

新手可按“网页端试用、接口接入、本地部署”的顺序推进，不必一开始就追求完整本地化。

Apple Silicon 用户优先选择原生 arm64 环境，Intel 用户更适合轻量测试或远程接口方案。

无论哪种机型，都要养成环境隔离、版本记录、短文本先测、批量任务留日志的习惯。

这样既能提高安装成功率，也能在后续升级、迁移和故障处理中节省大量时间。