fix: stop silently swallowing unknown Llama kwargs; --rpc_servers is a no-op (#2210)

[Anai-Guo]

Fixes #2210

Problem

Llama.__init__ ends in a bare **kwargs (llama_cpp/llama.py) that is never read anywhere in the body. Every keyword it does not recognise is silently discarded, so a wrong spelling produces no error at the call site — the failure surfaces much later, or not at all.

This is not hypothetical: the bundled server hits it itself. llama_cpp/server/model.py still passes two settings that are no longer parameters of Llama.__init__:

setting	passed at	status
rpc_servers	model.py, from ModelSettings.rpc_servers (--rpc_servers)	llama_model_params no longer carries an rpc-servers field
mul_mat_q	model.py, from ModelSettings.mul_mat_q	removed upstream long ago

So python3 -m llama_cpp.server --rpc_servers host:port has been a silent no-op: the flag is accepted, documented in --help, and thrown away.

The same sink swallows embeddings=True (plural) — the spelling used by llama_model_params/llama_context_params and by Llama.__getstate__'s own round-trip, so it is an easy thing to reach for.

Changes

• llama_cpp/llama.py — warn (UserWarning) on unexpected keyword arguments instead of dropping them, and accept embeddings= as an alias for embedding=. The signature is unchanged and nothing is turned into an error, so no existing caller breaks.
• llama_cpp/server/model.py — stop passing rpc_servers= / mul_mat_q= to Llama(...), and warn if the user actually set either, so the setting fails loudly instead of silently.
• llama_cpp/server/settings.py — say in the field descriptions that both are deprecated and ignored.

Both halves are needed: patching only llama.py would make the new warning fire on every server start, because the server is itself a caller of the sink.

Verification

No model or compiled backend needed — the check is a signature replay against the real Llama.__init__ (extracted from the file with ast) plus executing the new prologue verbatim from the patched source.

signature unchanged by patch: True

--- what the SERVER sends, before/after the model.py change ---
unpatched server  kwargs sent=39  silently swallowed by Llama -> ['mul_mat_q', 'rpc_servers']
patched server    kwargs sent=37  silently swallowed by Llama -> []

--- user-facing repros against the real Llama.__init__ signature ---
  {'embeddings': True}                -> lands in **kwargs: ['embeddings']
  {'rpc_servers': '127.0.0.1:50052'}  -> lands in **kwargs: ['rpc_servers']
  {'embedding': True}                 -> lands in **kwargs: []

--- patched prologue behaviour (source lifted verbatim from llama.py) ---
  {'embeddings': True}                     embedding=True   warnings=[]
  {'rpc_servers': ..., 'mul_mat_q': True}  embedding=False  warnings=['Llama.__init__ got unexpected keyword argument(s): mul_mat_q, rpc_servers. They are ignored. ...']
  {}                                       embedding=False  warnings=[]

--- server-side guard ---
rpc_servers=None                 mul_mat_q=True  -> []
rpc_servers='127.0.0.1:50052'    mul_mat_q=True  -> ['The `rpc_servers` server setting is no longer supported ...']
rpc_servers=None                 mul_mat_q=False -> ['The `mul_mat_q` server setting is obsolete and has no effect.']

ruff format --check and ruff check (repo pyproject.toml, ruff 0.15.11) are clean on all three files.

Note

Issue #2210 describes the alias in the other direction (embedding as the old name). On current main it is the reverse — embedding is the real parameter — so this PR adds the alias in the direction that actually silently fails today. If you would rather restore working RPC support than deprecate rpc_servers, that is a larger change against the current llama_model_params and I am happy to split it out.

🤖 Generated with Claude Code