BILIVE常见问题解决方案：从安装到运行的全方位排错指南
BILIVE常见问题解决方案：从安装到运行的全方位排错指南
BILIVE是一款功能强大的B站直播录制工具，能够实现7x24小时无人监守录制、渲染弹幕、识别字幕、自动切片、自动上传等功能，且兼容超低配置机器。本文将为您提供从安装到运行过程中的常见问题解决方案，帮助您快速排查并解决使用过程中遇到的各种难题。
一、安装阶段常见问题及解决方法
1.1 克隆项目失败
问题描述：执行git clone --recurse-submodules https://gitcode.com/gh_mirrors/bi/bilive命令时，出现克隆失败或子模块拉取不完整的情况。
解决方法：
- 检查网络连接是否正常，确保能够访问GitCode仓库。
- 如果网络不稳定，可以分两步进行：先克隆主项目
git clone https://gitcode.com/gh_mirrors/bi/bilive，然后进入项目目录执行git submodule update --init --recursive拉取子模块。
1.2 依赖安装错误
问题描述：运行pip install -r requirements.txt时，出现依赖安装失败或版本冲突的问题。
解决方法：
- 确保使用Python 3.10版本，可通过
python --version命令检查。 - 创建虚拟环境隔离依赖，执行
python -m venv venv，然后激活虚拟环境（Windows：venv\Scripts\activate，Linux/Mac：source venv/bin/activate），再安装依赖。 - 对于aarch64架构的用户，由于PyPI上没有triton库的release版本，需要在安装时注释掉requirements.txt中的triton依赖。
1.3 FFmpeg安装问题
问题描述：程序运行时提示缺少FFmpeg。
解决方法：
- Ubuntu/Debian系统：执行
sudo apt-get install ffmpeg安装。 - CentOS系统：执行
sudo yum install ffmpeg安装。 - Windows系统：从FFmpeg官网下载对应版本，将可执行文件路径添加到系统环境变量中。
二、配置阶段常见问题及解决方法
2.1 whisper语音识别配置错误
问题描述：配置whisper语音识别时，出现无法识别或API调用失败的情况。
解决方法：
- 采用API方式：确保在bilive.toml文件中正确设置
asr_method = "api"，并填写有效的WHISPER_API_KEY。注意groq的free tier有请求限制，如遇限制可升级到dev tier。 - 采用本地部署方式：需保证有NVIDIA显卡且驱动安装正确，可通过
nvidia-smi和nvcc -V命令检查。下载所需模型文件并放置在src/subtitle/models文件夹中，确保GPU显存大于模型所需VRAM（如small模型至少需要2.7GB显存）。
2.2 MLLM模型和图像生成模型配置问题
问题描述：配置自动切片或自动生成视频封面功能时，出现模型无法调用或API key无效的问题。
解决方法：
- 确保在bilive.toml文件中正确设置
auto_slice = true（自动切片）和generate_cover = true（自动生成封面）。 - 根据选择的模型，在对应位置填写正确的API key，可参考官方文档获取各模型的API key申请方式。推荐使用DMXAPI，一个Key即可使用全球大模型。
BILIVE支持多种大模型API，通过DMXAPI可实现一个Key用全球大模型
三、运行阶段常见问题及解决方法
3.1 录制启动失败
问题描述：执行./record.sh后，录制服务无法启动或提示端口被占用。
解决方法：
- 检查RECORD_KEY环境变量是否设置，密码需由字母数字组成，长度在8-80位之间。可通过
export RECORD_KEY=your_password临时设置，或添加到.bashrc文件中持久化设置。 - 如提示端口被占用，可修改record.sh中的端口号，或使用
lsof -i :端口号查找占用进程并杀死。
3.2 上传功能异常
问题描述：执行./upload.sh后，视频无法上传或上传失败。
解决方法：
- 检查登录状态，确保已通过bilitool登录并导出cookie.json文件到项目根目录。对于源码部署，可执行
pip install bilitool后运行bilitool login --export扫码登录；对于Docker部署，可通过docker logs bilive_docker查看二维码扫码登录。 - 检查网络连接和上传线路设置，在bilive.toml中可将
upload_line设置为"auto"自动探测线路，或指定"bldsa"、"ws"等固定线路。
3.3 日志查看与问题排查
问题描述：程序运行异常但无明显错误提示。
解决方法：
- 如有异常，优先提供[debug]级别的日志，可在issue中提出问题并附上相关日志内容。
查看项目的日志文件，日志文件夹结构如下：
logs ├── record # blrec 录制日志 ├── scan # scan 处理日志 [debug]级别 ├── upload # upload 上传日志 [debug]级别 └── runtime # 每次执行的日志 [info]级别 四、Docker部署常见问题及解决方法
4.1 Docker容器启动失败
问题描述：执行Docker run命令后，容器无法启动或闪退。
解决方法：
- 检查挂载路径是否正确，确保本地路径存在且具有读写权限。
- 对于GPU版本，确保已安装nvidia-docker且显卡驱动正常，可通过
docker run --gpus all nvidia/cuda:11.0.3-base-ubuntu20.04 nvidia-smi测试GPU是否可用。
4.2 Docker Compose使用问题
问题描述：使用docker compose up -d启动时出现错误。
解决方法：
- 检查compose.yml文件中的配置是否正确，如需使用GPU版本，需在文件中添加相应的GPU配置。
- 执行
docker compose logs查看详细日志，定位错误原因。
五、获取更多帮助
如果您在使用BILIVE过程中遇到其他问题，除了查看官方文档外，还可以通过以下方式获取帮助：
- 加入项目交流群：微信搜一搜“AIShareLab”获取更多支持。
微信搜一搜“AIShareLab”加入BILIVE交流群获取帮助
希望本文能帮助您顺利解决BILIVE使用过程中的常见问题，让您的直播录制体验更加顺畅。如果您有其他问题或建议，欢迎提出issue交流。
