Jina Reranker 替代方案：改用 ModelScope 模型

适用项目：webnovel-writer v6.2.1
问题：把默认的 Jina Reranker（jina-reranker-v3）替换为 ModelScope 上的模型，或其他 OpenAI 兼容的 rerank 服务。

代码层面的结论

• Rerank 客户端（webnovel-writer/scripts/data_modules/api_client.py 的 RerankAPIClient）本身就支持任意 OpenAI 兼容的 rerank 接口（Jina/Cohere 格式），Jina 只是默认值，不是硬编码；
• 请求格式：POST {RERANK_BASE_URL}/v1/rerank，body 为 {"query", "documents", "model", "top_n"}；
• 响应解析只认 results[].relevance_score 字段（rag_adapter.py:1087）；
• Rerank 是"软"失败：调用失败只跳过重排（保留原排序继续检索），不会像 Embedding 那样导致整体降级 BM25——所以换错配置最坏结果是"重排静默失效"，不会崩。

三个替代方案

方案 A：ModelScope 云端 API（推荐先 curl 验证）

ModelScope 的推理端点 api-inference.modelscope.cn 提供 OpenAI 兼容接口（本项目 Embedding 默认就是它）。Rerank 可同样指向它。书项目根目录的 .env 改为：

EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=你的modelscope_key

RERANK_BASE_URL=https://api-inference.modelscope.cn/v1
RERANK_MODEL=Qwen/Qwen3-Reranker-4B
RERANK_API_KEY=你的modelscope_key

代码会把 URL 拼成 https://api-inference.modelscope.cn/v1/rerank。改之前先用 curl 验证端点和返回字段（这一步很关键，因为解析器只认 relevance_score）：

curl -s https://api-inference.modelscope.cn/v1/rerank \
  -H "Authorization: Bearer 你的modelscope_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen/Qwen3-Reranker-4B", "query": "萧炎修炼", "documents": ["萧炎在密室突破斗师", "药老讲解炼丹"]}'

确认返回里有 results 数组且每项带 index + relevance_score，再改 .env。若返回字段是 score 而不是 relevance_score，会被代码静默忽略（重排无效但不出错），这种情况换方案 B 或 C。

ModelScope 上的模型选择：

方案 B：阿里云百炼 DashScope（官方确认的 OpenAI 兼容 rerank）

代码里已内置 DashScope 兼容路径（_is_dashscope_url / _build_dashscope_url，api_client.py:278-317），且接口格式与解析字段完全匹配（返回 relevance_score）：

RERANK_BASE_URL=https://dashscope.aliyuncs.com/compatible-api/v1
RERANK_MODEL=qwen3-rerank
RERANK_API_KEY=你的dashscope_key

qwen3-rerank 就是 Qwen3-Reranker 的云上服务版，支持 100+ 语言、单次最多 500 篇文档。

方案 C：ModelScope 权重本地部署（离线/不想付 API 费）

下载权重后用 vLLM / Xinference 起一个 OpenAI 兼容的 /rerank 服务，再把 RERANK_BASE_URL 指到 http://localhost:端口/v1 即可——代码对 URL 无域名限制。注意 Qwen3-Reranker 是生成式（decoder-only）模型，不能用 AutoModelForSequenceClassification 加载，推荐直接走 vLLM 部署。

操作步骤汇总

1. 先 curl 验证端点与返回字段（上面的命令）；
2. 改配置：编辑书项目根目录的 .env（初始化时生成的 .env.example 可复制），只改 RERANK_* 三行；
3. 生效与验证：

   • 配置加载顺序是：进程环境变量 > 书项目根 .env > ~/.claude/webnovel-writer/.env（docs/guides/rag-and-config.md）——如果你之前在 shell 里 export 过旧的 RERANK_*，它会覆盖 .env，先清掉；

   • 之后跑一次 /webnovel-write 或检索相关查询，观察有没有 [ERR] Rerank ... 输出（没有 = 正常；有 = 端点/Key/模型名问题）；

   • 想查整体状态可跑：

     python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<书根>" doctor --format text
     

     看 RAG 检查项。

注意事项

• RERANK_API_KEY 留空会导致请求 401 失败（软失败，只是不重排）；
• 多本书时建议每本书单独配 .env，避免串配置。

参考来源

• DashScope OpenAI 兼容重排序 API 文档
• Qwen3-Reranker-4B（ModelScope）
• webnovel-writer RAG 与配置说明