ModelBridge

README

ModelBridge

中文文档 | Configuration reference

ModelBridge is a Gin-based LLM API protocol bridge. It accepts requests in the OpenAI Chat, OpenAI Responses, Anthropic Messages, Gemini, or Ollama Chat schemas, converts them through a shared internal representation, and forwards them to one configured upstream. See CONFIG.md for the full environment-variable reference, supported target protocols, model-list routes and conversion notes.

Quick Start

Install:

curl -fsSL https://cdn.bring.cool/cnb/Bring/Project/Gateways/ModelBridge@main/install.sh | sh

Windows PowerShell:

irm https://cdn.bring.cool/cnb/Bring/Project/Gateways/ModelBridge@main/install.ps1 | iex

Run against an OpenAI-compatible upstream:

TARGET_PROTOCOL=openai-chat \
TARGET_BASE_URL=https://api.openai.com/v1 \
TARGET_TOKEN="$OPENAI_API_KEY" \
go run ./cmd/server

TARGET_TOKEN may be empty for local or unauthenticated upstreams, or when client authentication should pass through to the upstream.

Health check:

curl http://localhost:8080/healthz

Inbound Routes

Protocol	Route
OpenAI Chat	POST /v1/chat/completions
OpenAI Responses	POST /v1/responses (HTTP); GET /v1/responses (WebSocket)
Claude Messages	POST /v1/messages
Gemini	POST /v1beta/models/{model}:generateContent
Gemini stream	POST /v1beta/models/{model}:streamGenerateContent
Ollama Chat	POST /api/chat

GET /v1/responses accepts OpenAI Responses WebSocket Mode frames. Each response.create is converted through the shared IR and can therefore target any configured upstream protocol. previous_response_id state is scoped to the current WebSocket connection and is not retained after reconnecting.

Model-list routes (GET /v1/models, GET /v1beta/models, GET /api/tags) are documented in CONFIG.md.

Docker

Use the published image directly:

docker run --rm -p 8080:8080 \
  -e TARGET_PROTOCOL=openai-chat \
  -e TARGET_BASE_URL=https://api.openai.com/v1 \
  -e TARGET_TOKEN="$OPENAI_API_KEY" \
  docker.cnb.cool/bring/project/gateways/modelbridge:latest

Installing the binary in your own image

You can also install the binary into your own Dockerfile with the one-liner. The base image needs a POSIX shell plus curl or wget (so distroless/scratch cannot run the installer). Point MODELBRIDGE_INSTALL_DIR at a directory already on PATH — a Docker RUN has no $HOME, and /usr/local/bin is the installer's built-in fallback for exactly this case:

FROM debian:bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl \
    && rm -rf /var/lib/apt/lists/* \
    && curl -fsSL https://cdn.bring.cool/cnb/Bring/Project/Gateways/ModelBridge@main/install.sh \
       | MODELBRIDGE_INSTALL_DIR=/usr/local/bin sh \
    && [ -x /usr/local/bin/modelbridge ]

EXPOSE 8080
ENTRYPOINT ["/usr/local/bin/modelbridge"]

Runtime variables (TARGET_PROTOCOL, TARGET_BASE_URL, TARGET_TOKEN, …) are read by the binary at startup, so inject them with docker run -e or ENV. The installer only ships the binary — it never sets these.

Development

go test ./...
go test -coverprofile=coverage.out -covermode=atomic ./...

Smoke and benchmark workflows are documented in docs/verification.md.

License

Licensed under the Apache License 2.0.

Copyright 2026 leun