feat: add parallax serve command

Author: gufengc

docs/user_guide/quick_start.md

@@ -135,22 +135,26 @@ For models such as Qwen3 and gpt-oss, the "reasoning" (or "thinking") feature is
 
 ### Skipping Scheduler
 Developers can start Parallax backend engine without a scheduler. Pipeline parallel start/end layers should be set manually.
+
+For a standalone single-machine server:
+```sh
+parallax serve --m Qwen/Qwen3-0.6B
+```
+
 An example of serving Qwen3-0.6B with 2-nodes:
 - First node:
 ```sh
-python3 ./parallax/src/parallax/launch.py \
+parallax serve \
 --model-path Qwen/Qwen3-0.6B \
 --port 3000 \
---max-batch-size 8 \
 --start-layer 0 \
 --end-layer 14
 ```
 - Second node:
 ```sh
-python3 ./parallax/src/parallax/launch.py \
+parallax serve \
 --model-path Qwen/Qwen3-0.6B \
 --port 3000 \
---max-batch-size 8 \
 --start-layer 14 \
 --end-layer 28
 ```

src/parallax/cli.py

@@ -261,6 +261,32 @@ def join_command(args, passthrough_args: list[str] | None = None):
     _execute_with_graceful_shutdown(cmd, env=env)
 
 
+def serve_command(args, passthrough_args: list[str] | None = None):
+    """Start a standalone Parallax server by launching launch.py directly."""
+    if not args.skip_upload:
+        update_package_info()
+
+    check_python_version()
+
+    project_root = get_project_root()
+    launch_script = project_root / "src" / "parallax" / "launch.py"
+
+    if not launch_script.exists():
+        logger.info(f"Error: Launch script not found at {launch_script}")
+        sys.exit(1)
+
+    env = os.environ.copy()
+    env["SGLANG_ENABLE_JIT_DEEPGEMM"] = "0"
+
+    passthrough_args = passthrough_args or []
+    cmd = [sys.executable, str(launch_script), "--model-path", args.model_path]
+
+    if passthrough_args:
+        cmd.extend(passthrough_args)
+
+    _execute_with_graceful_shutdown(cmd, env=env)
+
+
 def chat_command(args, passthrough_args: list[str] | None = None):
     """Start the Parallax chat server (equivalent to scripts/chat.sh)."""
     check_python_version()
@@ -358,6 +384,7 @@ def main():
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
+  parallax serve --model-path Qwen/Qwen3-0.6B                         # Start standalone server
   parallax run                                                          # Start scheduler with frontend
   parallax run -m {model-name} -n {number-of-worker-nodes}              # Start scheduler without frontend
   parallax run -m Qwen/Qwen3-0.6B -n 2                                  # example
@@ -369,6 +396,21 @@ def main():
 
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
 
+    # Add 'serve' command parser
+    serve_parser = subparsers.add_parser(
+        "serve", help="Start a standalone Parallax server by launching the model locally"
+    )
+    serve_parser.add_argument(
+        "-m",
+        "--model-path",
+        required=True,
+        type=str,
+        help="Path to the model repository or model name",
+    )
+    serve_parser.add_argument(
+        "-u", "--skip-upload", action="store_true", help="Skip upload package info"
+    )
+
     # Add 'run' command parser
     run_parser = subparsers.add_parser(
         "run", help="Start the Parallax scheduler (equivalent to scripts/start.sh)"
@@ -424,6 +466,8 @@ def main():
 
     if args.command == "run":
         run_command(args, passthrough_args)
+    elif args.command == "serve":
+        serve_command(args, passthrough_args)
     elif args.command == "join":
         join_command(args, passthrough_args)
     elif args.command == "chat":

tests/test_cli.py

@@ -0,0 +1,61 @@
+from argparse import Namespace
+from pathlib import Path
+from unittest.mock import patch
+
+from parallax import cli
+
+
+def test_serve_command_launches_local_server_without_scheduler(tmp_path):
+    launch_script = tmp_path / "src" / "parallax" / "launch.py"
+    launch_script.parent.mkdir(parents=True)
+    launch_script.touch()
+
+    args = Namespace(model_path="Qwen/Qwen3-0.6B", skip_upload=True)
+
+    with (
+        patch.object(cli, "check_python_version"),
+        patch.object(cli, "get_project_root", return_value=Path(tmp_path)),
+        patch.object(cli.sys, "executable", "/repo/.venv/bin/python"),
+        patch.object(cli, "_execute_with_graceful_shutdown") as execute,
+    ):
+        cli.serve_command(args, ["--log-level", "DEBUG", "--port", "3005"])
+
+    cmd = execute.call_args.args[0]
+    env = execute.call_args.kwargs["env"]
+
+    assert cmd == [
+        "/repo/.venv/bin/python",
+        str(launch_script),
+        "--model-path",
+        "Qwen/Qwen3-0.6B",
+        "--log-level",
+        "DEBUG",
+        "--port",
+        "3005",
+    ]
+    assert "--scheduler-addr" not in cmd
+    assert env["SGLANG_ENABLE_JIT_DEEPGEMM"] == "0"
+
+
+def test_main_dispatches_serve_command_with_passthrough_args():
+    with (
+        patch.object(
+            cli.sys,
+            "argv",
+            [
+                "parallax",
+                "serve",
+                "--model-path",
+                "Qwen/Qwen3-0.6B",
+                "--log-level",
+                "DEBUG",
+            ],
+        ),
+        patch.object(cli, "serve_command") as serve_command,
+    ):
+        cli.main()
+
+    args, passthrough_args = serve_command.call_args.args
+    assert args.command == "serve"
+    assert args.model_path == "Qwen/Qwen3-0.6B"
+    assert passthrough_args == ["--log-level", "DEBUG"]