Unify CUDA 12.9 dependency environment

.dockerignore

@@ -5,13 +5,18 @@
 .idea
 
 # Python caches
+.venv/
+.uv-cache/
 __pycache__/
 *.pyc
 
 # Runtime data
 logs/
 output/
 data/
+test/
+tests/
+ui/storage/
 
 # Frontend artifacts
 **/node_modules/

.github/workflows/ci-smoke.yml

@@ -21,7 +21,15 @@ jobs:
           python-version: "3.12"
 
       - name: Install uv
-        run: python -m pip install --upgrade pip uv
+        run: python -m pip install --upgrade pip uv==0.12.0
+
+      - name: Validate dependency lock
+        run: |
+          uv lock --check
+          if grep -Eq 'name = "nvidia-cuda-(cccl|crt|nvcc|nvrtc|runtime|tileiras)"|nvidia-cutlass-dsl-libs-cu13|extra = \["cu13"\]' uv.lock; then
+            echo "CUDA 13 runtime/compiler dependency found in uv.lock"
+            exit 1
+          fi
 
       - name: Sync Python dependencies
         run: uv sync
@@ -52,3 +60,21 @@ jobs:
 
       - name: Build frontend
         run: npm run build
+
+  dependency-resolution:
+    name: Resolve unified all-extras environment
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: python -m pip install --upgrade pip uv==0.12.0
+
+      - name: Verify unified environment
+        run: uv sync --frozen --dry-run --no-dev --all-extras

Dockerfile

@@ -6,9 +6,9 @@ RUN npm ci
 COPY ui/frontend/ ./
 RUN npm run build
 
-FROM nvidia/cuda:13.1.1-base-ubuntu24.04
+FROM nvidia/cuda:12.9.1-base-ubuntu24.04
 
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.12.0 /uv /uvx /bin/
 
 ENV DEBIAN_FRONTEND=noninteractive \
     PYTHONUNBUFFERED=1 \
@@ -32,4 +32,4 @@ RUN uv sync --frozen --no-dev --all-extras
 
 EXPOSE 5050
 
-CMD ["ultrarag", "show", "ui", "--port", "5050", "--host", "0.0.0.0"]
+CMD ["ultrarag", "show", "ui", "--port", "5050", "--host", "0.0.0.0"]

Dockerfile.base-cpu

@@ -1,6 +1,6 @@
 FROM ubuntu:24.04
 
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.12.0 /uv /uvx /bin/
 
 ENV DEBIAN_FRONTEND=noninteractive \
     PYTHONUNBUFFERED=1 \
@@ -23,4 +23,4 @@ RUN uv sync --frozen --no-dev
 
 EXPOSE 5050
 
-CMD ["ultrarag", "show", "ui", "--port", "5050", "--host", "0.0.0.0"]
+CMD ["ultrarag", "show", "ui", "--port", "5050", "--host", "0.0.0.0"]

Dockerfile.base-gpu

@@ -1,6 +1,6 @@
-FROM nvidia/cuda:13.1.1-base-ubuntu24.04
+FROM nvidia/cuda:12.9.1-base-ubuntu24.04
 
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.12.0 /uv /uvx /bin/
 
 ENV DEBIAN_FRONTEND=noninteractive \
     PYTHONUNBUFFERED=1 \

README.md

@@ -127,9 +127,9 @@ If you haven't installed uv yet, please execute:
 
 ```shell
 ## Direct installation
-pip install uv
+pip install uv==0.12.0
 ## Download
-curl -LsSf https://astral.sh/uv/install.sh | sh
+curl -LsSf https://astral.sh/uv/0.12.0/install.sh | sh
 ```
 
 **Download Source Code**
@@ -154,6 +154,10 @@ Choose one of the following modes to install dependencies based on your use case
   ```shell
   uv sync --all-extras
   ```
+  This is the recommended team setup: every MCP server shares the same
+  `.venv` and `uv.lock`. Linux GPU dependencies are locked to CUDA 12.9,
+  including the official vLLM cu129 wheel.
+
 - On-demand installation: If you only need to run specific modules, keep the corresponding `--extra` as needed, for example:
 
   ```shell

docs/README_zh.md

@@ -127,9 +127,9 @@ https://github.com/user-attachments/assets/9cca0d4f-fb47-4232-9e47-69bfbb7b5d5d
 
 ```shell
 ## 直接安装
-pip install uv
+pip install uv==0.12.0
 ## 下载
-curl -LsSf https://astral.sh/uv/install.sh | sh
+curl -LsSf https://astral.sh/uv/0.12.0/install.sh | sh
 ```
 
 **下载源码**
@@ -154,6 +154,10 @@ cd UltraRAG
   ```shell
   uv sync --all-extras
   ```
+  这是推荐的团队安装方式：所有 MCP Server 共用同一个 `.venv` 和
+  `uv.lock`。Linux GPU 依赖统一锁定在 CUDA 12.9，包括官方 vLLM cu129
+  wheel。
+
 - 按需安装：如果您只需运行指定模块，请保留对应 `--extra`，例如：
   ```shell
   uv sync --extra retriever   # 检索模块

pyproject.toml

@@ -9,7 +9,8 @@ description = "UltraRAG"
 readme = "README.md"
 requires-python = ">=3.11, <3.13"
 dependencies = [
-    "fastmcp>=3.3.1",
+    # 3.4.5 requires Starlette >=1 through its client extra; MinerU/Gradio need <1.
+    "fastmcp>=3.3.1,<3.4.5",
     "mcp",
     "rich",
     "pandas",
@@ -25,7 +26,8 @@ dependencies = [
     "aiohttp",
     "pillow",
     "flask",
-    "numpy",
+    # faiss-gpu-cu12 1.14 requires NumPy 2; <2.4 also satisfies vLLM/Numba.
+    "numpy>=2,<2.4",
     "fakeredis",
     "pymilvus",
     "pypinyin",
@@ -55,10 +57,13 @@ retriever = [
 ]
 
 generation = [
-    "vllm>=0.22.1",
+    # Newer cu129 wheels currently pull CUDA 13 tooling or conflict with MinerU.
+    "vllm==0.22.1",
     "openai",
     "transformers",
     "torch",
+    # 0.2.4 has no CPython 3.12 Linux x86_64 wheel.
+    "xgrammar<0.2.4",
 ]
 
 evaluation = [
@@ -67,7 +72,7 @@ evaluation = [
 ]
 
 corpus = [
-    "mineru[core]",
+    "mineru[core]>=3,<4",
 ]
 
 all = [
@@ -95,6 +100,7 @@ dev = [
 package = true
 
 [tool.uv.sources]
+vllm = { index = "vllm-cu129" }
 torch = [
     { index = "pytorch-cu129", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
 ]
@@ -109,3 +115,8 @@ torchaudio = [
 name = "pytorch-cu129"
 url = "https://download.pytorch.org/whl/cu129"
 explicit = true
+
+[[tool.uv.index]]
+name = "vllm-cu129"
+url = "https://wheels.vllm.ai/0.22.1/cu129"
+explicit = true