在Mac上部署广听AI(kouchou-ai)的完整指南

广听AI(kouchou-ai)是一个面向公众参与的智能对话系统，本文将详细介绍如何在Mac环境下进行非开发人员的本地部署。通过Docker容器化技术，即使没有编程背景的用户也能轻松搭建和使用这个AI系统。

系统要求与准备工作

在开始部署前，请确保您的Mac满足以下基本要求：

硬件要求：

• Mac电脑（Intel或Apple Silicon芯片均可）
• 至少8GB内存（推荐16GB以获得更好体验）
• 20GB可用磁盘空间

软件要求：

• macOS Catalina(10.15)或更高版本
• 稳定的互联网连接
• 有效的OpenAI API密钥

网络要求：

• 能够访问OpenAI API服务的网络环境
• 建议使用有线网络或稳定的Wi-Fi连接

详细部署步骤

第一步：安装Docker Desktop

Docker是容器化技术的代表，它能让广听AI系统在隔离的环境中运行，避免与您电脑上的其他软件产生冲突。

1. 访问Docker官网下载Mac版Docker Desktop
2. 双击下载的.dmg文件，按照向导完成安装
3. 安装完成后，在应用程序文件夹中找到并启动Docker
4. 等待Docker图标在菜单栏显示为绿色运行状态

验证安装： 打开终端(Terminal)，输入以下命令：

docker --version

如果显示Docker版本信息，说明安装成功。

第二步：获取广听AI软件包

1. 下载最新稳定版的广听AI发布包
2. 将下载的zip文件解压到您选择的目录（建议使用英文路径）
3. 记住解压后的文件夹位置，后续步骤需要用到

第三步：准备OpenAI API密钥

广听AI需要OpenAI的API密钥才能提供智能对话服务。

1. 登录OpenAI平台创建API密钥
2. 建议账户中充值至少5美元额度（具体取决于您的使用频率）
3. 妥善保存您的API密钥，不要在公共场合泄露

安全提示：API密钥相当于您的"信用卡"，请勿分享给他人或上传到任何公开平台。

第四步：运行安装脚本

1. 打开终端应用程序（可在Spotlight搜索"终端"找到）
2. 使用cd命令导航到解压的广听AI文件夹：

   cd /path/to/kouchou-ai-folder
   

3. 给安装脚本添加执行权限：

   chmod +x setup_mac.sh
   

4. 执行安装脚本：

   ./setup_mac.sh
   

5. 根据提示输入您的OpenAI API密钥
6. 等待安装过程自动完成（首次运行可能需要10-15分钟）

安装过程说明：

• 脚本会自动下载所需的Docker镜像
• 配置必要的环境变量
• 构建并启动广听AI服务容器

第五步：访问广听AI系统

安装完成后，您可以通过以下地址访问系统：

• 用户界面：http://localhost:3000 （这是普通用户查看报告和进行交互的界面）

• 管理后台：http://localhost:4000 （这是管理员配置系统参数和查看详细数据的界面）

使用建议： 首次访问时，建议先浏览管理后台，了解系统功能和配置选项。

日常使用与维护

启动与停止服务

启动服务：

./start_mac.sh

或通过Docker Desktop界面手动启动相关容器。

停止服务：

./stop_mac.sh

或通过Docker Desktop界面停止容器。

更新API密钥

如需更换OpenAI API密钥：

1. 先停止运行中的服务
2. 重新运行安装脚本：

   ./setup_mac.sh
   

3. 输入新的API密钥
4. 系统会自动重新配置并启动

注意：重新运行安装脚本会覆盖之前的配置，但不会影响已存储的数据。

常见问题解决

Docker相关问题

症状：Docker无法启动或报错 解决方案：

1. 检查Docker Desktop是否获得必要的系统权限
2. 尝试重启Docker服务
3. 确保没有其他程序占用Docker所需的端口

资源不足问题

症状：系统运行缓慢或崩溃 解决方案：

1. 打开Docker Desktop设置
2. 调整资源分配：
   • 内存：至少4GB（推荐8GB）
   • CPU：至少2核（推荐4核）
3. 重启Docker服务

API密钥无效

症状：系统无法连接AI服务 解决方案：

1. 确认API密钥输入正确
2. 检查OpenAI账户是否有足够余额
3. 确保网络可以访问OpenAI API

最佳实践建议

1. 定期备份：虽然广听AI的数据存储在容器中，但建议定期导出重要数据
2. 监控使用量：关注OpenAI API的使用情况，避免意外超额
3. 系统更新：关注广听AI的版本更新，及时获取新功能和性能改进
4. 安全防护：不要在公共网络环境下使用默认配置运行系统

通过以上步骤，您应该已经成功在Mac上部署了广听AI系统。这套系统将帮助您收集和分析公众意见，为决策提供数据支持。如果在使用过程中遇到任何问题，可以参考项目文档或寻求技术支持。