6.2 路由：判断的下游是路径

6.2 路由：判断的下游是路径

本节摘要：路由是分类的特例——选项表就是你的下游路径，因此天然有限可枚举，是"判断题里的判断题"。两类典型：意图路由（把请求分发给不同处理管线）与模型路由（按请求难度在便宜与旗舰模型间选择——一次约 100ms、近零成本的 Choice，决定后面秒级 LLM 调用的成本，简单流量占比高的系统里路由器本身就是成本优化器；LangChain 的 ModelRouterMiddleware 已做成声明式配置）。路由独有的一道功课是给错误定价：错发到贵模型只是费钱，错发到弱模型伤质量，据此定置信度阈值。本节内嵌完整的意图路由脚本（含置信度门控与 other 处理）。

学习目标

阅读完本节，你应当能够：

1. 实现一个带门控的意图路由器并运行内嵌脚本。
2. 配置 LangChain 的 ModelRouterMiddleware 做模型路由。
3. 用"错误代价表"为自己的路由器定阈值。

一、意图路由：完整实现

以下脚本即本教程的 02_choice_intent_routing.py，完整内嵌于此（pip install requests，需 TYPESAFE_API_KEY）。它演示第 3.2 节选项表准则与第 5.3 节门控的落地三要点：criteria 是"选项名→具体情形"且带 other；probabilities 与 confidence 两个都看；低置信度转人工而不是硬猜：

# 02_choice_intent_routing.py —— 意图分类 + 置信度门控
import json
import os
import sys

import requests

API_URL = "https://api.typesafe.ai/v1/systemone"

QUESTIONS = {
    "route": {
        "type": "choice",
        "instructions": "将客服工单路由到最合适的团队。以工单的核心诉求为准，而非顺带提到的内容",
        "criteria": {
            "billing":   "计费、扣款、退款、发票、订阅与价格问题",
            "technical": "产品故障、报错、无法登录、功能不按预期工作",
            "sales":     "询价、方案咨询、购买意向、合作洽谈",
            "other":     "以上皆非，或语义混杂无法判断",
        },
    }
}


def route_ticket(state: str) -> dict:
    resp = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {os.environ['TYPESAFE_API_KEY']}"},
        json={"model": "jev-latest", "state": state, "questions": QUESTIONS},
        timeout=10,
    )
    resp.raise_for_status()
    answers = resp.json()["answers"]["route"]
    # 返回：choice（胜出项）、probabilities（全选项分布）、confidence（整体把握）
    return answers


def main() -> None:
    if not os.environ.get("TYPESAFE_API_KEY"):
        sys.exit("请先设置环境变量 TYPESAFE_API_KEY")

    tickets = [
        "你们上个月多扣了我两次费，我要退款，再不处理我就投诉。",
        "App 一打开就闪退，重装也没用，安卓 14。",
        "我们公司 200 人想买团队版，能约个人聊下价格吗？",
        "顺便问下今天天气怎么样，还有你们的logo是谁设计的？",
    ]

    # 阈值：来自第 9.3 节的代价分析 —— 路由错了代价低（再转一次），
    # 但"other 也自动路由"代价高，故 confidence 阈值取中等偏低即可
    CONF_THRESHOLD = 0.5

    for ticket in tickets:
        a = route_ticket(ticket)
        top, top_p = a["choice"], a["probabilities"][a["choice"]]
        conf = a.get("confidence", 0.0)
        print(f"\n工单：{ticket}")
        print(f"  判定 -> {top}  (p={top_p:.2f}, confidence={conf:.2f})")
        print(f"  分布 -> {json.dumps(a['probabilities'], ensure_ascii=False)}")

        if top == "other" or conf < CONF_THRESHOLD:
            print("  动作 -> 转人工（判断不可靠或语义不明）")
        else:
            print(f"  动作 -> 自动路由到 {top} 组")


if __name__ == "__main__":
    main()
​

预期行为：前两条自信路由（billing / technical 且置信度尚可）；第三条偏 sales；第四条落进 other → 转人工。跑完看输出的分布细节，体会"choice + probabilities + confidence 三件套缺一不可"。

二、模型路由：成本杀手

模型路由的选项表是你的模型梯队，判别标准是任务难度：

from langchain_typesafe import ModelRouterMiddleware, ModelChoice

router = ModelRouterMiddleware(
    instructions="根据任务复杂度选择模型",
    choices={
        "fast":     ModelChoice(model="openai:luna", criteria="简单改写、格式转换、事实性问答"),
        "powerful": ModelChoice(model="openai:sol",  criteria="多步推理、长文写作、复杂代码"),
    },
)
​

经济学账：Jev 路由一次 ≈ 100ms、近零成本；路由正确时省下的是旗舰与便宜模型之间的差价。真实流量里"简单请求"占比越高，路由器回本越快——LangChain 官方演示的正是这条路径。手写版本 = 意图路由脚本换一张选项表（fast/powerful/other），外加一个"other 默认走旗舰"的兜底。

Agent 场景的第三种路由——工具选择（从注册的工具表里挑一个）——结构完全相同：选项 = 工具名 + 各自适用情形的描述。

三、给路由错误定价

路由与普通分类的本质差异：选项是动作，错误有代价。上线前填这张表：

通用规则：代价不对称时阈值不对称——"贵而安全"的方向放宽，"便宜而出事"的方向收紧。第 9.3 节会把这张表公式化。

本节要点回顾

1. 意图路由：Choice + 门控 + other 兜底；内嵌脚本可直接跑。
2. 模型路由：选项 = 模型梯队，一次近零成本判断决定秒级调用成本；ModelRouterMiddleware 声明式可用。
3. 定价：路由错误有方向性代价——不可容忍的方向设高阈值，兜底方向放宽。

路由把判断接到"路径"上，评分把判断接到"标尺"上——而且一次只测一个维度。下一节：复合评分模式。