ModelBridge

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 and forwards them to one configured upstream. Same-protocol HTTP requests pass through by default; cross-protocol requests use a shared IR. See CONFIG.md for the full environment-variable reference, supported target protocols, model-list routes and conversion notes.

Same-protocol forwarding preserves request bodies, upstream status codes, and stream events. Model mapping changes only the model; Claude still receives the configured positive default when max_tokens is absent. Keyword rewriting, developer-role conversion, and Copilot compatibility use the IR pipeline. Forced streaming changes only necessary request fields, then aggregates the response for non-streaming clients; streaming clients retain passthrough. Passthrough does not inject gateway metrics, synthesize usage or terminal frames, or clean tool calls. WebSocket requests still use the IR.

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

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