Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

SyntheticDataKit: take a port argument and move off 8000 when it is taken (#13072)

Daniel Hane4d2f4b530fa
diff --git a/tests/test_synthetic_vllm_port.py b/tests/test_synthetic_vllm_port.py
new file mode 100644
index 00000000000..f0036b19795
--- /dev/null
+++ b/tests/test_synthetic_vllm_port.py
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""SyntheticDataKit's vLLM server port (#2494).
+
+The port was fixed at 8000 in the `vllm serve` call, the readiness probe and the
+synthetic-data-kit config, so a kit could neither take a `port` argument nor start
+where 8000 was already taken (Studio listens there in the Unsloth Docker image)."""
+
+import socket
+
+import pytest
+
+import unsloth.dataprep.synthetic as synthetic
+from unsloth.dataprep.synthetic import SyntheticDataKit
+
+
+def busy_port():
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+ # All interfaces, as Studio binds in the Docker image: BSD lets a wildcard bind share a port with a
+ # loopback-only listener, so a 127.0.0.1 listener would not read as taken on macOS.
+ s.bind(("", 0))
+ s.listen()
+ yield s.getsockname()[1]
+
+
+def _free_port():
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+ s.bind(("", 0))
+ return s.getsockname()[1]
+
+
+def test_default_port_is_kept_when_free(monkeypatch):
+ port = _free_port()
+ monkeypatch.setattr(SyntheticDataKit, "port", port)
+ assert synthetic._pick_vllm_port(None) == port
+
+
+def test_default_port_moves_when_taken(monkeypatch, busy_port):
+ monkeypatch.setattr(SyntheticDataKit, "port", busy_port)
+ picked = synthetic._pick_vllm_port(None)
+ assert picked != busy_port
+ assert synthetic._port_is_free(picked)
+
+
+def test_explicit_port_is_used_as_given(busy_port):
+ assert synthetic._pick_vllm_port(busy_port) == busy_port
+ assert synthetic._pick_vllm_port(str(busy_port)) == busy_port
+
+
+def test_check_vllm_status_queries_the_given_port(monkeypatch):
+ import requests
+
+ urls = []
+
+ class _Response:
+ status_code = 200
+
+ def _get(url, **kwargs):
+ urls.append(url)
+ return _Response()
+
+ monkeypatch.setattr(requests, "get", _get)
+ assert SyntheticDataKit.check_vllm_status(8123) is True
+ assert SyntheticDataKit.check_vllm_status() is True
+ assert urls == ["http://localhost:8123/metrics", "http://localhost:8000/metrics"]
+
+
+def _built_kit(monkeypatch, tmp_path, **kwargs):
+ """Run __init__ with the model download, vLLM and the waits stubbed out."""
+ import transformers
+
+ class _Loaded:
+ @staticmethod
+ def from_pretrained(*args, **kwargs):
+ return object()
+
+ monkeypatch.setattr(transformers, "AutoConfig", _Loaded)
+ monkeypatch.setattr(transformers, "AutoTokenizer", _Loaded)
+ load_vllm = lambda **kwargs: {"model": kwargs["model_name"], "max_model_len": 2048}
+ monkeypatch.setattr(
+ synthetic,
+ "_load_vllm_utils",
+ lambda: (load_vllm, lambda **kwargs: None, lambda **kwargs: None),
+ )
+ argv = []
+
+ class _Popen:
+ stdout = stderr = None
+
+ def __init__(self, args, **kwargs):
+ argv.extend(args)
+
+ monkeypatch.setattr(synthetic.subprocess, "Popen", _Popen)
+ monkeypatch.setattr(synthetic, "PipeCapture", lambda *args, **kwargs: None)
+ monkeypatch.setattr(SyntheticDataKit, "_await_vllm_server", lambda self, timeout: None)
+ monkeypatch.setattr(SyntheticDataKit, "_await_metrics_endpoint", lambda self: None)
+ monkeypatch.setattr(SyntheticDataKit, "cleanup", lambda self: None)
+ monkeypatch.chdir(tmp_path)
+ kit = SyntheticDataKit(model_name = "some/model", **kwargs)
+ kit.prepare_qa_generation(output_folder = str(tmp_path / "data"))
+ config = (tmp_path / "synthetic_data_kit_config.yaml").read_text(encoding = "utf-8")
+ return kit, argv, config
+
+
+def test_server_and_config_use_the_explicit_port(monkeypatch, tmp_path):
+ kit, argv, config = _built_kit(monkeypatch, tmp_path, port = 8123)
+ assert kit.port == 8123
+ assert argv[argv.index("--port") + 1] == "8123"
+ assert 'api_base: "http://localhost:8123/v1"' in config
+ assert "port: 8123 " in config
+ assert "8000" not in config
+
+
+def test_server_and_config_follow_a_moved_default(monkeypatch, tmp_path, busy_port):
+ monkeypatch.setattr(SyntheticDataKit, "port", busy_port)
+ kit, argv, config = _built_kit(monkeypatch, tmp_path)
+ assert kit.port != busy_port
+ assert argv[argv.index("--port") + 1] == str(kit.port)
+ assert f'api_base: "http://localhost:{kit.port}/v1"' in config
diff --git a/tests/test_synthetic_vllm_startup_failure.py b/tests/test_synthetic_vllm_startup_failure.py
index 3ada20515ef..ea74c12ffc6 100644
--- a/tests/test_synthetic_vllm_startup_failure.py
+++ b/tests/test_synthetic_vllm_startup_failure.py
@@ -362,7 +362,7 @@ def test_the_metrics_wait_is_bounded_by_time_not_by_attempts(monkeypatch):
calls = {"n": 0}
- def stalled_check():
+ def stalled_check(port = 8000):
calls["n"] += 1
clock["now"] += 5.0
return False
@@ -428,7 +428,7 @@ def test_the_metrics_wait_accepts_an_unbounded_timeout():
"""Same arithmetic, same fix, pinned so the helper is not left half done."""
calls = {"n": 0}
- def check():
+ def check(port = 8000):
calls["n"] += 1
return calls["n"] >= 3
diff --git a/unsloth/dataprep/synthetic.py b/unsloth/dataprep/synthetic.py
index 96f713bb6ef..45bb05445dd 100644
--- a/unsloth/dataprep/synthetic.py
+++ b/unsloth/dataprep/synthetic.py
@@ -12,6 +12,7 @@
__all__ = [
"SyntheticDataKit",
]
+import socket
import subprocess
import threading
from collections import deque
@@ -187,7 +188,38 @@ def _remaining(deadline):
return None if deadline is None else deadline - time.monotonic()
+def _port_is_free(port):
+ """Whether `vllm serve --port port` could bind, probed the way vLLM binds (all interfaces, SO_REUSEADDR)."""
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+ if os.name != "nt":
+ # On Windows SO_REUSEADDR lets a bind steal a port in use, so the probe would always pass.
+ s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ try:
+ s.bind(("", port))
+ except OSError:
+ return False
+ return True
+
+
+def _pick_vllm_port(port):
+ """`port` as given, else 8000, else a free port when 8000 is taken (Studio in the Unsloth Docker image)."""
+ if port is not None:
+ return int(port)
+ if _port_is_free(SyntheticDataKit.port):
+ return SyntheticDataKit.port
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+ s.bind(("", 0))
+ free = s.getsockname()[1]
+ print(
+ f"Unsloth: port {SyntheticDataKit.port} is in use, so the vLLM server will use port {free}."
+ )
+ return free
+
+
class SyntheticDataKit:
+ # Kept as the class default so kits built without __init__ still have a port.
+ port = 8000
+
def __init__(
self,
model_name = "unsloth/Llama-3.1-8B-Instruct-unsloth-bnb-4bit",
@@ -197,6 +229,7 @@ class SyntheticDataKit:
conservativeness = 1.0,
token = None,
timeout = 1200,
+ port = None,
**kwargs,
):
assert type(model_name) is str
@@ -258,10 +291,14 @@ class SyntheticDataKit:
if "model" in engine_args:
del engine_args["model"]
+ # Picked here, not before the model download, so a released fallback port is not left free for minutes.
+ self.port = _pick_vllm_port(port)
subprocess_commands = [
"vllm",
"serve",
str(model_name),
+ "--port",
+ str(self.port),
]
for key, value in engine_args.items():
flag = key.replace("_", "-")
@@ -331,11 +368,11 @@ class SyntheticDataKit:
is ten minutes, not the hundred the message promises.
"""
deadline = _deadline(timeout)
- while not self.check_vllm_status():
+ while not self.check_vllm_status(self.port):
if deadline is not None and time.monotonic() >= deadline:
self._fail_vllm_server(
"printed its readiness line but never answered "
- f"http://localhost:8000/metrics (waited {timeout:g} seconds)"
+ f"http://localhost:{self.port}/metrics (waited {timeout:g} seconds)"
)
time.sleep(poll_interval)
@@ -388,7 +425,7 @@ class SyntheticDataKit:
f"Unsloth: the vLLM server behind SyntheticDataKit "
f"{what_happened}.\n"
f"Nothing after this point can work: `synthetic-data-kit` reaches "
- f"the model over http://localhost:8000/v1, so ingest/create/"
+ f"the model over http://localhost:{self.port}/v1, so ingest/create/"
f'save-as would each report "VLLM server not available", write '
f"no file, and leave the failure to surface as a FileNotFoundError "
f"much later on.\n"
@@ -419,10 +456,10 @@ class SyntheticDataKit:
)
@staticmethod
- def check_vllm_status():
+ def check_vllm_status(port = 8000):
try:
# requests has no default timeout, so a stalled server hung here.
- response = requests.get("http://localhost:8000/metrics", timeout = 5)
+ response = requests.get(f"http://localhost:{port}/metrics", timeout = 5)
return response.status_code == 200
except requests.exceptions.RequestException:
# ConnectionError alone let a read timeout escape as a stray traceback out of the readiness loop.
@@ -562,6 +599,7 @@ class SyntheticDataKit:
.replace("{cleanup_threshold}", str(cleanup_threshold))
.replace("{cleanup_batch_size}", str(cleanup_batch_size))
.replace("{cleanup_temperature}", str(cleanup_temperature))
+ .replace("{port}", str(self.port))
)
with open("synthetic_data_kit_config.yaml", "w", encoding = "utf-8") as f:
diff --git a/unsloth/dataprep/synthetic_configs.py b/unsloth/dataprep/synthetic_configs.py
index 396a2dca90f..301e14fbe03 100644
--- a/unsloth/dataprep/synthetic_configs.py
+++ b/unsloth/dataprep/synthetic_configs.py
@@ -32,8 +32,8 @@ paths:
# VLLM server configuration
vllm:
- api_base: "http://localhost:8000/v1" # Base URL for VLLM API
- port: 8000 # Port for VLLM server
+ api_base: "http://localhost:{port}/v1" # Base URL for VLLM API
+ port: {port} # Port for VLLM server
model: "{model_name}" # Default model to use
max_retries: 3 # Number of retries for API calls
retry_delay: 1.0 # Initial delay between retries (seconds)