返回
原文
Hacker News 热门（buzzing.cc 中文翻译）
精选
75AI 编辑部评分，满分 100

Wayfinder Router：在本地和托管的大语言模型之间进行确定性查询路由

2026-06-29 00:58· 45天前· handfuloflight
AI 导读

Wayfinder Router 通过分析提示词的结构（长度、标题、列表、代码）和措辞（证明、数学、硬约束），在微秒级完成路由决策，完全离线且无需调用其他模型。默认仅使用结构特征，词汇线索因盲测未泛化而默认为关闭。对比依赖模型调用的路由器（如 RouteLLM、NotDiamond），它避免了延迟、成本和随机性。用户可在自有数据上校准评分阈值。支持任何 OpenAI 兼容 API（含 Ollama、Anthropic、Groq、vLLM 等），可自托管。提供终端和网页演示（--dry-run 无需密钥），以及基准测试和 FAQ。

推荐理由

Wayfinder Router 把 prompt 路由变成了离线文本分析，无需额外模型调用，对希望节省成本同时保持私密的开发者很实用，比现有方案更轻量和确定，但纯语义难题仍是短板。

正文 · AI 翻译
Wayfinder

一种快速、离线的“难易判断”机制，针对每条提示词给出确定性评分，无需调用模型。将简单问题路由至小型/本地模型，复杂问题路由至大型模型，也可在其后端组合任意模型路由器。

无需调用模型来决定路由 确定性且完全离线
基于自有数据进行校准 自带密钥，自行托管

Wayfinder 对提示词的结构（长度、标题、列表、代码）和措辞（证明、数学、硬约束）进行评分，生成 0.0–1.0 的复杂度分数，然后将简单问题路由至小型/本地模型，复杂问题路由至大型模型。其决策本身就是产品：确定性、亚毫秒级、完全离线——无需 API 密钥、无需网络、无需调用模型。路由目标由你决定：可以是两层、N 层阶梯，或在其后端组合的模型路由器。

廉价提示词留在本地，复杂提示词交给昂贵模型，这样你就不必再为“总结这段内容”和“修正我的拼写错误”支付顶级模型的价格。

对比分析

大多数路由器通过调用模型来做决策：训练好的分类器、大语言模型裁判或托管 API。这给本应节省成本的环节增加了延迟、成本和随机性。Wayfinder 则通过读取结构和措辞来决策，因此判断过程是免费的，且每次结果一致。

路由器 决策方式 需要调用模型？ 自行托管 可校准
Wayfinder 确定性结构评分 否 是 是
RouteLLM 训练好的分类器（偏好数据） 是 是 需重新训练
NotDiamond / Martian 学习型、托管式 是 否 通过平台
OpenRouter（自动） 托管式自动路由器 是 否 —
Bifrost / LiteLLM 提供商网关（非复杂度路由） 否 是 不适用

最后两行的网关（OpenRouter、Bifrost、LiteLLM）解决的是另一个问题：根据价格、可用性和故障转移，由哪个提供商处理调用。Wayfinder 解决的是提示词应归入哪个层级：廉价还是昂贵，按难度划分，离线决策。两者可以组合使用。运行 Wayfinder 来做廉价与昂贵的判断，再通过底层的网关来对接提供商。

Wayfinder 追求的不是顶尖的准确率数字——它提供的是你可以离线运行、并根据自身流量进行调优的路由决策。默认情况下，它仅对提示词结构进行评分；它也能读取词汇线索（如证明、数学、约束条件），但这些功能默认是关闭的，因为一项双盲测试表明，其性能提升并不具备泛化能力（它只能捕捉约 20% 未见过的困难提示词，并且输给了一个简单的词频基线）。一个难度纯粹来自语义层面的提示词（比如一段微妙的代码片段，或“第 100 个质数是多少？”），在结构上并无明显特征，此时语义路由器会胜出。基准测试（make benchmark）展示了它在哪些方面优于或劣于诚实的基线模型和完美的预言机；FAQ 则给出了直白的版本——包括它在 RouterBench 的短小但困难的项目上表现不比随机好，以及为什么你仍然会运行它。

试试演示（无需密钥）

两种方式让你亲自查看路由决策——无需 API 密钥，无需模型，无需任何网络连接。

在你的终端中——使用 Wayfinder 调色板进行以决策为先的聊天。终端聊天功能已包含在默认安装中，因此无需额外添加任何东西——或者通过 uvx 无需安装即可运行：

uvx wayfinder-router chat --dry-run      # zero install, zero keys
# or:  pip install wayfinder-router && wayfinder-router chat

每一轮对话都会显示其路由去向（● 本地 / ◆ 云端）、结构评分及原因（/why），以及与始终使用云端相比的累计节省。使用 /init 可在不离开聊天的情况下设置模型，/route · /local · /cloud 可强制指定某一轮的路由，并且对话会在不同会话间持久保存（/threads）。

在你的浏览器中——带有实时阈值滑块的网页聊天界面：

pip install "wayfinder-router[gateway]"
wayfinder-router webchat --dry-run
# opens http://127.0.0.1:8088/demo

webchat 是 serve（网关及其 /demo 页面；支持 --no-open、--port、--host 0.0.0.0、--dry-run 参数）的一个轻量级启动器；serve 是无头命令。在无配置的情况下，它仅作决策使用（--dry-run），因此你可以零设置进行尝试；要获得真实回复，请运行 wayfinder-router init 来搭建 [gateway.models]（然后运行 wayfinder-router doctor 确认你的密钥已解析）——请参阅快速入门指南。

兼容任何 OpenAI 兼容的 API

Wayfinder 会将每次调用转发至符合 OpenAI 风格的 `/chat/completions` 端点——因此，如果你的提供商支持该协议（大多数都支持），它就能直接运行。一个层级（tier）包含一个 `base_url`、一个模型名称，以及在请求时从环境中读取的一个密钥；无需 SDK，也无需为每个提供商编写代码。你可以将免费的本地模型与托管模型配对使用，或者运行两个云端层级。

……外加 Groq、Together、OpenRouter、Fireworks、DeepSeek，以及本地服务器（vLLM、LM Studio、llama.cpp）——以及任何接受 Bearer 密钥的、兼容 OpenAI 的端点。

在桌面版 Chat 中使用 ChatGPT Codex 账户（需主动选择加入）

原生桌面应用可以通过符合条件的 ChatGPT Codex 账户路由 Chat 请求，而无需 OpenAI 平台 API 密钥。这是一个独立的 codex-app-server 提供商——并非用于任意 OpenAI API 调用的 Bearer token——并且它永远不会被默认启用为路由。

将该路由添加到桌面网关配置中，重启网关，然后通过“设置”→“账户”登录：

[gateway.models.chatgpt-sol]
provider = "codex-app-server"
model = "gpt-5.6-sol"
context_window = 1050000

只有当该模型由独立的 Codex 运行时（runtime）通告时，账户路由才会出现在 Chat 中。登录不会改变“自动”模式或任何现有的路由阶梯。请求由托管服务处理并离开 Mac；离线模式会禁用该提供商。Wayfinder 接收的是标准化的账户状态和模型名称，绝不会获取账户 token，也不会扩大其凭据代理范围。开发版本可以使用显式选定或同位置部署的辅助程序。发布版本会拒绝未经验证的兄弟可执行文件；只有当其运行时和签名检查通过时，才接受固定的 ChatGPT 应用回退方案。公开发布仍受限于一个固定、已授权、架构正确且经过嵌套签名的辅助程序。完整的边界定义请参阅提供商设计文档。

快速入门

将 Wayfinder 置于你的模型之前。你的应用继续使用 OpenAI API；你只需更改一个 `base_url`。

  1. 搭建配置——`init` 命令会写入一个初始的 `wayfinder-router.toml`（无密钥的本地 Ollama → Anthropic 云端）以及一个 `.env.example` 文件，然后检查你的密钥：

    pip install "wayfinder-router[gateway]"
wayfinder-router init                 # starter config (hybrid preset)
wayfinder-router init --preset openai # two OpenAI tiers (gpt-4o-mini → gpt-4o)
wayfinder-router init --preset gemini # two Gemini tiers (gemini-2.5-flash → gemini-2.5-pro)
wayfinder-router init --interactive   # pick providers/models step by step

    或者，手动在 `wayfinder-router.toml` 中描述你的两个模型：

    [routing]
threshold = 0.5            # below -> local, at/above -> cloud

[gateway.models.local]
base_url = "http://localhost:11434/v1"
model = "llama3.2"

[gateway.models.cloud]
base_url = "https://api.openai.com/v1"
model = "gpt-4o"
api_key_env = "OPENAI_API_KEY"   # read from this env var, never stored
# api_key_cmd = "op read op://Private/OpenAI/credential"  # optional: fill it from a vault

    Wayfinder 从不存储密钥：模型指定一个环境变量（api_key_env），请求时从你的环境中读取该密钥。无需"安装"任何东西——只需导出变量即可。不想在 shell 中粘贴原始密钥？可以添加一个可选的 api_key_cmd，Wayfinder 会在启动时从你的密钥存储中填充该变量——op read …（1Password）、security …（macOS 钥匙串）、secret-tool …（Linux）、pass/gopass、vault kv get …、aws secretsmanager get-secret-value …、bw、doppler、gcloud secrets …，或任何能输出密钥的命令。密钥仅保存在内存中，绝不会写入磁盘。wayfinder-router doctor 会检测你安装了哪些工具，并给出精确的命令行建议。

  2. 设置好你的密钥，然后运行网关。doctor 会在你启动前重新检查配置以及每个模型的密钥是否解析成功（✓ 已设置 / ✗ 未设置）：

    export ANTHROPIC_API_KEY=sk-...     # or OPENAI_API_KEY, per your config
wayfinder-router doctor             # ✓/✗ per model — is each key set?
wayfinder-router serve --port 8088

  3. 将你现有的客户端指向它。无需修改代码：

    client = openai.OpenAI(base_url="http://localhost:8088/v1", api_key="unused")
client.chat.completions.create(model="auto", messages=[{"role": "user", "content": "..."}])

简单的提示词走本地，困难的走云端，每个响应都会携带 x-wayfinder-router-model 和 x-wayfinder-router-score，让你清楚请求去了哪里。想对某个请求强制指定层级？设置 model="local" 或 "cloud"（或 prefer-local / prefer-hosted），通过 X-Wayfinder-Threshold 标头为单次调用调整阈值，或者以 /local 或 /cloud 开头发送聊天消息（参见"控制单个请求"）。

检查是否正常运行：

curl -s localhost:8088/healthz
# {"status":"ok","models":["cloud","local"]}

curl -s -D - -o /dev/null http://localhost:8088/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i x-wayfinder-router
# x-wayfinder-router-model: local
# x-wayfinder-router-score: 0.00

还没有后端？wayfinder-router serve --dry-run 会返回路由决策结果，而不调用上游服务，这样你在接入真实模型之前，30 秒内就能感受路由效果。

安装

命令 获得内容
pip install wayfinder-router 评分器、CLI、Python API 以及终端聊天（chat）；评分器/库导入保持轻量依赖
pip install "wayfinder-router[gateway]" 添加兼容 OpenAI 的路由网关，这是服务部署的常见场景
pip install "wayfinder-router[ui]" 添加本地校准/解释/配置 UI
pip install "wayfinder-router[all]" 在默认安装基础上添加网关和 UI

作为本地服务运行

将 Wayfinder 设置为你的机器始终在线的 LLM 端点，这样所有兼容 OpenAI 的应用都可以共享一个本地 base_url，而你只需设置一次密钥。`service install` 命令会将其注册到操作系统服务管理器中，以便在登录时启动，并在退出时自动重启：

wayfinder-router service install     # macOS (launchd) or Linux (systemd user unit)
wayfinder-router service status      # is it running? endpoint + /healthz
wayfinder-router service uninstall

然后，将你的应用指向它一次——大多数兼容 OpenAI 的工具都会读取 `OPENAI_BASE_URL`：

export OPENAI_BASE_URL=http://127.0.0.1:8088/v1

macOS 是主要目标平台；Linux 也能运行。`--print` 参数会输出单元文件而不进行安装，如果没有服务管理器，它会写入单元文件并打印一条用于启动它的命令。这是同一个网关，只是保持持续运行——路由决策保持不变。

工作原理

Wayfinder 位于你正在使用的任何兼容 OpenAI 的客户端之后。你只需将该客户端的 base_url 指向网关一次，此后它便不可见。同一个客户端无论是路由到本地还是托管服务，都能处理请求。

  your client   (chat app, IDE, agent, or code)
       |
       v
  Wayfinder gateway   scores, picks a model
       |
       |-- low  -->  local    (Ollama, vLLM)
       |-- high -->  hosted   (OpenAI, any /v1)
       |
       v
  response returns via the same client,
  with x-wayfinder-router-* headers

由此衍生出以下几点：

  • 前端的界面由你决定。可以是聊天 GUI（Open WebUI、LibreChat）、带有自定义端点的 IDE 助手（Cursor、Continue）、智能体框架，或者是你基于 OpenAI SDK 编写的代码。今天想要一个聊天窗口？把 Open WebUI 放在前端，然后指向网关即可。
  • 本地和托管服务都是后端，而非应用。本地模型只是一个使用 OpenAI 的 `/v1` 协议进行通信的服务器（Ollama、LM Studio、vLLM、llama.cpp）；托管服务也是同样的形态。用户无需切换 UI，通常也不知道是哪个模型在回答。

密钥在请求时从环境中读取，绝不会触及配置文件或评分路径。

从 CLI 对提示词进行评分

echo "Summarise this paragraph in one sentence." | wayfinder-router route -

[[routing.tiers]]
min_score = 0.0
model = "llama-3b"
[[routing.tiers]]
min_score = 0.3
model = "llama-70b"
[[routing.tiers]]
min_score = 0.6
model = "claude-cloud"

分类器是一个拟合的多项逻辑回归模型，对每个模型进行线性评分后取 argmax。你通常使用 `calibrate` 命令生成它，而不是手动编写。

每个 `[gateway.models.<name>]` 配置块将一个路由名称映射到上游 base_url、一个模型以及可选的 api_key_env（环境变量名称，而非密钥本身）。网关是唯一接触密钥或网络的组件；评分器、配置和校准器保持纯净并离线运行。

在你的数据上进行校准

该截断值是一个代理指标，因此需要根据您自身的流量进行调整。`wayfinder-router calibrate` 会读取一个带标签的 JSONL 数据集（`{"text": ..., "label": ...}`），并输出一段配置片段。该过程离线运行，从不调用模型；标签即为您的真实标注。

wayfinder-router calibrate data.jsonl --mode threshold              # sweep the binary cut
wayfinder-router calibrate data.jsonl --mode tiers                  # ordinal multi-model
wayfinder-router calibrate data.jsonl --mode classifier --out wayfinder-router.toml

该配置片段可直接放入 `wayfinder-router.toml` 文件中；准确率和选定的断点值会打印到标准错误输出。分类器通过确定性的 L2 正则化牛顿法/IRLS 算法拟合，采用纯 Python 实现，仅需数次迭代即可收敛。

若要以成本而非单纯准确率来选择截断值，请使用成本感知目标函数。`--objective knee` 会自动选择成本感知的拐点（它最大化质量恢复率 × 成本节省率——无需猜测目标，且不会像纯准确率在标签倾斜时那样坍缩为始终路由到昂贵模型）；`--objective cost-quality --target-savings X` 则用于保持特定的节省下限。添加 `--weights` 可使用并输出自定义特征权重（例如词汇表选择加入机制），从而生成一个完整、可部署的配置（参见 docs/lexical-routing.md）：

wayfinder-router calibrate data.jsonl --mode threshold --objective knee \
  --costs local=0.2,cloud=1.0 \
  --weights reasoning_term_count=5,math_symbol_count=3,constraint_term_count=1.5

成本仅为元数据——它用于校准截断值，并会在 `/metrics` 端点上报告，但从不参与每次请求的决策过程，该决策始终保持确定性和零成本。

引导单个请求

部署配置设定了默认边界，但客户端可以在纯 OpenAI 传输层上为单个请求覆盖该决策。覆盖操作仅改变请求的发送目标；提示词仍会被评分，且不会增加任何模型调用。

  • model 字段是一条路由指令。`auto`（或任何普通模型 ID）让 Wayfinder 自行决定；配置好的端点名称（`local`、`cloud`）将请求固定到该处；`prefer-local` / `prefer-hosted` 将请求固定到路由器的低端/高端（`prefer-cloud` 仍可作为 `prefer-hosted` 的别名使用）。
  • `X-Wayfinder-Threshold` 标头可为该请求重新设定决策截断值，其值为 0.0-1.0 之间的数字，并复用您的权重（仅限二元路由器）。
  • 消息内指令（需主动启用：`[gateway] slash_directives = true`）让普通聊天框也能控制路由——以 `/local`、`/cloud`、`/prefer-hosted` 或 `/auto` 开头的消息会锁定该轮对话的路由（指令本身在模型看到之前会被剥离）。只有已知的指令才会被执行；任何以 `/` 开头但非上述指令的内容均作为普通文本处理（WF-ADR-0036）。
  • 离线模式让你在无网络环境下也能继续工作。设置 `[gateway] offline = true`（或针对单次请求发送 `X-Wayfinder-Offline: true`），Wayfinder 将只使用最便宜/本地层级，绝不调用云端层级——这样在飞机上请求就不会因超时而挂起。提示词仍会被评分和上报，仅交付方式发生变化（WF-ADR-0039）。
# Pin one call to cloud regardless of score:
client.chat.completions.create(model="cloud", messages=[...])
# Or move the cut for one call (keep model="auto"):
client.chat.completions.create(
    model="auto", messages=[...], extra_headers={"X-Wayfinder-Threshold": "0.8"}
)

每次响应都会在 `-model` 和 `-score` 头部旁边添加 `x-wayfinder-router-mode`（值为 `scored` / `pinned` / `threshold-override`），方便你查看是哪个通道决定了路由。

通过聊天界面驱动路由（无需分支）

由于模型字段本身就是路由指令，任何兼容 OpenAI 的聊天界面都无需修改代码即可驱动路由：应用原本的模型下拉菜单会变成每个对话的路由选择器（`auto` / `prefer-local` / `prefer-hosted` / 已固定的端点）。网关会在 `GET /v1/models` 中列出这些选项，因此界面可以自动发现它们。

  • LibreChat——将 `examples/librechat.yaml` 和 `examples/docker-compose.override.yml` 复制到你的项目目录中，运行 `docker compose up`，然后选择 "Wayfinder" 端点即可。
  • Open WebUI——添加一个指向该网关的 OpenAI 连接；它会自动发现路由选项。

具体配置请参见 `examples/` 目录。标准界面唯一无法实现的是每个对话的实时阈值滑块；这正是 `wayfinder-chat` 分支所增加的功能，而这条无需分支的路径首先验证了其可行性。

查看请求的去向

Wayfinder 的控制功能分散在你已有的各种工具中，因此很容易忽略它的运行。以下四个界面可以显示或控制路由：

界面 显示内容 位置
模型下拉菜单 路由选择器（`auto` / `prefer-local` / `prefer-hosted` / 已固定的端点） 你的客户端，来自 `GET /v1/models`
响应头部 每次请求的去向及原因（`-model` / `-score` / `-mode` / `-request-id`） 每次响应
调试响应体字段 响应体内的决策信息，需主动启用 请求头部 `X-Wayfinder-Debug: true`
仪表盘 近期决策、按模型统计的计数与评分——仅含元数据，绝不包含提示词文本 GET /router（JSON 格式，路径为 /router/recent）

该仪表盘与用于调优而非生产流量的 off-path wayfinder-router UI 控制台相互独立。

从反馈中学习

不要猜测路由切分点，而是通过自行判断本地输出与托管输出来学习。循环流程为：收集判断结果、进行校准、自动路由。

通过 A/B 引导流程进行初始化。对于每个样本提示词，wayfinder-router onboard 会同时运行两个分支，并询问哪个结果足够好；答案即为一个标签：

wayfinder-router onboard prompts.jsonl --arms local,cloud --calibrate > wayfinder-router.toml

比较结果输出到 stderr；--calibrate 将生成的配置打印到 stdout。每条判断结果都会向反馈日志追加一行 {"text", "label"}，该日志本身即为校准数据集，因此日志可直接转化为配置。

如需跳过人工评分，可让 wayfinder-router 自动判断标签。它会运行两个层级，并向自动评判器询问“较便宜的层级是否足够好？”——同样是关于充分性的问题，无需人工介入：

wayfinder-router judge prompts.jsonl --arms local,cloud --gold gold.jsonl > wayfinder-router.toml

内置评判器是一个确定性文本比较器，在无法判断时会选择弃权而非猜测。由于错误标签会静默降低在线路由质量，评判器仅在通过信任门控后才会输出配置——这些门控包括：与人工标注的 --gold 集的一致性（Cohen's κ ≥ 0.6）、相比多数基线的折外提升，以及两个分支均有代表性样本。若门控未通过，则会输出混淆矩阵并拒绝生成配置（标签仍会被记录）。传递 --save-comparisons out.jsonl 参数可同时保留原始响应（默认关闭——因其为数据体存储）。

一旦开始自动路由，请通过记录哪个模型实际足够好来保持诚实：

curl localhost:8088/v1/feedback -d '{"text": "...", "label": "cloud"}'

然后通过 cron 定时任务、k8s CronJob 或 UI 中的点击操作，按计划重新拟合。重新校准仅重写 [routing] 部分，并保留您的 [gateway] 端点；运行中的网关可热加载结果，无需重启：

wayfinder-router recalibrate                  # log -> calibrate -> write config
wayfinder-router recalibrate --min-labels 50  # no-op until you have enough signal

评判过程会运行模型，因此它位于网关层（使用您的密钥）；评分核心保持不变，日志中不包含任何机密信息。

部署与集成

CLI、新手引导和用户界面是为运维人员和初始启动而设计的。在生产环境中，提示词通过网关（透明模式）或库（进程内模式）进行路由，因此路由发生在提示词所在的位置。

将网关作为服务、边车或独立进程运行：

docker build -t wayfinder-router . && docker run -p 8088:8088 -v "$PWD/data:/data" wayfinder-router
# or: docker compose up gateway   (see docker-compose.example.yml)

将现有客户端指向它，无需修改应用程序。任何支持 OpenAI API 的对象都可以接受 base_url，包括智能体框架（LangChain、LlamaIndex）、带有自定义端点的 IDE 助手（Cursor、Continue）以及 LiteLLM 等网关：

client = openai.OpenAI(base_url="http://localhost:8088/v1", api_key="unused")

请参阅集成指南，了解如何在聊天 UI（Open WebUI、LibreChat、Jan）、编辑器（Continue、Cline、Zed、JetBrains）、智能体框架（LangChain、LlamaIndex、CrewAI、AutoGen、OpenAI Agents SDK、Vercel AI SDK）以及 CLI（aider、Copilot CLI）中进行复制粘贴式设置——此外还有标准的 OPENAI_BASE_URL / OPENAI_API_KEY 配置对。

Claude Code 使用的是 Anthropic 的 Messages API 而非 OpenAI 的 API，因此网关提供了一个 POST /v1/messages 适配器（WF-DESIGN-0011），用于在 Anthropic 和 OpenAI 之间进行双向转换——包括流式传输和工具调用。将其指向网关根地址后，Claude Code 就会像其他客户端一样通过 Wayfinder 进行路由：

export ANTHROPIC_BASE_URL="http://localhost:8088"   # client appends /v1/messages
export ANTHROPIC_API_KEY="unused"                   # the gateway uses each upstream's own key
claude

从用户所在的位置接入反馈。你的应用、IDE 或聊天界面会显示点赞或点踩按钮，并提交用户评价；下一次重新校准将从中学习：

fetch("http://localhost:8088/v1/feedback", {
  method: "POST",
  body: JSON.stringify({ text: prompt, label: wasGoodEnough ? "local" : "cloud" }),
});

网关以异步方式转发并支持流式传输：带有 stream: true 的请求会以服务器推送事件的形式返回，因此聊天客户端可以在 token 到达时即时渲染。上游超时或连接失败会返回符合 OpenAI 格式的错误信息，而不是裸的 500 错误；每个响应都带有用于追踪的请求 ID，路由决策和重载失败信息也会被记录。

除此之外，它还具备你期望的生产级控制功能——按请求设置超时、带目标级熔断和故障转移的有界重试、支出预算上限、精确匹配的响应缓存、速率限制，以及支持按密钥设置预算和允许列表的虚拟 API 密钥。这些功能默认处于关闭或宽松状态；有关每个设置及其对应的标头，请参阅网关配置参考。

解释与调优

要查看提示词为何被路由到特定位置，可以请求按特征维度分解：每个特征的值、其归一化水平、权重及其在分数中的占比。

wayfinder-router route prompt.md --explain

交互式调优可通过本地 Web UI 实现：

  • 解释——粘贴提示词；查看分数、层级阶梯和贡献柱状图，拖动阈值滑块即可实时观察路由变化。
  • 校准——粘贴带标签的数据集，运行一个模式，查看准确率、扫描曲线以及生成的配置片段。
  • 配置——编辑 wayfinder-router.toml 文件，支持实时验证并保存。
  • 上手——在浏览器中对本地模型和托管模型进行 A/B 测试，分别评判，并根据日志进行校准（模型调用需要 [gateway] 配置）。
pip install "wayfinder-router[ui]"
wayfinder-router ui --port 8099    # then open http://localhost:8099

该 UI 是对相同纯函数的一个轻量封装；它从不调用模型，其中也不会出现任何密钥。

Python API

from wayfinder_router import score_complexity, RoutingConfig, explain_score

result = score_complexity(prompt_text, config=RoutingConfig.binary(threshold=0.7))
print(result.recommendation, result.score, result.features)
for fc in explain_score(result.features, RoutingConfig().weights):
    print(fc.name, fc.contribution)

起源

Wayfinder 最初是作为一个更大需求工具内部的路由实验而诞生的，后来被拆分出来，因为路由是运行时关注的问题，而非知识性问题：提示词路由器不应强迫你安装一个并不需要的引擎。最终成果是一个小巧、专注的工具，其评分核心保持无依赖——你可以导入 wayfinder_router，仅用标准库即可对提示词进行评分（WF-ADR-0001, WF-ADR-0029）。

开源/仓库部署/工程

来源：Hacker News 热门（buzzing.cc 中文翻译） · github.com

导出 Markdown
返回
精选AI 评分 75/100打开原文
导出 Markdown

Wayfinder Router：在本地和托管的大语言模型之间进行确定性查询路由

Hacker News 热门（buzzing.cc 中文翻译）·2026-06-29 00:58·45天前·handfuloflight
AI 导读

Wayfinder Router 通过分析提示词的结构（长度、标题、列表、代码）和措辞（证明、数学、硬约束），在微秒级完成路由决策，完全离线且无需调用其他模型。默认仅使用结构特征，词汇线索因盲测未泛化而默认为关闭。对比依赖模型调用的路由器（如 RouteLLM、NotDiamond），它避免了延迟、成本和随机性。用户可在自有数据上校准评分阈值。支持任何 OpenAI 兼容 API（含 Ollama、Anthropic、Groq、vLLM 等），可自托管。提供终端和网页演示（--dry-run 无需密钥），以及基准测试和 FAQ。

正文 · AI 翻译
Wayfinder

一种快速、离线的“难易判断”机制，针对每条提示词给出确定性评分，无需调用模型。将简单问题路由至小型/本地模型，复杂问题路由至大型模型，也可在其后端组合任意模型路由器。

无需调用模型来决定路由 确定性且完全离线
基于自有数据进行校准 自带密钥，自行托管

Wayfinder 对提示词的结构（长度、标题、列表、代码）和措辞（证明、数学、硬约束）进行评分，生成 0.0–1.0 的复杂度分数，然后将简单问题路由至小型/本地模型，复杂问题路由至大型模型。其决策本身就是产品：确定性、亚毫秒级、完全离线——无需 API 密钥、无需网络、无需调用模型。路由目标由你决定：可以是两层、N 层阶梯，或在其后端组合的模型路由器。

廉价提示词留在本地，复杂提示词交给昂贵模型，这样你就不必再为“总结这段内容”和“修正我的拼写错误”支付顶级模型的价格。

对比分析

大多数路由器通过调用模型来做决策：训练好的分类器、大语言模型裁判或托管 API。这给本应节省成本的环节增加了延迟、成本和随机性。Wayfinder 则通过读取结构和措辞来决策，因此判断过程是免费的，且每次结果一致。

路由器 决策方式 需要调用模型？ 自行托管 可校准
Wayfinder 确定性结构评分 否 是 是
RouteLLM 训练好的分类器（偏好数据） 是 是 需重新训练
NotDiamond / Martian 学习型、托管式 是 否 通过平台
OpenRouter（自动） 托管式自动路由器 是 否 —
Bifrost / LiteLLM 提供商网关（非复杂度路由） 否 是 不适用

最后两行的网关（OpenRouter、Bifrost、LiteLLM）解决的是另一个问题：根据价格、可用性和故障转移，由哪个提供商处理调用。Wayfinder 解决的是提示词应归入哪个层级：廉价还是昂贵，按难度划分，离线决策。两者可以组合使用。运行 Wayfinder 来做廉价与昂贵的判断，再通过底层的网关来对接提供商。

Wayfinder 追求的不是顶尖的准确率数字——它提供的是你可以离线运行、并根据自身流量进行调优的路由决策。默认情况下，它仅对提示词结构进行评分；它也能读取词汇线索（如证明、数学、约束条件），但这些功能默认是关闭的，因为一项双盲测试表明，其性能提升并不具备泛化能力（它只能捕捉约 20% 未见过的困难提示词，并且输给了一个简单的词频基线）。一个难度纯粹来自语义层面的提示词（比如一段微妙的代码片段，或“第 100 个质数是多少？”），在结构上并无明显特征，此时语义路由器会胜出。基准测试（make benchmark）展示了它在哪些方面优于或劣于诚实的基线模型和完美的预言机；FAQ 则给出了直白的版本——包括它在 RouterBench 的短小但困难的项目上表现不比随机好，以及为什么你仍然会运行它。

试试演示（无需密钥）

两种方式让你亲自查看路由决策——无需 API 密钥，无需模型，无需任何网络连接。

在你的终端中——使用 Wayfinder 调色板进行以决策为先的聊天。终端聊天功能已包含在默认安装中，因此无需额外添加任何东西——或者通过 uvx 无需安装即可运行：

uvx wayfinder-router chat --dry-run      # zero install, zero keys
# or:  pip install wayfinder-router && wayfinder-router chat

每一轮对话都会显示其路由去向（● 本地 / ◆ 云端）、结构评分及原因（/why），以及与始终使用云端相比的累计节省。使用 /init 可在不离开聊天的情况下设置模型，/route · /local · /cloud 可强制指定某一轮的路由，并且对话会在不同会话间持久保存（/threads）。

在你的浏览器中——带有实时阈值滑块的网页聊天界面：

pip install "wayfinder-router[gateway]"
wayfinder-router webchat --dry-run
# opens http://127.0.0.1:8088/demo

webchat 是 serve（网关及其 /demo 页面；支持 --no-open、--port、--host 0.0.0.0、--dry-run 参数）的一个轻量级启动器；serve 是无头命令。在无配置的情况下，它仅作决策使用（--dry-run），因此你可以零设置进行尝试；要获得真实回复，请运行 wayfinder-router init 来搭建 [gateway.models]（然后运行 wayfinder-router doctor 确认你的密钥已解析）——请参阅快速入门指南。

兼容任何 OpenAI 兼容的 API

Wayfinder 会将每次调用转发至符合 OpenAI 风格的 `/chat/completions` 端点——因此，如果你的提供商支持该协议（大多数都支持），它就能直接运行。一个层级（tier）包含一个 `base_url`、一个模型名称，以及在请求时从环境中读取的一个密钥；无需 SDK，也无需为每个提供商编写代码。你可以将免费的本地模型与托管模型配对使用，或者运行两个云端层级。

……外加 Groq、Together、OpenRouter、Fireworks、DeepSeek，以及本地服务器（vLLM、LM Studio、llama.cpp）——以及任何接受 Bearer 密钥的、兼容 OpenAI 的端点。

在桌面版 Chat 中使用 ChatGPT Codex 账户（需主动选择加入）

原生桌面应用可以通过符合条件的 ChatGPT Codex 账户路由 Chat 请求，而无需 OpenAI 平台 API 密钥。这是一个独立的 codex-app-server 提供商——并非用于任意 OpenAI API 调用的 Bearer token——并且它永远不会被默认启用为路由。

将该路由添加到桌面网关配置中，重启网关，然后通过“设置”→“账户”登录：

[gateway.models.chatgpt-sol]
provider = "codex-app-server"
model = "gpt-5.6-sol"
context_window = 1050000

只有当该模型由独立的 Codex 运行时（runtime）通告时，账户路由才会出现在 Chat 中。登录不会改变“自动”模式或任何现有的路由阶梯。请求由托管服务处理并离开 Mac；离线模式会禁用该提供商。Wayfinder 接收的是标准化的账户状态和模型名称，绝不会获取账户 token，也不会扩大其凭据代理范围。开发版本可以使用显式选定或同位置部署的辅助程序。发布版本会拒绝未经验证的兄弟可执行文件；只有当其运行时和签名检查通过时，才接受固定的 ChatGPT 应用回退方案。公开发布仍受限于一个固定、已授权、架构正确且经过嵌套签名的辅助程序。完整的边界定义请参阅提供商设计文档。

快速入门

将 Wayfinder 置于你的模型之前。你的应用继续使用 OpenAI API；你只需更改一个 `base_url`。

  1. 搭建配置——`init` 命令会写入一个初始的 `wayfinder-router.toml`（无密钥的本地 Ollama → Anthropic 云端）以及一个 `.env.example` 文件，然后检查你的密钥：

    pip install "wayfinder-router[gateway]"
wayfinder-router init                 # starter config (hybrid preset)
wayfinder-router init --preset openai # two OpenAI tiers (gpt-4o-mini → gpt-4o)
wayfinder-router init --preset gemini # two Gemini tiers (gemini-2.5-flash → gemini-2.5-pro)
wayfinder-router init --interactive   # pick providers/models step by step

    或者，手动在 `wayfinder-router.toml` 中描述你的两个模型：

    [routing]
threshold = 0.5            # below -> local, at/above -> cloud

[gateway.models.local]
base_url = "http://localhost:11434/v1"
model = "llama3.2"

[gateway.models.cloud]
base_url = "https://api.openai.com/v1"
model = "gpt-4o"
api_key_env = "OPENAI_API_KEY"   # read from this env var, never stored
# api_key_cmd = "op read op://Private/OpenAI/credential"  # optional: fill it from a vault

    Wayfinder 从不存储密钥：模型指定一个环境变量（api_key_env），请求时从你的环境中读取该密钥。无需"安装"任何东西——只需导出变量即可。不想在 shell 中粘贴原始密钥？可以添加一个可选的 api_key_cmd，Wayfinder 会在启动时从你的密钥存储中填充该变量——op read …（1Password）、security …（macOS 钥匙串）、secret-tool …（Linux）、pass/gopass、vault kv get …、aws secretsmanager get-secret-value …、bw、doppler、gcloud secrets …，或任何能输出密钥的命令。密钥仅保存在内存中，绝不会写入磁盘。wayfinder-router doctor 会检测你安装了哪些工具，并给出精确的命令行建议。

  2. 设置好你的密钥，然后运行网关。doctor 会在你启动前重新检查配置以及每个模型的密钥是否解析成功（✓ 已设置 / ✗ 未设置）：

    export ANTHROPIC_API_KEY=sk-...     # or OPENAI_API_KEY, per your config
wayfinder-router doctor             # ✓/✗ per model — is each key set?
wayfinder-router serve --port 8088

  3. 将你现有的客户端指向它。无需修改代码：

    client = openai.OpenAI(base_url="http://localhost:8088/v1", api_key="unused")
client.chat.completions.create(model="auto", messages=[{"role": "user", "content": "..."}])

简单的提示词走本地，困难的走云端，每个响应都会携带 x-wayfinder-router-model 和 x-wayfinder-router-score，让你清楚请求去了哪里。想对某个请求强制指定层级？设置 model="local" 或 "cloud"（或 prefer-local / prefer-hosted），通过 X-Wayfinder-Threshold 标头为单次调用调整阈值，或者以 /local 或 /cloud 开头发送聊天消息（参见"控制单个请求"）。

检查是否正常运行：

curl -s localhost:8088/healthz
# {"status":"ok","models":["cloud","local"]}

curl -s -D - -o /dev/null http://localhost:8088/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i x-wayfinder-router
# x-wayfinder-router-model: local
# x-wayfinder-router-score: 0.00

还没有后端？wayfinder-router serve --dry-run 会返回路由决策结果，而不调用上游服务，这样你在接入真实模型之前，30 秒内就能感受路由效果。

安装

命令 获得内容
pip install wayfinder-router 评分器、CLI、Python API 以及终端聊天（chat）；评分器/库导入保持轻量依赖
pip install "wayfinder-router[gateway]" 添加兼容 OpenAI 的路由网关，这是服务部署的常见场景
pip install "wayfinder-router[ui]" 添加本地校准/解释/配置 UI
pip install "wayfinder-router[all]" 在默认安装基础上添加网关和 UI

作为本地服务运行

将 Wayfinder 设置为你的机器始终在线的 LLM 端点，这样所有兼容 OpenAI 的应用都可以共享一个本地 base_url，而你只需设置一次密钥。`service install` 命令会将其注册到操作系统服务管理器中，以便在登录时启动，并在退出时自动重启：

wayfinder-router service install     # macOS (launchd) or Linux (systemd user unit)
wayfinder-router service status      # is it running? endpoint + /healthz
wayfinder-router service uninstall

然后，将你的应用指向它一次——大多数兼容 OpenAI 的工具都会读取 `OPENAI_BASE_URL`：

export OPENAI_BASE_URL=http://127.0.0.1:8088/v1

macOS 是主要目标平台；Linux 也能运行。`--print` 参数会输出单元文件而不进行安装，如果没有服务管理器，它会写入单元文件并打印一条用于启动它的命令。这是同一个网关，只是保持持续运行——路由决策保持不变。

工作原理

Wayfinder 位于你正在使用的任何兼容 OpenAI 的客户端之后。你只需将该客户端的 base_url 指向网关一次，此后它便不可见。同一个客户端无论是路由到本地还是托管服务，都能处理请求。

  your client   (chat app, IDE, agent, or code)
       |
       v
  Wayfinder gateway   scores, picks a model
       |
       |-- low  -->  local    (Ollama, vLLM)
       |-- high -->  hosted   (OpenAI, any /v1)
       |
       v
  response returns via the same client,
  with x-wayfinder-router-* headers

由此衍生出以下几点：

  • 前端的界面由你决定。可以是聊天 GUI（Open WebUI、LibreChat）、带有自定义端点的 IDE 助手（Cursor、Continue）、智能体框架，或者是你基于 OpenAI SDK 编写的代码。今天想要一个聊天窗口？把 Open WebUI 放在前端，然后指向网关即可。
  • 本地和托管服务都是后端，而非应用。本地模型只是一个使用 OpenAI 的 `/v1` 协议进行通信的服务器（Ollama、LM Studio、vLLM、llama.cpp）；托管服务也是同样的形态。用户无需切换 UI，通常也不知道是哪个模型在回答。

密钥在请求时从环境中读取，绝不会触及配置文件或评分路径。

从 CLI 对提示词进行评分

echo "Summarise this paragraph in one sentence." | wayfinder-router route -

[[routing.tiers]]
min_score = 0.0
model = "llama-3b"
[[routing.tiers]]
min_score = 0.3
model = "llama-70b"
[[routing.tiers]]
min_score = 0.6
model = "claude-cloud"

分类器是一个拟合的多项逻辑回归模型，对每个模型进行线性评分后取 argmax。你通常使用 `calibrate` 命令生成它，而不是手动编写。

每个 `[gateway.models.<name>]` 配置块将一个路由名称映射到上游 base_url、一个模型以及可选的 api_key_env（环境变量名称，而非密钥本身）。网关是唯一接触密钥或网络的组件；评分器、配置和校准器保持纯净并离线运行。

在你的数据上进行校准

该截断值是一个代理指标，因此需要根据您自身的流量进行调整。`wayfinder-router calibrate` 会读取一个带标签的 JSONL 数据集（`{"text": ..., "label": ...}`），并输出一段配置片段。该过程离线运行，从不调用模型；标签即为您的真实标注。

wayfinder-router calibrate data.jsonl --mode threshold              # sweep the binary cut
wayfinder-router calibrate data.jsonl --mode tiers                  # ordinal multi-model
wayfinder-router calibrate data.jsonl --mode classifier --out wayfinder-router.toml

该配置片段可直接放入 `wayfinder-router.toml` 文件中；准确率和选定的断点值会打印到标准错误输出。分类器通过确定性的 L2 正则化牛顿法/IRLS 算法拟合，采用纯 Python 实现，仅需数次迭代即可收敛。

若要以成本而非单纯准确率来选择截断值，请使用成本感知目标函数。`--objective knee` 会自动选择成本感知的拐点（它最大化质量恢复率 × 成本节省率——无需猜测目标，且不会像纯准确率在标签倾斜时那样坍缩为始终路由到昂贵模型）；`--objective cost-quality --target-savings X` 则用于保持特定的节省下限。添加 `--weights` 可使用并输出自定义特征权重（例如词汇表选择加入机制），从而生成一个完整、可部署的配置（参见 docs/lexical-routing.md）：

wayfinder-router calibrate data.jsonl --mode threshold --objective knee \
  --costs local=0.2,cloud=1.0 \
  --weights reasoning_term_count=5,math_symbol_count=3,constraint_term_count=1.5

成本仅为元数据——它用于校准截断值，并会在 `/metrics` 端点上报告，但从不参与每次请求的决策过程，该决策始终保持确定性和零成本。

引导单个请求

部署配置设定了默认边界，但客户端可以在纯 OpenAI 传输层上为单个请求覆盖该决策。覆盖操作仅改变请求的发送目标；提示词仍会被评分，且不会增加任何模型调用。

  • model 字段是一条路由指令。`auto`（或任何普通模型 ID）让 Wayfinder 自行决定；配置好的端点名称（`local`、`cloud`）将请求固定到该处；`prefer-local` / `prefer-hosted` 将请求固定到路由器的低端/高端（`prefer-cloud` 仍可作为 `prefer-hosted` 的别名使用）。
  • `X-Wayfinder-Threshold` 标头可为该请求重新设定决策截断值，其值为 0.0-1.0 之间的数字，并复用您的权重（仅限二元路由器）。
  • 消息内指令（需主动启用：`[gateway] slash_directives = true`）让普通聊天框也能控制路由——以 `/local`、`/cloud`、`/prefer-hosted` 或 `/auto` 开头的消息会锁定该轮对话的路由（指令本身在模型看到之前会被剥离）。只有已知的指令才会被执行；任何以 `/` 开头但非上述指令的内容均作为普通文本处理（WF-ADR-0036）。
  • 离线模式让你在无网络环境下也能继续工作。设置 `[gateway] offline = true`（或针对单次请求发送 `X-Wayfinder-Offline: true`），Wayfinder 将只使用最便宜/本地层级，绝不调用云端层级——这样在飞机上请求就不会因超时而挂起。提示词仍会被评分和上报，仅交付方式发生变化（WF-ADR-0039）。
# Pin one call to cloud regardless of score:
client.chat.completions.create(model="cloud", messages=[...])
# Or move the cut for one call (keep model="auto"):
client.chat.completions.create(
    model="auto", messages=[...], extra_headers={"X-Wayfinder-Threshold": "0.8"}
)

每次响应都会在 `-model` 和 `-score` 头部旁边添加 `x-wayfinder-router-mode`（值为 `scored` / `pinned` / `threshold-override`），方便你查看是哪个通道决定了路由。

通过聊天界面驱动路由（无需分支）

由于模型字段本身就是路由指令，任何兼容 OpenAI 的聊天界面都无需修改代码即可驱动路由：应用原本的模型下拉菜单会变成每个对话的路由选择器（`auto` / `prefer-local` / `prefer-hosted` / 已固定的端点）。网关会在 `GET /v1/models` 中列出这些选项，因此界面可以自动发现它们。

  • LibreChat——将 `examples/librechat.yaml` 和 `examples/docker-compose.override.yml` 复制到你的项目目录中，运行 `docker compose up`，然后选择 "Wayfinder" 端点即可。
  • Open WebUI——添加一个指向该网关的 OpenAI 连接；它会自动发现路由选项。

具体配置请参见 `examples/` 目录。标准界面唯一无法实现的是每个对话的实时阈值滑块；这正是 `wayfinder-chat` 分支所增加的功能，而这条无需分支的路径首先验证了其可行性。

查看请求的去向

Wayfinder 的控制功能分散在你已有的各种工具中，因此很容易忽略它的运行。以下四个界面可以显示或控制路由：

界面 显示内容 位置
模型下拉菜单 路由选择器（`auto` / `prefer-local` / `prefer-hosted` / 已固定的端点） 你的客户端，来自 `GET /v1/models`
响应头部 每次请求的去向及原因（`-model` / `-score` / `-mode` / `-request-id`） 每次响应
调试响应体字段 响应体内的决策信息，需主动启用 请求头部 `X-Wayfinder-Debug: true`
仪表盘 近期决策、按模型统计的计数与评分——仅含元数据，绝不包含提示词文本 GET /router（JSON 格式，路径为 /router/recent）

该仪表盘与用于调优而非生产流量的 off-path wayfinder-router UI 控制台相互独立。

从反馈中学习

不要猜测路由切分点，而是通过自行判断本地输出与托管输出来学习。循环流程为：收集判断结果、进行校准、自动路由。

通过 A/B 引导流程进行初始化。对于每个样本提示词，wayfinder-router onboard 会同时运行两个分支，并询问哪个结果足够好；答案即为一个标签：

wayfinder-router onboard prompts.jsonl --arms local,cloud --calibrate > wayfinder-router.toml

比较结果输出到 stderr；--calibrate 将生成的配置打印到 stdout。每条判断结果都会向反馈日志追加一行 {"text", "label"}，该日志本身即为校准数据集，因此日志可直接转化为配置。

如需跳过人工评分，可让 wayfinder-router 自动判断标签。它会运行两个层级，并向自动评判器询问“较便宜的层级是否足够好？”——同样是关于充分性的问题，无需人工介入：

wayfinder-router judge prompts.jsonl --arms local,cloud --gold gold.jsonl > wayfinder-router.toml

内置评判器是一个确定性文本比较器，在无法判断时会选择弃权而非猜测。由于错误标签会静默降低在线路由质量，评判器仅在通过信任门控后才会输出配置——这些门控包括：与人工标注的 --gold 集的一致性（Cohen's κ ≥ 0.6）、相比多数基线的折外提升，以及两个分支均有代表性样本。若门控未通过，则会输出混淆矩阵并拒绝生成配置（标签仍会被记录）。传递 --save-comparisons out.jsonl 参数可同时保留原始响应（默认关闭——因其为数据体存储）。

一旦开始自动路由，请通过记录哪个模型实际足够好来保持诚实：

curl localhost:8088/v1/feedback -d '{"text": "...", "label": "cloud"}'

然后通过 cron 定时任务、k8s CronJob 或 UI 中的点击操作，按计划重新拟合。重新校准仅重写 [routing] 部分，并保留您的 [gateway] 端点；运行中的网关可热加载结果，无需重启：

wayfinder-router recalibrate                  # log -> calibrate -> write config
wayfinder-router recalibrate --min-labels 50  # no-op until you have enough signal

评判过程会运行模型，因此它位于网关层（使用您的密钥）；评分核心保持不变，日志中不包含任何机密信息。

部署与集成

CLI、新手引导和用户界面是为运维人员和初始启动而设计的。在生产环境中，提示词通过网关（透明模式）或库（进程内模式）进行路由，因此路由发生在提示词所在的位置。

将网关作为服务、边车或独立进程运行：

docker build -t wayfinder-router . && docker run -p 8088:8088 -v "$PWD/data:/data" wayfinder-router
# or: docker compose up gateway   (see docker-compose.example.yml)

将现有客户端指向它，无需修改应用程序。任何支持 OpenAI API 的对象都可以接受 base_url，包括智能体框架（LangChain、LlamaIndex）、带有自定义端点的 IDE 助手（Cursor、Continue）以及 LiteLLM 等网关：

client = openai.OpenAI(base_url="http://localhost:8088/v1", api_key="unused")

请参阅集成指南，了解如何在聊天 UI（Open WebUI、LibreChat、Jan）、编辑器（Continue、Cline、Zed、JetBrains）、智能体框架（LangChain、LlamaIndex、CrewAI、AutoGen、OpenAI Agents SDK、Vercel AI SDK）以及 CLI（aider、Copilot CLI）中进行复制粘贴式设置——此外还有标准的 OPENAI_BASE_URL / OPENAI_API_KEY 配置对。

Claude Code 使用的是 Anthropic 的 Messages API 而非 OpenAI 的 API，因此网关提供了一个 POST /v1/messages 适配器（WF-DESIGN-0011），用于在 Anthropic 和 OpenAI 之间进行双向转换——包括流式传输和工具调用。将其指向网关根地址后，Claude Code 就会像其他客户端一样通过 Wayfinder 进行路由：

export ANTHROPIC_BASE_URL="http://localhost:8088"   # client appends /v1/messages
export ANTHROPIC_API_KEY="unused"                   # the gateway uses each upstream's own key
claude

从用户所在的位置接入反馈。你的应用、IDE 或聊天界面会显示点赞或点踩按钮，并提交用户评价；下一次重新校准将从中学习：

fetch("http://localhost:8088/v1/feedback", {
  method: "POST",
  body: JSON.stringify({ text: prompt, label: wasGoodEnough ? "local" : "cloud" }),
});

网关以异步方式转发并支持流式传输：带有 stream: true 的请求会以服务器推送事件的形式返回，因此聊天客户端可以在 token 到达时即时渲染。上游超时或连接失败会返回符合 OpenAI 格式的错误信息，而不是裸的 500 错误；每个响应都带有用于追踪的请求 ID，路由决策和重载失败信息也会被记录。

除此之外，它还具备你期望的生产级控制功能——按请求设置超时、带目标级熔断和故障转移的有界重试、支出预算上限、精确匹配的响应缓存、速率限制，以及支持按密钥设置预算和允许列表的虚拟 API 密钥。这些功能默认处于关闭或宽松状态；有关每个设置及其对应的标头，请参阅网关配置参考。

解释与调优

要查看提示词为何被路由到特定位置，可以请求按特征维度分解：每个特征的值、其归一化水平、权重及其在分数中的占比。

wayfinder-router route prompt.md --explain

交互式调优可通过本地 Web UI 实现：

  • 解释——粘贴提示词；查看分数、层级阶梯和贡献柱状图，拖动阈值滑块即可实时观察路由变化。
  • 校准——粘贴带标签的数据集，运行一个模式，查看准确率、扫描曲线以及生成的配置片段。
  • 配置——编辑 wayfinder-router.toml 文件，支持实时验证并保存。
  • 上手——在浏览器中对本地模型和托管模型进行 A/B 测试，分别评判，并根据日志进行校准（模型调用需要 [gateway] 配置）。
pip install "wayfinder-router[ui]"
wayfinder-router ui --port 8099    # then open http://localhost:8099

该 UI 是对相同纯函数的一个轻量封装；它从不调用模型，其中也不会出现任何密钥。

Python API

from wayfinder_router import score_complexity, RoutingConfig, explain_score

result = score_complexity(prompt_text, config=RoutingConfig.binary(threshold=0.7))
print(result.recommendation, result.score, result.features)
for fc in explain_score(result.features, RoutingConfig().weights):
    print(fc.name, fc.contribution)

起源

Wayfinder 最初是作为一个更大需求工具内部的路由实验而诞生的，后来被拆分出来，因为路由是运行时关注的问题，而非知识性问题：提示词路由器不应强迫你安装一个并不需要的引擎。最终成果是一个小巧、专注的工具，其评分核心保持无依赖——你可以导入 wayfinder_router，仅用标准库即可对提示词进行评分（WF-ADR-0001, WF-ADR-0029）。

来源：Hacker News 热门（buzzing.cc 中文翻译）· github.com