项目定位与设计理念

Wayfinder Router 是一个确定性提示词复杂度路由器（deterministic prompt-complexity router），其核心目标是在不调用任何模型的前提下，根据提示词的结构与词汇特征，快速判定应当将其路由到本地小模型还是云端大模型，从而节省成本同时保持响应质量。资料来源：README.md:1-30。

该项目采用"分层纯净度"（purity layering）的架构思想：评分核心（scorer）、配置加载器（config）、校准器（calibrator）保持纯函数式且完全离线运行；只有网关层（gateway）与可选的本地 UI 才负责接触 API 密钥与网络请求。资料来源：README.md:24-28。

Wayfinder 的设计哲学强调：

• 零模型调用决策：路由决策由结构分析得出，而非依赖另一个 LLM 的判断；
• 完全可复现：相同的提示词与阈值永远得到相同的路由结果；
• 自带数据可校准：用户可基于自身流量数据微调阈值，而非依赖通用预训练模型；
• 自带密钥自托管：密钥仅在请求时从环境变量读取，绝不写入配置文件。资料来源：README.md:13-23。

核心架构

flowchart LR
    A[客户端应用] -->|OpenAI API| B[Wayfinder Gateway]
    B --> C{评分核心<br/>scorer}
    C -->|score < threshold| D[本地模型<br/>local]
    C -->|score ≥ threshold| E[云端模型<br/>cloud]
    D --> F[响应回传]
    E --> F
    B -.日志.-> G[反馈日志<br/>feedback log]
    G -.校准.-> H[calibrate]
    H -.重写.-> I[wayfinder-router.toml]
    I -.热加载.-> B

如上图所示，请求先经由网关进入，评分核心离线计算一个 0.0–1.0 之间的复杂度分数，再与配置中的阈值或层级表对比，决定目标模型。资料来源：README.md:32-48。

快速上手（Quickstart）

安装与初始化

pip install "wayfinder-router[gateway]"
wayfinder-router init                 # 起步配置（hybrid 预设）
wayfinder-router init --preset openai # 两级 OpenAI（gpt-4o-mini → gpt-4o）
wayfinder-router init --preset gemini # 两级 Gemini（flash → pro）
wayfinder-router init --interactive   # 逐步选择 provider/model

init 子命令会生成一份 wayfinder-router.toml 起步配置以及 .env.example 文件，并自动校验密钥可用性。资料来源：README.md:78-95。

最简配置示例

[routing]
threshold = 0.5            # 低于阈值路由到 local，否则路由到 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"   # 仅记录环境变量名
# api_key_cmd = "op read op://Private/OpenAI/credential"  # 可选：从 vault 注入

客户端只需将 base_url 切换为 Wayfinder 网关地址（如 http://localhost:8088/v1），原有的 OpenAI SDK 调用无需修改。资料来源：README.md:97-115。

CLI 评分与路由

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

输出包括推荐模型、复杂度分数、参与的特征值，添加 --json 可得到机器可读的 JSON，供上层 agent 自主路由。资料来源：README.md:142-175。

路由模式优先级

Wayfinder 支持三种路由模式，按优先级排列：classifier > tiers > threshold。资料来源：README.md:117-140。

• Binary（默认）：单一阈值切分；
• Tiered：按分数段映射到任意数量的模型；
• Classifier：多分类器对每个候选模型输出线性分数后取 argmax。

2026.6.7 版本：网关升级为控制平面

最新发布的 Wayfinder Router 2026.6.7 将网关从"个人代理"演进为"团队级控制平面"，新增多项面向生产环境的能力（均为 opt-in，路由决策方式不变）：

上述新增能力遵循"路由决策保持纯净"的设计原则，所有这些团队级控制都在网关层完成，不影响评分核心的离线与确定性。资料来源：README.md:240-265。

Docker 部署

docker build -t wayfinder-router . && docker run -p 8088:8088 -v "$PWD/data:/data" wayfinder-router
# 或：docker compose up gateway

Dockerfile 与 docker-compose.example.yml 已经随仓库提供。资料来源：README.md:42-46。

测试与开发

pip install -e .[dev]   # 或：pip install pytest
make test

测试套件覆盖：scorer、config、calibration、explain、feedback、onboard、recalibrate、CLI、gateway 以及 UI 各模块。资料来源：README.md:49-52。

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)

库导入仅依赖标准库，可作为进程内（in-process）路由使用，避开网关的网络开销。资料来源：README.md:296-305。

See Also

• How it compares — 与 RouteLLM、NotDiamond、OpenRouter 等的对比
• Calibration & Lexical Routing — 词汇特征权重与校准方法
• FAQ — 常见问题与已知弱点
• Benchmark — RouterBench / RouterArena 评测
• Explainer — 设计理念与决策记录索引

路由引擎架构

概述与定位

Wayfinder 路由引擎是一个确定性、离线、无模型调用的提示词复杂度评分器。它的核心职责是读取提示词的结构特征（长度、标题、列表、代码块）以及可选的词法线索（推理词、数学符号、硬约束），在毫秒级时间内为每个提示词打分并推荐本地或云端模型。资料来源：README.md:36-50

整个路由引擎由两类层组成：纯函数核心（scorer、tiers、classifier、config、calibrator、explain）保持无依赖且可独立 import；非纯层（gateway、本地 UI）通过可选的 extras 引入，负责网络与密钥管理。资料来源：README.md:200-220

flowchart TD
    A[客户端请求<br/>OpenAI 兼容] --> B[Wayfinder Gateway]
    B --> C{路由决策}
    C -->|mode=scored| D[评分器<br/>score_complexity]
    C -->|mode=pinned| E[直接锁定端点]
    C -->|mode=threshold-override| F[请求级 X-Wayfinder-Threshold]
    D --> G{路由模式}
    G -->|binary| H[threshold 阈值切割]
    G -->|tiered| I[[routing.tiers] 阶梯匹配]
    G -->|classifier| J[多项逻辑回归 argmax]
    H --> K[本地模型 / Ollama / vLLM]
    I --> K
    J --> K
    H --> L[云端模型 / OpenAI / Anthropic]
    I --> L
    J --> L
    K --> M[响应回传 + 路由头]
    L --> M

评分与三种路由模式

结构化特征评分

评分器从提示词中提取结构特征（word_count、heading_count、list_item_count、code_block_count 等），并按权重线性求和得到 0.0–1.0 的分数。词法线索（reasoning_term_count 等）默认关闭，需要在配置中显式提高权重才会启用。资料来源：README.md:160-175

三种路由模式（优先级：classifier > tiers > threshold）

Binary（二元切割）：单一阈值是最简单也最常用的模式。低于阈值走本地，等于或高于阈值走云端。--threshold N 可在运行时覆盖，WAYFINDER_ROUTER_THRESHOLD 环境变量同样生效。资料来源：README.md:155-165

Tiered（多档分级）：按分数段映射到任意数量的模型。例如：

[[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"

资料来源：README.md:170-185

Classifier（分类器）：通过 calibrate --mode classifier 离线拟合的多项逻辑回归模型，对每个模型输出一条线性分数，取 argmax。通常由 calibrate 自动生成而非手写。资料来源：README.md:185-195

请求级干预与单次控制

引擎将 OpenAI 的 model 字段视为路由指令，而非模型标识：

响应头 x-wayfinder-router-mode 会标注决策来自哪种通道（scored / pinned / threshold-override）。资料来源：README.md:140-160

校准、词法线索与配置管理

引擎虽然默认开箱即用，但鼓励用户基于自身流量重新校准。wayfinder-router calibrate 子命令读取 {"text": ..., "label": ...} 格式的 JSONL 数据集，离线运行 L2 正则化的 Newton/IRLS 拟合，输出可直接粘贴进 wayfinder-router.toml 的配置片段。--objective knee 选项会自动选择成本-质量拐点，避免在偏斜标签上退化为"全部走昂贵模型"。资料来源：README.md:60-90

词法线索（证明、数学、约束）在真实前沿流量上能让 held-out 技能从 −0.038 提升到 +0.057、节省 61% RouterBench 成本，但双盲测试显示其泛化能力并不强，因此默认关闭，需要显式启用。资料来源：README.md:165-180、docs/lexical-routing.md

与 Gateway 的集成

路由引擎通过 [gateway.models.<name>] 块映射路由名到上游 base_url、model 及 api_key_env（环境变量名而非密钥本身）。Gateway 是唯一接触密钥与网络的层；评分器、配置和校准器始终保持纯函数与离线。GET /v1/models 会向客户端暴露路由选项（auto / prefer-local / prefer-hosted 及配置的端点），使 LibreChat、Open WebUI 等兼容 UI 自动获得路由模式选择器而无需 fork。资料来源：README.md:195-210、examples/README.md:1-25

wayfinder-router.toml 由 CLI 在当前目录向上回溯发现，三种模式按优先级（classifier > tiers > threshold）生效，标量分数 weights 适用于前两种。资料来源：README.md:150-165

参见

• 快速开始与 Quickstart
• 词法路由指南
• 集成示例（LibreChat / Open WebUI）
• 基准测试与公平比较
• 常见问题 FAQ
• 2026.6.7 版本说明 — gateway as a control plane

1. 总体架构与请求生命周期

控制平面在网关请求处理管道中以前置守护栏的形式出现，顺序为：限流 → 密钥鉴权 → 预算 → 缓存读取 → 评分与路由 → 转发 → 缓存写入 → 计费 → 度量导出。这样设计确保所有守护栏都在请求真正落到上游模型前生效，避免无谓的网络与计费开销 资料来源：wayfinder_router/gateway.py:1-200。

flowchart LR
    A[Client Request] --> B[Rate Limiter]
    B -->|429| Z[Reject]
    B --> C[Virtual Key Auth]
    C -->|401| Z
    C --> D[Budget Check]
    D -->|402| Z
    D --> E[Cache Lookup]
    E -->|hit| Y[Replay Response]
    E -->|miss| F[Score + Route]
    F --> G[Upstream Call]
    G --> H[Cache Write]
    H --> I[Cost Attribution]
    I --> J[Metrics + Headers]
    Y --> J
    J --> K[Response to Client]

每个阶段都向响应注入 x-wayfinder-router-* 头，便于运维侧观察决策与拦截位置 资料来源：README.md:150-200。

2. 虚拟 API 密钥（Virtual Keys）

虚拟密钥让单个 Wayfinder 网关实例可以被多团队共享使用，同时为每个团队提供独立的配额、限流与模型白名单。wayfinder-router keys new 生成新密钥，仅存储 SHA-256 哈希；原始令牌仅在创建时显示一次 资料来源：README.md:165-175。

2.1 配置结构

每个密钥在 wayfinder-router.toml 中由 [gateway.keys.<id>] 块描述。嵌套的 budget、rate_limit、models 字段分别用于设定该密钥的预算上限、限流策略与可访问模型白名单；网关侧采用"最严格优先"策略合并用户级与密钥级配置 资料来源：wayfinder_router/vkeys.py:1-150。

2.2 节省归因

/v1/savings 端点支持 by_key 维度，揭示每条密钥的累计支出、路由节省金额与命中率。wayfinder_router_key_requests_total Prometheus 指标按密钥打标，使财务与可观测系统可独立核算 资料来源：README.md:170-180、资料来源：wayfinder_router/metrics.py:1-120。

2.3 模型白名单与降级

当密钥携带 models = ["local"] 之类的允许列表时，网关会把评分结果"夹"到最近的可允许层级——例如评分请求 cloud 但白名单仅含 local 时，请求会被强制路由到本地端点 资料来源：decisions/WF-ADR-0035.md:1-60。

3. 限流、可靠性与重试

3.1 速率限制

[gateway.rate_limit] 段支持 rpm（每分钟请求数）与 tpm（每分钟上游 token 数）两种维度，二者可独立启用并叠加生效。窗口长度由 window 控制，默认 60 秒。超额时返回 HTTP 429 并附带 Retry-After；未超限的响应会回传 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset，便于客户端自我节流 资料来源：wayfinder_router/ratelimit.py:1-160、资料来源：decisions/WF-ADR-0034.md:1-50。

3.2 重试与熔断

[gateway.reliability] 段提供 max_retries 与 breaker_cooldown 两个开关：前者限定对瞬时传输错误、429 与 5xx 的有界重试次数，后者控制每个上游目标的熔断恢复时间。熔断器按目标独立维护，避免单点失败污染整体可用性 资料来源：wayfinder_router/reliability.py:1-180、资料来源：decisions/WF-ADR-0031.md:1-60。

4. 响应缓存

[gateway.cache] 提供基于精确匹配的响应缓存，对确定性请求返回已存储的回答，使重复请求瞬时且免费。该功能默认关闭，开启后仅在内存中保存，并可通过 max_bytes（默认 64 MiB）与 max_entries 控制体量 资料来源：wayfinder_router/cache.py:1-150、资料来源：decisions/WF-ADR-0033.md:1-40。

4.1 命中观测

每次响应都会携带 x-wayfinder-router-cache: hit|miss 头，运维侧据此判断缓存效果。关闭缓存时会自动清空既有条目，防止陈旧数据回流 资料来源：README.md:155-165。

4.2 适用边界

缓存仅对"相同输入产生相同输出"的请求有效：例如 temperature=0 的聊天补全、确定的嵌入调用等。带 stream: true 的流式请求在网关层会被缓存决策拦截后再决定是否走流通道，避免不一致体验 资料来源：wayfinder_router/cache.py:50-120。

5. 预算守护

[gateway.budget] 段控制总支出上限，由 limit、window（day / month / all）与 on_breach（degrade / block）三个字段构成。degrade（默认）将超额请求降级到最便宜的层级，永不抬升成本；block 则直接返回 HTTP 402 阻止调用 资料来源：decisions/WF-ADR-0032.md:1-50。

预算计算依赖真实价格：在 [gateway.models.<name>] 中需提供 cost_per_1k 字段，否则系统会以"成本未知"的形式跳过预算检查并在响应头 x-wayfinder-router-budget 中明示。价格元数据同时上报到 /metrics，供财务与可观测系统使用 资料来源：wayfinder_router/pricing.py:1-120。

6. 配置速查表

7. 常见故障与处理

• 预算未生效：检查模型配置是否提供 cost_per_1k；若缺失，预算是"软跳过"而非拒绝 资料来源：wayfinder_router/pricing.py:80-120。
• 密钥失效：keys new 仅展示原始令牌一次；丢失后必须重新签发，原哈希不可逆 资料来源：wayfinder_router/vkeys.py:60-100。
• 缓存命中率低：检查请求是否带有影响输出的字段（temperature、seed、tools），非确定性请求会被旁路 资料来源：wayfinder_router/cache.py:30-80。
• 熔断时间过长：breaker_cooldown 单位为秒，过高会导致流量长时间被剔除；建议配合监控逐步调优 资料来源：decisions/WF-ADR-0031.md:30-60。

See Also

• Wayfinder Router 主维基页
• 可靠性设计（WF-ADR-0031）
• 预算守护（WF-ADR-0032）
• 响应缓存（WF-ADR-0033）
• 速率限制（WF-ADR-0034）
• 虚拟密钥（WF-ADR-0035）

概述

Wayfinder 的路由决策基于一个 0.0–1.0 的"复杂度分数",该分数通过纯离线、确定性的方式计算（不调用任何模型）。然而,这个分数本身只是难度的代理指标,因此最终的"切割点"(threshold / tiers / classifier)必须由使用者根据自身流量调优。校准(Calibration)、引导(Onboarding)与反馈循环(Feedback Loop) 正是用来解决这一问题的子系统:它把人工判断转成可执行的路由配置,并在网关运行期间持续迭代,使切割点始终贴近真实业务负载。整套机制运行在纯 Python 中,从不发起模型调用,因此即便在最严格的离线环境也能保持可重现。 资料来源：README.md

校准(calibrate)

wayfinder-router calibrate 是整个反馈循环的"拟合"环节。它读取一个 JSONL 格式的标注数据集 {"text": ..., "label": ...},在本地拟合三种模式之一,并把可直接部署的 TOML 配置片段输出到 stdout,把准确率与所选切割点打印到 stderr。 资料来源：wayfinder_router/calibrate.py

拟合算法使用确定性 L2 正则化的 Newton/IRLS,纯 Python 实现,通常在数轮迭代内收敛。 资料来源：README.md 资料来源：decisions/WF-ADR-0003-calibration-and-classifier.md

成本感知目标

单纯追求准确率会令模型在偏斜标签下"全选贵的"。为此 calibrate 提供两类目标函数:

• --objective knee — 自动挑选成本曲线的拐点,最大化 quality_recovered × cost_saved,无需指定目标,也不会退化为全选高端模型。
• --objective cost-quality --target-savings X — 在保证不低于 X 节省率的前提下最大化质量。

成本通过 --costs local=0.2,cloud=1.0 提供,仅参与拟合与 /metrics 报告,绝不参与单请求决策,从而保证路由本身保持确定性、零成本。 资料来源：README.md 资料来源：wayfinder_router/pricing.py

词法特征校准

词法线索(推理词、数学符号、约束词等)在默认状态下是关闭的,因其通用性较差(benchmarks/blind-eval.md 显示盲测下提升仅约 20% 且会输给纯词数基线)。可通过 --weights 在 calibrate 中一并拟合并写出,使产出的配置可直接部署。 资料来源：docs/lexical-routing.md 资料来源：benchmarks/calibration-eval.md

引导与反馈(onboard / feedback)

仅靠历史日志启动时往往缺乏标签。wayfinder-router onboard 通过 A/B 方式在终端或 UI 中对同一条样本同时跑两臂模型,让用户挑选"哪一臂足够好",其判定 {"text", "label"} 直接落到反馈日志中,等同于 calibrate 的数据集。配合 --calibrate 选项,onboard 可一次性把日志转成 TOML 并写入文件。 资料来源：wayfinder_router/onboard.py 资料来源：README.md

当网关已在运行时,可直接通过 HTTP 端点写入判定,无需重启:

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

判定被持久化为 JSONL,无任何提示词原文以外的敏感信息;密钥读取和模型调用仅限于网关层,评分核心不被触发。 资料来源：wayfinder_router/feedback.py

重校准与热重载(recalibrate)

flowchart LR
  A[prompt traffic] --> B{router}
  B --> C[judge / onboard]
  C --> D[feedback log<br/>JSONL]
  D --> E[recalibrate]
  E --> F[wayfinder-router.toml]
  F --> B
  B -.header.-> G[per-request<br/>X-Wayfinder-Threshold]

wayfinder-router recalibrate 编排"日志 → calibrate → 写配置"的全流程,可由 cron、Kubernetes CronJob 或 UI 按钮触发。它只重写 [routing] 段,完整保留 [gateway] 中的端点、密钥与重试配置;运行中的网关会无重启地热加载新配置。 资料来源：wayfinder_router/recalibrate.py 资料来源：README.md

为避免在标签不足时给出噪声拟合,recalibrate 接受 --min-labels 50 阈值,在样本数不达标时静默 no-op,从而保护生产稳定性。 资料来源：wayfinder_router/recalibrate.py

常见失败模式

• 样本过少即启动:约 20 条仅是冒烟测试;真实部署至少应达到 --min-labels 50 推荐值,否则配置容易被个别极值样本拉偏。 资料来源：benchmarks/calibration-eval.md
• 盲目启用词法权重:在自有语料外泛化能力差,务必通过 calibrate --weights 在本业务流量上重训。 资料来源：docs/lexical-routing.md
• 把成本误用于请求决策:cost 仅参与拟合与统计上报,不得在单请求路径上读取,否则破坏离线确定性。 资料来源：wayfinder_router/pricing.py

See Also

• 配置与切割点形状(Threshold / Tiers / Classifier):参见 *Routing Modes* 页面
• 网关故障转移、重试与限速:参见 *Gateway Reliability & Cost Controls* 页面
• 双盲评估与基线对比:参见 benchmarks/blind-eval.md 与 benchmarks/README.md
• 设计动机与历史取舍:decisions/WF-ADR-0003-calibration-and-classifier.md

Pitfall Log / 踩坑日志

项目：itsthelore/wayfinder-router

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://news.ycombinator.com/item?id=48704373 | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48704373 | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48704373 | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48704373 | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48704373 | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48704373 | release_recency=unknown