1. 为什么 Qwen3-Reranker-4B 部署完还要折腾 LiteLLMQwen3-Reranker-4B 是一个 4B 参数量的重排序模型输入一个 query 加一批候选文档输出每个文档的相关性分数。它常被放在 RAG 检索链路的后半段先用向量库粗召回几十上百条再用 reranker 精排把真正相关的几条喂给大模型。相比 0.6B 版本4B 在中文长文本、多跳问答上的排序质量更稳代价是显存和延迟上去了所以一般用 vLLM 起服务而不是塞进业务进程里。vLLM 从 0.6 版本之后对 rerank 任务的支持逐渐完善你可以用vllm serve直接把 Qwen3-Reranker-4B 拉起来暴露一个兼容 OpenAI 风格的 HTTP 接口。问题在于这个接口是「裸」的地址是内网 IP 加端口没有鉴权、没有统一入口、没有多模型路由。你本地可能同时跑着 embedding、chat、rerank 好几个 vLLM 实例每个端口都不一样业务代码里到处硬编码http://100.129.110.100:9001这种地址换台机器就全崩。LiteLLM 的定位就是这层「统一网关」。它用一个config.yaml把不同 provider、不同api_base、不同模型聚合成一个 OpenAI 兼容入口业务侧只认一个 base_url 和一把 key。把 Qwen3-Reranker-4B 接进 LiteLLM核心就两件事告诉 LiteLLM 这个模型的api_base指向你的 vLLM 服务以及把它的mode标成rerank否则 LiteLLM 会默认按 chat 模型去调直接报错。再往上一层如果你希望本地 vLLM 和云端模型走同一个 Key、同一套调用习惯可以把这个 LiteLLM 网关再对接到 TaoToken 的统一通道。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它提供统一的 API Key 和 OpenAI 兼容入口适合把本地模型和托管模型放在一个调用体系里管理。这篇就按「vLLM 起服务 → LiteLLM 配 api_base 和 rerank → curl 验证 → 排错」的顺序走一遍配置都能直接复制。适合谁看本地已经用 vLLM 跑起 Qwen3-Reranker-4B、想加一层统一网关的开发者或者手上有多台推理机、想用一份配置管理所有模型的团队。如果你还没起 vLLM 服务下面第二节也会给启动命令。2. 前置准备vLLM 起 Qwen3-Reranker-4B 与 TaoToken Key2.1 用 vLLM 启动 rerank 服务先确认环境Python 3.10vLLM 建议 0.6.4 及以上rerank 支持较完整CUDA 驱动正常。Qwen3-Reranker-4B 的权重可以从 ModelScope 或 HuggingFace 拉这里以本地路径为例。启动命令vllm serve /models/Qwen3-Reranker-4B \ --served-model-name qwen3-reranker-4b \ --host 0.0.0.0 \ --port 9001 \ --task rerank \ --dtype bfloat16 \ --max-model-len 8192 \ --gpu-memory-utilization 0.85几个参数说明。--task rerank是关键不加的话 vLLM 会按生成模型加载rerank 接口不存在。--served-model-name决定后面请求里model字段填什么这里定为qwen3-reranker-4b。--max-model-len 8192对 reranker 够用Qwen3-Reranker 支持较长上下文但排序场景里 query 加文档一般不会太长调小能省显存。--gpu-memory-utilization 0.85留一点余量给系统。启动成功后日志里会出现类似Route: /v1/rerank的注册信息。你可以先用最朴素的 curl 确认服务活着curl http://127.0.0.1:9001/v1/rerank \ -H Content-Type: application/json \ -d { model: qwen3-reranker-4b, query: 什么是重排序模型, documents: [重排序模型用于对候选文档打分, 今天天气不错] }如果返回里带results数组和relevance_score说明 vLLM 侧没问题。注意此时还没有任何鉴权api_base就是http://100.129.110.100:9001这种内网地址。2.2 拿 TaoToken 的 Key如果你只在本机用LiteLLM 可以完全不接外部通道。但如果你想让本地 reranker 和云端模型共用一套 Key、统一计费和调用入口就需要一个上游通道。TaoToken 的 Key 获取路径是打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台在 API Keys 页面创建一个新 Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建时给它起个能认出来的名字比如litellm-local-rerank方便后面在日志里区分。复制出来的 Key 形如sk-xxxx只显示一次先存到环境变量里export TAOTOKEN_API_KEYsk-你的keyTaoToken 的 API 入口是 https://taotoken.net/api 这个地址不加任何查询参数直接作为api_base用。它的接口是 OpenAI 兼容风格所以 LiteLLM 里可以按openai/前缀的 provider 来配。这里要区分两个api_base一个是 LiteLLM 指向本地 vLLM 的地址http://100.129.110.100:9001一个是 LiteLLM 指向 TaoToken 的地址https://taotoken.net/api。前者是「模型在哪」后者是「统一通道在哪」。很多人第一次配会混后面配置节会分开写清楚。2.3 装 LiteLLMLiteLLM 用 pip 装即可建议固定版本因为 rerank 相关字段在不同版本间有差异。原文提到 1.93.0这里也用这个版本pip install litellm[proxy]1.93.0装完确认命令可用litellm --version如果要用到配置文件里的model_info确保版本不要太老1.9x 系列对mode: rerank的识别是正常的。低于 1.5x 的版本可能不认这个字段会把它当 chat 模型处理。3. LiteLLM config.yaml 可复制配置api_base 与 rerank 参数这一节是核心。LiteLLM 的配置文件默认叫config.yaml放在你启动 proxy 的目录下。下面给一份完整可复制的配置同时包含本地 vLLM reranker 和 TaoToken 通道两部分。model_list: # 本地 vLLM 起的 Qwen3-Reranker-4B - model_name: qwen3-reranker-4b litellm_params: model: openai/qwen3-reranker-4b api_base: http://100.129.110.100:9001 api_key: dummy model_info: mode: rerank # 通过 TaoToken 统一通道调用的模型示例 - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY general_settings: master_key: sk-litellm-local-2024 litellm_settings: drop_params: true逐段拆解。model_name是业务侧请求时填的model字段也就是对外暴露的名字这里叫qwen3-reranker-4b。litellm_params.model里的openai/前缀告诉 LiteLLM 用 OpenAI 兼容的调用方式去发请求后面跟的qwen3-reranker-4b是发给 vLLM 的模型名要和--served-model-name一致。api_base填http://100.129.110.100:9001这是你 vLLM 服务的实际地址。api_key填dummy就行因为本地 vLLM 没开鉴权但 LiteLLM 的 openai provider 要求这个字段存在随便给个非空值即可。model_info.mode: rerank是整份配置里最关键的一行。LiteLLM 靠它判断这个模型该走/rerank端点还是/chat/completions。不写这行你调 rerank 时会收到类似This model does not support the rerank endpoint或者直接被路由到 chat 接口报参数错误。原文里提到的model_info写法就是这个作用。TaoToken 那段用os.environ/TAOTOKEN_API_KEY从环境变量读 Key避免把明文写进文件。api_base是https://taotoken.net/api注意这里不带任何 UTM 参数就是纯 API 地址。general_settings.master_key是 LiteLLM 自己的入口鉴权业务侧调 LiteLLM 时用这个 key和上游的 TaoToken key 是两回事。如果你用的是 LiteLLM 的 UI 或者某些客户端比如 Cline、CC Switch 这类它们可能不直接读 yaml而是在「Advanced settings / LiteLLM Params」里填 JSON。等价写法是{ api_base: http://100.129.110.100:9001, model_info: { mode: rerank } }这段 JSON 就是原文 excerpt 里提到的填法Provider 选 Cohere 或 OpenAI 兼容都行重点是api_base和mode两个字段别丢。填完保存客户端会把它合并进 LiteLLM 的模型定义。启动 proxylitellm --config ./config.yaml --port 4000启动日志里会列出已加载的模型确认qwen3-reranker-4b在列表里且没有报 yaml 解析错误。到这里LiteLLM 侧就配好了业务侧统一访问http://127.0.0.1:4000。4. 验证请求curl 打通 LiteLLM 的 rerank 链路配置写完必须验证否则你不知道是 vLLM 的问题还是 LiteLLM 的问题。分两步走先直连 vLLM再走 LiteLLM。直连 vLLM 的验证上一节已经给过这里重点走 LiteLLM。请求 LiteLLM 的 rerank 端点curl http://127.0.0.1:4000/rerank \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-local-2024 \ -d { model: qwen3-reranker-4b, query: Qwen3-Reranker-4B 怎么接入 LiteLLM, documents: [ 在 LiteLLM 的 config.yaml 里配置 api_base 和 model_info.mode 为 rerank, 今天股市大涨, vLLM 用 --task rerank 启动重排序模型 ], top_n: 2 }注意几个点。URL 是/rerank不是/v1/rerankLiteLLM 的 proxy 默认挂在根路径下具体以你启动日志里显示的为准有的版本两个都支持。Authorization用的是master_key不是 TaoToken 的 key。model填的是model_name也就是qwen3-reranker-4b。top_n可选表示只返回分数最高的前 N 条。正常返回长这样{ id: rerank-xxx, results: [ { index: 0, relevance_score: 0.9231, document: { text: 在 LiteLLM 的 config.yaml 里配置 api_base 和 model_info.mode 为 rerank } }, { index: 2, relevance_score: 0.8104, document: { text: vLLM 用 --task rerank 启动重排序模型 } } ], usage: { total_tokens: 87 } }看到results里按relevance_score降序排列且第一条是语义最相关的说明整条链路通了业务 → LiteLLM4000→ vLLM9001→ Qwen3-Reranker-4B。如果你还想验证 TaoToken 通道那段配置可以调一个 chat 模型curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回正常说明 TaoToken 的 Key 和入口都没问题。这样你就有两条可用路径本地 reranker 走 LiteLLM 内网转发云端模型走 TaoToken 统一通道业务侧可以只认 LiteLLM 一个入口。实测下来把top_n设成 3 到 5 比较实用RAG 场景里精排后喂给大模型的文档数不宜太多否则上下文浪费。分数阈值可以自己在业务侧卡比如低于 0.3 的直接丢。5. 常见报错排查401、local proxy failed、reading choices配这套链路报错基本集中在几个地方。下面按真实遇到的错误对照排查。401 Unauthorized。两种可能。一是调 LiteLLM 时Authorization头没带或带错检查是不是用了master_key。二是 LiteLLM 转发到 TaoToken 时上游返回 401说明TAOTOKEN_API_KEY环境变量没生效或者 Key 失效。排查方法先echo $TAOTOKEN_API_KEY确认变量有值再直连 TaoToken 的/chat/completions看是否 401。如果直连也 401去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新生成一个 Key。local proxy failed / connection refused。LiteLLM 报这个通常是api_base指向的 vLLM 服务没起来或者地址端口写错。先在 LiteLLM 所在机器上curl http://100.129.110.100:9001/v1/rerank确认能通。如果 vLLM 在另一台机器检查防火墙和端口监听ss -tlnp | grep 9001。还有一种情况是 vLLM 启动时--host只绑了127.0.0.1外部访问不到改成0.0.0.0。reading choices / KeyError choices。这个报错说明 LiteLLM 把 rerank 请求当成 chat 请求发出去了vLLM 返回的是 rerank 格式没有choices字段LiteLLM 解析时找不到就报错。根因就是model_info.mode没配或配错。检查 config.yaml 里对应模型下有没有model_info: mode: rerank注意缩进model_info和litellm_params同级mode在model_info下面。如果你是在客户端 UI 里填 JSON确认model_info是对象而不是字符串。OAuth / authentication_error。如果你在 LiteLLM 里配了需要 OAuth 的 provider或者客户端比如某些 IDE 插件走了 OAuth 流程可能报这个。本地 vLLM 场景一般不涉及但如果你把 LiteLLM 接到需要 OAuth 的托管服务上要确认 token 没过期。TaoToken 用的是 API Key 方式不涉及 OAuth所以配 TaoToken 那段不会出这个错。模型名不匹配。报model not found或The model does not exist。检查三处名字是否一致vLLM 的--served-model-name、config.yaml 里litellm_params.model去掉openai/后的部分、请求体里的model。这三处任意一处不一致都会失败。建议统一用qwen3-reranker-4b这个小写带连字符的名字。返回分数全是 0 或顺序乱。这不是配置错误是模型本身对输入的处理问题。Qwen3-Reranker 对 query 和 document 的拼接格式有要求vLLM 的 rerank 实现一般会按模型自带的 template 处理。如果分数异常先直连 vLLM 测同样的输入排除 LiteLLM 的干扰。如果直连也异常检查 vLLM 版本是否支持该模型的 rerank template必要时升级 vLLM。排查顺序建议固定成先直连 vLLM → 再直连 LiteLLM → 最后走业务代码。每层单独验证能快速定位是哪一层的问题比一上来就查业务日志高效得多。6. 把本地 reranker 和统一通道串起来的几个实践建议配置跑通之后有几个细节值得固化下来。第一api_base尽量用环境变量或配置中心管理别硬编码在 yaml 里。LiteLLM 支持os.environ/XXX语法vLLM 地址也可以这么写api_base: os.environ/VLLM_RERANK_BASE这样换机器只改环境变量配置文件不用动。第二LiteLLM 的master_key和 TaoToken 的 Key 分开管理。前者是网关入口鉴权后者是上游通道鉴权混用会导致排查困难。业务侧只拿master_key上游 Key 只配在 LiteLLM 服务端。第三rerank 的top_n和分数阈值放在业务侧控制不要写死在 LiteLLM 配置里。LiteLLM 只负责转发排序策略是业务逻辑。这样调整策略不用重启网关。第四如果你同时有多个 reranker比如 0.6B 和 4B可以在 config.yaml 里配两个model_name指向不同api_base业务侧按场景选。小模型走低延迟场景4B 走高精度场景统一从 LiteLLM 入口调。第五长期跑编码或 Agent 类任务的话可以考虑用 TaoToken 的 Coding Plan 把调用额度集中管理入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。本地 reranker 负责精排云端模型负责生成两边通过 LiteLLM 和 TaoToken 串成一个体系Key 和调用习惯都统一。最后提醒一点vLLM 的 rerank 接口路径在不同版本间可能有/v1/rerank和/rerank的差异LiteLLM 转发时以你实际能通的为准。配好后用第 4 节的 curl 各测一遍把能通的路径记下来写进团队文档省得下次换人又踩一遍。 
长河君 · 2026/10/17 18:17:54 · 阅读 1.2k Qwen3-Reranker-4B 的 vLLM 模型配置到 LiteLLM：api_base 与 rerank 接入 TaoToken 实践
1. 为什么 Qwen3-Reranker-4B 部署完还要折腾 LiteLLMQwen3-Reranker-4B 是一个 4B 参数量的重排序模型输入一个 query 加一批候选文档输出每个文档的相关性分数。它常被放在 RAG 检索链路的后半段先用向量库粗召回几十上百条再用 reranker 精排把真正相关的几条喂给大模型。相比 0.6B 版本4B 在中文长文本、多跳问答上的排序质量更稳代价是显存和延迟上去了所以一般用 vLLM 起服务而不是塞进业务进程里。vLLM 从 0.6 版本之后对 rerank 任务的支持逐渐完善你可以用vllm serve直接把 Qwen3-Reranker-4B 拉起来暴露一个兼容 OpenAI 风格的 HTTP 接口。问题在于这个接口是「裸」的地址是内网 IP 加端口没有鉴权、没有统一入口、没有多模型路由。你本地可能同时跑着 embedding、chat、rerank 好几个 vLLM 实例每个端口都不一样业务代码里到处硬编码http://100.129.110.100:9001这种地址换台机器就全崩。LiteLLM 的定位就是这层「统一网关」。它用一个config.yaml把不同 provider、不同api_base、不同模型聚合成一个 OpenAI 兼容入口业务侧只认一个 base_url 和一把 key。把 Qwen3-Reranker-4B 接进 LiteLLM核心就两件事告诉 LiteLLM 这个模型的api_base指向你的 vLLM 服务以及把它的mode标成rerank否则 LiteLLM 会默认按 chat 模型去调直接报错。再往上一层如果你希望本地 vLLM 和云端模型走同一个 Key、同一套调用习惯可以把这个 LiteLLM 网关再对接到 TaoToken 的统一通道。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它提供统一的 API Key 和 OpenAI 兼容入口适合把本地模型和托管模型放在一个调用体系里管理。这篇就按「vLLM 起服务 → LiteLLM 配 api_base 和 rerank → curl 验证 → 排错」的顺序走一遍配置都能直接复制。适合谁看本地已经用 vLLM 跑起 Qwen3-Reranker-4B、想加一层统一网关的开发者或者手上有多台推理机、想用一份配置管理所有模型的团队。如果你还没起 vLLM 服务下面第二节也会给启动命令。2. 前置准备vLLM 起 Qwen3-Reranker-4B 与 TaoToken Key2.1 用 vLLM 启动 rerank 服务先确认环境Python 3.10vLLM 建议 0.6.4 及以上rerank 支持较完整CUDA 驱动正常。Qwen3-Reranker-4B 的权重可以从 ModelScope 或 HuggingFace 拉这里以本地路径为例。启动命令vllm serve /models/Qwen3-Reranker-4B \ --served-model-name qwen3-reranker-4b \ --host 0.0.0.0 \ --port 9001 \ --task rerank \ --dtype bfloat16 \ --max-model-len 8192 \ --gpu-memory-utilization 0.85几个参数说明。--task rerank是关键不加的话 vLLM 会按生成模型加载rerank 接口不存在。--served-model-name决定后面请求里model字段填什么这里定为qwen3-reranker-4b。--max-model-len 8192对 reranker 够用Qwen3-Reranker 支持较长上下文但排序场景里 query 加文档一般不会太长调小能省显存。--gpu-memory-utilization 0.85留一点余量给系统。启动成功后日志里会出现类似Route: /v1/rerank的注册信息。你可以先用最朴素的 curl 确认服务活着curl http://127.0.0.1:9001/v1/rerank \ -H Content-Type: application/json \ -d { model: qwen3-reranker-4b, query: 什么是重排序模型, documents: [重排序模型用于对候选文档打分, 今天天气不错] }如果返回里带results数组和relevance_score说明 vLLM 侧没问题。注意此时还没有任何鉴权api_base就是http://100.129.110.100:9001这种内网地址。2.2 拿 TaoToken 的 Key如果你只在本机用LiteLLM 可以完全不接外部通道。但如果你想让本地 reranker 和云端模型共用一套 Key、统一计费和调用入口就需要一个上游通道。TaoToken 的 Key 获取路径是打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台在 API Keys 页面创建一个新 Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建时给它起个能认出来的名字比如litellm-local-rerank方便后面在日志里区分。复制出来的 Key 形如sk-xxxx只显示一次先存到环境变量里export TAOTOKEN_API_KEYsk-你的keyTaoToken 的 API 入口是 https://taotoken.net/api 这个地址不加任何查询参数直接作为api_base用。它的接口是 OpenAI 兼容风格所以 LiteLLM 里可以按openai/前缀的 provider 来配。这里要区分两个api_base一个是 LiteLLM 指向本地 vLLM 的地址http://100.129.110.100:9001一个是 LiteLLM 指向 TaoToken 的地址https://taotoken.net/api。前者是「模型在哪」后者是「统一通道在哪」。很多人第一次配会混后面配置节会分开写清楚。2.3 装 LiteLLMLiteLLM 用 pip 装即可建议固定版本因为 rerank 相关字段在不同版本间有差异。原文提到 1.93.0这里也用这个版本pip install litellm[proxy]1.93.0装完确认命令可用litellm --version如果要用到配置文件里的model_info确保版本不要太老1.9x 系列对mode: rerank的识别是正常的。低于 1.5x 的版本可能不认这个字段会把它当 chat 模型处理。3. LiteLLM config.yaml 可复制配置api_base 与 rerank 参数这一节是核心。LiteLLM 的配置文件默认叫config.yaml放在你启动 proxy 的目录下。下面给一份完整可复制的配置同时包含本地 vLLM reranker 和 TaoToken 通道两部分。model_list: # 本地 vLLM 起的 Qwen3-Reranker-4B - model_name: qwen3-reranker-4b litellm_params: model: openai/qwen3-reranker-4b api_base: http://100.129.110.100:9001 api_key: dummy model_info: mode: rerank # 通过 TaoToken 统一通道调用的模型示例 - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY general_settings: master_key: sk-litellm-local-2024 litellm_settings: drop_params: true逐段拆解。model_name是业务侧请求时填的model字段也就是对外暴露的名字这里叫qwen3-reranker-4b。litellm_params.model里的openai/前缀告诉 LiteLLM 用 OpenAI 兼容的调用方式去发请求后面跟的qwen3-reranker-4b是发给 vLLM 的模型名要和--served-model-name一致。api_base填http://100.129.110.100:9001这是你 vLLM 服务的实际地址。api_key填dummy就行因为本地 vLLM 没开鉴权但 LiteLLM 的 openai provider 要求这个字段存在随便给个非空值即可。model_info.mode: rerank是整份配置里最关键的一行。LiteLLM 靠它判断这个模型该走/rerank端点还是/chat/completions。不写这行你调 rerank 时会收到类似This model does not support the rerank endpoint或者直接被路由到 chat 接口报参数错误。原文里提到的model_info写法就是这个作用。TaoToken 那段用os.environ/TAOTOKEN_API_KEY从环境变量读 Key避免把明文写进文件。api_base是https://taotoken.net/api注意这里不带任何 UTM 参数就是纯 API 地址。general_settings.master_key是 LiteLLM 自己的入口鉴权业务侧调 LiteLLM 时用这个 key和上游的 TaoToken key 是两回事。如果你用的是 LiteLLM 的 UI 或者某些客户端比如 Cline、CC Switch 这类它们可能不直接读 yaml而是在「Advanced settings / LiteLLM Params」里填 JSON。等价写法是{ api_base: http://100.129.110.100:9001, model_info: { mode: rerank } }这段 JSON 就是原文 excerpt 里提到的填法Provider 选 Cohere 或 OpenAI 兼容都行重点是api_base和mode两个字段别丢。填完保存客户端会把它合并进 LiteLLM 的模型定义。启动 proxylitellm --config ./config.yaml --port 4000启动日志里会列出已加载的模型确认qwen3-reranker-4b在列表里且没有报 yaml 解析错误。到这里LiteLLM 侧就配好了业务侧统一访问http://127.0.0.1:4000。4. 验证请求curl 打通 LiteLLM 的 rerank 链路配置写完必须验证否则你不知道是 vLLM 的问题还是 LiteLLM 的问题。分两步走先直连 vLLM再走 LiteLLM。直连 vLLM 的验证上一节已经给过这里重点走 LiteLLM。请求 LiteLLM 的 rerank 端点curl http://127.0.0.1:4000/rerank \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-local-2024 \ -d { model: qwen3-reranker-4b, query: Qwen3-Reranker-4B 怎么接入 LiteLLM, documents: [ 在 LiteLLM 的 config.yaml 里配置 api_base 和 model_info.mode 为 rerank, 今天股市大涨, vLLM 用 --task rerank 启动重排序模型 ], top_n: 2 }注意几个点。URL 是/rerank不是/v1/rerankLiteLLM 的 proxy 默认挂在根路径下具体以你启动日志里显示的为准有的版本两个都支持。Authorization用的是master_key不是 TaoToken 的 key。model填的是model_name也就是qwen3-reranker-4b。top_n可选表示只返回分数最高的前 N 条。正常返回长这样{ id: rerank-xxx, results: [ { index: 0, relevance_score: 0.9231, document: { text: 在 LiteLLM 的 config.yaml 里配置 api_base 和 model_info.mode 为 rerank } }, { index: 2, relevance_score: 0.8104, document: { text: vLLM 用 --task rerank 启动重排序模型 } } ], usage: { total_tokens: 87 } }看到results里按relevance_score降序排列且第一条是语义最相关的说明整条链路通了业务 → LiteLLM4000→ vLLM9001→ Qwen3-Reranker-4B。如果你还想验证 TaoToken 通道那段配置可以调一个 chat 模型curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回正常说明 TaoToken 的 Key 和入口都没问题。这样你就有两条可用路径本地 reranker 走 LiteLLM 内网转发云端模型走 TaoToken 统一通道业务侧可以只认 LiteLLM 一个入口。实测下来把top_n设成 3 到 5 比较实用RAG 场景里精排后喂给大模型的文档数不宜太多否则上下文浪费。分数阈值可以自己在业务侧卡比如低于 0.3 的直接丢。5. 常见报错排查401、local proxy failed、reading choices配这套链路报错基本集中在几个地方。下面按真实遇到的错误对照排查。401 Unauthorized。两种可能。一是调 LiteLLM 时Authorization头没带或带错检查是不是用了master_key。二是 LiteLLM 转发到 TaoToken 时上游返回 401说明TAOTOKEN_API_KEY环境变量没生效或者 Key 失效。排查方法先echo $TAOTOKEN_API_KEY确认变量有值再直连 TaoToken 的/chat/completions看是否 401。如果直连也 401去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新生成一个 Key。local proxy failed / connection refused。LiteLLM 报这个通常是api_base指向的 vLLM 服务没起来或者地址端口写错。先在 LiteLLM 所在机器上curl http://100.129.110.100:9001/v1/rerank确认能通。如果 vLLM 在另一台机器检查防火墙和端口监听ss -tlnp | grep 9001。还有一种情况是 vLLM 启动时--host只绑了127.0.0.1外部访问不到改成0.0.0.0。reading choices / KeyError choices。这个报错说明 LiteLLM 把 rerank 请求当成 chat 请求发出去了vLLM 返回的是 rerank 格式没有choices字段LiteLLM 解析时找不到就报错。根因就是model_info.mode没配或配错。检查 config.yaml 里对应模型下有没有model_info: mode: rerank注意缩进model_info和litellm_params同级mode在model_info下面。如果你是在客户端 UI 里填 JSON确认model_info是对象而不是字符串。OAuth / authentication_error。如果你在 LiteLLM 里配了需要 OAuth 的 provider或者客户端比如某些 IDE 插件走了 OAuth 流程可能报这个。本地 vLLM 场景一般不涉及但如果你把 LiteLLM 接到需要 OAuth 的托管服务上要确认 token 没过期。TaoToken 用的是 API Key 方式不涉及 OAuth所以配 TaoToken 那段不会出这个错。模型名不匹配。报model not found或The model does not exist。检查三处名字是否一致vLLM 的--served-model-name、config.yaml 里litellm_params.model去掉openai/后的部分、请求体里的model。这三处任意一处不一致都会失败。建议统一用qwen3-reranker-4b这个小写带连字符的名字。返回分数全是 0 或顺序乱。这不是配置错误是模型本身对输入的处理问题。Qwen3-Reranker 对 query 和 document 的拼接格式有要求vLLM 的 rerank 实现一般会按模型自带的 template 处理。如果分数异常先直连 vLLM 测同样的输入排除 LiteLLM 的干扰。如果直连也异常检查 vLLM 版本是否支持该模型的 rerank template必要时升级 vLLM。排查顺序建议固定成先直连 vLLM → 再直连 LiteLLM → 最后走业务代码。每层单独验证能快速定位是哪一层的问题比一上来就查业务日志高效得多。6. 把本地 reranker 和统一通道串起来的几个实践建议配置跑通之后有几个细节值得固化下来。第一api_base尽量用环境变量或配置中心管理别硬编码在 yaml 里。LiteLLM 支持os.environ/XXX语法vLLM 地址也可以这么写api_base: os.environ/VLLM_RERANK_BASE这样换机器只改环境变量配置文件不用动。第二LiteLLM 的master_key和 TaoToken 的 Key 分开管理。前者是网关入口鉴权后者是上游通道鉴权混用会导致排查困难。业务侧只拿master_key上游 Key 只配在 LiteLLM 服务端。第三rerank 的top_n和分数阈值放在业务侧控制不要写死在 LiteLLM 配置里。LiteLLM 只负责转发排序策略是业务逻辑。这样调整策略不用重启网关。第四如果你同时有多个 reranker比如 0.6B 和 4B可以在 config.yaml 里配两个model_name指向不同api_base业务侧按场景选。小模型走低延迟场景4B 走高精度场景统一从 LiteLLM 入口调。第五长期跑编码或 Agent 类任务的话可以考虑用 TaoToken 的 Coding Plan 把调用额度集中管理入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。本地 reranker 负责精排云端模型负责生成两边通过 LiteLLM 和 TaoToken 串成一个体系Key 和调用习惯都统一。最后提醒一点vLLM 的 rerank 接口路径在不同版本间可能有/v1/rerank和/rerank的差异LiteLLM 转发时以你实际能通的为准。配好后用第 4 节的 curl 各测一遍把能通的路径记下来写进团队文档省得下次换人又踩一遍。