From 99fe66b08668ee160d92b2030dbb954391739a1f Mon Sep 17 00:00:00 2001 From: LauraGPT <18321252+LauraGPT@users.noreply.github.com> Date: Thu, 10 Sep 2026 12:32:01 +0000 Subject: [PATCH] docs: clarify isolated installation and startup failures Signed-off-by: LauraGPT <18321252+LauraGPT@users.noreply.github.com> --- .github/workflows/tests.yml | 2 +- CONTRIBUTING.md | 9 ++-- README.md | 16 +++--- README_zh.md | 16 +++--- docs/installation.md | 91 +++++++++++++++++++++++++++++++++ tests/test_github_templates.py | 2 +- tests/test_installation_docs.py | 41 +++++++++++++++ 7 files changed, 159 insertions(+), 18 deletions(-) create mode 100644 docs/installation.md create mode 100644 tests/test_installation_docs.py diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 480e545..1baf84d 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -34,4 +34,4 @@ jobs: python -m pip check - name: Test Gradio runtime compatibility - run: python -m pytest -q tests/test_gradio_runtime_compat.py + run: python -m pytest -q tests/test_gradio_runtime_compat.py tests/test_installation_docs.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27bff1b..9f3dadb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,19 +35,20 @@ When a fix needs a release, link the released version and ask the reporter to re ```bash git clone https://github.com/modelscope/FunClip.git cd FunClip -python3 -m venv .venv +python3.12 -m venv .venv source .venv/bin/activate -pip install -r requirements.txt +python -m pip install -r requirements.txt +python -m pip check ``` -FunClip's current Fun-ASR-Nano, SenseVoice, and subtitle compatibility paths require `funasr>=1.3.26`. +Install a matching PyTorch/torchaudio pair for your platform before the remaining requirements; see [installation and troubleshooting](docs/installation.md#english). Keep this environment separate from native Transformers 5.x examples. FunClip's current model and subtitle compatibility paths require `funasr>=1.4.9`. ## Validation Run the focused checks that match your change. For documentation, issue templates, package metadata, and provider-routing changes, start with: ```bash -python3 -m pytest -q tests/test_github_templates.py tests/test_funasr_requirement.py tests/test_openai_api.py +python -m pytest -q tests/test_github_templates.py tests/test_funasr_requirement.py tests/test_installation_docs.py tests/test_openai_api.py python3 -m py_compile funclip/launch.py funclip/videoclipper.py funclip/utils/subtitle_utils.py git diff --check ``` diff --git a/README.md b/README.md index dca0182..65ded3f 100644 --- a/README.md +++ b/README.md @@ -53,20 +53,24 @@ ### Python env install -FunClip basic functions rely on a python environment only. +Use a separate Python environment for FunClip. The commands below use Python 3.12; install a matching PyTorch/torchaudio pair for your platform before the remaining requirements. See the [installation and troubleshooting guide](docs/installation.md#english) for the Linux CPU recipe, Windows activation and certificate errors. ```shell -# clone funclip repo git clone https://github.com/modelscope/FunClip.git cd FunClip -# install Python requirments -pip install -r ./requirements.txt +python3.12 -m venv .venv +. .venv/bin/activate +python -m pip install -r requirements.txt +python -m pip check +python funclip/launch.py --help ``` +Keep this environment on the repository's **Transformers 4.x** requirements. Nano's separate native **Transformers 5.x** quickstart is not an upgrade command for an existing FunClip installation. + For a versioned snapshot, download [FunClip-2.2.1.tar.gz](https://github.com/modelscope/FunClip/releases/download/v2.2.1/FunClip-2.2.1.tar.gz) or [FunClip-2.2.1.zip](https://github.com/modelscope/FunClip/releases/download/v2.2.1/FunClip-2.2.1.zip), then verify it with the published [SHA256SUMS](https://github.com/modelscope/FunClip/releases/download/v2.2.1/SHA256SUMS). Model weights are downloaded separately when FunClip starts and are not included in these source archives. -FunClip v2.2.1 keeps the supported Gradio 4 runtime and renders built-in subtitles with Pillow so the selected foreground color survives video encoding. Existing installations should run `pip install -U -r requirements.txt` before restarting. +FunClip v2.2.1 keeps the supported Gradio 4 runtime and renders built-in subtitles with Pillow so the selected foreground color survives video encoding. Existing installations should run `python -m pip install -U -r requirements.txt` inside their FunClip environment before restarting. -FunClip's current model and subtitle compatibility paths require `funasr>=1.4.9`. This includes the MOSS vLLM adapter, long-audio generation controls, normalized `sentence_info` speaker segments, and the earlier SenseVoice and realtime fixes. If you installed FunClip before this requirement was updated, run `pip install -U "funasr>=1.4.9"` before starting the Gradio service. [Release notes](https://github.com/modelscope/FunASR/releases/tag/v1.4.9) · [PyPI](https://pypi.org/project/funasr/1.4.9/) +FunClip's current model and subtitle compatibility paths require `funasr>=1.4.9`. This includes the MOSS vLLM adapter, long-audio generation controls, normalized `sentence_info` speaker segments, and the earlier SenseVoice and realtime fixes. If you installed FunClip before this requirement was updated, run `python -m pip install -U "funasr>=1.4.9"` before starting the Gradio service. [Release notes](https://github.com/modelscope/FunASR/releases/tag/v1.4.9) · [PyPI](https://pypi.org/project/funasr/1.4.9/) ### imagemagick install (Optional) diff --git a/README_zh.md b/README_zh.md index c4a2edd..49a534a 100644 --- a/README_zh.md +++ b/README_zh.md @@ -55,20 +55,24 @@ ### Python环境安装 -FunClip的运行仅依赖于一个Python环境，若您是一个小白开发者，可以先了解下如何使用Python，pip等~ +为 FunClip 创建独立的 Python 环境。以下使用 Python 3.12；安装其余依赖前，请先安装适合当前平台且版本匹配的 PyTorch/torchaudio。[安装与排错指南](docs/installation.md#中文)提供 Linux CPU 示例、Windows 激活方式和证书错误的处理顺序。 ```shell -# 克隆funclip仓库 git clone https://github.com/modelscope/FunClip.git cd FunClip -# 安装相关Python依赖 -pip install -r ./requirements.txt +python3.12 -m venv .venv +. .venv/bin/activate +python -m pip install -r requirements.txt +python -m pip check +python funclip/launch.py --help ``` +此环境继续使用仓库要求的 **Transformers 4.x**。Nano 原生 **Transformers 5.x** 快速开始是另一条独立路径，不应直接用于升级已有 FunClip 环境。 + 如需固定版本，可下载 [FunClip-2.2.1.tar.gz](https://github.com/modelscope/FunClip/releases/download/v2.2.1/FunClip-2.2.1.tar.gz) 或 [FunClip-2.2.1.zip](https://github.com/modelscope/FunClip/releases/download/v2.2.1/FunClip-2.2.1.zip)，并使用发布页提供的 [SHA256SUMS](https://github.com/modelscope/FunClip/releases/download/v2.2.1/SHA256SUMS) 校验文件。模型权重会在 FunClip 启动时单独下载，不包含在源码归档中。 -FunClip v2.2.1 使用 Pillow 渲染可选字幕颜色，并继续在 Gradio 4 环境中要求 `starlette<1.0`。已有安装请在重启前执行 `pip install -U -r requirements.txt`。容器用户可用 `--listen` 监听全部网卡；只有同时显式传入 `--share` 才会创建 Gradio 公网分享链接。 +FunClip v2.2.1 使用 Pillow 渲染可选字幕颜色，并继续在 Gradio 4 环境中要求 `starlette<1.0`。已有安装请在 FunClip 环境中执行 `python -m pip install -U -r requirements.txt` 后重启。容器用户可用 `--listen` 监听全部网卡；只有同时显式传入 `--share` 才会创建 Gradio 公网分享链接。 -FunClip 当前模型与字幕兼容路径需要 `funasr>=1.4.9`，其中包括 MOSS 的 vLLM 适配器、长音频生成上限、归一化的 `sentence_info` 说话人分段，以及此前的 SenseVoice 和实时修复。如果你之前已经安装过 FunClip，请先执行 `pip install -U "funasr>=1.4.9"`，再启动 Gradio 服务。[发布说明](https://github.com/modelscope/FunASR/releases/tag/v1.4.9) · [PyPI](https://pypi.org/project/funasr/1.4.9/) +FunClip 当前模型与字幕兼容路径需要 `funasr>=1.4.9`，其中包括 MOSS 的 vLLM 适配器、长音频生成上限、归一化的 `sentence_info` 说话人分段，以及此前的 SenseVoice 和实时修复。如果你之前已经安装过 FunClip，请先执行 `python -m pip install -U "funasr>=1.4.9"`，再启动 Gradio 服务。[发布说明](https://github.com/modelscope/FunASR/releases/tag/v1.4.9) · [PyPI](https://pypi.org/project/funasr/1.4.9/) ### 安装 ImageMagick（可选） diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..346c917 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,91 @@ +# Installation And Startup / 安装与启动 + +[English](#english) · [中文](#中文) + +## English + +### Start In One Environment + +Run commands from the FunClip repository root. Use Python 3.12 for the example below, and keep FunClip separate from existing ASR services. Install a matching PyTorch/torchaudio pair for your platform using the [official PyTorch instructions](https://pytorch.org/get-started/locally/), then install this repository's requirements. + +Linux x86-64 CPU example, in a new environment: + +```bash +python3.12 -m venv .venv +. .venv/bin/activate +python -m pip install --index-url https://download.pytorch.org/whl/cpu \ + "torch==2.10.0" "torchaudio==2.10.0" +python -m pip install -r requirements.txt +python -m pip check +python funclip/launch.py --help +``` + +This is a CPU setup, not a CUDA recipe. For a GPU or another platform, select the appropriate matching pair before installing the remaining requirements; do not replace packages in a running production environment. Windows/macOS hardware and driver combinations need separate validation. + +On Windows, you can use the environment's Python directly without changing PowerShell's execution policy: + +```powershell +py -3.12 -m venv .venv +# Install the platform-appropriate torch/torchaudio pair into this environment first. +.\.venv\Scripts\python.exe -m pip install -r requirements.txt +.\.venv\Scripts\python.exe -m pip check +.\.venv\Scripts\python.exe funclip\launch.py --help +``` + +`--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. + +### 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/). + +**The package was installed, but this Python cannot find it:** compare the interpreter and pip paths before reinstalling anything: + +```bash +python -c "import sys; print(sys.executable); print(sys.version)" +python -m pip --version +python -m pip show funasr torch torchaudio gradio moviepy transformers +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. + +**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 +python -c "from funasr import AutoModel; print('FunASR import OK')" +python funclip/launch.py --help +``` + +For index/proxy diagnostics, inspect `python -m pip config debug` locally. Before posting output, redact credentials, tokens, proxy passwords and private index URLs. Include the FunClip commit, OS, interpreter/package versions, the failing command and the full traceback. A screenshot cut off before the final exception cannot establish the cause. These distinctions come from the two different failure paths reported in [#147](https://github.com/modelscope/FunClip/issues/147); that issue remains open for the original environments to be retested. + +### Keep The Two Transformers Routes Separate + +FunClip currently requires **Transformers 4.x** (`transformers<5.0`) and `huggingface_hub<1.0`. Its toolkit model, clipping and Gradio paths are not the same environment as the native Nano **Transformers 5.x** example. Installing the native example's requirements into FunClip can violate these constraints. + +For standalone native transcription, use a different virtual environment and the [native Transformers guide](https://www.funasr.com/en/docs/native-transformers.html). Native transcription alone does not provide FunClip's timestamp-based video clipping workflow. + +## 中文 + +### 先固定一个环境 + +在 FunClip 仓库根目录执行命令。上面的 Linux x86-64 CPU 示例使用 Python 3.12 和独立虚拟环境，先安装匹配的 PyTorch/torchaudio，再安装 `requirements.txt`。GPU、Windows 或 macOS 请按 [PyTorch 官方安装说明](https://pytorch.org/get-started/locally/)选择适合平台的匹配版本，不要直接替换正在运行的生产服务环境。 + +Windows 可以使用上面的完整 `.venv\Scripts\python.exe` 路径，不必修改 PowerShell 执行策略。后续安装、检查和启动都应使用同一个解释器。 + +`python funclip/launch.py --help` 只检查导入与参数解析，不下载模型、不启动公网服务，也不证明识别或视频导出成功。`pip check` 只检查依赖声明是否兼容，不能代替动态库加载、模型下载或真实推理测试。 + +### 按报错阶段处理 + +**安装时出现 `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 的安装结果当成当前环境已经装好。 + +**调用栈已经进入 `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。报告者尚未完成原环境复测时，诊断或文档更新不等于问题已经解决。 + +### 不混用 Transformers 环境 + +FunClip 当前依赖 **Transformers 4.x** 和 `huggingface_hub<1.0`，Nano 原生 **Transformers 5.x** 是另一条路径。不要在 FunClip 环境里直接执行原生示例的升级命令。 + +如果只需原生语音转写，请在另一个虚拟环境使用[原生 Transformers 指南](https://www.funasr.com/docs/native-transformers.html)。原生转写本身不提供 FunClip 所需的完整时间戳视频裁剪流程。 diff --git a/tests/test_github_templates.py b/tests/test_github_templates.py index d922f3e..3ff438e 100644 --- a/tests/test_github_templates.py +++ b/tests/test_github_templates.py @@ -52,7 +52,7 @@ def test_contributing_guide_documents_local_validation_path(): text = guide.read_text() required = [ "pip install -r requirements.txt", - "python3 -m pytest -q tests/test_github_templates.py tests/test_funasr_requirement.py tests/test_openai_api.py", + "python -m pytest -q tests/test_github_templates.py tests/test_funasr_requirement.py tests/test_installation_docs.py tests/test_openai_api.py", "python3 -m py_compile funclip/launch.py funclip/videoclipper.py funclip/utils/subtitle_utils.py", "Audio or video input", "Screenshots or clips", diff --git a/tests/test_installation_docs.py b/tests/test_installation_docs.py new file mode 100644 index 0000000..3ca5c3a --- /dev/null +++ b/tests/test_installation_docs.py @@ -0,0 +1,41 @@ +from pathlib import Path + +import pytest + + +ROOT = Path(__file__).resolve().parents[1] + + +@pytest.mark.parametrize("filename", ["README.md", "README_zh.md", "CONTRIBUTING.md"]) +def test_installation_entries_use_one_python_environment(filename): + text = (ROOT / filename).read_text() + assert "-m venv .venv" in text + assert "python -m pip install -r requirements.txt" in text + assert "python -m pip check" in text + assert "docs/installation.md" in text + + +def test_contributor_minimum_matches_application_requirements(): + requirement = next( + line for line in (ROOT / "requirements.txt").read_text().splitlines() + if line.startswith("funasr>=") + ) + assert requirement in (ROOT / "CONTRIBUTING.md").read_text() + + +def test_troubleshooting_keeps_tls_and_runtime_boundaries(): + guide = (ROOT / "docs/installation.md").read_text() + assert "CERTIFICATE_VERIFY_FAILED" in guide + assert "sys.executable" in guide + assert "python -m pip --version" in guide + assert "python -m pip config debug" in guide + assert "from funasr import AutoModel" in guide + assert "https://pip.pypa.io/en/stable/topics/https-certificates/" in guide + assert "https://www.funasr.com/docs/native-transformers.html" in guide + assert "https://www.funasr.com/en/docs/native-transformers.html" in guide + assert "Transformers 4.x" in guide and "Transformers 5.x" in guide + for block in guide.split("```")[1::2]: + if block.startswith(("bash\n", "shell\n", "powershell\n")): + assert "--trusted-host" not in block + assert "verify=False" not in block + assert "PIP_TRUSTED_HOST=" not in block