{ "stable": true, "versions": { "1.0.0": { "manifest": { "id": "io.github.orcvole.bgereranker", "title": "BGE Reranker", "author": "OrcVole", "tagline": "Self-hosted reranking API (BAAI bge-reranker-v2-m3 on HuggingFace TEI)", "description": "## BGE Reranker (bge-reranker-v2-m3) on Text Embeddings Inference\n\nA private, self-hosted **reranking API**. It serves the Apache-2.0 model\n[`BAAI/bge-reranker-v2-m3`](https://huggingface.co/BAAI/bge-reranker-v2-m3) - a multilingual\nXLM-RoBERTa cross-encoder - using Hugging Face\n[Text Embeddings Inference (TEI)](https://github.com/huggingface/text-embeddings-inference), the\nproduction-grade Rust server. The model weights are **baked into the image**, so the app is ready\nwithin seconds of install, runs fully offline, and never phones home.\n\nThis is the reranking half of a two-stage retrieve-then-rerank pipeline. A retriever (vector search or\nkeyword search) returns a shortlist of candidate passages; the reranker scores each candidate against\nthe query with a cross-encoder, which is far more accurate than the first-stage similarity. You keep\nthe top results. It pairs naturally with an embeddings server and a vector database.\n\n### The API\n\nSend a query and a list of candidate texts; get a relevance score for each.\n\n```bash\ncurl https://your-app-domain/rerank \\\n -H \"Authorization: Bearer $RERANKER_API_KEY\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":\"what is panda?\",\"texts\":[\"hi\",\"The giant panda is a bear endemic to China.\"]}'\n# -> [{\"index\":1,\"score\":0.99...}, {\"index\":0,\"score\":0.00...}] (sorted best-first)\n```\n\nRequest fields: `query` (string), `texts` (array of strings), and the optional `raw_scores`,\n`return_text`, `truncate`, `truncation_direction`. TEI returns a score for every text and sorts the\nresults best-first; take as many as you need from the top. (TEI's `/rerank` has no server-side `top_n`;\nslice client-side.)\n\n### Security and topology\n\n- One strong API key is generated on first run and stored inside the app; send it as\n `Authorization: Bearer `. The reranking API is open at the network layer and protected by the\n key, so programmatic clients get a clean 401 (never an SSO redirect).\n- The browsable Swagger docs at `/docs` are placed behind Cloudron single sign-on.\n- `/health` is open and unauthenticated for platform monitoring.\n\n### Notes\n\n- CPU inference, amd64 only (the TEI CPU build bundles Intel MKL; there is no arm64 CPU image).\n- The model is fixed (baked). For text embeddings, run the companion TEI embeddings app instead.\n- This is an API, not a web app. Opening the domain shows a short landing page describing the API and\n how to call it; the interactive Swagger docs are at `/docs` (behind login).\n", "changelog": "[1.0.0]\n* First release.\n* Serves BAAI/bge-reranker-v2-m3 (Apache-2.0, multilingual XLM-RoBERTa cross-encoder) on Hugging Face\n Text Embeddings Inference 1.9.3 (CPU build), packaged for Cloudron.\n* Model weights are baked into the image and pinned by Hugging Face commit revision, with the large\n files verified by sha256 at build time. The app is ready within seconds of install, fully offline.\n* Reranking API on POST /rerank, protected by an auto-generated Bearer API key. The /health path is\n open; the Swagger docs at /docs are behind Cloudron single sign-on.\n* TEI is fronted by a small nginx reverse proxy that answers /health immediately, so the app stays\n healthy during the model warmup (TEI binds its port only after warmup) instead of restart-looping.\n* memoryLimit is 6 GiB to cover the warmup memory peak.\n* Read-only root filesystem, runs as the unprivileged cloudron user, all state under /app/data.\n", "icon": "file://logo.png", "version": "1.0.0", "upstreamVersion": "1.9.3", "healthCheckPath": "/health", "httpPort": 8080, "addons": { "localstorage": {}, "proxyAuth": { "path": "/docs" } }, "memoryLimit": 6442450944, "configurePath": "/docs", "optionalSso": true, "postInstallMessage": "### This is a reranking API, not a web app\n\nThere is no dashboard to use. The app serves `POST /rerank` over HTTP. Opening the app's domain in a\nbrowser shows a short **landing page** that says what the API is and how to call it (no login needed to\nread it); the interactive Swagger docs are at `/docs` (behind your Cloudron login). The model\n`BAAI/bge-reranker-v2-m3` is baked into the image, so the app reports healthy within seconds and serves\nits first rerank after a brief warmup (well under a minute); there is no first-boot download.\n\n### 1. Get your API key\n\nOpen a Terminal for this app (the `>_` button in the dashboard) and run:\n\n```\ncat /app/data/.secrets/keys.env\n```\n\nCopy the `RERANKER_API_KEY` value. It was generated on first run and never changes on update or\nrestore, so you can configure integrators with it once.\n\n### 2. Call the reranker\n\nSend it as `Authorization: Bearer `:\n\n```\ncurl https://__APP_DOMAIN__/rerank \\\n -H \"Authorization: Bearer YOUR_KEY\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":\"what is panda?\",\"texts\":[\"hi\",\"The giant panda is a bear endemic to China.\"]}'\n```\n\nYou get a relevance score for each text, sorted best-first, with the original index:\n\n```\n[{\"index\":1,\"score\":0.99...}, {\"index\":0,\"score\":0.00...}]\n```\n\nTake as many top results as you need (slice client-side; there is no server-side `top_n`).\n\n### 3. Where things are\n\n- `POST /rerank` and `/info`, `/metrics`: protected by the Bearer key.\n- `/health`: open, for platform monitoring.\n- `/docs`: the interactive Swagger UI, behind Cloudron login. This is the `Open` button target.\n\n### Security\n\nThe reranking API is open at the network layer and protected by the key, so a request without the key\nreturns a clean `401` rather than a login redirect (this is what lets non-browser clients integrate).\nDo not put the Cloudron single sign-on wall in front of `/rerank`. Keep the key secret; it is stored\ninside the app at `/app/data/.secrets/keys.env` and is never written to the logs.\n", "checklist": { "apikey": { "message": "Get your API key: open a Terminal for this app (the `>_` button) and run `cat /app/data/.secrets/keys.env`. Send it as `Authorization: Bearer ` to `POST /rerank`." }, "api": { "message": "This is a reranking API, not a web app. Opening the app's domain shows a short landing page explaining what it is and how to call it; the interactive Swagger docs are at `/docs` (behind login). Call `POST /rerank` with a `query` and a list of `texts` (it returns a relevance score for each). The model `BAAI/bge-reranker-v2-m3` is baked in, so the app is healthy within seconds and serves reranking after a brief warmup (under a minute)." } }, "tags": [ "ai", "reranking", "rag", "search", "nlp" ], "mediaLinks": [ "https://raw.githubusercontent.com/OrcVole/bge-reranker-cloudron/main/screenshots/overview.png", "https://raw.githubusercontent.com/OrcVole/bge-reranker-cloudron/main/screenshots/docs.png" ], "website": "https://github.com/OrcVole/bge-reranker-cloudron", "documentationUrl": "https://github.com/OrcVole/bge-reranker-cloudron", "contactEmail": "OrcVole@users.noreply.github.com", "packagerName": "OrcVole", "packagerUrl": "https://github.com/OrcVole/bge-reranker-cloudron", "manifestVersion": 2, "minBoxVersion": "9.1.0", "iconUrl": "https://raw.githubusercontent.com/OrcVole/bge-reranker-cloudron/main/logo.png", "dockerImage": "ghcr.io/orcvole/bge-reranker-cloudron@sha256:3891c46d5d3204553ae0cf2e6103b2119963f478245ff8bb2cd0a939c11ea28d" }, "creationDate": "2026-06-27T22:23:01.906Z", "ts": 1782598981906, "publishState": "published" } } }