Skip to content

README claims vLLM compatibility that was never tested; only llama.cpp has evidence #17

Description

@harshaneel

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:

  1. 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.
  2. 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.
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions