Follow-up split out of #14.
Problem
The :proxy documentation names servers we have never tested against.
README.md, in the Bring your own model server section:
If you already run llama.cpp, vLLM, or anything else that speaks the OpenAI
chat-completions API, the proxy tag gives you the translation layer alone.
vLLM is named as though it is supported. It has never been tested. Every test in
this repo, unit and integration, runs against llama-server. The bundled images
run llama-server. The proxy image test stubs an upstream that we wrote
ourselves to return exactly what our code expects, which proves the container
works, not that any third-party server does.
llama.cpp is the only upstream with real evidence behind it.
Why it matters
"vLLM works" is a claim someone will act on. When it does not work, the failure
lands in whichever translation detail differs, and the operator has no reason to
suspect the documentation was aspirational. Being OpenAI-shaped is not a binary:
servers differ on /tokenize, on /v1/models payloads, on streaming chunk
shapes, on whether finish_reason is populated the same way, and on tool-call
index semantics. localaik depends on several of those.
Two concrete places where a merely OpenAI-ish upstream would break:
/tokenize is not part of the OpenAI API at all. It is a llama.cpp extension,
and both Gemini countTokens and Anthropic count_tokens are translated onto
it. A vLLM upstream would fail those routes outright.
- Streamed tool calls rely on OpenAI's
index contract, which took seven review
rounds to get right against llama.cpp's output alone.
Suggested fix
Pick one:
- Narrow the claim. Say llama.cpp is what localaik is tested against, and
that other OpenAI-compatible servers may work but are unverified. Cheapest,
and honest today.
- Earn the claim. Add an integration job that runs the suite against a real
vLLM or Ollama, and document exactly which routes pass. This is the only route
that makes the current wording true.
- Document the known gaps. Keep the broad claim but list the specific
dependencies that are not standard OpenAI, starting with /tokenize, so a
reader can judge their own server.
Option 1 now, and option 3 alongside it, would be my suggestion. Option 2 is
worth considering only if supporting other servers is actually a goal.
Note that main.go's --upstream flag help and the LK_UPSTREAM row in the
README's env table both say "OpenAI-compatible", which is fine as a statement of
the wire protocol required. The problem is specifically naming products we have
not run.
Follow-up split out of #14.
Problem
The
:proxydocumentation names servers we have never tested against.README.md, in theBring your own model serversection:vLLM is named as though it is supported. It has never been tested. Every test in
this repo, unit and integration, runs against
llama-server. The bundled imagesrun
llama-server. The proxy image test stubs an upstream that we wroteourselves to return exactly what our code expects, which proves the container
works, not that any third-party server does.
llama.cpp is the only upstream with real evidence behind it.
Why it matters
"vLLM works" is a claim someone will act on. When it does not work, the failure
lands in whichever translation detail differs, and the operator has no reason to
suspect the documentation was aspirational. Being OpenAI-shaped is not a binary:
servers differ on
/tokenize, on/v1/modelspayloads, on streaming chunkshapes, on whether
finish_reasonis populated the same way, and on tool-callindexsemantics. localaik depends on several of those.Two concrete places where a merely OpenAI-ish upstream would break:
/tokenizeis not part of the OpenAI API at all. It is a llama.cpp extension,and both Gemini
countTokensand Anthropiccount_tokensare translated ontoit. A vLLM upstream would fail those routes outright.
indexcontract, which took seven reviewrounds to get right against llama.cpp's output alone.
Suggested fix
Pick one:
that other OpenAI-compatible servers may work but are unverified. Cheapest,
and honest today.
vLLM or Ollama, and document exactly which routes pass. This is the only route
that makes the current wording true.
dependencies that are not standard OpenAI, starting with
/tokenize, so areader can judge their own server.
Option 1 now, and option 3 alongside it, would be my suggestion. Option 2 is
worth considering only if supporting other servers is actually a goal.
Note that
main.go's--upstreamflag help and theLK_UPSTREAMrow in theREADME's env table both say "OpenAI-compatible", which is fine as a statement of
the wire protocol required. The problem is specifically naming products we have
not run.