OpenAI-compatible lite / deep 意图路由网关。 默认成本优先,只有证据足够时升级到更强模型。

runtime Python 3.11+ entries intentmux lite deep LiteLLM sidecar compatible route logs metadata only

built with FastAPI kernel Aurelio Semantic Router config YAML tests pytest package uv license Apache-2.0

English

IntentMux 是一个轻量路由 sidecar。它接收 OpenAI-compatible chat completion 请求,把 model=intentmux 的请求路由到两个产品级 route:

• lite:低风险、低成本、普通问答和轻量任务。
• deep:代码、debug、架构、高风险判断和需要更强模型的任务。

IntentMux 不提供模型,也不替代 LiteLLM、OpenRouter 或其他 provider gateway。 它只负责入口模型语义、路由决策、协议代理和可审计日志。

model=intentmux -> route_id(lite/deep) -> target_model -> OpenAI-compatible upstream

两种部署形态都支持:

Direct gateway:
client -> IntentMux :4001/v1, model=intentmux|lite|deep
 -> OpenAI-compatible upstream
LiteLLM-first sidecar:
client -> LiteLLM :4000, model=intentmux
 -> IntentMux :4001
 -> LiteLLM target model group

如果已有 LiteLLM,推荐继续让 LiteLLM 管 provider routing、fallback、key、 budget 和模型池。IntentMux 只做意图路由。

默认决策顺序:

explicit route -> hard escalation -> semantic score + threshold -> configured fallback

• model=lite / model=deep 或 metadata.route_id 是显式路由。
• hard rules 只用于安全、凭据泄露、生产事故、数据损坏等高风险强制升级。
• 普通工程词、工具调用结构、长上下文和 agent 形态只进入审计信号,不直接升级。
• embedding 不可用时按 fallback_route_id fail open,仓库默认配置为 deep。
• upstream 连接错误或 5xx 返回脱敏 502;upstream 4xx 按代理语义透传,同时记入审计日志。

默认在线路由内核是 Aurelio Semantic Router。 内置 basic 只作为 fallback/debug baseline。

IntentMux 默认依赖 Aurelio Semantic Router 作为成熟路由匹配内核,当前默认形态是 HybridRouter + HybridLocalIndex。 IntentMux 在其上提供 OpenAI-compatible 网关入口、lite / deep 产品语义、 运行时配置、日志审计、质量报告和 LiteLLM sidecar 集成。

本地进程:

uv run python -m router.app

容器示例:

uv run python scripts/init_runtime_home.py
docker compose -f examples/docker-compose.yml up -d --build

默认端点:

首次接入先做四件事:

1. 选择直连 IntentMux,或在 LiteLLM 中新增 intentmux 模型入口。
2. 复制 examples/intentmux-home/ 到自己的运行时目录。
3. 在运行时 config/routes.yaml 中配置 routes.lite.target_model 和 routes.deep.target_model。
4. 跑 /ready 和 preflight,再用 decision endpoint 查看一次真实路由结果。

核心配置文件是 routes.yaml:

route_model: intentmux
fallback_route_id: deep
routes:
 lite:
 target_model: your-lite-model
 description: 低风险、普通问答、解释、翻译、轻量总结
 utterances:
 - 帮我解释一下这段概念
 deep:
 target_model: your-deep-model
 description: 代码、debug、架构、高风险判断
 utterances:
 - 这个线上 bug 为什么偶发

生产部署应显式设置:

• INTENTMUX_HOME:运行时目录,保存真实配置、语义资产、日志和缓存。
• ROUTER_CONFIG:运行时 routes.yaml 路径。
• ROUTER_CLOUD_MODE=true:云端/公网部署启用 fail-closed 安全检查。
• ROUTER_INBOUND_API_KEY:云端/公网部署必须配置入口认证。
• ROUTER_LITELLM_BASE_URL:上游 OpenAI-compatible gateway。
• ROUTER_EMBEDDING_URL / ROUTER_EMBEDDING_MODEL:embedding upstream。
• ROUTER_AUDIT_LOG_ENABLED=true 和 ROUTER_AUDIT_LOG_DIR:持久 route audit。
• ROUTER_REQUIRE_ROUTE_BANK=true:生产 route bank 缺失时启动失败。

/ready 会暴露当前配置来源、运行时目录、日志状态、route bank 是否加载和每个 route 的 utterance 数量。不要盲信文档或旧状态文件,先看 live /ready 和最新日志。 云端模式下 /ready 和 /v1/models 都需要 ROUTER_INBOUND_API_KEY;/health 保留为无鉴权平台探活。 上云前用 scripts/build_cloud_runtime.py --include-route-cache 生成只含配置、 route bank 和预热 route cache 的干净 runtime,再用 scripts/check_cloud_runtime.py --require-route-cache 做门控;不要把本机 runtime 目录原样上传。 云端运行时资产边界见 docs/cloud_hosting.md。

IntentMux 当前支持:

• GET /health
• GET /ready
• GET /v1/models
• POST /v1/chat/completions
• POST /v1/intentmux/decision

入口模型:

/v1/models 只广告 intentmux、lite、deep,不泄漏部署侧 target_model。

查看一次路由决策,不转发到上游:

curl http://127.0.0.1:4001/v1/intentmux/decision \
 -H "Content-Type: application/json" \
 -d '{"model":"intentmux","messages":[{"role":"user","content":"这个线上 bug 为什么偶发?"}]}'

decision response 会返回 route_id、target_model、policy_id、分数、阈值、 margin 和 route-bank match provenance。匹配样本文本不会出现在响应或 audit log 中。

这个项目默认进入日志驱动维护。文档只能说明当前意图,真正接手时应先验证 live 状态。

常用检查:

uv run pytest -n auto -q
uv run ruff check .
uv run python scripts/verify_route_contract.py
uv run python scripts/preflight.py --router-base-url http://127.0.0.1:4001
curl -fsS http://127.0.0.1:4001/ready

生产或私有部署还应跑 daily health:

uv run python scripts/intentmux_daily_health.py \
 --log-dir /path/to/intentmux-home/logs \
 --timezone Asia/Shanghai \
 --min-route-records 1 \
 --run-e2e

代码或镜像变更需要 rebuild/recreate IntentMux sidecar;配置、route bank 或环境变量变更 需要 restart。更完整的门禁见 docs/production_rollout_gate.md。

默认 route audit 只记录元数据:route、target、reason、状态码、耗时、request id、 决策分数和 match provenance。不记录 prompt、completion、token usage 或 bearer token。

可选 prompt review log 只适合私有部署,用于本地复核和生成脱敏样本。公开环境应保持关闭。

质量改进的基本原则:

1. 从 route audit 中找 low confidence、upstream failure、slow request 和分布漂移。
2. 用 bounded replay / eval / quality report 做 before/after 对比。
3. 只有接受、脱敏、可复核的样本才能进入 eval 或 route bank。
4. route bank、threshold、margin、hard rule 变化必须附带报告,不靠口头判断上线。

相关文档:

• docs/PROJECT_CONTROL.md:当前产品控制面和工作顺序。
• docs/PATROL_HANDOFF.md:巡检和运行时交接。
• docs/log_driven_quality_loop.md:日志驱动质量闭环。
• docs/router_data_pipeline_research.md:语义资产管线。
• docs/cloud_hosting.md:云端托管与运行产物边界。
• docs/production_rollout_gate.md:生产变更门禁。

IntentMux 已具备可运行的两档路由、LiteLLM sidecar 兼容、metadata-only audit、 route-bank provenance、preflight、E2E、daily health 和质量报告脚本。

默认不再主动调整路由行为。后续改动应由日志、replay、eval 或 calibration report 证明有重复模式后再推进。

后续可能继续打磨的方向:

• accepted findings 到 redacted regression cases 的导入门禁;
• 更有代表性的公开 eval / calibration 证据;
• 日志驱动的 route bank、threshold、margin 或 hard rule 小步调整。