Rerank API 的 Key 看起来和普通对话 Key 一样，实际风险更高：它每次请求都会带上用户查询和一批候选文档正文，并按调用量计费。Key 一旦泄露，别人可以消耗你的余额，也可能让你的账单里出现大量陌生请求。
本文讲两条获取路径：厂商官方平台，以及国内 AI 网关；再讲创建时的权限与额度设置、环境变量写法、401 排查和轮换流程。模型范围和价格以站内模型价格为准。
说明：Cohere、Jina AI、阿里云、硅基流动、火山引擎等名称归其权利人所有，本文仅用于技术说明。中商起航 AI 网关与上述厂商无隶属关系，接口与模型以站内说明为准。
一、Rerank Key 和对话 Key 的区别
对话 Key 调用生成模型，输入是消息，输出是文本。Rerank Key 调用重排序模型，输入是一条查询加一组候选文档，输出是每条文档的相关性分数和排序。
差异主要在三点：
- 数据更敏感：候选文档往往来自企业内部知识库，可能包含合同、制度、客户信息。
- 计费方式不同：通常按查询与文档的 token 数计费，长文档和大队列会放大消耗。
- 权限更单一：很多平台允许为 Key 限定模型范围，只放行 rerank 模型，降低误用风险。
因此，不要把 rerank Key 和对话 Key 混用，也不要把同一个 Key 同时发给多个项目。Key 的粒度应该是“环境 + 项目”。
二、路线 A：从厂商官方平台获取
Cohere、Jina AI、阿里云百炼、硅基流动、火山引擎等平台都提供重排序服务。入口和字段不同，流程大同小异：
- 选择平台：先确认支持的语言、最大文档长度、是否支持中文，以及数据是否出境。
- 注册账号：国内平台通常需要手机号或企业认证，海外平台需要邮箱和支付方式。
- 开通服务：在控制台找到 Rerank 或重排序服务，确认目标模型已经开通。
- 创建 Key：进入 API Keys 页面新建密钥，按“项目-环境”命名，例如
rag-prod。 - 设置限制：能设额度就设额度，能设过期时间就设过期时间，能限定模型就只勾选 rerank 模型。
- 立即测试：复制 Key 后先跑一条最小请求，确认鉴权、模型名和返回结构都正确。
不同平台的鉴权头不完全一样。Cohere 与 Jina 常用 Authorization: Bearer <key>，部分国内平台使用自己的签名方式。不要凭记忆写请求头，按当前官方文档抄。
三、路线 B：通过中商起航 AI 网关获取
如果团队没有海外支付方式，或者希望把多个模型的账单合并，可以走网关：
- 打开 中商起航 AI 网关 完成注册。
- 进入控制台的「API 密钥」页面，新建 Key。
- 填写名称，选择项目或分组，设置额度上限和过期时间。
- 在钱包充值，确认余额足够跑通测试。
- 复制 Key，保存到密码管理器，不要留在聊天记录里。
网关把重排序能力暴露为 POST /v1/rerank，同时兼容 /rerank，Base URL 为 https://ai.zhongshangqihang.com/v1。注意：Rerank 不在 OpenAI 的 Chat Completions 规范里，它是独立端点，不能直接套用聊天接口的 SDK 方法。
| 维度 | 厂商官方平台 | 中商起航 AI 网关 |
|---|---|---|
| 注册与付款 | 海外平台通常需外币卡，国内平台需实名 | 国内注册与充值，方式以结算页为准 |
| 网络 | 海外端点可能不稳定 | 国内直连，减少网络排查成本 |
| 模型范围 | 只覆盖该厂商模型 | 多上游模型统一入口，以模型列表为准 |
| 账单 | 按厂商分别对账 | 多模型合并账单，便于报销 |
| 数据路径 | 请求直达厂商 | 经网关转发，需确认数据处理条款 |
| 适合谁 | 固定单一厂商、需要原厂支持 | 多模型、国内团队、统一运维 |
两条路线可以并存。生产环境保留官方账户做兜底，国内团队和测试环境走网关，是常见做法。选之前先确认合同主体、发票类型和数据条款。
四、创建 Key 时的四个安全设置
拿到 Key 只是开始，创建时的设置决定后续出问题时的损失边界。
第一，按环境拆分。 开发、测试、生产各用一个 Key，命名里带项目和日期。这样排查账单时能直接定位到来源，泄露时也只需要停用一个。
第二，设置额度上限。 给每个 Key 设日额度或月额度，至少设一个告警阈值。Rerank 的消耗和文档数量、文档长度直接相关，一个循环脚本可能在短时间内产生大量请求。
第三，设置过期时间。 测试 Key 建议设短过期，生产 Key 按团队制度轮换。临时给外包或合作方开的 Key，到期自动失效比人工回收可靠。
第四，最小权限。 如果平台支持模型范围、IP 白名单或项目分组，只开放 rerank 模型和必要的来源地址。不要为了方便给 Key 开全部模型权限。
五、环境变量与代码读取
Key 只应该存在于服务端环境变量或密钥管理服务中，不要写进代码仓库，也不要打包进前端。最小配置如下：
RERANK_API_KEY=sk-你的密钥
RERANK_BASE_URL=https://ai.zhongshangqihang.com/v1
把 .env 加入 .gitignore，部署时通过平台的环境变量面板注入。Python 读取方式：
import os
import requests
api_key = os.environ["RERANK_API_KEY"]
base_url = os.environ.get("RERANK_BASE_URL", "https://ai.zhongshangqihang.com/v1")
resp = requests.post(
f"{base_url}/rerank",
headers={"Authorization": f"Bearer {api_key}"},
json={
"model": "你的重排序模型名",
"query": "试用期有多长？",
"documents": ["试用期为 14 天。", "支持对公转账。"],
"top_n": 2,
},
timeout=20,
)
resp.raise_for_status()
print(resp.json()["results"])
模型名以模型价格页为准。如果团队使用密钥管理服务，把 Key 存为密文，运行时注入，不要把它打印到日志。排查问题时可以打印请求 ID 和状态码，但不要打印完整的 Authorization 头。
六、401 排查：先分清认证失败和权限不足
401 表示身份没有被识别，403 表示身份已识别但没有权限。很多网关会把两者统一成一种错误结构，所以要看响应体和错误码，不要只看状态码。
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 401 Unauthorized | Key 拼错、前后有空格、复制时被截断 | 重新复制，确认没有换行符 |
| 401 invalid token | Key 已删除、已过期或属于其他项目 | 在控制台核对状态并重新创建 |
| 401 但 Key 确认无误 | 请求头字段写错，或 Base URL 指向了别的服务 | 按文档检查 Authorization 与路径 |
| 403 Forbidden | Key 没有该模型权限，或账户被冻结 | 检查模型范围与账户状态 |
| 404 Not Found | 模型名或端点路径错误 | 核对 /v1/rerank 与模型列表 |
| 429 Too Many Requests | 并发过高或触发额度限制 | 指数退避重试，检查额度与速率 |
排查顺序建议固定下来：先确认请求 URL 和请求头，再确认 Key 状态，然后确认模型名，最后看账户余额和限流。把这四步写成检查清单，比每次凭感觉试更快。
七、轮换与泄露处理
Key 轮换不是等出事才做。建议按固定周期轮换，人员离职、代码仓库误提交、日志中出现完整 Key 时立即执行。
- 在控制台新建 Key，名称里带轮换日期。
- 先把新 Key 写入测试环境，跑通一条最小请求。
- 更新生产环境变量并重启服务，观察错误率和调用量。
- 确认旧 Key 没有流量后，再禁用或删除。
- 查看最近调用日志，确认没有陌生来源或异常峰值。
- 记录轮换时间，把下一次轮换写进团队日历。
如果怀疑 Key 已经泄露，先停用旧 Key，再查账单和日志，不要先删日志。保留证据有助于判断影响范围。轮换完成后，检查代码仓库历史、CI 变量和聊天记录，确认没有其他副本。
八、常见问题
Rerank API Key 能调用对话模型吗？
取决于平台是否允许。即使技术上可以，也不建议这么做。重排序 Key 应该只用于 rerank 端点，避免一个 Key 同时承担生成和检索两类账单。
可以把 Key 放在前端或小程序里吗？
不可以。前端代码和网络请求都能被用户看到，Key 等于公开。正确做法是让前端调用自己的后端，由后端持有 Key 并转发请求。
401 和 403 有什么区别？
401 是认证失败，通常意味着 Key 无效、过期或请求头不对；403 是权限不足，Key 可能有效，但没有调用该模型或该项目的权限。先看错误体里的 code 和 message。
一个 Key 可以给多个项目共用吗？
技术上通常可以，运维上不建议。共用 Key 会让账单无法拆分，泄露时影响面也更大。至少按环境和项目拆开。
Key 多久轮换一次比较合适？
按团队安全制度执行。常见做法是定期轮换，并在人员变动、疑似泄露、仓库误提交时立即轮换。轮换频率没有统一标准，关键是流程可执行。
