跳到导航

路由

model 支持两种用法:传入 model: "auto" 由 JoyToken 自动选择最终模型和 provider(推荐),或直接传入模型目录中的具体模型 ID,将请求固定到指定模型。

常用写法

目标请求写法
智能路由(推荐)model: "auto"
指定档位model: "auto" + `tier: “economy"
指定模型model: "<模型目录中的 modelName>"

智能路由

用户只需传入 model: "auto",即可启动 JoyToken 智能路由引擎。系统结合多维请求特征、语义规则与大模型复核,识别系统设定、工具意图、上下文和用户诉求,判断任务类型及复杂度,并匹配相应的路由策略。

对于复杂请求,系统自动生成任务计划,完成任务拆解、模型与档位匹配及结果聚合;简单请求则直接进行单模型择优。

在策略约束下,系统从持续扩展的在线模型与能力资源池中,综合质量、成本、时延和实时成功率进行智能调度,并通过自动熔断、流量切换与跨档兜底,保障服务质量与连续性。

{
"model": "auto",
"messages": [
{ "role": "user", "content": "用一句话总结这张工单。" }
]
}
curl -X POST "$JOY_TOKEN_API_BASE_URL/openai/v1/chat/completions" \
-H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [{ "role": "user", "content": "用一句话总结这张工单。" }]
}'

指定模型

把 GET /api/v1/models 返回的 modelName 作为请求的 model 传入。此时 JoyToken 跳过打分和路由,直接把请求发给该模型。

{
"model": "deepseek-v4-flash",
"messages": [
{ "role": "user", "content": "用一句话总结这张工单。" }
]
}
curl -X POST "$JOY_TOKEN_API_BASE_URL/openai/v1/chat/completions" \
-H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [{ "role": "user", "content": "用一句话总结这张工单。" }]
}'

档位

tier 用于收窄 auto 请求的候选范围;不传则由 JoyToken 自行决定。

档位适合场景
economy成本优先、批处理、低风险任务
standard默认平衡档
premium高质量或关键评估任务

编排模式(多任务规划)

对于复杂请求,JoyToken 可能以编排模式处理单个 model: "auto" 请求:先生成任务计划(plan),用选定的子模型逐个执行任务,最后汇总出最终答案。你无需显式开启,由网关根据请求自动决定。

如何识别

信号说明
plan(顶层)有序任务列表,仅编排模式返回
choices[].message.content变为各任务输出的 JSON 数组(含 content 和 title),而非单一字符串
metadata(数组)每个任务一条,含保留任务 __planner__ 和 __final__
流式 planning 事件首先发出一个 orchestration.phase 为 planning 的 chunk,携带有序的 plan,其后紧跟 __planner__ 的 metadata 事件
流式任务 chunk每个任务的正文 chunk 都携带 orchestration 字段(task_id、task_seq、task_status、title)
流式 metadata 事件每个任务在其正文之后各发出一个独立 metadata 事件(值为单个对象,而非数组)

任务生命周期

字段说明
task_id任务标识;__planner__ 和 __final__ 为保留值
task_seq执行顺序;0 为规划器
task_status任务状态,如 DONE
tag任务角色,如 orchestration、search、reasoning、writing、aggregation
title可读的任务标题

编排模式下每个任务单独计费(每个任务一条 metadata/billing),且可能使用不同子模型。渲染前请先将 choices[].message.content 按 JSON 解析,并对所有任务 metadata 的 billing.credits_used 求和。

确认路由结果

信号说明
metadata.modelJoyToken 最终模型
metadata.tier实际计费/路由档位
metadata.billingCredits 和 token 消耗

常见排查

现象优先检查
tier 不允许API Key 策略是否允许该 tier
没有候选模型tier、模型黑名单、钱包和 Key 预算
IP 不允许服务端出口 IP 是否在白名单
auto 失败策略、tier、余额过滤后是否还有候选模型
传入具体模型名被拒绝模型名是否与目录完全一致,以及 API Key 策略是否允许该模型
指定模型返回 model_exhausted模型名是否与目录完全一致,以及该模型是否有上游容量
指定模型时 tier 不生效正常现象:指定模型始终按模型自身档位计费