From cc9c6b6cfe49c6d9e6f84247b785ac08a2c808f5 Mon Sep 17 00:00:00 2001 From: Arcitec <38923130+Arcitec@users.noreply.github.com> Date: Thu, 18 Sep 2025 18:51:43 +0200 Subject: [PATCH 1/3] docs: Clarify that UV handles Python and the environment creation - Some users have been confused and were manually creating and activating Python venvs, which is not good since it can lead to the wrong Python version or dependency conflicts. - Therefore, we add more detailed guidance to explain that `uv` manages the whole environment, the Python version, all dependencies and automatic environment activation. - A few users were also confused about where `uv tool` installs binaries, but instead of explaining that in depth, we now add a link to the documentation page which explains how it works, and also instruct users to carefully read the `uv tool` output since it tells them how to add the installation to the system's path. --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fb26c46..6fc84f6 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,8 @@ git lfs pull # download large repository files 4. Install required dependencies: We use `uv` to manage the project's dependency environment. The following command -will install the correct versions of all dependencies into your `.venv` directory: +will *automatically* create a `.venv` project-directory and then installs the correct +versions of Python and all required dependencies: ```bash uv sync --all-extras @@ -208,7 +209,7 @@ uv sync --all-extras --default-index "https://mirrors.tuna.tsinghua.edu.cn/pypi/ > please ensure that you have installed NVIDIA's [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit) > version **12.8** (or newer) on your system. -5. Download the required models: +5. Download the required models via [uv tool](https://docs.astral.sh/uv/guides/tools/#installing-tools): Download via `huggingface-cli`: @@ -226,14 +227,16 @@ uv tool install "modelscope" modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints ``` +> [!IMPORTANT] +> If the commands above aren't available, please carefully read the `uv tool` +> output. It will tell you how to add the tools to your system's path. + > [!NOTE] > In addition to the above models, some small models will also be automatically > downloaded when the project is run for the first time. If your network environment > has slow access to HuggingFace, it is recommended to execute the following > command before running the code: > -> 除了以上模型外，项目初次运行时还会自动下载一些小模型，如果您的网络环境访问HuggingFace的速度较慢，推荐执行： -> > ```bash > export HF_ENDPOINT="https://hf-mirror.com" > ``` @@ -277,6 +280,10 @@ Have fun! > make it slower. The performance impact is highly dependent on your specific > hardware, drivers and operating system. Please try with and without it, > to discover what works best on your personal system. +> +> Lastly, be aware that *all* `uv` commands will **automatically activate** the correct +> per-project virtual environments. Do *not* manually activate any environments +> before running `uv` commands, since that could lead to dependency conflicts! #### 📝 Using IndexTTS2 in Python From ae5653986c35858d48d2205b48d67bc64437054a Mon Sep 17 00:00:00 2001 From: Arcitec <38923130+Arcitec@users.noreply.github.com> Date: Fri, 19 Sep 2025 02:35:27 +0200 Subject: [PATCH 2/3] chore: Note why package build isolation was disabled for DeepSpeed --- pyproject.toml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index b79bad9..1f67e94 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -88,6 +88,10 @@ build-backend = "hatchling.build" [tool.uv] # Disable build isolation when building DeepSpeed from source. +# NOTE: This is *necessary* so that DeepSpeed builds directly within our `.venv`, +# and finds our CUDA-enabled version of PyTorch, which DeepSpeed *needs* during +# its compilation to determine what GPU support to compile for itself. It also +# saves time, since it won't waste time downloading a generic PyTorch version. no-build-isolation-package = ["deepspeed"] [tool.uv.sources] From 5471d8256fc7867772030b1c0c75fe633f49ea76 Mon Sep 17 00:00:00 2001 From: Arcitec <38923130+Arcitec@users.noreply.github.com> Date: Fri, 19 Sep 2025 21:11:31 +0200 Subject: [PATCH 3/3] docs: Install HuggingFace CLI with high-speed download feature The Xet storage method uses de-duplication and chunked downloads to speed up transfers in some situations: https://pypi.org/project/hf-xet/ But most importantly, installing the Xet support gets rid of some annoying HuggingFace CLI messages about missing the feature. --- README.md | 2 +- docs/README_zh.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6fc84f6..afc5989 100644 --- a/README.md +++ b/README.md @@ -214,7 +214,7 @@ uv sync --all-extras --default-index "https://mirrors.tuna.tsinghua.edu.cn/pypi/ Download via `huggingface-cli`: ```bash -uv tool install "huggingface_hub[cli]" +uv tool install "huggingface-hub[cli,hf_xet]" hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints ``` diff --git a/docs/README_zh.md b/docs/README_zh.md index 534adc4..1407449 100644 --- a/docs/README_zh.md +++ b/docs/README_zh.md @@ -185,7 +185,7 @@ uv sync --all-extras --default-index "https://mirrors.tuna.tsinghua.edu.cn/pypi/ HuggingFace下载： ```bash -uv tool install "huggingface_hub[cli]" +uv tool install "huggingface-hub[cli,hf_xet]" hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints ```