模型加载与配置

全局模型目录

GET /models 返回的公共模型目录仍然是系统级能力源，字段包含：

providers[].name
providers[].models[].name
providers[].models[].description
providers[].models[].category

Admin Frontend 会基于这些字段渲染主模型下拉框与角色化路由选择器。

用于实例化提供商配置定义的聊天模型的辅助工具。

load_models_config `cached`

load_models_config(config_path=None)

加载并缓存提供商配置文件。

参数：

名称	类型	描述	默认
`config_path`	`str \| Path \| None`	配置文件的可选路径覆盖。	`None`

返回：

类型	描述
`dict[str, Any]`	dict[str, Any]: 解析后的提供商配置数据。

引发：

类型	描述
`FileNotFoundError`	如果无法找到配置文件。
`JSONDecodeError`	如果文件包含无效的 JSON。

示例：

>>> config = load_models_config()
>>> isinstance(config, dict)
True
>>> "openai" in config
True

>>> config = load_models_config("custom_models.json")
>>> # 从自定义路径加载配置

list_models

list_models(
    provider,
    category=None,
    *,
    config_path=None,
    config=None,
)

返回给定提供商/类别的已配置模型。

参数：

名称	类型	描述	默认
`provider`	`str`	配置文件中定义的提供商键。	必需
`category`	`str \| None`	可选的类别键，例如 `omni_models`。	`None`
`config_path`	`str \| Path \| None`	配置文件路径的覆盖。	`None`

返回：

类型	描述
`list[dict[str, Any]]`	list[dict[str, Any]]: 包含元数据的匹配模型条目。

示例：

>>> models = list_models("openai")
>>> isinstance(models, list)
True
>>> len(models) > 0
True

>>> chat_models = list_models("openai", "chat_models")
>>> # 获取 OpenAI 的聊天模型列表

resolve_model_credentials

resolve_model_credentials(
    model_name,
    *,
    provider=None,
    config_path=None,
    config=None,
    api_key=None,
    dashscope_region=None,
)

解析模型可用的全部提供商、基础 URL 和 API 密钥组合。

参数：

名称	类型	描述	默认
`model_name`	`str`	要检查的模型标识符。	必需
`provider`	`str \| None`	显式指定的提供商名称。	`None`
`config_path`	`str \| Path \| None`	可选的配置文件覆盖。	`None`
`api_key`	`str \| None`	优先使用的显式 API 密钥。	`None`
`dashscope_region`	`str \| None`	DashScope 基础 URL 的区域选择器。	`None`

返回：

类型	描述
`list[tuple[str, str \| None, str \| None]]`	list[tuple[str, str \| None, str \| None]]: (provider, base_url, api_key)
`list[tuple[str, str \| None, str \| None]]`	组合，覆盖所有匹配的提供商和 URL。

示例：

>>> resolve_model_credentials("gpt-4")
[('openai', None, 'sk-...')]

>>> resolve_model_credentials("qwen-turbo", dashscope_region="beijing")
[('dashscope', 'https://dashscope.aliyuncs.com/compatible-mode/v1', 'ak-...')]

>>> resolve_model_credentials("openai/gpt-4o", provider="openrouter")
[('openrouter', 'https://openrouter.ai/api/v1', 'sk-...')]

create_chat_model

create_chat_model(
    model_name,
    *,
    temperature=0.0,
    provider=None,
    config_path=None,
    api_key=None,
    dashscope_region=None,
    client_kwargs=None,
)

根据提供商配置实例化聊天模型。

参数：

名称	类型	描述	默认
`model_name`	`str`	要实例化的模型名称。	必需
`temperature`	`float`	传递给底层客户端的温度值。	`0.0`
`provider`	`str \| None`	显式指定的提供商名称。	`None`
`config_path`	`str \| Path \| None`	可选的配置路径覆盖。	`None`
`api_key`	`str \| None`	显式传入的 API 密钥。	`None`
`dashscope_region`	`str \| None`	DashScope 基础 URL 的区域选择器。	`None`
`client_kwargs`	`Mapping[str, Any] \| None`	额外传递的客户端参数。	`None`

返回：

名称	类型	描述
`BaseLanguageModel`	`BaseLanguageModel`	可直接调用的 LLM 客户端实例。

引发：

类型	描述
`ModelConfigError`	当无法解析 API 密钥或配置缺失时抛出。
`FileNotFoundError`	当配置路径不存在时抛出。

build_public_models_catalog

build_public_models_catalog(
    *, config_path=None, config=None
)

构建用于 API 输出的公开模型清单。

参数：

名称	类型	描述	默认
`config_path`	`str \| Path \| None`	模型配置文件的可选路径覆盖。	`None`
`config`	`dict \| None`	直接传入的配置字典，优先于 config_path。	`None`

返回：

类型	描述
`dict[str, Any]`	dict[str, Any]: 公开模型清单，包含提供商与模型列表。

Agent 级角色化模型路由

chat Agent 现在支持可选 model_routing_config，用于把不同运行阶段路由到不同模型角色：

tool_call_model
general_model
complex_task_model
reasoning_model

兼容约定：

Agent 现有的 model_name、model_provider、model_temperature 仍然是主模型与回退模型。
若请求或评测显式传入 model_* 覆盖，则当前执行会折叠为单模型路径。
若某个角色槽位为空，则该阶段回退到主模型三元组。

Shared chat-model routing config models and helpers.

This module centralizes the Agent-scoped multi-model routing control plane so the API layer, runtime implementations, evaluation runner, and admin UI can share one validation and decision contract.

RoutedModelConfig

Bases: BaseModel

One configured model tuple for a routing role.

AgentModelRoutingConfig

Bases: BaseModel

Agent-scoped multi-model routing configuration for chat runtimes.

ModelRoutingContext `dataclass`

Lightweight turn context used for deterministic route selection.

ResolvedModelRoute `dataclass`

Resolved model tuple and route metadata for one runtime stage.

to_observability_payload

to_observability_payload()

Serialize one route decision for observability payloads.

parse_agent_model_routing_config

parse_agent_model_routing_config(raw_json_text)

Parse one serialized Agent model routing config safely.

serialize_agent_model_routing_config

serialize_agent_model_routing_config(config_payload)

Serialize one Agent model routing config for persistence.

resolve_tool_call_model_route

resolve_tool_call_model_route(
    *,
    primary_model_name,
    primary_model_provider,
    primary_model_temperature,
    model_routing_config,
    explicit_override_active,
    stage_name,
)

Resolve the model tuple for one tool-oriented stage.

resolve_generation_model_route

resolve_generation_model_route(
    *,
    primary_model_name,
    primary_model_provider,
    primary_model_temperature,
    model_routing_config,
    explicit_override_active,
    routing_context,
    stage_name="llm_generation",
)

Resolve the model tuple for final response generation.

Bases: BaseSettings

应用主配置 - 聚合所有子配置。

属性：

名称	类型	描述
`app_name`	`str`	应用名称。
`log_level`	`str`	日志级别。
`app_env`	`Literal['development', 'staging', 'production']`	运行环境标识。
`app_instance`	`str`	运行实例标识。
`env_guard_mode`	`EnvironmentGuardMode`	环境保护模式（off/warn/strict）。
`expected_public_hosts`	`list[str]`	允许访问的外部 Host 白名单。
`cors_allowed_origins`	`list[str]`	CORS 允许来源（支持逗号分隔字符串或 list 输入）。
`postgres_user`	`str`	PostgreSQL 用户名。
`postgres_password`	`SecretStr`	PostgreSQL 密码。
`database_url`	`str`	完整数据库 URL 覆盖。
`minio_access_key`	`str`	MinIO 访问密钥。
`minio_secret_key`	`SecretStr`	MinIO 密钥。
`minio_root_user`	`str`	Docker MinIO root 用户。
`minio_root_password`	`SecretStr`	Docker MinIO root 密码。
`database`	`DatabaseSettings`	数据库子配置。
`chat_model`	`ChatModelSettings`	聊天模型子配置。
`minio`	`MinioSettings`	MinIO 子配置。
`qdrant`	`QdrantSettings`	Qdrant 子配置。
`embedding`	`EmbeddingSettings`	Embedding 子配置。
`rerank`	`RerankSettings`	Rerank 子配置。
`multi_query`	`MultiQuerySettings`	Multi-Query RAG 扩展子配置。
`rag`	`RAGSettings`	RAG 检索默认参数子配置。
`chunking`	`ChunkingSettings`	分块子配置。
`timeouts`	`TimeoutSettings`	超时子配置。
`mcp`	`MCPSettings`	MCP 出站能力配置。
`skill`	`SkillSettings`	Skill 运行时配置。
`fusion`	`FusionSettings`	Fusion 运行时配置。
`scheduled_tasks`	`ScheduledTasksSettings`	定时任务运行时配置。
`runtime_checkpoint`	`RuntimeCheckpointSettings`	运行时 checkpoint 配置。
`agent_memory`	`AgentMemorySettings`	Agent 长期记忆配置。
`langfuse`	`LangfuseSettings`	Langfuse 观测导出配置。
`release`	`ReleaseSettings`	部署发布元数据。
`admin_access`	`AdminAccessSettings`	后台身份与会话配置。
`agent`	`AgentSettings`	Agent 通用配置。
`agent_types`	`AgentTypesSettings`	智能体类型配置。
`base_dir`	`Path`	项目根目录。
`log_dir`	`Path`	日志目录。
`log_file`	`Path`	日志文件路径。

resolved_database_url `property`

resolved_database_url

解析最终 DATABASE_URL：env var > TOML + credentials > default。

返回：

名称	类型	描述
`str`	`str`	最终的数据库连接 URL。

resolved_minio_access_key `property`

resolved_minio_access_key

MinIO access key: MINIO_ACCESS_KEY > MINIO_ROOT_USER > default。

返回：

名称	类型	描述
`str`	`str`	解析后的 MinIO access key。

resolved_minio_secret_key `property`

resolved_minio_secret_key

MinIO secret key: MINIO_SECRET_KEY > MINIO_ROOT_PASSWORD > default。

返回：

名称	类型	描述
`str`	`str`	解析后的 MinIO secret key。

ensure_log_directory

ensure_log_directory()

确保日志目录存在。

引发：

类型	描述
`OSError`	当无法创建目录时抛出。

settings_customise_sources `classmethod`

settings_customise_sources(settings_cls, **kwargs)

配置源优先级：init args > env vars > .env > TOML [app] > defaults。

嵌套子模型各自读取 config.toml 对应 section。

参数：

名称	类型	描述	默认
`settings_cls`	`type[BaseSettings]`	Settings 类。	必需
`**kwargs`	`Any`	默认源参数。	`{}`

返回：

类型	描述
`tuple[Any, ...]`	tuple[Any, ...]: 配置源元组，按优先级排列。