diff --git a/Cargo.lock b/Cargo.lock index 07cfb531..1fdff976 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3763,7 +3763,7 @@ dependencies = [ [[package]] name = "tw-api" -version = "0.94.0" +version = "0.95.0" dependencies = [ "serde", "serde_json", @@ -3774,7 +3774,7 @@ dependencies = [ [[package]] name = "tw-bedrock" -version = "0.94.0" +version = "0.95.0" dependencies = [ "aws-credential-types", "aws-sigv4", @@ -3795,7 +3795,7 @@ dependencies = [ [[package]] name = "tw-breaker" -version = "0.94.0" +version = "0.95.0" dependencies = [ "serde", "serde_json", @@ -3803,7 +3803,7 @@ dependencies = [ [[package]] name = "tw-config" -version = "0.94.0" +version = "0.95.0" dependencies = [ "blake3", "libc", @@ -3829,7 +3829,7 @@ dependencies = [ [[package]] name = "tw-control" -version = "0.94.0" +version = "0.95.0" dependencies = [ "axum", "base64 0.22.1", @@ -3875,7 +3875,7 @@ dependencies = [ [[package]] name = "tw-dialect" -version = "0.94.0" +version = "0.95.0" dependencies = [ "memchr", "serde", @@ -3884,7 +3884,7 @@ dependencies = [ [[package]] name = "tw-engine" -version = "0.94.0" +version = "0.95.0" dependencies = [ "chrono", "serde", @@ -3898,7 +3898,7 @@ dependencies = [ [[package]] name = "tw-gateway" -version = "0.94.0" +version = "0.95.0" dependencies = [ "arc-swap", "async-stream", @@ -3950,7 +3950,7 @@ dependencies = [ [[package]] name = "tw-guard" -version = "0.94.0" +version = "0.95.0" dependencies = [ "aho-corasick", "base64 0.22.1", @@ -3971,7 +3971,7 @@ dependencies = [ [[package]] name = "tw-handover" -version = "0.94.0" +version = "0.95.0" dependencies = [ "libc", "serde", @@ -3984,7 +3984,7 @@ dependencies = [ [[package]] name = "tw-link" -version = "0.94.0" +version = "0.95.0" dependencies = [ "serde", "serde_json", @@ -3998,7 +3998,7 @@ dependencies = [ [[package]] name = "tw-observe" -version = "0.94.0" +version = "0.95.0" dependencies = [ "tokio", "tracing", @@ -4007,7 +4007,7 @@ dependencies = [ [[package]] name = "tw-pack" -version = "0.94.0" +version = "0.95.0" dependencies = [ "age", "blake3", @@ -4031,7 +4031,7 @@ dependencies = [ [[package]] name = "tw-plugin" -version = "0.94.0" +version = "0.95.0" dependencies = [ "libc", "rand 0.10.2", @@ -4047,7 +4047,7 @@ dependencies = [ [[package]] name = "tw-pricing" -version = "0.94.0" +version = "0.95.0" dependencies = [ "arc-swap", "flate2", @@ -4060,14 +4060,14 @@ dependencies = [ [[package]] name = "tw-secret" -version = "0.94.0" +version = "0.95.0" dependencies = [ "thiserror 2.0.20", ] [[package]] name = "tw-store" -version = "0.94.0" +version = "0.95.0" dependencies = [ "blake3", "bytes", @@ -4087,7 +4087,7 @@ dependencies = [ [[package]] name = "tw-sync" -version = "0.94.0" +version = "0.95.0" dependencies = [ "age", "axum", @@ -4115,7 +4115,7 @@ dependencies = [ [[package]] name = "tw-types" -version = "0.94.0" +version = "0.95.0" dependencies = [ "serde", "serde_json", @@ -4124,7 +4124,7 @@ dependencies = [ [[package]] name = "tw-watch" -version = "0.94.0" +version = "0.95.0" dependencies = [ "libc", "notify", @@ -4135,7 +4135,7 @@ dependencies = [ [[package]] name = "tw-yaml" -version = "0.94.0" +version = "0.95.0" dependencies = [ "saphyr-parser", "serde_yaml_ng", @@ -4145,7 +4145,7 @@ dependencies = [ [[package]] name = "twcore" -version = "0.94.0" +version = "0.95.0" dependencies = [ "anyhow", "axum", diff --git a/Cargo.toml b/Cargo.toml index 1369bd05..9f0678a3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -61,7 +61,7 @@ categories = ["network-programming", "web-programming::http-server"] # 二进制走 CalVer,crate 走 SemVer —— 两者是两回事,卖给不同的人。 # 这里是 crate 的版本。 -version = "0.94.0" +version = "0.95.0" [workspace.dependencies] # ── 内部 crate ─────────────────────────────────────────── diff --git a/crates/tw-api/msg-codes.txt b/crates/tw-api/msg-codes.txt index 9b0f3863..a6375293 100644 --- a/crates/tw-api/msg-codes.txt +++ b/crates/tw-api/msg-codes.txt @@ -92,6 +92,9 @@ config.manual_model_too_long config.manual_model_wildcard config.min_speed_range config.model_spec_blank_model +config.model_spec_effort_default +config.model_spec_effort_disabled +config.model_spec_effort_duplicate config.model_spec_nothing_set config.model_spec_wildcard config.model_spec_zero diff --git a/crates/tw-api/src/lib.rs b/crates/tw-api/src/lib.rs index 0a851367..7fd5971b 100644 --- a/crates/tw-api/src/lib.rs +++ b/crates/tw-api/src/lib.rs @@ -183,6 +183,75 @@ slug_enum! { PriceTable = "price_table", /// 这一家上游手写的(配置里的 `model_specs`),优先于价目表 Manual = "manual", + /// 上游模型目录报告的能力 + Upstream = "upstream", + } +} + +slug_enum! { + /// 客户端可选择的推理强度,按从低到高排列。是否能转发还取决于协议。 + pub enum ReasoningLevel { + Minimal = "minimal", + Low = "low", + Medium = "medium", + High = "high", + Xhigh = "xhigh", + Max = "max", + Ultra = "ultra", + } +} + +/// 一整组推理档位。空列表明确表示不可调;没有这项才是自动或未知。 +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +#[cfg_attr(feature = "ts", derive(ts_rs::TS))] +#[serde(deny_unknown_fields)] +pub struct ReasoningEffort { + pub supported_levels: Vec, + /// 省略时在最终可用档位里优先 medium,否则取最低档。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub default_level: Option, +} + +impl ReasoningEffort { + /// 排序、去重并在最终集合内选择默认值。手写值另由配置校验严格检查。 + pub fn normalized(&self) -> Self { + let supported_levels: Vec<_> = ReasoningLevel::ALL + .iter() + .copied() + .filter(|level| self.supported_levels.contains(level)) + .collect(); + let default_level = self + .default_level + .filter(|level| supported_levels.contains(level)) + .or_else(|| { + supported_levels + .contains(&ReasoningLevel::Medium) + .then_some(ReasoningLevel::Medium) + }) + .or_else(|| supported_levels.first().copied()); + Self { + supported_levels, + default_level, + } + } +} + +/// 编辑推理档位:旧客户端省略时保留,恢复自动必须显式提交 auto。 +#[derive(Debug, Clone, Default, Serialize, Deserialize)] +#[cfg_attr(feature = "ts", derive(ts_rs::TS))] +#[serde(tag = "mode", rename_all = "snake_case")] +pub enum ReasoningEffortChange { + #[default] + Keep, + Auto, + Set { + value: ReasoningEffort, + }, +} + +impl ReasoningEffortChange { + fn is_keep(&self) -> bool { + matches!(self, Self::Keep) } } @@ -1150,7 +1219,10 @@ pub const MSG_CODES: &str = include_str!("../msg-codes.txt"); /// [`Status`] 增加 `gateway_addrs`(全部实际绑定的套接字)和 `gateway_probe`(公开的进程标识, /// `/healthz` 的 `x-thinkwatch-gateway` 响应头原样返回),用于从其他网络命名空间确认连到的 /// 是当前网关。请求库 SCHEMA 不变。 -pub const CONTROL_API_VERSION: u32 = 59; +/// **60 起模型规格支持手动推理档位**:[`ModelSpecSave::reasoning_effort`] 区分保留、 +/// 设置和恢复自动。[`ModelRow`] 带上游报告、手动覆盖、实际可用档位和过滤结果。 +/// [`SpecSource::Upstream`] 表示上游报告的规格。请求库 SCHEMA 不变。 +pub const CONTROL_API_VERSION: u32 = 60; /// `/live` 的速度看最近多久(见 [`LiveView::tokens_per_sec`]),毫秒 pub const LIVE_RATE_WINDOW_MS: u64 = 3_000; @@ -3845,25 +3917,42 @@ pub struct ModelRow { pub id: String, /// 在启用范围里 pub enabled: bool, - /// 上下文窗口:这一家手写的(`model_specs`),没写时来自价目表 + /// 上下文窗口:手动覆盖优先,然后上游报告,最后价目表 #[serde(default, skip_serializing_if = "Option::is_none")] pub context_window: Option, /// `context_window` 从哪儿来。不知道上下文窗口时没有 #[serde(default, skip_serializing_if = "Option::is_none")] pub context_window_source: Option, - /// 一次最多输出多少 token:这一家手写的,没写时来自价目表 + /// 一次最多输出多少 token:手动覆盖优先,然后上游报告,最后价目表 #[serde(default, skip_serializing_if = "Option::is_none")] pub max_output_tokens: Option, /// `max_output_tokens` 从哪儿来。不知道输出上限时没有 #[serde(default, skip_serializing_if = "Option::is_none")] pub max_output_tokens_source: Option, - /// 会不会推理:这一家手写的,没写时来自价目表。不知道时没有 + /// 会不会推理:手动覆盖优先,然后上游报告,最后价目表。不知道时没有 #[serde(default, skip_serializing_if = "Option::is_none")] pub reasoning: Option, /// `reasoning` 从哪儿来。不知道时没有 #[serde(default, skip_serializing_if = "Option::is_none")] pub reasoning_source: Option, - /// 收不收图:这一家手写的,没写时来自价目表。不知道时没有 + /// 推理开关的手动原值;非空手动档位推导出的 true 不会写进这里。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub manual_reasoning: Option, + /// 实际可用的档位(已应用推理开关和协议转换限制)。没有表示未知。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reasoning_effort: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reasoning_effort_source: Option, + /// 上游实际报告的档位;手动覆盖时仍保留,供界面解释和恢复自动。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reported_reasoning_effort: Option, + /// 配置原值,包含省略的默认值。不能从生效值反推它。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub manual_reasoning_effort: Option, + /// 当前协议转换不能表示、因而没有向客户端提供的档位。 + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub reasoning_effort_filtered_levels: Vec, + /// 收不收图:手动覆盖优先,然后上游报告,最后价目表。不知道时没有 #[serde(default, skip_serializing_if = "Option::is_none")] pub image_input: Option, /// `image_input` 从哪儿来。不知道时没有 @@ -3939,7 +4028,8 @@ pub struct ProviderSave { } /// 设一家上游的一个模型的规格(`PUT /provider-model-spec`):价目表不认识这个模型、 -/// 或者写错了时手写。**四项都空就是删掉这一项**,回到价目表。 +/// 或者写错了时手写。旧的四项按请求替换;推理档位必须显式 auto 才清除。 +/// 所有规格(含保留的高级字段)都空时删除模型项。 #[derive(Debug, Clone, Default, Serialize, Deserialize)] #[cfg_attr(feature = "ts", derive(ts_rs::TS))] pub struct ModelSpecSave { @@ -3955,6 +4045,9 @@ pub struct ModelSpecSave { /// 会不会推理。空 = 用价目表的 #[serde(default, skip_serializing_if = "Option::is_none")] pub reasoning: Option, + /// 省略或 keep 保留原值,auto 移除覆盖,set 整组替换。 + #[serde(default, skip_serializing_if = "ReasoningEffortChange::is_keep")] + pub reasoning_effort: ReasoningEffortChange, /// 收不收图。空 = 用价目表的 #[serde(default, skip_serializing_if = "Option::is_none")] pub image_input: Option, diff --git a/crates/tw-config/src/lib.rs b/crates/tw-config/src/lib.rs index 0c55a4b1..70ec66fb 100644 --- a/crates/tw-config/src/lib.rs +++ b/crates/tw-config/src/lib.rs @@ -39,7 +39,10 @@ pub use aliases::{Alias, Aliases}; pub use credential::{CredentialError, Header, Headers, Secret, SecretResolveError, auth_header}; pub use init::{generate_control_key, generate_initial, generate_key}; pub use limits::{KeyLimit, LimitMeasure, LimitPer, UsageLimit}; -pub use model_specs::{ModelSpec, ReasoningHistory, ResolvedSpec, Sourced, SpecSource}; +pub use model_specs::{ + ModelSpec, ReasoningEffort, ReasoningHistory, ReasoningLevel, ReportedSpec, ResolvedSpec, + Sourced, SpecSource, +}; pub use plugins::Plugin; pub use proxy::{DIRECT, OnProxyFail, Proxy, ProxyKind, SYSTEM}; pub use validate::ValidationError; diff --git a/crates/tw-config/src/model_specs.rs b/crates/tw-config/src/model_specs.rs index 47347c4c..c22adbc6 100644 --- a/crates/tw-config/src/model_specs.rs +++ b/crates/tw-config/src/model_specs.rs @@ -18,6 +18,7 @@ use serde::{Deserialize, Serialize}; use crate::{Config, Provider}; +pub use tw_api::{ReasoningEffort, ReasoningLevel}; /// Request-side reasoning-history capability. Independent of the API protocol. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] @@ -32,7 +33,7 @@ pub enum ReasoningHistory { } /// `providers[].model_specs` 的一项。每项都可选,但至少写一项(校验管)。 -#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct ModelSpec { /// Override this model's request-side reasoning-history format. @@ -47,6 +48,9 @@ pub struct ModelSpec { /// 会不会推理 #[serde(default, skip_serializing_if = "Option::is_none")] pub reasoning: Option, + /// 整组覆盖上游档位。非空表示支持推理,空列表明确表示不可调。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reasoning_effort: Option, /// 收不收图 #[serde(default, skip_serializing_if = "Option::is_none")] pub image_input: Option, @@ -67,6 +71,18 @@ pub enum SpecSource { PriceTable, /// 这一家的 `model_specs` Manual, + /// 上游模型目录 + Upstream, +} + +/// 只含上游实际报告的规格;未知字段保持 None,不从模型名字推测。 +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct ReportedSpec { + pub context_window: Option, + pub max_output_tokens: Option, + pub reasoning: Option, + pub image_input: Option, + pub reasoning_effort: Option, } /// 一个值和它的来源。 @@ -78,12 +94,13 @@ pub struct Sourced { /// 一个模型的规格,每一项连同来源。**不知道就是 `None`**:编出来的数客户端会照着截断, /// 编出来的「不会推理」客户端会照着不让选推理档。 -#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +#[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct ResolvedSpec { pub context_window: Option>, pub max_output_tokens: Option>, pub reasoning: Option>, pub image_input: Option>, + pub reasoning_effort: Option>, } impl ResolvedSpec { @@ -114,6 +131,60 @@ impl Provider { pub fn model_spec(&self, book: &tw_pricing::PriceBook, model: &str) -> ResolvedSpec { resolve(book, Some(&self.name), self.model_specs.get(model), model) } + + /// 客户端目录和控制面共用:手动 > 上游 > 价目表;价目表没有档位。 + pub fn model_spec_with_metadata( + &self, + book: &tw_pricing::PriceBook, + model: &str, + reported: Option<&ReportedSpec>, + ) -> ResolvedSpec { + let mut out = self.model_spec(book, model); + if let Some(reported) = reported { + fn reported_over_table(slot: &mut Option>, value: Option) { + if !slot + .as_ref() + .is_some_and(|s| s.source == SpecSource::Manual) + && let Some(value) = value + { + *slot = Some(Sourced { + value, + source: SpecSource::Upstream, + }); + } + } + reported_over_table(&mut out.context_window, reported.context_window); + reported_over_table(&mut out.max_output_tokens, reported.max_output_tokens); + reported_over_table( + &mut out.reasoning, + reported.reasoning.or_else(|| { + reported + .reasoning_effort + .as_ref() + .filter(|effort| !effort.supported_levels.is_empty()) + .map(|_| true) + }), + ); + reported_over_table(&mut out.image_input, reported.image_input); + reported_over_table(&mut out.reasoning_effort, reported.reasoning_effort.clone()); + } + // 禁止推理时不提供可调档位;空档位本身不表示模型不会推理。 + if let Some(reasoning) = out.reasoning.filter(|s| !s.value) + && out + .reasoning_effort + .as_ref() + .is_none_or(|effort| !effort.value.supported_levels.is_empty()) + { + out.reasoning_effort = Some(Sourced { + value: ReasoningEffort::default(), + source: reasoning.source, + }); + } + if let Some(effort) = &mut out.reasoning_effort { + effort.value = effort.value.normalized(); + } + out + } } impl Config { @@ -172,13 +243,21 @@ fn resolve( price.and_then(|p| p.max_output_tokens), ), reasoning: pick( - spec.and_then(|s| s.reasoning), + spec.and_then(|s| { + s.reasoning.or_else(|| { + s.reasoning_effort + .as_ref() + .filter(|effort| !effort.supported_levels.is_empty()) + .map(|_| true) + }) + }), price.and_then(|p| p.reasoning), ), image_input: pick( spec.and_then(|s| s.image_input), price.and_then(|p| p.image_input), ), + reasoning_effort: pick(spec.and_then(|s| s.reasoning_effort.clone()), None), } } @@ -194,7 +273,10 @@ mod tests { Provider { name: "relay".into(), base_url: "https://relay.example.com/v1".into(), - model_specs: specs.iter().map(|(m, s)| (m.to_string(), *s)).collect(), + model_specs: specs + .iter() + .map(|(m, s)| (m.to_string(), s.clone())) + .collect(), ..Default::default() } } @@ -293,3 +375,170 @@ mod tests { ); } } + +#[cfg(test)] +mod effort_tests { + use super::*; + + fn profile(levels: &[ReasoningLevel], default: Option) -> ReasoningEffort { + ReasoningEffort { + supported_levels: levels.to_vec(), + default_level: default, + } + } + + #[test] + fn manual_profiles_are_atomic_and_imply_reasoning_without_copying_the_upstream_default() { + use ReasoningLevel::*; + let book = tw_pricing::PriceBook::builtin().unwrap(); + let mut provider = Provider::default(); + let reported = ReportedSpec { + reasoning: Some(false), + reasoning_effort: Some(profile(&[Low, High], Some(High))), + ..Default::default() + }; + provider.model_specs.insert( + "private".into(), + ModelSpec { + reasoning_effort: Some(profile(&[Max, Low, Medium], None)), + ..Default::default() + }, + ); + let resolved = provider.model_spec_with_metadata(&book, "private", Some(&reported)); + assert_eq!(resolved.reasoning(), Some(true)); + let effort = resolved.reasoning_effort.unwrap(); + assert_eq!(effort.source, SpecSource::Manual); + assert_eq!(effort.value, profile(&[Low, Medium, Max], Some(Medium))); + provider.model_specs.clear(); + let resolved = provider.model_spec_with_metadata(&book, "private", Some(&reported)); + assert_eq!(resolved.reasoning(), Some(false)); + assert!( + resolved + .reasoning_effort + .unwrap() + .value + .supported_levels + .is_empty() + ); + } + + #[test] + fn unknown_empty_and_reasoning_without_levels_remain_distinct() { + let book = tw_pricing::PriceBook::builtin().unwrap(); + let mut provider = Provider::default(); + assert!( + provider + .model_spec_with_metadata(&book, "private", None) + .reasoning_effort + .is_none() + ); + provider.model_specs.insert( + "private".into(), + ModelSpec { + reasoning: Some(true), + ..Default::default() + }, + ); + assert!( + provider + .model_spec_with_metadata(&book, "private", None) + .reasoning_effort + .is_none() + ); + provider + .model_specs + .get_mut("private") + .unwrap() + .reasoning_effort = Some(ReasoningEffort::default()); + let resolved = provider.model_spec_with_metadata(&book, "private", None); + assert_eq!(resolved.reasoning(), Some(true)); + assert_eq!( + resolved.reasoning_effort.unwrap().value, + ReasoningEffort::default() + ); + let reported = ReportedSpec { + reasoning: Some(false), + ..Default::default() + }; + let resolved = provider.model_spec_with_metadata(&book, "private", Some(&reported)); + assert_eq!( + resolved.reasoning_effort.unwrap().source, + SpecSource::Manual, + "an explicit empty manual profile retains its source even when another source also disables reasoning" + ); + } + + #[test] + fn upstream_specs_override_price_table_and_manual_values_win_field_by_field() { + let book = tw_pricing::PriceBook::builtin().unwrap(); + let mut provider = Provider::default(); + let reported = ReportedSpec { + context_window: Some(12345), + image_input: Some(false), + ..Default::default() + }; + provider.model_specs.insert( + "claude-sonnet-4-5".into(), + ModelSpec { + image_input: Some(true), + ..Default::default() + }, + ); + let spec = provider.model_spec_with_metadata(&book, "claude-sonnet-4-5", Some(&reported)); + assert_eq!(spec.context_window(), Some(12345)); + assert_eq!(spec.context_window.unwrap().source, SpecSource::Upstream); + assert_eq!(spec.image_input(), Some(true)); + assert_eq!(spec.image_input.unwrap().source, SpecSource::Manual); + } + + #[test] + fn invalid_manual_efforts_fail_before_the_configuration_is_applied() { + let yaml = |fields: &str| { + format!( + "version: 1\nclients:\n - name: c\n key: tw-test\nproviders:\n - name: relay\n base_url: https://relay.example/v1\n model_specs:\n private: {fields}\n" + ) + }; + for (fields, code) in [ + ( + "{ reasoning_effort: { supported_levels: [high, high] } }", + "config.model_spec_effort_duplicate", + ), + ( + "{ reasoning_effort: { supported_levels: [low], default_level: high } }", + "config.model_spec_effort_default", + ), + ( + "{ reasoning: false, reasoning_effort: { supported_levels: [high] } }", + "config.model_spec_effort_disabled", + ), + ( + "{ reasoning_effort: { supported_levels: [], default_level: high } }", + "config.model_spec_effort_default", + ), + ] { + let cfg: Config = serde_yaml_ng::from_str(&yaml(fields)).unwrap(); + assert_eq!( + crate::check_model_spec( + "relay", + "private", + cfg.providers[0].model_specs.get("private") + ) + .unwrap_err() + .msg() + .code, + code, + "{fields}" + ); + } + for fields in [ + "{ reasoning_effort: { supported_levels: [imaginary] } }", + "{ reasoning_effort: { supported_levels: [high], typo: high } }", + "{ reasoning_effort: {} }", + ] { + assert!( + serde_yaml_ng::from_str::(&yaml(fields)).is_err(), + "{fields}" + ); + } + } +} diff --git a/crates/tw-config/src/validate.rs b/crates/tw-config/src/validate.rs index 99ea4ba6..52f64175 100644 --- a/crates/tw-config/src/validate.rs +++ b/crates/tw-config/src/validate.rs @@ -134,6 +134,16 @@ pub enum ValidationError { ModelSpecWildcard { upstream: String, model: String }, #[error("{}", self.msg())] ModelSpecEmpty { upstream: String, model: String }, + #[error("{}", self.msg())] + ModelSpecEffortDuplicate { + upstream: String, + model: String, + level: String, + }, + #[error("{}", self.msg())] + ModelSpecEffortDefault { upstream: String, model: String }, + #[error("{}", self.msg())] + ModelSpecEffortDisabled { upstream: String, model: String }, /// `field` 是字段名本身(`context_window`、`max_output_tokens`),不翻 #[error("{}", self.msg())] ModelSpecZero { @@ -484,8 +494,23 @@ impl ValidationError { ), ModelSpecEmpty { upstream, model } => msg!( "config.model_spec_nothing_set", upstream = upstream, model = model => - "the model spec `{model}` of upstream `{upstream}` sets none of context_window, \ - max_output_tokens, reasoning and image_input. Set at least one, or remove it" + "the model spec `{model}` of upstream `{upstream}` sets no specifications. Set at least one, or remove it" + ), + ModelSpecEffortDuplicate { + upstream, + model, + level, + } => msg!( + "config.model_spec_effort_duplicate", upstream = upstream, model = model, level = level => + "the model spec `{model}` of upstream `{upstream}` repeats reasoning level `{level}`" + ), + ModelSpecEffortDefault { upstream, model } => msg!( + "config.model_spec_effort_default", upstream = upstream, model = model => + "the model spec `{model}` of upstream `{upstream}` has a default reasoning level outside supported_levels" + ), + ModelSpecEffortDisabled { upstream, model } => msg!( + "config.model_spec_effort_disabled", upstream = upstream, model = model => + "the model spec `{model}` of upstream `{upstream}` disables reasoning but declares nonempty reasoning levels" ), ModelSpecZero { upstream, @@ -1235,6 +1260,29 @@ pub fn check_model_spec( let (upstream, model) = named(); return Err(ValidationError::ModelSpecEmpty { upstream, model }); } + if let Some(effort) = &spec.reasoning_effort { + for (index, level) in effort.supported_levels.iter().enumerate() { + if effort.supported_levels[..index].contains(level) { + let (upstream, model) = named(); + return Err(ValidationError::ModelSpecEffortDuplicate { + upstream, + model, + level: level.to_string(), + }); + } + } + if effort + .default_level + .is_some_and(|level| !effort.supported_levels.contains(&level)) + { + let (upstream, model) = named(); + return Err(ValidationError::ModelSpecEffortDefault { upstream, model }); + } + if spec.reasoning == Some(false) && !effort.supported_levels.is_empty() { + let (upstream, model) = named(); + return Err(ValidationError::ModelSpecEffortDisabled { upstream, model }); + } + } // 0 不是「不知道」:上下文窗口是 0 的模型什么都装不下,输出上限是 0 的什么都答不出 for (field, v) in [ ("context_window", spec.context_window), diff --git a/crates/tw-config/src/wire.rs b/crates/tw-config/src/wire.rs index e5e59c84..2e9dbb3b 100644 --- a/crates/tw-config/src/wire.rs +++ b/crates/tw-config/src/wire.rs @@ -27,6 +27,7 @@ impl From for tw_api::SpecSource { match s { SpecSource::PriceTable => Self::PriceTable, SpecSource::Manual => Self::Manual, + SpecSource::Upstream => Self::Upstream, } } } diff --git a/crates/tw-config/tests/manual/schema.rs b/crates/tw-config/tests/manual/schema.rs index 632606c4..52777c86 100644 --- a/crates/tw-config/tests/manual/schema.rs +++ b/crates/tw-config/tests/manual/schema.rs @@ -36,6 +36,9 @@ fn protocols() -> Vec<&'static str> { fn reasoning_histories() -> Vec<&'static str> { super::fields::() } +fn reasoning_levels() -> Vec<&'static str> { + super::fields::() +} fn billings() -> Vec<&'static str> { super::fields::() } @@ -845,8 +848,17 @@ pub fn sections() -> Vec
{ Kind::Bool, Def::Unset, t( - "Whether the model reasons. The model list (`GET /v1/models`) carries it, so clients offer reasoning levels for it. Unset: the price table's; the list leaves it out when the price table does not say.", - "这个模型会不会推理。模型列表(`GET /v1/models`)带着它,客户端据此给出推理档位。不写:取价目表的;价目表也没写时,列表里不给这一项。", + "Whether the model reasons. This boolean does not declare adjustable effort levels; use reasoning_effort for those. False conflicts with nonempty manual levels. Unset: use known metadata or the price table.", + "这个模型会不会推理。此开关不声明可调档位,档位由 reasoning_effort 指定。false 不能与非空手动档位并存。不写:使用已知元数据或价目表。", + ), + ), + row( + "reasoning_effort", + Kind::Obj("providers[].model_specs.*.reasoning_effort"), + Def::Unset, + t( + "Override the entire reasoning effort profile. Unset: automatic upstream metadata; an empty supported_levels list explicitly disables adjustable effort. Nonempty levels imply reasoning support.", + "整组覆盖推理档位。不写时自动使用上游元数据;supported_levels 空列表明确表示不可调。非空档位自动表示支持推理。", ), ), row( @@ -860,6 +872,30 @@ pub fn sections() -> Vec
{ ), ], }, + Section { + path: "providers[].model_specs.*.reasoning_effort", + ty: checked!(ReasoningEffort, "{supported_levels: []}"), + rows: vec![ + row( + "supported_levels", + Kind::Strs, + Def::Required, + t( + "Supported levels: minimal, low, medium, high, xhigh, max, ultra. No duplicates. Empty explicitly means no adjustable effort; protocol conversion may further restrict these choices.", + "支持的档位:minimal、low、medium、high、xhigh、max、ultra,不可重复。空列表明确表示不可调;协议转换可能进一步限制可用档位。", + ), + ), + row( + "default_level", + Kind::Enum(reasoning_levels), + Def::Unset, + t( + "Must be one of supported_levels. Unset: prefer medium in the final available set, otherwise its lowest level. The manual profile does not inherit the upstream default.", + "必须属于 supported_levels。不写时在最终可用集合中优先 medium,否则最低档;手动档位不混用上游默认值。", + ), + ), + ], + }, Section { path: "providers[].min_speed", ty: checked!(MinSpeed, "{tokens_per_sec: 15}"), diff --git a/crates/tw-control/src/lib.rs b/crates/tw-control/src/lib.rs index 867a6cbf..d63d61eb 100644 --- a/crates/tw-control/src/lib.rs +++ b/crates/tw-control/src/lib.rs @@ -612,7 +612,7 @@ fn one_or_many(v: &tw_engine::rule::OneOrMany) -> Vec { /// 不该被拖上整个数据面。 pub(crate) fn model_list(m: tw_gateway::ModelList) -> tw_api::ModelList { match m { - tw_gateway::ModelList::Listed { models } => tw_api::ModelList::Listed { models }, + tw_gateway::ModelList::Listed { models, .. } => tw_api::ModelList::Listed { models }, tw_gateway::ModelList::NotImplemented { status } => { tw_api::ModelList::NotImplemented { status } } diff --git a/crates/tw-control/src/resources.rs b/crates/tw-control/src/resources.rs index 0e08316f..e31f85e7 100644 --- a/crates/tw-control/src/resources.rs +++ b/crates/tw-control/src/resources.rs @@ -152,8 +152,8 @@ fn chatgpt_login(cfg: &tw_config::Config, name: &str, token_endpoint: &str) -> O (ours && !shared).then(|| o.refresh.clone()) } -/// 手写一家上游的一个模型的上下文窗口、输出上限、会不会推理、收不收图;四项都空就删掉 -/// 那一项,回到价目表。 +/// 编辑一家上游的模型规格。推理档位区分保留、设置和恢复自动,高级历史字段保持原值。 +/// 所有字段都空才删除这一项。 /// /// **只动这一家 `model_specs` 里的这一项**([`edit::set_model_spec`]),不走编辑上游那条 /// 路:那条路按读进来的结构把整项写回去,用户写成和默认值一样的字段会被顺手删掉。 @@ -177,14 +177,20 @@ async fn set_model_spec( if !cfg.providers.iter().any(|p| p.name == req.provider) { return Err(not_found("upstream", &req.provider)); } - // The UI edits the four public specifications, not the advanced history override. - spec.reasoning_history = cfg + let previous = cfg .providers .iter() .find(|p| p.name == req.provider) - .and_then(|p| p.model_specs.get(model)) - .and_then(|s| s.reasoning_history); - let spec = (!spec.is_empty()).then_some(spec); + .and_then(|p| p.model_specs.get(model)); + spec.reasoning_history = previous.and_then(|s| s.reasoning_history); + spec.reasoning_effort = match &req.reasoning_effort { + tw_api::ReasoningEffortChange::Keep => { + previous.and_then(|s| s.reasoning_effort.clone()) + } + tw_api::ReasoningEffortChange::Auto => None, + tw_api::ReasoningEffortChange::Set { value } => Some(value.clone()), + }; + let spec = (!spec.is_empty()).then_some(spec.clone()); tw_config::check_model_spec(&req.provider, model, spec.as_ref()) .map_err(|e| invalid(e.msg()))?; Ok(edit::set_model_spec( @@ -431,7 +437,19 @@ fn models_view( .map(|id| { let r = book.resolve_for(&p.name, &id); // 规格和 `/v1/models` 给客户端的是同一个查法 - let spec = p.model_spec(&book, &id); + let reported = listing.capabilities.get(&id); + let spec = p.model_spec_with_metadata(&book, &id, reported); + let (effort, filtered) = spec + .reasoning_effort + .as_ref() + .map(|s| { + tw_gateway::model_capabilities::usable_effort( + &s.value, + p.effective_protocol(), + ) + }) + .map(|(e, f)| (Some(e), f)) + .unwrap_or_default(); tw_api::ModelRow { enabled: p.uses_model(&id), context_window: spec.context_window(), @@ -440,6 +458,18 @@ fn models_view( max_output_tokens_source: spec.max_output_tokens.map(|s| s.source.into()), reasoning: spec.reasoning(), reasoning_source: spec.reasoning.map(|s| s.source.into()), + manual_reasoning: p.model_specs.get(&id).and_then(|s| s.reasoning), + reasoning_effort: effort, + reasoning_effort_source: spec + .reasoning_effort + .as_ref() + .map(|s| s.source.into()), + reported_reasoning_effort: reported.and_then(|s| s.reasoning_effort.clone()), + manual_reasoning_effort: p + .model_specs + .get(&id) + .and_then(|s| s.reasoning_effort.clone()), + reasoning_effort_filtered_levels: filtered, image_input: spec.image_input(), image_input_source: spec.image_input.map(|s| s.source.into()), price: r.as_ref().map(|r| { diff --git a/crates/tw-control/tests/handover.rs b/crates/tw-control/tests/handover.rs index de391086..20dec39d 100644 --- a/crates/tw-control/tests/handover.rs +++ b/crates/tw-control/tests/handover.rs @@ -146,7 +146,7 @@ async fn status_reports_the_handover_phase_and_the_draining_count() { let st = status(&s).await; assert_eq!(st.handover, tw_api::HandoverState::Draining); assert_eq!(st.draining, 3); - assert_eq!(st.api_version, 59); + assert_eq!(st.api_version, tw_api::CONTROL_API_VERSION); } /// arm 之后(以及接替者正在接管时)不开始新的账号登录:回调端口不交接。(平常、排空中的 diff --git a/crates/tw-control/tests/model_specs.rs b/crates/tw-control/tests/model_specs.rs index 92b34f4c..f388d1ae 100644 --- a/crates/tw-control/tests/model_specs.rs +++ b/crates/tw-control/tests/model_specs.rs @@ -396,3 +396,95 @@ async fn editing_public_specs_and_provider_forms_preserves_history_capabilities( Some(tw_config::ReasoningHistory::Reasoning) ); } + +#[tokio::test] +async fn effort_overrides_are_set_preserved_validated_and_explicitly_reset() { + let up = upstream().await; + let b = bed(&config( + up, + " models: [private]\n model_specs:\n private: { reasoning_history: reasoning }\n", + "", + )); + let mut request = json!({"provider":"relay","model":"private","reasoning_effort":{"mode":"set","value":{"supported_levels":["high","ultra"]}}}); + let (st, written) = call(&b.app, "PUT", "/provider-model-spec", request.clone()).await; + assert_eq!(st, StatusCode::OK, "{written}"); + let original = tw_config::try_parse(&b.file()).unwrap().providers[0].model_specs["private"] + .reasoning_effort + .clone(); + let model = row(&rows(&b).await, "private").clone(); + assert_eq!( + model["manual_reasoning_effort"], + json!({"supported_levels":["high","ultra"]}) + ); + assert_eq!(model["reasoning"], true); + assert!( + model.get("manual_reasoning").is_none(), + "inferred support is not a manual boolean" + ); + assert_eq!( + model["reasoning_effort"], + json!({"supported_levels":["high"],"default_level":"high"}) + ); + assert_eq!(model["reasoning_effort_filtered_levels"], json!(["ultra"])); + // Old clients omit the new field; editing another specification must preserve it. + let (st, result) = call( + &b.app, + "PUT", + "/provider-model-spec", + json!({"provider":"relay","model":"private","context_window":64000}), + ) + .await; + assert_eq!(st, StatusCode::OK, "{result}"); + let cfg = tw_config::try_parse(&b.file()).unwrap(); + assert_eq!( + cfg.providers[0].model_specs["private"].reasoning_effort, + original + ); + assert_eq!( + cfg.providers[0].model_specs["private"].reasoning_history, + Some(tw_config::ReasoningHistory::Reasoning) + ); + let before = b.file(); + request["reasoning_effort"]["value"]["default_level"] = json!("medium"); + let (st, result) = call(&b.app, "PUT", "/provider-model-spec", request).await; + assert_eq!(st, StatusCode::BAD_REQUEST); + assert_eq!(result["code"], "config.model_spec_effort_default"); + assert_eq!(b.file(), before); + let (st, result) = call(&b.app,"PUT","/provider-model-spec",json!({"provider":"relay","model":"private","reasoning_effort":{"mode":"auto"},"base_version":"stale"})).await; + assert_eq!(st, StatusCode::CONFLICT, "{result}"); + let (st, result) = call( + &b.app, + "PUT", + "/provider-model-spec", + json!({"provider":"relay","model":"private","reasoning_effort":{"mode":"auto"}}), + ) + .await; + assert_eq!(st, StatusCode::OK, "{result}"); + assert!( + tw_config::try_parse(&b.file()).unwrap().providers[0].model_specs["private"] + .reasoning_effort + .is_none() + ); +} + +#[tokio::test] +async fn model_rows_expose_reported_manual_and_effective_effort_separately() { + let app = axum::Router::new().route("/v1/models", axum::routing::get(|| async { axum::Json(json!({"data":[{"id":"private","effort":{"supported_levels":["low","high"],"default_level":"high"}}]})) })); + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + tokio::spawn(async move { axum::serve(listener, app).await.unwrap() }); + let b = bed(&config(address, "", "")); + let model = row(&rows(&b).await, "private").clone(); + assert_eq!(model["reasoning_effort_source"], "upstream"); + assert_eq!( + model["reasoning_effort"], + model["reported_reasoning_effort"] + ); + assert!(model.get("manual_reasoning_effort").is_none()); + let (st,result)=call(&b.app,"PUT","/provider-model-spec",json!({"provider":"relay","model":"private","reasoning_effort":{"mode":"set","value":{"supported_levels":[]}}})).await; + assert_eq!(st, StatusCode::OK, "{result}"); + let model = row(&rows(&b).await, "private").clone(); + assert_eq!(model["reasoning_effort_source"], "manual"); + assert_eq!(model["reasoning_effort"], json!({"supported_levels":[]})); + assert_eq!(model["reported_reasoning_effort"]["default_level"], "high"); +} diff --git a/crates/tw-gateway/src/codex_catalog.rs b/crates/tw-gateway/src/codex_catalog.rs index efcc18c3..dee0b8ea 100644 --- a/crates/tw-gateway/src/codex_catalog.rs +++ b/crates/tw-gateway/src/codex_catalog.rs @@ -14,7 +14,7 @@ use axum::http::{HeaderMap, HeaderValue, StatusCode, header}; use axum::response::{IntoResponse, Response}; use futures::{StreamExt, stream}; use serde_json::{Value, json}; -use tw_config::{Provider, SpecSource}; +use tw_config::Provider; use tw_types::msg; use crate::error::GatewayError; @@ -360,7 +360,15 @@ pub(crate) async fn list( let book = state.pricing.load(); let models: Vec<_> = names(&rt.config, &catalog, allow.as_deref()) .iter() - .map(|name| project(name, &candidates(&rt, &catalog, name), &book, &upstreams)) + .map(|name| { + project( + name, + &candidates(&rt, &catalog, name), + &book, + &upstreams, + &state.models, + ) + }) .collect(); let body = serde_json::to_vec(&json!({"models":models})).expect("catalog is JSON"); if body.len() > MAX_BYTES { @@ -409,18 +417,12 @@ fn generic(name: &str) -> Value { }) } -fn pick(spec: Option>, native: Option) -> Option { - match spec { - Some(s) if s.source == SpecSource::Manual => Some(s.value), - _ => native.or(spec.map(|s| s.value)), - } -} - fn project( name: &str, candidates: &[(&Provider, &str)], book: &tw_pricing::PriceBook, upstreams: &HashMap, + directory: &crate::models::Directory, ) -> Value { let definitions: Vec<_> = candidates .iter() @@ -435,38 +437,30 @@ fn project( let mut reasoning = Vec::new(); let mut images = Vec::new(); for ((p, model), definition) in candidates.iter().zip(&definitions) { - let spec = p.model_spec(book, model); - contexts.push(pick( - spec.context_window, - definition.and_then(|d| d["context_window"].as_u64()), - )); - max_contexts.push(pick( - spec.context_window, - definition.and_then(|d| { - d["max_context_window"] - .as_u64() - .or_else(|| d["context_window"].as_u64()) - }), - )); - let enabled = pick( - spec.reasoning, - definition.and_then(|d| { - d["supported_reasoning_levels"] - .as_array() - .map(|v| !v.is_empty()) - }), + let reported = definition + .map(crate::model_capabilities::reported) + .or_else(|| directory.capabilities(&p.name, model)); + let spec = p.model_spec_with_metadata(book, model, reported.as_ref()); + contexts.push(spec.context_window()); + max_contexts.push( + if spec + .context_window + .as_ref() + .is_some_and(|s| s.source == tw_config::SpecSource::Manual) + { + spec.context_window() + } else { + definition + .and_then(|d| d["max_context_window"].as_u64()) + .or(spec.context_window()) + }, ); - reasoning.push(if enabled == Some(false) { - None - } else { - *definition - }); - images.push(pick( - spec.image_input, - definition - .and_then(|d| d["input_modalities"].as_array()) - .map(|v| v.iter().any(|v| v == "image")), - )); + reasoning.push( + spec.reasoning_effort + .as_ref() + .map(|effort| effort.value.clone()), + ); + images.push(spec.image_input()); } let context = (!contexts.is_empty() && contexts.iter().all(Option::is_some)) .then(|| contexts.iter().flatten().copied().min()) @@ -486,12 +480,14 @@ fn project( object.remove("max_context_window"); } let requires_translation = candidates.iter().any(|(provider, _)| { - !matches!( - provider.effective_protocol(), - Some(tw_config::Protocol::OpenaiResponses | tw_config::Protocol::Chatgpt) - ) + crate::model_capabilities::requires_translation(provider.effective_protocol()) }); - metadata::apply_reasoning(&mut out, &reasoning, requires_translation); + metadata::apply_reasoning( + &mut out, + &reasoning, + requires_translation, + definitions.first().copied().flatten(), + ); if !images.is_empty() && images.iter().all(|v| *v == Some(true)) { out["input_modalities"] = json!(["text", "image"]); } else { diff --git a/crates/tw-gateway/src/codex_catalog/metadata.rs b/crates/tw-gateway/src/codex_catalog/metadata.rs index 24e22c02..c835c73a 100644 --- a/crates/tw-gateway/src/codex_catalog/metadata.rs +++ b/crates/tw-gateway/src/codex_catalog/metadata.rs @@ -1,7 +1,5 @@ //! Project reported API model capabilities without adopting native instructions. -use std::collections::BTreeSet; - use serde_json::{Value, json}; pub(super) fn ordinary(model: &Value) -> Option { @@ -18,60 +16,48 @@ pub(super) fn ordinary(model: &Value) -> Option { .collect::>() ); } - if let Some(levels) = model["effort"]["supported_levels"].as_array() { - let mut seen = BTreeSet::new(); - let levels: Vec<_> = levels - .iter() - .filter_map(Value::as_str) - .filter(|effort| { - matches!(*effort, "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra") - && seen.insert(*effort) - }) - .map(|effort| json!({"effort": effort, "description": format!("Reasoning effort: {effort}")})) - .collect(); - let default = model["effort"]["default_level"] - .as_str() - .filter(|effort| levels.iter().any(|level| level["effort"] == *effort)); - out["supported_reasoning_levels"] = json!(levels); - out["default_reasoning_level"] = json!(default); + let reported = crate::model_capabilities::reported(model); + if let Some(effort) = reported.reasoning_effort { + set_reasoning(&mut out, &effort); + } + if let Some(reasoning) = reported.reasoning { + out["reasoning"] = json!(reasoning); + } + if let Some(max_output) = reported.max_output_tokens { + out["max_output_tokens"] = json!(max_output); } Some(out) } +/// Preserve native descriptions for discovered levels; hand-written levels get plain labels. +pub(super) fn set_reasoning(out: &mut Value, effort: &tw_config::ReasoningEffort) { + let levels: Vec<_> = effort.supported_levels.iter().map(|level| { + out["supported_reasoning_levels"].as_array() + .and_then(|levels| levels.iter().find(|v| v["effort"] == level.slug())).cloned() + .unwrap_or_else(|| json!({"effort":level.slug(),"description":format!("Reasoning effort: {level}")})) + }).collect(); + out["supported_reasoning_levels"] = json!(levels); + out["default_reasoning_level"] = json!(effort.default_level); +} + /// Definitions may disagree on prompts or tools while sharing effort choices. /// Keep only levels that every routing candidate explicitly supports. pub(super) fn apply_reasoning( out: &mut Value, - profiles: &[Option<&Value>], + profiles: &[Option], requires_translation: bool, + first_definition: Option<&Value>, ) { - let first = profiles.first().copied().flatten(); - let mut levels = first - .and_then(|p| p["supported_reasoning_levels"].as_array()) - .cloned() - .unwrap_or_default(); - levels.retain(|level| { - level["effort"].as_str().is_some_and(|effort| { - (!requires_translation || tw_dialect::think::parse_openai(effort).is_some()) - && profiles.iter().all(|profile| { - profile - .and_then(|p| p["supported_reasoning_levels"].as_array()) - .is_some_and(|levels| levels.iter().any(|v| v["effort"] == effort)) - }) - }) - }); - let default = first - .and_then(|p| p["default_reasoning_level"].as_str()) - .filter(|effort| levels.iter().any(|v| v["effort"] == *effort)) - .or_else(|| { - levels - .iter() - .find(|v| v["effort"] == "medium") - .or_else(|| levels.first()) - .and_then(|v| v["effort"].as_str()) - }); - out["default_reasoning_level"] = json!(default); - out["supported_reasoning_levels"] = json!(levels); + let common = crate::model_capabilities::common_effort( + &profiles.iter().map(Option::as_ref).collect::>(), + requires_translation, + ) + .unwrap_or_default(); + if let Some(levels) = first_definition.and_then(|p| p["supported_reasoning_levels"].as_array()) + { + out["supported_reasoning_levels"] = json!(levels); + } + set_reasoning(out, &common); } #[cfg(test)] @@ -107,7 +93,12 @@ mod tests { .unwrap(); assert!(profile["default_reasoning_level"].is_null()); out = json!({}); - apply_reasoning(&mut out, &[Some(&profile)], false); + apply_reasoning( + &mut out, + &[crate::model_capabilities::reported(&profile).reasoning_effort], + false, + Some(&profile), + ); assert_eq!( out["supported_reasoning_levels"].as_array().unwrap().len(), 2 diff --git a/crates/tw-gateway/src/lib.rs b/crates/tw-gateway/src/lib.rs index 610be338..a99b2b90 100644 --- a/crates/tw-gateway/src/lib.rs +++ b/crates/tw-gateway/src/lib.rs @@ -44,6 +44,7 @@ pub mod lenient; pub mod limits; pub mod listen; pub mod live; +pub mod model_capabilities; pub mod models; pub mod oauth; pub mod outbound; diff --git a/crates/tw-gateway/src/model_capabilities.rs b/crates/tw-gateway/src/model_capabilities.rs new file mode 100644 index 00000000..e49e1998 --- /dev/null +++ b/crates/tw-gateway/src/model_capabilities.rs @@ -0,0 +1,99 @@ +//! Parse only declared model capabilities, shared by background discovery and Codex. + +use serde_json::Value; +use tw_config::{Protocol, ReasoningEffort, ReasoningLevel, ReportedSpec}; + +pub(crate) fn reported(model: &Value) -> ReportedSpec { + let effort = model["supported_reasoning_levels"] + .as_array() + .map(|levels| (levels, &model["default_reasoning_level"])) + .or_else(|| { + model["effort"]["supported_levels"] + .as_array() + .map(|levels| (levels, &model["effort"]["default_level"])) + }); + let reasoning_effort = effort.and_then(|(levels, default)| { + let supported_levels: Vec<_> = levels + .iter() + .filter_map(|v| v.as_str().or_else(|| v["effort"].as_str())) + .filter_map(ReasoningLevel::from_slug) + .collect(); + // A nonempty but entirely unrecognized list is unknown, not a declaration of no levels. + if !levels.is_empty() && supported_levels.is_empty() { + return None; + } + let default_level = default + .as_str() + .and_then(ReasoningLevel::from_slug) + .filter(|level| supported_levels.contains(level)); + let mut effort = ReasoningEffort { + supported_levels, + default_level, + } + .normalized(); + effort.default_level = default_level; + Some(effort) + }); + ReportedSpec { + context_window: model["context_window"] + .as_u64() + .or_else(|| model["inputTokenLimit"].as_u64()) + .filter(|v| *v > 0), + max_output_tokens: model["max_output_tokens"] + .as_u64() + .or_else(|| model["outputTokenLimit"].as_u64()) + .filter(|v| *v > 0), + reasoning: model["reasoning"] + .as_bool() + .or_else(|| model["supports_reasoning"].as_bool()) + .or_else(|| model["thinking"].as_bool()), + image_input: model["input_modalities"] + .as_array() + .map(|modalities| modalities.iter().any(|v| v == "image")), + reasoning_effort, + } +} + +pub(crate) fn requires_translation(protocol: Option) -> bool { + !matches!( + protocol, + Some(Protocol::OpenaiResponses | Protocol::Chatgpt) + ) +} + +/// Protocol restrictions apply equally to manual and discovered declarations. +pub fn usable_effort( + effort: &ReasoningEffort, + protocol: Option, +) -> (ReasoningEffort, Vec) { + let mut usable = effort.clone(); + let mut filtered = Vec::new(); + if requires_translation(protocol) { + usable.supported_levels.retain(|level| { + let supported = tw_dialect::think::parse_openai(level.slug()).is_some(); + if !supported { + filtered.push(*level); + } + supported + }); + } + (usable.normalized(), filtered) +} + +/// A public model/alias can offer only levels confirmed by every routing candidate. +pub(crate) fn common_effort( + profiles: &[Option<&ReasoningEffort>], + translate: bool, +) -> Option { + let mut common = profiles.first().copied().flatten()?.clone(); + if profiles.iter().any(Option::is_none) { + return None; + } + common.supported_levels.retain(|level| { + (!translate || tw_dialect::think::parse_openai(level.slug()).is_some()) + && profiles + .iter() + .all(|p| p.is_some_and(|p| p.supported_levels.contains(level))) + }); + Some(common.normalized()) +} diff --git a/crates/tw-gateway/src/models.rs b/crates/tw-gateway/src/models.rs index 3ea843be..7d0d99bf 100644 --- a/crates/tw-gateway/src/models.rs +++ b/crates/tw-gateway/src/models.rs @@ -26,7 +26,7 @@ //! 界面没有别的办法知道它问完了:以前启动那一刻读到的「还没问」会一直挂在 //! 上游页上,直到别的什么事让它重读一次概览。 -use std::collections::HashMap; +use std::collections::{BTreeMap, HashMap}; use std::sync::Mutex; use std::time::Duration; @@ -108,6 +108,7 @@ pub struct Listing { pub models: Vec, /// 其中上游自己列出的。上游没给出清单时是空的 pub listed: Vec, + pub capabilities: BTreeMap, /// 最近一次向上游问的时间。还没问过是空 pub checked_at_ms: Option, /// 没从上游拿到清单的原因 @@ -120,7 +121,7 @@ enum Answer { /// 还没问过 Pending, /// 列出来了 - Listed(Vec), + Listed(Vec, BTreeMap), /// 问到了,但上游没给出清单:没有这个接口、格式认不出、空的 NoList(tw_types::Msg), /// 没问到:连不上、密钥被拒、取不到密钥 @@ -201,6 +202,14 @@ impl Directory { listing_of(entry.as_ref(), p) } + /// One model's declared capabilities, without cloning the entire provider listing. + pub fn capabilities(&self, provider: &str, model: &str) -> Option { + match &self.lock().get(provider)?.answer { + Answer::Listed(_, capabilities) => capabilities.get(model).cloned(), + _ => None, + } + } + /// 按目录和配置推出汇总,并换进 `into`。 /// /// **推算和换入在同一把锁里,配置在锁里现取。**否则一次探测回来和一次 @@ -291,7 +300,7 @@ impl Directory { } match e.answer { Answer::Pending | Answer::Failed(_) => true, - Answer::Listed(_) | Answer::NoList(_) => { + Answer::Listed(..) | Answer::NoList(_) => { age >= REFRESH_EVERY.as_millis() as u64 } } @@ -344,23 +353,24 @@ fn listing_of(entry: Option<&Entry>, p: &tw_config::Provider) -> Listing { let fetching = entry.is_some_and(|e| e.in_flight > 0); let error = entry.and_then(|e| match &e.answer { Answer::NoList(why) | Answer::Failed(why) => Some(why.clone()), - Answer::Pending | Answer::Listed(_) => None, + Answer::Pending | Answer::Listed(..) => None, }); let status = match entry.map(|e| &e.answer) { None | Some(Answer::Pending) => Status::Pending, - Some(Answer::Listed(_)) => Status::Listed, + Some(Answer::Listed(..)) => Status::Listed, Some(Answer::NoList(_)) => Status::NoList, Some(Answer::Failed(_)) => Status::Failed, }; match entry.map(|e| &e.answer) { // 上游列出的在前,手动添加的接在后面。**删得掉的只有手动添加的那些**:上游列出 // 的模型不该用的话,用启用范围把它排除在外 - Some(Answer::Listed(listed)) => Listing { + Some(Answer::Listed(listed, capabilities)) => Listing { source: Source::Discovered, status, fetching, models: with_manual(listed, &p.models), listed: listed.clone(), + capabilities: capabilities.clone(), checked_at_ms, error: None, }, @@ -371,6 +381,7 @@ fn listing_of(entry: Option<&Entry>, p: &tw_config::Provider) -> Listing { fetching, models: with_manual(&[], &p.models), listed: Vec::new(), + capabilities: BTreeMap::new(), checked_at_ms, error, }, @@ -380,6 +391,7 @@ fn listing_of(entry: Option<&Entry>, p: &tw_config::Provider) -> Listing { fetching, models: Vec::new(), listed: Vec::new(), + capabilities: BTreeMap::new(), checked_at_ms, error, }, @@ -424,7 +436,10 @@ async fn ask(state: &AppState, rt: &Runtime, p: &tw_config::Provider) -> Answer ); } match r.models { - ModelList::Listed { models } => Answer::Listed(models), + ModelList::Listed { + models, + capabilities, + } => Answer::Listed(models, capabilities), // 探测说了为什么列不出(Bedrock 没有列模型的权限)就用它的话 ModelList::NotImplemented { status } => Answer::NoList(r.error.unwrap_or_else(|| { msg!( @@ -498,7 +513,7 @@ async fn finish(state: &AppState, asking: Vec) { continue; }; match &answer { - Answer::Listed(models) => { + Answer::Listed(models, _) => { tracing::debug!(provider = %a.name, models = models.len(), "fetched the model list") } Answer::NoList(why) | Answer::Failed(why) => { @@ -896,7 +911,7 @@ mod tests { d.record( &p.name, &identity(&c, p), - Answer::Listed(vec![format!("{}-m", p.name)]), + Answer::Listed(vec![format!("{}-m", p.name)], BTreeMap::new()), 1, ); } @@ -1004,7 +1019,12 @@ mod tests { ] { let i = c.providers.iter().position(|x| x.name == p).unwrap(); let models = models.into_iter().map(String::from).collect(); - d.record(p, &identity(&c, &c.providers[i]), Answer::Listed(models), 1); + d.record( + p, + &identity(&c, &c.providers[i]), + Answer::Listed(models, BTreeMap::new()), + 1, + ); } d.record( "no-list", @@ -1124,7 +1144,12 @@ mod tests { let before = identity(&c, &c.providers[0]); c.providers[0].base_url = "https://elsewhere.example".into(); d.reconcile(&c); - d.record("a", &before, Answer::Listed(vec!["stale".into()]), 1); + d.record( + "a", + &before, + Answer::Listed(vec!["stale".into()], BTreeMap::new()), + 1, + ); assert_eq!(d.listing(&c.providers[0]).source, Source::None); } @@ -1137,7 +1162,10 @@ mod tests { d.record( &p.name, &identity(&c, p), - Answer::Listed(vec![format!("{}-1", p.name), format!("{}-2", p.name)]), + Answer::Listed( + vec![format!("{}-1", p.name), format!("{}-2", p.name)], + BTreeMap::new(), + ), 1, ); } @@ -1234,13 +1262,13 @@ mod tests { d.record( "listed", &id("listed"), - Answer::Listed(vec!["m".into()]), + Answer::Listed(vec!["m".into()], BTreeMap::new()), now - minute, ); d.record( "listed-old", &id("listed-old"), - Answer::Listed(vec!["m".into()]), + Answer::Listed(vec!["m".into()], BTreeMap::new()), now - day, ); d.record( @@ -1274,7 +1302,12 @@ mod tests { assert_eq!(l.error.as_ref().map(|m| m.text.as_str()), Some("连不上")); // 正在问的不再排进后台那一轮 assert!(d.due(&c, REFRESH_EVERY.as_millis() as u64).is_empty()); - d.record("a", &id, Answer::Listed(vec!["m".into()]), 2); + d.record( + "a", + &id, + Answer::Listed(vec!["m".into()], BTreeMap::new()), + 2, + ); let l = d.listing(p); assert!(!l.fetching); assert_eq!((l.status, l.source), (Status::Listed, Source::Discovered)); @@ -1298,7 +1331,12 @@ mod tests { let fresh = provider("fresh"); let id = identity(&c, &fresh); d.begin("fresh", &id); - d.record("fresh", &id, Answer::Listed(vec!["m".into()]), 1); + d.record( + "fresh", + &id, + Answer::Listed(vec!["m".into()], BTreeMap::new()), + 1, + ); assert_eq!(d.listing(&fresh).status, Status::Listed); } @@ -1316,7 +1354,7 @@ mod tests { d.record( &p.name, &identity(&c, p), - Answer::Listed(vec!["gpt-5".into(), "gpt-5-mini".into()]), + Answer::Listed(vec!["gpt-5".into(), "gpt-5-mini".into()], BTreeMap::new()), 1, ); } diff --git a/crates/tw-gateway/src/probe.rs b/crates/tw-gateway/src/probe.rs index 271119f7..b8e986da 100644 --- a/crates/tw-gateway/src/probe.rs +++ b/crates/tw-gateway/src/probe.rs @@ -25,7 +25,11 @@ const PROBE_TIMEOUT: Duration = Duration::from_secs(8); #[serde(tag = "kind", rename_all = "snake_case")] pub enum ModelList { /// 拿到了 - Listed { models: Vec }, + Listed { + models: Vec, + #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")] + capabilities: std::collections::BTreeMap, + }, /// 上游没有这个接口。**不是错误**,很多中转站就是不实现 —— 但要说 /// 出来,因为按模型路由、模型清单这些功能对它就用不了。 NotImplemented { status: u16 }, @@ -42,7 +46,7 @@ pub enum ModelList { impl ModelList { pub fn models(&self) -> &[String] { match self { - ModelList::Listed { models } => models, + ModelList::Listed { models, .. } => models, _ => &[], } } @@ -131,7 +135,13 @@ pub async fn probe_bedrock( ), ), Ok(Ok(models)) if models.is_empty() => ok(ModelList::Empty, None), - Ok(Ok(models)) => ok(ModelList::Listed { models }, None), + Ok(Ok(models)) => ok( + ModelList::Listed { + models, + capabilities: Default::default(), + }, + None, + ), Ok(Err(Failure::Status { status, kind, @@ -283,12 +293,29 @@ pub async fn probe( /// Codex 后端的模型清单:`{models:[{slug, visibility}]}`。后端隐藏的不列 fn classify_chatgpt_models(body: &str) -> ModelList { - let parsed = serde_json::from_str::(body) - .ok() - .and_then(|v| crate::chatgpt::parse_models(&v)); + let value = serde_json::from_str::(body).ok(); + let parsed = value.as_ref().and_then(crate::chatgpt::parse_models); match parsed { Some(models) if models.is_empty() => ModelList::Empty, - Some(models) => ModelList::Listed { models }, + Some(models) => { + let capabilities = value + .as_ref() + .and_then(|v| v["models"].as_array()) + .into_iter() + .flatten() + .filter_map(|m| { + let id = m["slug"].as_str()?; + models + .iter() + .any(|model| model == id) + .then(|| (id.to_string(), crate::model_capabilities::reported(m))) + }) + .collect(); + ModelList::Listed { + models, + capabilities, + } + } None => ModelList::Unrecognized { sample: body.trim().chars().take(200).collect(), }, @@ -341,7 +368,20 @@ fn classify_models(body: &str) -> ModelList { (true, _) => ModelList::Empty, // 数组在、有元素、一个名字都抠不出来 —— 那是新格式,不是空。 (false, true) => ModelList::Unrecognized { sample: sample() }, - (false, false) => ModelList::Listed { models }, + (false, false) => { + let capabilities = arr + .iter() + .filter_map(|m| { + let id = m.get("id").or_else(|| m.get("name"))?.as_str()?; + let id = id.strip_prefix("models/").unwrap_or(id); + Some((id.to_string(), crate::model_capabilities::reported(m))) + }) + .collect(); + ModelList::Listed { + models, + capabilities, + } + } } } diff --git a/crates/tw-gateway/src/server/listing.rs b/crates/tw-gateway/src/server/listing.rs index 16e333d0..405fecb1 100644 --- a/crates/tw-gateway/src/server/listing.rs +++ b/crates/tw-gateway/src/server/listing.rs @@ -113,14 +113,28 @@ fn listed_meta( catalog: &tw_engine::Catalog, cfg: &tw_config::Config, name: &str, + directory: &crate::models::Directory, ) -> ModelMeta { + let resolved = |provider: &str, model: &str| { + let Some(p) = cfg.providers.iter().find(|p| p.name == provider) else { + return model_meta(cfg, book, Some(provider), model); + }; + let reported = directory.capabilities(provider, model); + let spec = p.model_spec_with_metadata(book, model, reported.as_ref()); + ModelMeta { + max_input_tokens: spec.context_window(), + max_output_tokens: spec.max_output_tokens(), + reasoning: spec.reasoning(), + image_input: spec.image_input(), + } + }; if let Some((provider, model)) = catalog.first_served(name) { - return model_meta(cfg, book, Some(provider), model); + return resolved(provider, model); } if !cfg.aliases.contains(name) && let Some(provider) = catalog.providers_for(name).first() { - return model_meta(cfg, book, Some(provider), name); + return resolved(provider, name); } match cfg.aliases.find(name).and_then(|a| a.models.first()) { Some(model) => model_meta(cfg, book, None, model), @@ -128,6 +142,50 @@ fn listed_meta( } } +/// Normal model discovery shares the same effort intersection as the Codex catalog. +fn listed_object( + shape: ListingShape, + name: &str, + book: &tw_pricing::PriceBook, + catalog: &tw_engine::Catalog, + cfg: &tw_config::Config, + directory: &crate::models::Directory, +) -> serde_json::Value { + let mut out = shape.object(name, &listed_meta(book, catalog, cfg, name, directory)); + let candidates: Vec<_> = if catalog.alias(name).is_some() { + catalog + .served(name) + .iter() + .map(|(p, m)| (p.as_str(), m.as_str())) + .collect() + } else { + catalog + .providers_for(name) + .iter() + .map(|p| (p.as_str(), name)) + .collect() + }; + let mut translate = false; + let profiles: Vec<_> = candidates + .iter() + .map(|(provider, model)| { + let p = cfg.providers.iter().find(|p| p.name == *provider)?; + translate |= crate::model_capabilities::requires_translation(p.effective_protocol()); + let reported = directory.capabilities(provider, model); + p.model_spec_with_metadata(book, model, reported.as_ref()) + .reasoning_effort + .map(|s| s.value) + }) + .collect(); + if let Some(effort) = crate::model_capabilities::common_effort( + &profiles.iter().map(Option::as_ref).collect::>(), + translate, + ) { + out["effort"] = serde_json::to_value(effort).expect("effort is JSON"); + } + out +} + /// `GET /v1/models`。 /// /// 三种方言的响应结构不同,但**列表内容来自同一个函数** —— 差别只在 @@ -165,7 +223,7 @@ pub(super) async fn list_models( let book = state.pricing.load(); let objects: Vec<_> = models .iter() - .map(|m| shape.object(m, &listed_meta(&book, &catalog, &rt.config, m))) + .map(|m| listed_object(shape, m, &book, &catalog, &rt.config, &state.models)) .collect(); let body = match shape { @@ -365,8 +423,15 @@ pub(super) async fn get_model( ), )); } - let meta = listed_meta(&state.pricing.load(), &catalog, &rt.config, &model); - Ok(axum::Json(shape.object(&model, &meta)).into_response()) + Ok(axum::Json(listed_object( + shape, + &model, + &state.pricing.load(), + &catalog, + &rt.config, + &state.models, + )) + .into_response()) } #[cfg(test)] diff --git a/crates/tw-gateway/tests/chatgpt.rs b/crates/tw-gateway/tests/chatgpt.rs index 31b8ac9a..b32899ce 100644 --- a/crates/tw-gateway/tests/chatgpt.rs +++ b/crates/tw-gateway/tests/chatgpt.rs @@ -782,7 +782,7 @@ async fn models_come_from_the_codex_models_endpoint() { .await; assert!(got.ok, "{got:?}"); match &got.models { - tw_gateway::ModelList::Listed { models } => { + tw_gateway::ModelList::Listed { models, .. } => { assert_eq!(models, &vec!["gpt-5.5".to_string()], "后端隐藏的模型不列") } other => panic!("{other:?}"), diff --git a/crates/tw-gateway/tests/codex_catalog.rs b/crates/tw-gateway/tests/codex_catalog.rs index ef367aa8..49bf4984 100644 --- a/crates/tw-gateway/tests/codex_catalog.rs +++ b/crates/tw-gateway/tests/codex_catalog.rs @@ -791,3 +791,198 @@ async fn alias_discovery_policy_reloads_over_cached_metadata_and_is_key_scoped() state.reload(cfg).unwrap(); assert_eq!(slugs(&catalog(gw).await), ["raw"]); } + +fn manual_effort(levels: &[&str], default: Option<&str>) -> ModelSpec { + ModelSpec { + reasoning_effort: Some(tw_config::ReasoningEffort { + supported_levels: levels + .iter() + .map(|v| tw_config::ReasoningLevel::from_slug(v).unwrap()) + .collect(), + default_level: default.map(|v| tw_config::ReasoningLevel::from_slug(v).unwrap()), + }), + ..Default::default() + } +} + +#[tokio::test] +async fn manual_effort_works_without_model_lists_and_reloads_before_conditional_reads() { + let up = Upstream::new(json!({"error":"no model list"})); + let mut cfg = config(vec![provider( + "relay", + up.serve().await, + &["private-model"], + )]); + cfg.aliases = serde_yaml_ng::from_str("coding: private-model").unwrap(); + cfg.providers[0].model_specs.insert( + "private-model".into(), + manual_effort(&["low", "high", "max"], Some("high")), + ); + let (state, gw) = serve(cfg.clone()).await; + let first = request(gw).send().await.unwrap(); + let etag = first.headers()["etag"].clone(); + for model in first.json::().await.unwrap()["models"] + .as_array() + .unwrap() + { + assert_eq!(efforts(model), ["low", "high", "max"]); + assert_eq!(model["default_reasoning_level"], "high"); + } + cfg.providers[0].model_specs.clear(); + state.reload(cfg).unwrap(); + let response = request(gw) + .header("if-none-match", etag) + .send() + .await + .unwrap(); + assert_eq!(response.status(), 200); + for model in response.json::().await.unwrap()["models"] + .as_array() + .unwrap() + { + assert!(efforts(model).is_empty()); + assert!(model["default_reasoning_level"].is_null()); + } +} + +#[tokio::test] +async fn manual_profiles_override_upstream_atomically_and_reset_to_discovery() { + let up = + Upstream::new(json!({"data":[reported_model("private", &["low","high","max"], "max")]})); + let mut cfg = config(vec![provider("relay", up.serve().await, &["private"])]); + let (state, gw) = serve(cfg.clone()).await; + assert_eq!( + efforts(&catalog(gw).await["models"][0]), + ["low", "high", "max"] + ); + cfg.providers[0] + .model_specs + .insert("private".into(), manual_effort(&["medium", "high"], None)); + state.reload(cfg.clone()).unwrap(); + let manual = catalog(gw).await; + assert_eq!(efforts(&manual["models"][0]), ["medium", "high"]); + assert_eq!(manual["models"][0]["default_reasoning_level"], "medium"); + cfg.providers[0] + .model_specs + .insert("private".into(), manual_effort(&[], None)); + state.reload(cfg.clone()).unwrap(); + assert!(efforts(&catalog(gw).await["models"][0]).is_empty()); + cfg.providers[0].model_specs.clear(); + state.reload(cfg).unwrap(); + let automatic = catalog(gw).await; + assert_eq!(efforts(&automatic["models"][0]), ["low", "high", "max"]); + assert_eq!(automatic["models"][0]["default_reasoning_level"], "max"); + assert_eq!( + up.requests.lock().unwrap().len(), + 1, + "only metadata is cached" + ); +} + +#[tokio::test] +async fn manual_candidates_intersect_and_conversion_filters_the_final_default() { + let up = Upstream::new(json!({"data":[]})); + let addr = up.serve().await; + let mut cfg = config(vec![ + provider("first", addr, &["one"]), + provider("second", addr, &["two"]), + ]); + cfg.aliases = serde_yaml_ng::from_str("coding: [one, two]").unwrap(); + cfg.providers[0].model_specs.insert( + "one".into(), + manual_effort(&["low", "medium", "high", "ultra"], Some("ultra")), + ); + let (state, gw) = serve(cfg.clone()).await; + assert!( + efforts(&catalog(gw).await["models"][0]).is_empty(), + "an unknown candidate cannot promise shared choices" + ); + cfg.providers[1].model_specs.insert( + "two".into(), + manual_effort(&["medium", "high", "ultra"], Some("high")), + ); + cfg.providers[1].protocol = Some(Protocol::OpenaiChat); + state.reload(cfg).unwrap(); + let body = catalog(gw).await; + let alias = body["models"] + .as_array() + .unwrap() + .iter() + .find(|m| m["slug"] == "coding") + .unwrap(); + assert_eq!(efforts(alias), ["medium", "high"]); + assert_eq!(alias["default_reasoning_level"], "medium"); +} + +#[tokio::test] +async fn background_metadata_is_used_by_both_normal_and_codex_discovery() { + let up = Upstream::new(json!({"data":[reported_model("private", &["low","high"], "high")]})); + let addr = up.serve().await; + let mut p = provider("relay", addr, &[]); + // This protocol does not trigger an extra Codex metadata request. + p.protocol = Some(Protocol::Anthropic); + let (state, gw) = serve(config(vec![p])).await; + tw_gateway::models::refresh_one(&state, "relay") + .await + .unwrap(); + let codex = catalog(gw).await; + assert_eq!(efforts(&codex["models"][0]), ["low", "high"]); + let normal: Value = http() + .get(format!("http://{gw}/v1/models")) + .bearer_auth("gateway-test-key") + .send() + .await + .unwrap() + .json() + .await + .unwrap(); + assert_eq!( + normal["data"][0]["effort"], + json!({"supported_levels":["low","high"],"default_level":"high"}) + ); + let single: Value = http() + .get(format!("http://{gw}/v1/models/private")) + .bearer_auth("gateway-test-key") + .send() + .await + .unwrap() + .json() + .await + .unwrap(); + assert_eq!(single, normal["data"][0]); + assert_eq!(up.requests.lock().unwrap().len(), 1); +} + +#[tokio::test] +async fn manually_advertised_levels_reach_the_real_upstream_model() { + let up = Upstream::new(json!({"data":[]})); + let mut p = provider("relay", up.serve().await, &["private"]); + p.protocol = Some(Protocol::OpenaiChat); + p.model_specs.insert( + "private".into(), + manual_effort(&["low", "high", "max"], Some("high")), + ); + let mut cfg = config(vec![p]); + cfg.aliases = serde_yaml_ng::from_str("coding: private").unwrap(); + let (_, gw) = serve(cfg).await; + let body = catalog(gw).await; + let alias = body["models"] + .as_array() + .unwrap() + .iter() + .find(|m| m["slug"] == "coding") + .unwrap(); + for effort in efforts(alias) { + let response = http() + .post(format!("http://{gw}/v1/responses")) + .bearer_auth("gateway-test-key") + .json(&json!({"model":"coding","input":"Hello","reasoning":{"effort":effort}})) + .send() + .await + .unwrap(); + assert_eq!(response.status(), 200, "{}", response.text().await.unwrap()); + let sent = up.forwarded.lock().unwrap().last().unwrap().clone(); + assert_eq!(sent["model"], "private"); + assert_eq!(sent["reasoning_effort"], effort); + } +} diff --git a/docs/codex-model-catalog.md b/docs/codex-model-catalog.md index dea137a6..6bd1fcca 100644 --- a/docs/codex-model-catalog.md +++ b/docs/codex-model-catalog.md @@ -69,7 +69,7 @@ its [models endpoint](https://api-docs.deepseek.com/api/list-models). The effort list becomes Codex's `supported_reasoning_levels`; the reported default is kept when it is in the list. Optional or malformed fields do not create capabilities. No model-name table or inference from `reasoning: true` supplies missing levels. -A relay must preserve the metadata for Core to use it. +A relay can preserve this metadata for automatic discovery; missing or incorrect effort profiles can also be overridden manually. Aliases inherit the actual routing targets' reported capabilities. Effort choices are intersected separately from full native definitions, so differences @@ -79,6 +79,41 @@ candidate requires protocol translation, choices are also limited to efforts Core can translate; Responses and ChatGPT passthrough can retain newer native efforts such as `ultra`. +## Automatic discovery and manual overrides + +Core uses reported capabilities automatically. Background inventory retains the same specifications +for Lite and standard model discovery; the Codex catalog prefers metadata for the requesting client +version. Missing effort metadata remains unknown. Model names and price-table reasoning flags +do not generate effort choices. + +If the upstream has no model list, first add its actual model ID to `models`. Supply missing or +incorrect effort metadata for that exact model and provider: + +```yaml +providers: + - name: relay + base_url: https://relay.example.com/v1 + protocol: openai-chat + models: [private-model] + model_specs: + private-model: + reasoning_effort: + supported_levels: [low, high, max] + default_level: high +``` + +The entire manual profile replaces the upstream profile. Nonempty levels imply reasoning support; +`reasoning: true` is unnecessary. Omitting `reasoning_effort` restores automatic discovery, while +`supported_levels: []` explicitly declares no adjustable effort. `default_level` is optional: Core +prefers `medium` in the final available set, otherwise its lowest level. An explicit default must +belong to the declared set. Duplicate levels and `reasoning: false` with nonempty manual levels +are rejected. Alias intersections and protocol restrictions apply to manual profiles as well. + +Control API model rows expose reported, manual and effective efforts separately, together with +levels excluded by protocol conversion. In `PUT /provider-model-spec`, `reasoning_effort` uses +`mode: keep` (also the omitted default), `mode: auto`, or `mode: set` with `value` to retain, +remove or replace the override. Editing other specifications preserves the effort override. + ## Cache and limits Only upstream metadata is cached. Entries are isolated by the provider, diff --git a/docs/codex-model-catalog.zh-CN.md b/docs/codex-model-catalog.zh-CN.md index ca9f2207..aeee9959 100644 --- a/docs/codex-model-catalog.zh-CN.md +++ b/docs/codex-model-catalog.zh-CN.md @@ -53,13 +53,45 @@ Codex `client_version`,使用该上游的凭据和代理,不转发入站网 [模型接口文档](https://api-docs.deepseek.com/api/list-models)已定义这些字段。档位列表转为 Codex 的 `supported_reasoning_levels`,报告的默认值在列表内时保留。可选字段缺失或 格式错误时不编造能力,也不按模型名查表或仅凭 `reasoning: true` 推导档位;中转站需要 -透传这些元数据才能使用。 +透传这些元数据即可自动获取;没有透传时可在模型规格中手动声明。 别名继承实际路由目标报告的能力。推理档位独立于完整原生定义取交集,不会因为指令或 工具不同而丢掉共有档位,默认值必须在交集内。手动 `model_specs.reasoning: false` 移除档位选项。任一候选需要协议转换时,只保留 Core 能表达的档位;Responses 和 ChatGPT 直通可以保留 `ultra` 等更新的原生档位。 +## 自动获取与手动覆盖 + +默认读取上游实际报告的能力。后台模型清单保留同样的规格信息,供 Lite 和标准模型发现使用; +Codex 的版本化目录优先使用对应客户端版本的元数据。没有报告的档位保持未知, +不根据模型名称猜测,也不从价目表中的推理开关生成档位。 + +上游缺少模型列表时,先在 `models` 中手动添加真实模型 ID;缺少或错误的推理档位则按 +该上游、该模型填写覆盖值: + +```yaml +providers: + - name: relay + base_url: https://relay.example.com/v1 + protocol: openai-chat + models: [private-model] + model_specs: + private-model: + reasoning_effort: + supported_levels: [low, high, max] + default_level: high +``` + +`reasoning_effort` 整组替换上游档位,非空列表自动表示支持推理,不必另写 `reasoning: true`。 +不写这一项是自动;`supported_levels: []` 明确表示不可调。`default_level` 可省略, +Core 在最终可用集合中优先选择 `medium`,否则选择最低档;手写默认值必须属于所列档位。 +档位不能重复,`reasoning: false` 不能与非空手动档位并存。恢复自动时移除整项覆盖, +上游元数据和其默认值重新生效。别名交集与协议转换限制同样作用于手动档位。 + +控制 API 的模型行分别提供上游报告、手动原值、保存后的生效结果及协议过滤掉的档位。 +`PUT /provider-model-spec` 的 `reasoning_effort` 以 `mode: keep`(省略时亦如此)、 +`mode: auto`、`mode: set` 加 `value` 区分保留、清除和整组替换;编辑其他规格不会误删档位。 + ## 缓存和限制 只缓存上游元数据。缓存按上游、解析后的凭据及请求头、地址、客户端版本和代理配置 diff --git a/docs/config.md b/docs/config.md index 4367b4ad..1903eb5f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -730,18 +730,18 @@ region in `aws.region`; the model list is asked of that address too. #### `providers[].model_specs` -A model's context window and output limit come from the price table. A relay's -own models are often missing from it, and now and then it is wrong. Write the -numbers here, for this upstream and by the exact id in its model list. A value -written here takes precedence over the price table; one left out still comes -from it. At least one of the two is written, and neither can be 0. - -The same numbers are used everywhere: in `/v1/models` for every client format, -for an alias this upstream serves, when the gateway judges whether a -conversation still fits the model it is on, and as the output limit of a -request converted to Anthropic that does not set one. When several upstreams -offer the same model, `/v1/models` describes it by the first of them in -`providers`. +Model discovery uses upstream-reported capabilities automatically, with the price table supplying +known specifications that the upstream omits. Write overrides here for missing or incorrect values, +scoped to this upstream and an exact model ID. Each entry must set at least one specification; +context and output token counts must be positive. + +Manual values also apply when checking context capacity and supplying an omitted Anthropic output +limit. For discovery, manual values take precedence over reported metadata, then the price table. +Reasoning effort has no price-table fallback: use `reasoning_effort` to supply its levels and optional +default. Nonempty levels imply reasoning support, an empty list explicitly declares no adjustable +effort, and removing the override restores automatic discovery. Public effort choices are intersected +across all routing candidates and limited to values the required protocol conversions can represent. +See [Codex model discovery](codex-model-catalog.md#automatic-discovery-and-manual-overrides). @@ -751,10 +751,20 @@ offer the same model, `/v1/models` describes it by the first of them in | `reasoning_history` | `auto` \| `reasoning-content` \| `reasoning` \| `content-blocks` \| `disabled` | — | Override this model's request-side reasoning-history format. Unset: use the upstream setting. This is independent of whether the model can reason. | | `context_window` | integer | — | Context window: the most tokens a request can take in. Unset: the price table's. | | `max_output_tokens` | integer | — | The most tokens an answer can have. Unset: the price table's. | -| `reasoning` | bool | — | Whether the model reasons. The model list (`GET /v1/models`) carries it, so clients offer reasoning levels for it. Unset: the price table's; the list leaves it out when the price table does not say. | +| `reasoning` | bool | — | Whether the model reasons. This boolean does not declare adjustable effort levels; use reasoning_effort for those. False conflicts with nonempty manual levels. Unset: use known metadata or the price table. | +| `reasoning_effort` | object, [`providers[].model_specs.*.reasoning_effort`](#cfg-providers-model_specs-reasoning_effort) | — | Override the entire reasoning effort profile. Unset: automatic upstream metadata; an empty supported_levels list explicitly disables adjustable effort. Nonempty levels imply reasoning support. | | `image_input` | bool | — | Whether the model takes images as input. The model list carries it, as `input_modalities`. Unset: the price table's; the list leaves it out when the price table does not say. | + + + +| Field | Type | Default | Description | +|---|---|---|---| +| `supported_levels` | list of strings | **required** | Supported levels: minimal, low, medium, high, xhigh, max, ultra. No duplicates. Empty explicitly means no adjustable effort; protocol conversion may further restrict these choices. | +| `default_level` | `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` \| `ultra` | — | Must be one of supported_levels. Unset: prefer medium in the final available set, otherwise its lowest level. The manual profile does not inherit the upstream default. | + + ```yaml providers: - name: relay diff --git a/docs/config.zh-CN.md b/docs/config.zh-CN.md index 26010e6c..2b138abe 100644 --- a/docs/config.zh-CN.md +++ b/docs/config.zh-CN.md @@ -510,9 +510,9 @@ providers: #### `providers[].model_specs` -模型的上下文窗口和输出上限取自价目表。中转站自有的模型常常不在价目表里,价目表偶尔也会写错。这时在这里按这家上游、按它模型清单里的 ID(完全匹配)手写。写了的一项优先于价目表,没写的一项仍取价目表。两项至少写一项,都不能是 0。 +模型发现默认读取上游报告的能力,上游缺少的已知规格由价目表补充。在这里按上游、按真实模型 ID(完全匹配)覆盖缺失或错误的值。每项至少填写一个规格;上下文窗口和输出上限必须是正整数。 -各处用的是同一个数:各种客户端格式的 `/v1/models`、由这家上游服务的别名、网关判断一段对话是否还装得下当前模型,以及请求转换为 Anthropic 格式且没有写输出上限时补上的值。同一个模型由几家上游提供时,`/v1/models` 按 `providers` 中排在最前的那一家给出。 +手动值也用于上下文容量判断,以及补充转换到 Anthropic 请求时缺少的输出上限。模型发现按手动值、上游报告、价目表的顺序取值。推理档位没有价目表回退:在 `reasoning_effort` 中填写支持的档位和可选默认值。非空档位自动表示支持推理,空列表明确表示不可调,移除覆盖恢复自动获取。对外提供的档位取所有路由候选的交集,并受实际协议转换能力限制。参见 [Codex 模型发现](codex-model-catalog.zh-CN.md#自动获取与手动覆盖)。 @@ -522,10 +522,20 @@ providers: | `reasoning_history` | `auto` \| `reasoning-content` \| `reasoning` \| `content-blocks` \| `disabled` | — | 覆盖这个模型的请求侧思考历史格式。不写时遵从上游设置;与模型会不会推理是两项独立能力。 | | `context_window` | 整数 | — | 上下文窗口,即一次请求最多输入多少 token。不写:取价目表的。 | | `max_output_tokens` | 整数 | — | 一次回答最多输出多少 token。不写:取价目表的。 | -| `reasoning` | 布尔 | — | 这个模型会不会推理。模型列表(`GET /v1/models`)带着它,客户端据此给出推理档位。不写:取价目表的;价目表也没写时,列表里不给这一项。 | +| `reasoning` | 布尔 | — | 这个模型会不会推理。此开关不声明可调档位,档位由 reasoning_effort 指定。false 不能与非空手动档位并存。不写:使用已知元数据或价目表。 | +| `reasoning_effort` | 对象,见 [`providers[].model_specs.*.reasoning_effort`](#cfg-providers-model_specs-reasoning_effort) | — | 整组覆盖推理档位。不写时自动使用上游元数据;supported_levels 空列表明确表示不可调。非空档位自动表示支持推理。 | | `image_input` | 布尔 | — | 这个模型收不收图。模型列表里以 `input_modalities` 给出。不写:取价目表的;价目表也没写时,列表里不给这一项。 | + + + +| 字段 | 类型 | 默认值 | 说明 | +|---|---|---|---| +| `supported_levels` | 字符串列表 | **必填** | 支持的档位:minimal、low、medium、high、xhigh、max、ultra,不可重复。空列表明确表示不可调;协议转换可能进一步限制可用档位。 | +| `default_level` | `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` \| `ultra` | — | 必须属于 supported_levels。不写时在最终可用集合中优先 medium,否则最低档;手动档位不混用上游默认值。 | + + ```yaml providers: - name: relay diff --git a/release-notes/0.95.0.md b/release-notes/0.95.0.md new file mode 100644 index 00000000..d3cf84f1 --- /dev/null +++ b/release-notes/0.95.0.md @@ -0,0 +1,3 @@ +Model capabilities are discovered automatically from upstream model metadata and can now be overridden per provider and exact model ID. Relays that omit model lists or capability metadata can use manually configured model IDs and reasoning effort profiles, including supported levels, an optional default, and an explicit non-adjustable setting. Removing an override restores automatic discovery. + +Manual settings take precedence over upstream declarations. Aliases expose only reasoning levels shared by every routing candidate, and protocol conversion removes levels it cannot represent. Missing capability information remains unknown. Control API 60 distinguishes reported capabilities, manual overrides, and the effective profile, while omitted effort edits preserve existing settings.