feat: add vllm rust frontend (#457)

Author: gufengc

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
     branches: [ main ]
     paths:
       - '.github/workflows/ci.yml'
+      - 'install.sh'
       - 'src/**'
       - 'tests/**'
       - 'pyproject.toml'
@@ -72,14 +73,21 @@ jobs:
         fail_ci_if_error: false
         token: ${{ secrets.CODECOV_TOKEN }}
 
+    - name: Install Parallax and vLLM Rust frontend
+      if: matrix.os == 'macos-26' && matrix.python-version == '3.12'
+      shell: bash
+      run: |
+        ./install.sh --extras mac --python "${{ matrix.python-version }}"
+        test -x .venv/bin/vllm-rs
+
     - name: Run E2E tests (macOS only)
       if: matrix.os == 'macos-26' && matrix.python-version == '3.12'
       shell: bash
       env:
         TERM: xterm-256color
       run: |
         # Start the server
-        python src/parallax/launch.py \
+        .venv/bin/python src/parallax/launch.py \
           --model-path Qwen/Qwen3-0.6B \
           --max-num-tokens-per-batch 16384 \
           --kv-block-size 32 \
@@ -123,6 +131,7 @@ jobs:
           'http://localhost:3000/v1/chat/completions' \
           --header 'Content-Type: application/json' \
           --data '{
+            "model": "Qwen/Qwen3-0.6B",
             "messages": [
               {
                 "role": "user",
@@ -132,9 +141,7 @@ jobs:
             "stream": false,
             "max_tokens": 1024,
             "chat_template_kwargs": {"enable_thinking": false},
-            "sampling_params": {
-                "top_k": 3
-            }
+            "top_k": 3
         }')
 
         echo "Response received:"

AGENTS.md

@@ -0,0 +1,26 @@
+mac env:
+    python: .venv/bin/python
+
+gpu env:
+    ssh H200 server, then use conda activate parallax
+
+
+start a local server:
+    python src/parallax/launch.py --model-path <MODEL_NAME> --log-level DEBUG
+
+test the server:
+    curl --location 'http://localhost:3000/v1/chat/completions' --header 'Content-Type: application/json' --data '{
+        "max_tokens": 1024,
+        "messages": [
+            {
+                "role": "user",
+                "content": "hello"
+            }
+        ],
+        "stream": true
+    }'
+
+final check:
+    run when user ask to git commit
+    pre-commit run --all-files
+    pytest

README.md

@@ -54,6 +54,21 @@ The backend architecture:
 - [Getting Started](./docs/user_guide/quick_start.md)
 - [Working with OpenClaw 🦞](./docs/user_guide/work_with_openclaw.md)
 
+## Quick Install
+
+```sh
+git clone https://github.com/GradientHQ/parallax.git
+cd parallax
+./install.sh
+source .venv/bin/activate
+```
+
+The install script installs `uv` if needed, creates `.venv`, installs Parallax,
+and builds the `vllm-rs` frontend binary into `.venv/bin`. Use
+`./install.sh --extras gpu` on Linux/WSL GPU hosts or `./install.sh --extras mac`
+on Apple silicon macOS. For development dependencies, use `--extras gpu,dev` or
+`--extras mac,dev`.
+
 ## Contributing
 
 We warmly welcome contributions of all kinds! For guidelines on how to get involved, please refer to our [Contributing Guide](./docs/CONTRIBUTING.md).

docs/user_guide/install.md

@@ -3,6 +3,7 @@
 
 ### Prerequisites
 - Python>=3.11.0,<3.14.0
+- Git and curl
 - Ubuntu-24.04 for Blackwell GPUs
 
 Below are installation methods for different operating systems.
@@ -14,36 +15,40 @@ Below are installation methods for different operating systems.
 |macOS | ❌️ | ✅️ | ❌️ |
 
 ### From Source
-#### For Linux/WSL (GPU):
-Note: If you are using DGX Spark, please refer to the Docker installation section
+
+The source install script installs `uv` if needed, creates `.venv`, installs
+Parallax, and builds the `vllm-rs` frontend binary into `.venv/bin`.
+
 ```sh
 git clone https://github.com/GradientHQ/parallax.git
 cd parallax
-pip install -e '.[gpu]'
+./install.sh
+source .venv/bin/activate
 ```
 
-#### For macOS (Apple silicon):
-
-We recommend macOS users to create an isolated Python virtual environment before installation.
+The script automatically installs `mac` extras on macOS and `gpu` extras on
+Linux. You can also choose explicitly:
 
 ```sh
-git clone https://github.com/GradientHQ/parallax.git
-cd parallax
+# Linux/WSL GPU
+./install.sh --extras gpu
 
-# Enter Python virtual environment
-python3 -m venv ./venv
-source ./venv/bin/activate
-
-pip install -e '.[mac]'
+# macOS Apple silicon
+./install.sh --extras mac
 ```
 
-Next time to re-activate this virtual environment, run ```source ./venv/bin/activate```.
-
-#### Extra step for development:
+For development dependencies:
 ```sh
-pip install -e '.[dev]'
+./install.sh --extras gpu,dev
+# or
+./install.sh --extras mac,dev
 ```
 
+To use a specific supported Python version, pass `--python`, for example
+`./install.sh --python 3.12`.
+
+Next time to re-activate this virtual environment, run ```source .venv/bin/activate```.
+
 ### Windows Application
 [Click here](https://github.com/GradientHQ/parallax_win_cli/releases/latest/download/Parallax_Win_Setup.exe) to get latest Windows installer.