From 69fb6aee8c7ce15a5bdce12edc2d15e23467f688 Mon Sep 17 00:00:00 2001 From: zhenghaoz Date: Tue, 13 Oct 2026 15:42:13 +0800 Subject: [PATCH 1/3] docs: document compatible reranker APIs --- src/docs/concepts/ranking.md | 25 +++++++++++++++++++++++++ src/zh/docs/concepts/ranking.md | 25 +++++++++++++++++++++++++ 2 files changed, 50 insertions(+) diff --git a/src/docs/concepts/ranking.md b/src/docs/concepts/ranking.md index 8fb79dd..38ef3c8 100644 --- a/src/docs/concepts/ranking.md +++ b/src/docs/concepts/ranking.md @@ -130,6 +130,31 @@ Please sort repositories by the user's interests. `feedback` contains the user's recent feedback and `items` contains the list of recommended items to be ranked. The number of `feedback` items can be controlled by the `recommend.context_size`. The LLM-based reranker renders the query template and document templates, then sends them to the reranker API. The response is then parsed to extract the ranked list of item IDs. +#### API Compatibility + +Gorse supports the Jina/Cohere-style text reranking API. It sends a `POST` request with `model`, `query`, and a string array of `documents`, authenticates with `Authorization: Bearer `, and reads the document `index` and `relevance_score` from the top-level `results` array. + +The following interfaces are compatible with this basic text reranking protocol: + +| Service | Reranking endpoint | Notes | +|---------|--------------------|-------| +| [Jina AI](https://jina.ai/reranker/) | `https://api.jina.ai/v1/rerank` | Use a text reranking model. | +| [Cohere](https://docs.cohere.com/reference/rerank) | `https://api.cohere.com/v2/rerank` | Use the Rerank API, not the Chat API. | +| [Alibaba Cloud Model Studio](https://help.aliyun.com/en/model-studio/text-rerank-api) | `/compatible-api/v1/reranks` | Use `qwen3-rerank` and the compatible endpoint for your region and workspace, not the native text-rerank endpoint. | +| [SiliconFlow](https://docs.siliconflow.cn/docs/api/rerank-post) | `https://api.siliconflow.cn/v1/rerank` | Use a text reranking model available on the platform. | +| [vLLM](https://github.com/vllm-project/vllm/blob/main/examples/pooling/score/rerank_api_online.py) | `http://localhost:8000/rerank` | Replace the address with your deployment and use its served reranking model name. | + +Set `url` to the **complete reranking endpoint**, including the path, rather than an API base URL. For example, configure Jina AI as follows, in addition to the query and document templates above: + +```toml +[recommend.ranker.reranker_api] +auth_token = "" +model = "jina-reranker-v2-base-multilingual" +url = "https://api.jina.ai/v1/rerank" +``` + +Compatibility here refers to the basic text request and ranking response, not every provider-specific option. Gorse does not send multimodal documents or provider-specific parameters such as reranking instructions and truncation settings. A service advertising OpenAI compatibility is not necessarily compatible with this reranking protocol; interfaces with different authentication, request fields, or response formats require an adapter. + [^1]: Rendle, Steffen. "Factorization machines." 2010 IEEE International conference on data mining. IEEE, 2010. [^2]: Nogueira, Rodrigo, et al. "Document ranking with a pretrained sequence-to-sequence model." Findings of the association for computational linguistics: EMNLP 2020. 2020. [^3]: Liu, Junling, et al. "Is chatgpt a good recommender? a preliminary study." arXiv preprint arXiv:2304.10149 (2023). diff --git a/src/zh/docs/concepts/ranking.md b/src/zh/docs/concepts/ranking.md index 44b7732..e74799d 100644 --- a/src/zh/docs/concepts/ranking.md +++ b/src/zh/docs/concepts/ranking.md @@ -129,6 +129,31 @@ Please sort repositories by the user's interests. `feedback` 包含用户最近的反馈，`items` 包含要排序的推荐物品列表。`feedback` 的数量可以通过 `recommend.context_size` 控制。大语言模型重排器渲染查询模板和文档模板，然后将其发送到 Reranker API。然后解析响应以提取排序后的物品 ID 列表。 +#### API 兼容性 + +Gorse 支持 Jina/Cohere 风格的文本重排 API。它通过 `POST` 请求发送 `model`、`query` 和字符串数组 `documents`，使用 `Authorization: Bearer ` 认证，并从响应顶层的 `results` 数组中读取文档的 `index` 和 `relevance_score`。 + +以下接口兼容这一基础文本重排协议： + +| 服务 | 重排接口地址 | 说明 | +|------|--------------|------| +| [Jina AI](https://jina.ai/reranker/) | `https://api.jina.ai/v1/rerank` | 使用文本重排模型。 | +| [Cohere](https://docs.cohere.com/reference/rerank) | `https://api.cohere.com/v2/rerank` | 使用 Rerank API，而不是 Chat API。 | +| [阿里云百炼](https://help.aliyun.com/zh/model-studio/text-rerank-api) | `/compatible-api/v1/reranks` | 使用 `qwen3-rerank` 和对应地域、工作空间的兼容接口，而不是原生 text-rerank 接口。 | +| [硅基流动](https://docs.siliconflow.cn/docs/api/rerank-post) | `https://api.siliconflow.cn/v1/rerank` | 使用平台提供的文本重排模型。 | +| [vLLM](https://github.com/vllm-project/vllm/blob/main/examples/pooling/score/rerank_api_online.py) | `http://localhost:8000/rerank` | 将地址替换为实际部署地址，并使用服务提供的重排模型名称。 | + +`url` 必须填写**包含路径的完整重排接口地址**，而不是 API 基础地址。例如，除了上面的查询和文档模板，还可以配置 Jina AI： + +```toml +[recommend.ranker.reranker_api] +auth_token = "" +model = "jina-reranker-v2-base-multilingual" +url = "https://api.jina.ai/v1/rerank" +``` + +这里的兼容性仅指基础文本请求和排序响应，并不涵盖所有服务专属选项。Gorse 不发送多模态文档，也不发送重排指令、截断设置等服务专属参数。声明兼容 OpenAI 的服务不一定兼容这一重排协议；认证方式、请求字段或响应格式不同的接口需要通过适配器接入。 + [^1]: Rendle, Steffen. "Factorization machines." 2010 IEEE International conference on data mining. IEEE, 2010. [^2]: Liu, Junling, et al. "Is chatgpt a good recommender? a preliminary study." arXiv preprint arXiv:2304.10149 (2023). [^3]: Dai, Sunhao, et al. "Uncovering chatgpt’s capabilities in recommender systems." Proceedings of the 17th ACM Conference on Recommender Systems. 2023. From 54cfbe975346e980f69099c99aef5dc764893999 Mon Sep 17 00:00:00 2001 From: zhenghaoz Date: Tue, 13 Oct 2026 15:50:45 +0800 Subject: [PATCH 2/3] docs: simplify reranker compatibility tables --- src/docs/concepts/ranking.md | 14 +++++++------- src/zh/docs/concepts/ranking.md | 14 +++++++------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/docs/concepts/ranking.md b/src/docs/concepts/ranking.md index 38ef3c8..aa6ffb3 100644 --- a/src/docs/concepts/ranking.md +++ b/src/docs/concepts/ranking.md @@ -136,13 +136,13 @@ Gorse supports the Jina/Cohere-style text reranking API. It sends a `POST` reque The following interfaces are compatible with this basic text reranking protocol: -| Service | Reranking endpoint | Notes | -|---------|--------------------|-------| -| [Jina AI](https://jina.ai/reranker/) | `https://api.jina.ai/v1/rerank` | Use a text reranking model. | -| [Cohere](https://docs.cohere.com/reference/rerank) | `https://api.cohere.com/v2/rerank` | Use the Rerank API, not the Chat API. | -| [Alibaba Cloud Model Studio](https://help.aliyun.com/en/model-studio/text-rerank-api) | `/compatible-api/v1/reranks` | Use `qwen3-rerank` and the compatible endpoint for your region and workspace, not the native text-rerank endpoint. | -| [SiliconFlow](https://docs.siliconflow.cn/docs/api/rerank-post) | `https://api.siliconflow.cn/v1/rerank` | Use a text reranking model available on the platform. | -| [vLLM](https://github.com/vllm-project/vllm/blob/main/examples/pooling/score/rerank_api_online.py) | `http://localhost:8000/rerank` | Replace the address with your deployment and use its served reranking model name. | +| Service | Reranking endpoint | +|---------|--------------------| +| [Jina AI](https://jina.ai/reranker/) | `https://api.jina.ai/v1/rerank` | +| [Cohere](https://docs.cohere.com/reference/rerank) | `https://api.cohere.com/v2/rerank` | +| [Alibaba Cloud Model Studio](https://help.aliyun.com/en/model-studio/text-rerank-api) | `/compatible-api/v1/reranks` | +| [SiliconFlow](https://docs.siliconflow.cn/docs/api/rerank-post) | `https://api.siliconflow.cn/v1/rerank` | +| [vLLM](https://github.com/vllm-project/vllm/blob/main/examples/pooling/score/rerank_api_online.py) | `http://localhost:8000/rerank` | Set `url` to the **complete reranking endpoint**, including the path, rather than an API base URL. For example, configure Jina AI as follows, in addition to the query and document templates above: diff --git a/src/zh/docs/concepts/ranking.md b/src/zh/docs/concepts/ranking.md index e74799d..380a9ba 100644 --- a/src/zh/docs/concepts/ranking.md +++ b/src/zh/docs/concepts/ranking.md @@ -135,13 +135,13 @@ Gorse 支持 Jina/Cohere 风格的文本重排 API。它通过 `POST` 请求发 以下接口兼容这一基础文本重排协议： -| 服务 | 重排接口地址 | 说明 | -|------|--------------|------| -| [Jina AI](https://jina.ai/reranker/) | `https://api.jina.ai/v1/rerank` | 使用文本重排模型。 | -| [Cohere](https://docs.cohere.com/reference/rerank) | `https://api.cohere.com/v2/rerank` | 使用 Rerank API，而不是 Chat API。 | -| [阿里云百炼](https://help.aliyun.com/zh/model-studio/text-rerank-api) | `/compatible-api/v1/reranks` | 使用 `qwen3-rerank` 和对应地域、工作空间的兼容接口，而不是原生 text-rerank 接口。 | -| [硅基流动](https://docs.siliconflow.cn/docs/api/rerank-post) | `https://api.siliconflow.cn/v1/rerank` | 使用平台提供的文本重排模型。 | -| [vLLM](https://github.com/vllm-project/vllm/blob/main/examples/pooling/score/rerank_api_online.py) | `http://localhost:8000/rerank` | 将地址替换为实际部署地址，并使用服务提供的重排模型名称。 | +| 服务 | 重排接口地址 | +|------|--------------| +| [Jina AI](https://jina.ai/reranker/) | `https://api.jina.ai/v1/rerank` | +| [Cohere](https://docs.cohere.com/reference/rerank) | `https://api.cohere.com/v2/rerank` | +| [阿里云百炼](https://help.aliyun.com/zh/model-studio/text-rerank-api) | `/compatible-api/v1/reranks` | +| [硅基流动](https://docs.siliconflow.cn/docs/api/rerank-post) | `https://api.siliconflow.cn/v1/rerank` | +| [vLLM](https://github.com/vllm-project/vllm/blob/main/examples/pooling/score/rerank_api_online.py) | `http://localhost:8000/rerank` | `url` 必须填写**包含路径的完整重排接口地址**，而不是 API 基础地址。例如，除了上面的查询和文档模板，还可以配置 Jina AI： From 24ea39d45c7ffdd824293cf82d1db11a2ca423e5 Mon Sep 17 00:00:00 2001 From: zhenghaoz Date: Tue, 13 Oct 2026 15:58:51 +0800 Subject: [PATCH 3/3] docs: list llama.cpp as a compatible reranker --- src/docs/concepts/ranking.md | 1 + src/zh/docs/concepts/ranking.md | 1 + 2 files changed, 2 insertions(+) diff --git a/src/docs/concepts/ranking.md b/src/docs/concepts/ranking.md index aa6ffb3..945d9b3 100644 --- a/src/docs/concepts/ranking.md +++ b/src/docs/concepts/ranking.md @@ -143,6 +143,7 @@ The following interfaces are compatible with this basic text reranking protocol: | [Alibaba Cloud Model Studio](https://help.aliyun.com/en/model-studio/text-rerank-api) | `/compatible-api/v1/reranks` | | [SiliconFlow](https://docs.siliconflow.cn/docs/api/rerank-post) | `https://api.siliconflow.cn/v1/rerank` | | [vLLM](https://github.com/vllm-project/vllm/blob/main/examples/pooling/score/rerank_api_online.py) | `http://localhost:8000/rerank` | +| [llama.cpp (llama-server)](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md) | `http://localhost:8080/v1/rerank` | Set `url` to the **complete reranking endpoint**, including the path, rather than an API base URL. For example, configure Jina AI as follows, in addition to the query and document templates above: diff --git a/src/zh/docs/concepts/ranking.md b/src/zh/docs/concepts/ranking.md index 380a9ba..766400e 100644 --- a/src/zh/docs/concepts/ranking.md +++ b/src/zh/docs/concepts/ranking.md @@ -142,6 +142,7 @@ Gorse 支持 Jina/Cohere 风格的文本重排 API。它通过 `POST` 请求发 | [阿里云百炼](https://help.aliyun.com/zh/model-studio/text-rerank-api) | `/compatible-api/v1/reranks` | | [硅基流动](https://docs.siliconflow.cn/docs/api/rerank-post) | `https://api.siliconflow.cn/v1/rerank` | | [vLLM](https://github.com/vllm-project/vllm/blob/main/examples/pooling/score/rerank_api_online.py) | `http://localhost:8000/rerank` | +| [llama.cpp (llama-server)](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md) | `http://localhost:8080/v1/rerank` | `url` 必须填写**包含路径的完整重排接口地址**，而不是 API 基础地址。例如，除了上面的查询和文档模板，还可以配置 Jina AI：