Skip to content

FunASR-powered video transcription, subtitle generation, and LLM-assisted clipping tool with a local Gradio UI.

docs: document tested Conda CPU installation

zhifu gao2937b995d787
diff --git a/docs/installation.md b/docs/installation.md
index 346c917..d9baf4f 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -34,6 +34,39 @@ py -3.12 -m venv .venv
`--help` checks imports and argument parsing without downloading a model or starting a public service. It does not verify transcription or video export. A successful `pip check` only checks declared dependency compatibility, not native-library loading, model downloads or inference.
+### Conda Alternative (Linux x86-64 CPU)
+
+Conda is also supported; uv is not required. With Conda already installed, run
+the following from the repository root instead of creating the `.venv` above.
+Use a new environment name if `funclip` already belongs to another application.
+
+```bash
+conda create -n funclip --override-channels -c conda-forge python=3.12 pip -y
+conda run -n funclip python -m pip install --index-url https://download.pytorch.org/whl/cpu "torch==2.10.0" "torchaudio==2.10.0"
+conda run -n funclip python -m pip install --no-compile -r requirements.txt
+conda run -n funclip python -m pip check
+conda run --no-capture-output -n funclip python funclip/launch.py --help
+```
+
+`conda run -n funclip` keeps installation and execution in the same environment
+without depending on shell activation. `--no-compile` skips Python bytecode
+precompilation, not dependencies or compatibility checks. If installation is
+interrupted, inspect its final error and `python -m pip check` in this environment
+before continuing; an installer report or a downloaded wheel alone is not proof
+that the package was installed successfully.
+
+The isolated CPU setup was checked with Conda 26.9.4, Python 3.12.16 and
+torch/torchaudio 2.10.0+cpu; see the [validation scope and environment caveat in
+#230](https://github.com/modelscope/FunClip/issues/230#issuecomment-6550482593).
+This is not a CUDA, Windows or macOS recipe. The installation, native imports,
+CLI/Gradio checks and synthetic media I/O do not establish pretrained ASR quality
+or a complete recognition-to-clipping workflow.
+
+After the checks pass, launch with
+`conda run --no-capture-output -n funclip python funclip/launch.py`. Unlike
+`--help`, normal startup may download models and start the configured service.
+Confirm `ffmpeg -version` also works; install FFmpeg for your platform if absent.
+
### If Installation Or Startup Fails
**`CERTIFICATE_VERIFY_FAILED` during pip install:** fix the HTTPS trust failure first. It means the package download did not complete, so a later `No module named 'funasr'` is not evidence that requirements omitted the package. Check the failing hostname, system clock, proxy and configured package indexes. Use certificates supplied by your OS/Python distribution or an approved corporate CA; never disable certificate verification or make arbitrary hosts trusted to get an install through. Pip supports an approved CA bundle through `--cert`/`PIP_CERT`; see its [certificate documentation](https://pip.pypa.io/en/stable/topics/https-certificates/).
@@ -49,6 +82,19 @@ python -m pip check
Use that same `python` to launch FunClip. An IDE, notebook or shell may otherwise use another interpreter even if a bare `pip` command succeeded.
+**A fresh environment still loads another PyTorch installation's libraries:**
+preconfigured Linux deep-learning images may inject a system `torch/lib` path
+through `LD_LIBRARY_PATH`. Even when `pip check` passes and the Python package
+path is correct, this can mix an environment's CPU wheel with host CUDA libraries
+and fail with errors such as a missing `torch._C._dlpack_exchange_api`.
+Compare the Python executable/package path and the shared libraries actually
+loaded by that process. If a foreign PyTorch library directory is confirmed,
+exclude only that conflicting entry from the affected launch command's child
+environment, after Conda activation. Do not globally clear `LD_LIBRARY_PATH`:
+other entries may be needed by FFmpeg or unrelated services. Then recheck native
+imports, `ffmpeg -version` and `--help`; this diagnosis does not imply every
+import error has the same cause.
+
**The traceback already enters `site-packages/funasr`:** the package was found. Capture the complete exception, especially its final line; do not keep installing packages based only on intermediate `pkgutil` or import-stack frames. Check the import separately, then the application:
```bash
@@ -74,12 +120,43 @@ Windows 可以使用上面的完整 `.venv\Scripts\python.exe` 路径,不必
`python funclip/launch.py --help` 只检查导入与参数解析,不下载模型、不启动公网服务,也不证明识别或视频导出成功。`pip check` 只检查依赖声明是否兼容,不能代替动态库加载、模型下载或真实推理测试。
+### 使用 Conda(Linux x86-64 CPU)
+
+不需要安装 uv。已有 Conda 时,可以在仓库根目录执行上面的
+[Conda 命令](#conda-alternative-linux-x86-64-cpu),替代 `.venv` 方案。
+如果 `funclip` 环境名已被其他应用使用,请换一个新名字,并同步修改全部
+`conda run -n` 命令,避免覆盖原有服务环境。
+
+这条路径使用 Python 3.12,先从官方 CPU 索引安装匹配的 torch/torchaudio
+2.10.0,再安装仓库依赖。`conda run -n funclip` 保证安装、检查和启动使用
+同一个解释器,不依赖当前 shell 是否激活了环境。`--no-compile` 只省略
+Python 字节码预编译,不跳过依赖或兼容性检查。安装中断后,应先查看最后
+的异常并在同一环境运行 `python -m pip check`;下载完成或生成安装报告
+不等于安装成功。
+
+实际验证使用 Conda 26.9.4 / Python 3.12.16 / torch、torchaudio
+2.10.0+cpu;范围及验证机的动态库注意事项见 [#230 的实测回复](https://github.com/modelscope/FunClip/issues/230#issuecomment-6550482593)。
+安装、导入、CLI/Gradio 和合成媒体读写通过,不代表预训练 ASR 质量或完整
+识别到剪辑流程已经验收;GPU、Windows、macOS 需要各自的平台配置与验证。
+检查通过后可用 `conda run --no-capture-output -n funclip python funclip/launch.py`
+启动,正常启动可能下载模型并启动配置的服务。还应确认 `ffmpeg -version`
+成功,缺失时先安装对应平台的 FFmpeg。
+
### 按报错阶段处理
**安装时出现 `CERTIFICATE_VERIFY_FAILED`:** 先处理 HTTPS 证书信任问题。下载未完成,后续出现 `No module named 'funasr'` 并不说明依赖清单漏了这个包。检查失败域名、系统时间、代理和 pip 源;使用操作系统/Python 发行版提供的证书,企业代理则使用经管理员认可的 CA。不要通过关闭校验或随意信任主机绕过错误。受信任 CA 的 `--cert`/`PIP_CERT` 配置见 [pip 官方证书说明](https://pip.pypa.io/en/stable/topics/https-certificates/)。
**安装成功却找不到模块:** 运行英文部分的解释器和版本检查命令。确认 `sys.executable`、`python -m pip --version` 指向同一个虚拟环境,再用相同的 `python` 启动。不要把另一个 shell、IDE 或 notebook 的安装结果当成当前环境已经装好。
+**新环境仍加载了另一套 PyTorch 动态库:** Linux 深度学习预装镜像可能通过
+`LD_LIBRARY_PATH` 注入系统 `torch/lib`。即使 `pip check` 通过、Python 包路径
+也正确,CPU wheel 仍可能错载宿主 CUDA 库,出现
+`torch._C._dlpack_exchange_api` 缺失等错误。先核对解释器、包路径和进程实际
+加载的动态库;确认是外部 PyTorch 目录冲突后,只在受影响启动命令的子进程
+环境中、Conda 激活之后排除该条目录。不要全局清空 `LD_LIBRARY_PATH`,其他
+目录可能供 FFmpeg 或其他服务使用。随后重新检查真实导入、`ffmpeg -version`
+和 `--help`,不能把所有导入错误都归为这个原因。
+
**调用栈已经进入 `site-packages/funasr`:** 包已经被找到,不能仅凭中间的 `pkgutil`/导入堆栈判断缺少哪个依赖。先运行上面的独立 `AutoModel` 导入检查,再执行 `--help`,保留包含最后一行异常的完整 traceback。[#147](https://github.com/modelscope/FunClip/issues/147) 的两张截图分别属于证书失败和已进入 FunASR 的导入失败,不能当作同一个问题。
需要检查代理或源配置时,在本机查看 `python -m pip config debug`。公开日志前,删除账号密码、token、代理凭据和私有源地址;提供 FunClip commit、操作系统、解释器与包版本、完整命令和 traceback。报告者尚未完成原环境复测时,诊断或文档更新不等于问题已经解决。