> ## Documentation Index
> Fetch the complete documentation index at: https://forgekit-docs-mintlify-7cd64f48.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型路由

> 一份确定性、可 diff 的评分表在分发前挑出性价比最高、能胜任的模型层级 —— 并为自托管网关提供一个保底重映射。

Forge 在分发**之前**推荐性价比最高、能胜任任务的模型,依据是一份你可以在仓库中阅读的确定性评分表 (`src/model_tiers.json`)。与在代理内部于请求时决策的网关不同,路由决策在 git 中是可见且可 diff 的。

## 推荐一个层级 —— `forge route`

```bash theme={null}
forge route "<task>"            # cheapest capable model tier for the task
forge route gateway             # emit LiteLLM gateway config
```

推荐使用的是在标注样本库(英文 + Hinglish 行)上的示例 k-NN 数学,基于重叠相似度指标并有置信度门 —— 不是关键词查表。

<Note>
  从推荐的 `route.tier` 开始,只有当外部验证器失败之后再升级,永远不要预防性升级。这样既压得住花费,又不会在任务确实需要能力时封顶。
</Note>

## 先意图,再层级

路由与意图检测 (`src/intent.js`) 共享同一套数学:一段 prompt 通过同一个示例 k-NN 估计器映射到意图。注意两者使用不同的停用集合 —— route 把泛化动词(`fix` / `add` / `build`)视为复杂度噪声,而这些动词恰好是意图信号。

## 层级表

层级表 (`src/model_tiers.json`) 按家族(haiku / sonnet / opus / fable)固定了公开的 Anthropic 模型 ID。文档中的价格通过 docs check 与这份文件对账,所以散文和表格无法漂移。

## 自托管网关重映射

自托管的 LiteLLM 或代理网关会提供自己命名的模型,直接把库存 ID 原样发过去会 404。当配置了非默认的网关 base URL 时,Forge (`src/gateway_model_map.js`) **每个进程仅一次**拉取 `GET /v1/models`,并对每个层级家族对被宣告的每一个 id 打分:

<Steps>
  <Step title="硬家族门">
    家族关键词(haiku / sonnet / opus / fable)必须匹配 —— 这是硬门。
  </Step>

  <Step title="最佳重叠胜出">
    在同一家族内,由层级名字 token 的 `setOverlap` 系数挑出最佳匹配。
  </Step>

  <Step title="平局回退到规范名">
    平局时倾向于最接近规范名的 id。
  </Step>
</Steps>

<Warning>
  该重映射**只**在解析出的 id 是一个\_库存\_ ID 时才咨询网关 —— 显式的 `.forge/providers.json` 别名或 `ANTHROPIC_MODEL` 覆盖永远不会被触碰。当没有网关、`/v1/models` 不可达或家族不匹配时,它会保底为库存 ID,因此直连 `api.anthropic.com` 的用户会得到逐字节一致的结果。
</Warning>

`forge doctor` 的 **gateway models** 行会打印解析后的 `tier → model` 映射,便于校验。

## 提供商与成本

```bash theme={null}
forge config               # show / switch / add providers, set the default model
forge cost                 # real per-day spend
forge cost --stages        # measured per-stage cost factors
```

<Note>
  `forge cost --stages` **只报告实测过的阶段** —— 没有事件的阶段会显示"no data",而不是给出默认值。一个数字在被测量之前只是假设。
</Note>