feat: add support for specifying model alias used in requests and responses

docs/options/alias.md

@@ -0,0 +1,6 @@
+####> This option file is used in:
+####>   ramalama sandbox goose, ramalama sandbox opencode, ramalama serve
+####> If this file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--alias**
+Model name alias (referenced in the requests and responses of the API).

docs/ramalama-sandbox-goose.1.md.in

@@ -21,6 +21,8 @@ exits, the model server container is automatically stopped and removed.
 
 ## OPTIONS
 
+@@option alias
+
 @@option authfile
 
 @@option backend

docs/ramalama-sandbox-opencode.1.md.in

@@ -21,6 +21,8 @@ exits, the model server container is automatically stopped and removed.
 
 ## OPTIONS
 
+@@option alias
+
 @@option authfile
 
 @@option backend

docs/ramalama-serve.1.md.in

@@ -34,6 +34,8 @@ Useful, for instance, to add environment variables to the generated unit file, o
 
 Section, key and value are required and must be separated by colons.
 
+@@option alias
+
 @@option api
 
 @@option authfile

ramalama/cli.py

@@ -337,6 +337,8 @@ def configure_subcommands(parser):
     # output only shows subcommands the active runtime actually supports.
     # get_config().runtime is already set by Phase 1 of parse_args_from_cmd
     # before configure_subcommands() is called in Phase 2.
+    # These include the subcommands serve and run, which are handled
+    # in BaseInferenceRuntime and its subclasses
     runtime = ActiveConfig().runtime
     get_runtime(runtime).register_subcommands(subparsers)
     chat_parser(subparsers)

ramalama/plugins/runtimes/inference/llama_cpp.py

@@ -224,7 +224,8 @@ def service_ready_check(self, conn: HTTPConnection, args: Any, model_name: Optio
         if not model_name:
             model_name = New(args.MODEL, args).model_alias
 
-        if model_name not in model_names:
+        model_id = getattr(args, 'alias', None) or model_name
+        if model_id not in model_names:
             logger.debug(
                 f'{self.name} {container_name} /models does not include "{model_name}" in the model list: {model_names}'
             )
@@ -352,6 +353,12 @@ def _add_inference_args(self, parser: "argparse.ArgumentParser", command: str) -
                 default="on",
                 help="enable or disable the web UI (default: on)",
             )
+            parser.add_argument(
+                "--alias",
+                dest="alias",
+                help="model name alias (referenced in the requests and responses of the API)",
+                completer=suppressCompleter,
+            )
 
     @staticmethod
     def _set_openvino_env(args: argparse.Namespace) -> None:

ramalama/plugins/runtimes/inference/llama_cpp_commands.py

@@ -83,7 +83,9 @@ def _cmd_run(self, args: argparse.Namespace) -> list[str]:
         if not getattr(args, 'thinking', None):
             cmd += ["--reasoning-budget", "0"]
 
-        if model is not None:
+        if getattr(args, 'alias', None):
+            cmd += ["--alias", args.alias]
+        elif model is not None:
             cmd += ["--alias", model.model_alias]
 
         ctx_size = getattr(args, 'ctx_size', None)

ramalama/plugins/runtimes/inference/vllm.py

@@ -42,7 +42,10 @@ def _cmd_run(self, args: argparse.Namespace) -> list[str]:
         if model is not None:
             model_path = model._get_entry_model_path(is_container, should_generate, dry_run)
             cmd += ["--model", model_path]
-            cmd += ["--served-model-name", model.model_alias]
+            if getattr(args, 'alias', None):
+                cmd += ["--served-model-name", args.alias]
+            else:
+                cmd += ["--served-model-name", model.model_alias]
 
         ctx_size = getattr(args, 'ctx_size', None)
         if ctx_size:
@@ -91,6 +94,17 @@ def _register_serve_subcommand(self, subparsers: "argparse._SubParsersAction") -
         self._add_max_model_len_arg(parser)
         return parser
 
+    def _add_inference_args(self, parser: "argparse.ArgumentParser", command: str) -> None:
+        """Add vLLM-specific inference args to an already-created parser."""
+        super()._add_inference_args(parser, command)
+        if command == "serve":
+            parser.add_argument(
+                "--alias",
+                dest="alias",
+                help="model name alias (referenced in the requests and responses of the API)",
+                completer=suppressCompleter,
+            )
+
     def get_container_image(self, config: Any, detected_gpu_type: str) -> Optional[str]:
         if detected_gpu_type:
             image = config.images.get(f"VLLM_{detected_gpu_type}") or _VLLM_IMAGES.get(detected_gpu_type)

ramalama/transports/base.py

@@ -505,7 +505,7 @@ def _connect_and_chat(self, args, server_process):
 
         # Model name in the chat request must match RamalamaModelContext.alias()
         chat_args = copy.deepcopy(args)
-        chat_args.model = f"{self.model_organization}/{self.model_name}"
+        chat_args.model = getattr(args, 'alias', None) or self.model_alias
 
         if args.container:
             return self._handle_container_chat(chat_args, server_process)

test/e2e/test_serve.py

@@ -12,6 +12,7 @@
 from subprocess import STDOUT, CalledProcessError
 
 import pytest
+import requests
 import yaml
 
 from test.conftest import (
@@ -336,6 +337,27 @@ def test_serve_and_stop(shared_ctx, test_model):
     assert not re.search(f".*({container1_id}|{container2_id})", ps_result)
 
 
+@pytest.mark.e2e
+@pytest.mark.slow
+@skip_if_no_container
+def test_serve_model_with_alias(shared_ctx, test_model):
+    container_id  = f"serve_with_alias_{''.join(random.choices(string.ascii_letters + string.digits, k=5))}"
+    alias = "my_alias"
+    ctx = shared_ctx
+    serve_cmd = ["ramalama", "serve", "--name", container_id, "--alias", alias, "--detach", test_model]
+    ctx.check_call(serve_cmd)
+    try:
+        ps_list = ctx.check_output(["ramalama", "ps", "--format", "{{.Names}} {{.Ports}}"])
+        port = re.search(rf"{container_id}.*->(?P<port>\d+)", ps_list)["port"]
+        # FIXME: race-condition, chat can fail to connect if llama.cpp isn't ready, just sleep a little for now
+        time.sleep(10)
+        models = requests.get(f"http://127.0.0.1:{port}/v1/models").json()
+        assert models["models"][0]["name"] == alias
+        assert models["models"][0]["model"] == alias
+    finally:
+        ctx.check_call(["ramalama", "stop", container_id])
+
+
 @pytest.mark.e2e
 @pytest.mark.slow
 @skip_if_no_container

test/unit/test_engine.py

@@ -234,6 +234,26 @@ def test_is_healthy_success(mock_conn, mock_debug, health_status):
     assert mock_debug.call_args.args[0] == "llama.cpp server is ready"
 
 
+@pytest.mark.parametrize(
+    "health_status",
+    [
+        pytest.param(200, id="health api ok"),
+        pytest.param(404, id="no health api"),
+    ],
+)
+@patch("ramalama.engine.logger.debug")
+@patch("ramalama.engine.HTTPConnection")
+def test_is_healthy_success_with_alias(mock_conn, mock_debug, health_status):
+    mock_health_resp = Mock(status=health_status)
+    mock_models_resp = Mock(status=200)
+    mock_models_resp.read.return_value = '{"models": [{"name": "alias"}]}'
+    mock_conn.return_value.getresponse.side_effect = [mock_health_resp, mock_models_resp]
+    args = Namespace(MODEL="themodel", name="thecontainer", port=8080, debug=False, alias='alias')
+    assert ramalama.engine.is_healthy(args, model_name="themodel")
+    assert mock_conn.return_value.getresponse.call_count == 2
+    assert mock_debug.call_args.args[0] == "llama.cpp server is ready"
+
+
 @pytest.mark.parametrize(
     "status, ok",
     [

test/unit/test_inference_engine_plugins.py

@@ -34,6 +34,7 @@ def make_ns(
     max_tokens=0,
     port="8080",
     host="::",
+    alias=None,
     logfile=None,
     debug=False,
     webui="on",
@@ -56,6 +57,7 @@ def make_ns(
         max_tokens=max_tokens,
         port=port,
         host=host,
+        alias=alias,
         logfile=logfile,
         debug=debug,
         webui=webui,
@@ -156,6 +158,7 @@ def test_serve_basic(self, mock_colorize, mock_new, container_image_is_ggml):
         assert cmd[cmd.index("--model") + 1] == "/mnt/models/model.file"
         assert "--no-warmup" in cmd
         assert "--alias" in cmd
+        assert cmd[cmd.index("--alias") + 1] == 'mymodel'
         assert "-ngl" in cmd
 
     @patch("ramalama.plugins.runtimes.inference.llama_cpp_commands.should_colorize", return_value=False)
@@ -297,6 +300,26 @@ def test_serve_seed(self, mock_colorize):
         assert "--seed" in cmd
         assert cmd[cmd.index("--seed") + 1] == "42"
 
+    @patch("ramalama.plugins.runtimes.inference.llama_cpp_commands.should_colorize", return_value=False)
+    def test_serve_alias(self, mock_colorize):
+        ns = make_ns(alias='my_alias')
+        cmd = self.plugin.handle_subcommand("serve", ns)
+
+        assert "--alias" in cmd
+        assert cmd[cmd.index("--alias") + 1] == "my_alias"
+
+    @patch("ramalama.plugins.runtimes.inference.llama_cpp_commands.New")
+    @patch("ramalama.plugins.runtimes.inference.llama_cpp_commands.should_colorize", return_value=False)
+    def test_serve_alias_override_model_alias(self, mock_colorize, mock_new):
+        mock_model = make_transport_model(chat_template_path="/mnt/models/chat_template.file")
+        mock_new.return_value = mock_model
+
+        ns = make_ns(alias="my_alias", MODEL="ollama://mymodel")
+        cmd = self.plugin.handle_subcommand("serve", ns)
+
+        assert "--alias" in cmd
+        assert cmd[cmd.index("--alias") + 1] == "my_alias"
+
     @patch("ramalama.plugins.runtimes.inference.llama_cpp_commands.should_colorize", return_value=False)
     def test_serve_debug(self, mock_colorize):
         ns = make_ns(debug=True)
@@ -514,6 +537,7 @@ def test_serve_in_container(self, mock_new):
         assert isinstance(cmd[0], ContainerEntryPoint)
         assert "--model" in cmd
         assert "--served-model-name" in cmd
+        assert cmd[cmd.index("--served-model-name") + 1] == "mymodel"
         assert "--port" in cmd
 
     def test_serve_nocontainer(self):
@@ -544,6 +568,17 @@ def test_serve_seed(self):
         assert "--seed" in cmd
         assert cmd[cmd.index("--seed") + 1] == "123"
 
+    @patch("ramalama.plugins.runtimes.inference.vllm.New")
+    def test_serve_alias(self, mock_new):
+        mock_model = make_transport_model(chat_template_path="/mnt/models/chat_template.file")
+        mock_new.return_value = mock_model
+
+        ns = make_ns(alias="my_alias", MODEL="ollama://mymodel")
+        cmd = self.plugin.handle_subcommand("serve", ns)
+
+        assert "--served-model-name" in cmd
+        assert cmd[cmd.index("--served-model-name") + 1] == "my_alias"
+
     def test_serve_seed_not_added_when_none(self):
         ns = make_ns(seed=None)
         cmd = self.plugin.handle_subcommand("serve", ns)