本文记录 Windows + Miniconda 环境下，搭建 BAAI/bge-reranker-v2-m3 本地重排序服务，并实现 Dify 对接本地 Rerank 的完整流程。

同时记录踩坑过程、依赖冲突解决方案，并提供可直接复制运行的完整命令与代码，方便后续快速复现。

---

一、环境准备

1. 创建 Conda 环境

conda create -n rerank python=3.10 -y
conda activate rerank

2. 安装依赖

方式 1：先安装基础包（踩坑版本）

我自己尝试的分步安装方式，需要后续手动修复依赖冲突，仅用于记录踩坑过程：

pip install fastapi uvicorn FlagEmbedding

方式 2：一步到位安装（推荐，直接装正确版本）

直接安装全部正确版本依赖，无冲突、不报错、安装完可直接运行服务：

pip install ^
FlagEmbedding==1.4.0 ^
fastapi uvicorn ^
transformers==4.44.2 ^
tokenizers==0.19.1 ^
huggingface-hub==0.25.2 ^
fsspec[http]==2026.2.0

选择方式 2 安装完成后，可直接跳到第五步运行 rerank.py 启动服务

---

二、版本冲突问题

直接安装后运行代码，大概率会出现以下错误：

• AttributeError: XLMRobertaTokenizer has no attribute 'prepare_for_model'
• ImportError: cannot import name 'EncoderDecoderCache'

原因：transformers 版本过高，与 FlagEmbedding 不兼容。

---

三、解决方案

1. 强制降级核心依赖

pip install -U --force-reinstall ^
"transformers==4.44.2" ^
"tokenizers==0.19.1" ^
"huggingface-hub==0.25.2"

2. 依赖冲突说明

执行后会出现以下提示，不会影响 Rerank 服务运行，可忽略也可选择修复：

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
This behaviour is the source of the following dependency conflicts.
datasets 4.8.5 requires fsspec[http]<=2026.2.0,>=2023.1.0, but you have fsspec 2026.4.0 which is incompatible.

3. 检查当前依赖冲突

pip check

输出：

datasets 4.8.5 has requirement fsspec[http]<=2026.2.0,>=2023.1.0, but you have fsspec 2026.4.0.

4. 修复 fsspec 版本冲突

pip install "fsspec[http]==2026.2.0"

5. 验证依赖是否完全正常

pip check

输出：

No broken requirements found.

依赖环境正常

---

四、最终可用完整代码（OpenAI 兼容）

文件名：rerank.py

import os
import time

# 国内镜像加速下载
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
# 模型下载到当前目录 models 文件夹
os.environ["HUGGINGFACE_HUB_CACHE"] = "./models"

from fastapi import FastAPI, Body
from FlagEmbedding import FlagReranker
import uvicorn

app = FastAPI(title="Rerank Service (OpenAI Compatible)")

# 加载模型
reranker = FlagReranker(
    "BAAI/bge-reranker-v2-m3",
    use_fp16=True
)


@app.post("/v1/rerank")
def rerank(
    model: str = Body("bge-reranker-v2-m3"),
    query: str = Body(...),
    documents: list[str] = Body(...),
    top_n: int | None = Body(None)
):
    pairs = [[query, doc] for doc in documents]
    scores = reranker.compute_score(pairs)

    results = [
        {
            "index": idx,
            "relevance_score": float(score)
        }
        for idx, score in enumerate(scores)
    ]

    results.sort(key=lambda x: x["relevance_score"], reverse=True)

    if top_n is not None:
        results = results[:top_n]

    return {
        "id": f"rerank-{int(time.time() * 1000)}",
        "object": "list",
        "model": model,
        "results": results,
        "usage": {
            "total_tokens": 0
        }
    }


if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=6609)

---

五、启动 Rerank 服务

python rerank.py

成功启动日志

INFO:     Started server process [14712]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:6609 (Press CTRL+C to quit)
You're using a XLMRobertaTokenizerFast tokenizer...

---

六、Dify 配置（重排模型）

• 模型类型：Rerank

• 厂商：OpenAI 兼容

• API 地址：http://host.docker.internal:6609/v1，具体原因可参考 Dify 接入本地嵌入模型（FastAPI+SentenceTransformer）-为什么必须用 host.docker.internal

• 模型名称：BAAI/bge-reranker-v2-m3

• API Key：随意即可